Первая сессия: разбираемся в незнакомом репозитории

Лучшая первая задача для агента — не писать код, а помочь разобраться в чужом. Это безопасно: ничего не меняется. Это полезно: на вход в незнакомый проект обычно уходят часы. И это учит главному навыку — проверять, что агент говорит. В этом уроке вы проведёте первую сессию в репозитории, который знаете плохо.

Выбор репозитория и режима

Возьмите проект, который вы видели мельком: сайт другой команды, старый проект на поддержке, open source библиотеку, которой пользуетесь. Подойдёт любой git-репозиторий.

При запуске Codex смотрит, находится ли папка под системой контроля версий. Для git-репозиториев он предлагает режим Auto: агент может читать и править файлы внутри проекта и запускать обычные команды, а за пределы просит разрешения. Для папок без git рекомендуется режим только для чтения.

Для исследования правки не нужны, поэтому запустите сессию явно в режиме чтения:

cd ~/projects/legacy-site
codex --sandbox read-only

Так агент гарантированно ничего не изменит. Если ему понадобится запустить команду, которая выходит за рамки чтения, он спросит. Подробно о режимах — в уроке «Песочница и одобрения».

Вопрос первый: что это за проект

Начните с общего вопроса:

Расскажи об этом проекте: что он делает, на каком стеке, как устроены каталоги.
Как его запустить локально и как прогнать тесты? Для каждого утверждения
укажи файл, из которого ты это взял.

Последняя фраза — ключевая. Агент, который ссылается на файлы, проверяем. Агент, который «рассказывает в целом», может уверенно смешать реальный проект с типичным проектом на этом стеке.

Посмотрите, что агент делает, прежде чем ответить: какие команды запускает (ls, cat composer.json, grep), какие файлы открывает. Это хороший способ увидеть, как он ориентируется, — и заметить, если он пропустил что-то важное, например каталог плагинов.

Вопрос второй: как проходит запрос

Общая карта полезна, но настоящее понимание приходит, когда вы прослеживаете один конкретный сценарий насквозь:

Проследи, что происходит, когда пользователь отправляет форму заявки на
странице контактов: какой маршрут, какой компонент обрабатывает отправку,
где валидация, куда уходят данные (база, почта, CRM). Дай цепочку файлов
и функций по порядку.

Для сайта на OctoberCMS агент пройдёт от страницы темы к компоненту плагина, его обработчику AJAX, модели и сервису интеграции. Для мобильного приложения аналогичный вопрос — «что происходит при нажатии кнопки входа: экран, вьюмодель, запрос к API, хранение токена».

Чтобы направить агента, упоминайте файлы через @: наберите @ в поле ввода и начните печатать имя — Codex найдёт файл в проекте и вставит путь.

Проверяйте ответы

Агент ошибается реже, чем кажется новичку, но чаще, чем кажется после пары удачных сессий. Правило простое: всё, на что вы будете опираться, проверяйте выборочно.

• Откройте два-три файла из ответа и убедитесь, что функции действительно там и делают то, что описано.
• Попросите агента подтвердить спорное утверждение командой: «покажи grep, который это подтверждает».
• Если в ответе есть «скорее всего» или «обычно в таких проектах», переспросите: «проверь по коду, а не по типичной практике».

Выполнить команду самому, не выходя из сессии, можно с префиксом !:

!git log --oneline -10

Команда выполнится локально под теми же правилами песочницы и одобрений, что и команды агента.

Вопрос третий: где опасно

Хороший вопрос для незнакомого проекта — не только «как устроено», но и «где здесь можно сломать»:

Какие места в проекте выглядят хрупкими: нет тестов, сложная логика,
дублирование, устаревшие зависимости? Оцени, что из этого опаснее всего
трогать, и объясни почему.

Ответ — не приговор, а список гипотез, которые стоит проверить. Но он экономит время: вы сразу знаете, где читать внимательнее.

Что делать с результатом

В режиме чтения агент не может записать файлы, поэтому просите вывод в удобном виде — например, кратким конспектом в markdown. Скопируйте последний ответ командой /copy (или Ctrl+O) и сохраните его в заметки.

Этот конспект пригодится дважды: вам — как карта проекта, и агенту в следующих сессиях — как основа для файла AGENTS.md, о котором пойдёт речь в уроке «AGENTS.md: инструкции проекта».

Завершите сессию по Ctrl+C или командой /exit. Сессия сохранится: вернуться к ней можно командой codex resume --last из того же каталога. Подробно — в уроке «Сессии».

Типичные ошибки первой сессии

• Слишком общий вопрос. «Объясни весь проект» в большом репозитории приводит к поверхностному ответу и съедает контекст. Сужайте: один сценарий, один модуль.
• Вера на слово. Уверенный тон не равен правильному ответу. Ссылки на файлы и выборочная проверка обязательны.
• Смешивание тем. Разобрались с формой заявки, хотите разобраться с деплоем — начните новый чат командой /new. Одна сессия на одну тему работает лучше.