Как дать Codex правильный контекст проекта

Краткий ответ

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

Что Codex должен узнать перед изменением

Для большинства задач достаточно пяти групп сведений:

структура: где находится приложение, тесты, миграции и конфигурация;
сценарий: что делает пользователь или вызывающий сервис;
факт ошибки: сообщение, стек, неверный ответ или скриншот;
локальные правила: команды, стиль, ограничения совместимости;
состояние: есть ли незакоммиченные изменения и кому они принадлежат.

В IDE открытые файлы могут автоматически попадать в контекст. В CLI лучше прямо назвать пути или прикрепить нужные файлы. Но даже приложенный файл требует пояснения: какой фрагмент важен и что с ним нужно сделать.

Точка входа вместо полного дампа

Не вставляйте весь репозиторий в промпт. Назовите пользовательский маршрут или программную границу, а агент сам выполнит поиск по ссылкам и импортам.

Например:

Запрос POST /api/avatar отвечает 413 на изображение 1,2 МБ.
Начни с backend/src/media и конфигурации лимитов загрузки.
Сравни ограничение контроллера, middleware и reverse proxy.

Такая подсказка не диктует причину, но задаёт проверяемую область исследования. Если вы не знаете точку входа, попросите сначала построить карту: «найди обработчик, все ограничения размера и путь сохранения; пока ничего не меняй».

Контекст ошибки должен быть воспроизводимым

Скриншот полезен для визуального дефекта, но не заменяет последовательность действий. Сообщите:

1. окружение и роль пользователя; 2. начальное состояние данных; 3. точные действия; 4. ожидаемый результат; 5. фактический результат; 6. частоту воспроизведения.

Для нестабильного бага добавьте время, идентификатор запроса и фрагмент логов. Секреты и персональные данные перед отправкой нужно удалить или замаскировать.

Как учитывать незакоммиченные изменения

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

В рабочем дереве есть мои изменения формы профиля.
Сохрани их и не редактируй frontend/src/modules/profile.
Перед началом покажи, какие файлы относятся к текущему багу.

Git status и diff помогают увидеть состояние, но не объясняют намерение автора. Если изменения пересекаются с задачей, безопаснее остановиться и согласовать границу, чем молча перезаписать работу.

Контекст как доказательство, а не подсказка ответа

Не навязывайте непроверенную гипотезу: «проблема точно в кеше, исправь кеш». Лучше отделить наблюдение от предположения:

После повторного входа данные иногда устаревают. Я подозреваю кеш,
но сначала воспроизведи проблему и проверь сетевые ответы, состояние store
и инвалидацию запросов. Исправляй только подтверждённую причину.

Так агент может опровергнуть вашу гипотезу и сохранить причинно-следственную связь между симптомом, изменением и тестом.

Упражнение: минимальный пакет контекста

Подготовьте пакет для одного бага:

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

Затем удаляйте по одному элементу и спрашивайте: «может ли отсутствие этого факта привести к другому решению?» Оставьте только сведения, для которых ответ «да».

Частые вопросы

Нужно ли указывать каждый файл, который можно менять?

Нет. Укажите точку входа и настоящие ограничения. Codex может проследить импорты и вызовы сам. Полный разрешающий список нужен только там, где граница изменений принципиальна.

Стоит ли прикладывать длинный лог целиком?

Лучше приложить релевантный временной диапазон и сохранить несколько строк контекста до и после ошибки. Если причина неясна, дайте путь к файлу лога и попросите агента выполнить поиск, не засоряя основной диалог всем содержимым.

Что делать, если я не знаю архитектуру проекта?

Начните с read-only исследования: попросите определить точки входа, движение данных, внешние зависимости и команды проверки. После проверки карты превратите вывод в отдельную задачу реализации.

Что важно запомнить

Контекст должен менять решение, а не просто увеличивать промпт.
Называйте точку входа, сценарий, факт ошибки и правила проверки.
Отделяйте наблюдение от своей гипотезы о причине.
Всегда предупреждайте о чужих или незавершённых изменениях в рабочем дереве.

https://yadro-code.ru/lessons/without-university/codex-agent-workflows/codex-agent-02