Работа Codex в большом проекте упирается не только в размер репозитория. Главная сложность — выбрать правильный контекст: локальные правила, владельцев модулей, точки входа, тесты и ограничения совместимости. Если передать агенту весь проект без структуры, он потратит внимание на нерелевантные файлы. Если дать слишком мало, он пропустит зависимость и предложит небезопасное изменение. Предсказуемый процесс строится вокруг поэтапного поиска контекста и маленьких проверяемых изменений.
Начните с карты репозитория
Первый проход должен ответить на вопрос «где живёт нужное поведение». Найдите корень проекта, инструкции, package-файлы или аналогичные манифесты, точку запуска, тесты и конфигурацию сборки. Не нужно читать каждый файл. Сначала составьте короткую карту: приложение, библиотеки, тестовые данные, инструменты и документация.
Учебный пример: задача касается авторизации. На карте должны появиться middleware, контроллеры, модель пользователя, настройки сессии и тесты доступа. Файлы маркетинга или генерации отчётов в первую итерацию не входят. Такая фильтрация уменьшает риск изменить соседний поток только потому, что название файла кажется похожим.
Используйте правила репозитория как контракт
Codex обнаруживает файлы AGENTS.md и учитывает их в порядке от корня к текущему каталогу. Это удобный способ сообщить агенту правила проекта: команды проверки, стиль изменений, границы каталогов и обязательные шаги перед завершением. Правила должны быть конкретными. «Пиши хороший код» почти бесполезно; «после изменения запускай npm test -- --runInBand и не меняй сгенерированные файлы вручную» — проверяемо.
Проверьте, нет ли конфликтов между общими и локальными инструкциями. Вложенное правило может уточнить общий порядок, но не должно незаметно отменять требование безопасности. Устаревшие указания лучше удалить или явно пометить, иначе агент будет вынужден разрешать противоречия по косвенным признакам.
Сузьте контекст до пользовательского потока
Большие изменения лучше начинать с одного пользовательского потока. Опишите вход, основные преобразования, выход и побочные эффекты. Затем найдите по коду все точки, через которые проходит этот поток. Такой подход полезнее, чем список «прочитай все файлы модуля», потому что связывает исследование с наблюдаемым поведением.
- Зафиксируйте сценарий и его границы.
- Найдите публичную точку входа и ближайшие зависимости.
- Проверьте существующие тесты и пробелы в покрытии.
- Отделите обязательные изменения от возможных улучшений.
Если обнаружился второй независимый поток, не смешивайте его с первым без необходимости. Две маленькие задачи легче проверить и откатить, чем один большой diff с неясной причинностью.
Планируйте изменение через артефакты
Для сложного участка полезно перед кодом создать краткий план: область, текущая логика, целевая логика, риски и проверки. В официальном Cookbook по модернизации Codex такой подход разделён на обзор системы, дизайн, план работ и валидацию паритета. Для обычной задачи не нужны четыре больших документа, но принцип сохраняется: сначала договориться о форме результата, затем менять код.
План должен быть исполнимым. Вместо «улучшить архитектуру» напишите «вынести проверку прав из контроллера в сервис, сохранить коды ошибок, добавить тесты для трёх ролей». Отдельно перечислите то, что остаётся за рамками: миграция старых данных, изменение API клиентов или массовое форматирование.
Работайте малыми срезами и проверяйте границы
Малый срез — это изменение, которое можно объяснить одним предложением и проверить несколькими командами. После него посмотрите diff: нет ли случайных файлов, массовых замен, удаления комментариев или изменения формата данных. Затем запустите узкие тесты и только потом расширяйте проверку.
| Срез | Что меняем | Проверка | Риск |
|---|---|---|---|
| Логика | Один сервис | Юнит-тесты | Средний |
| Интерфейс | Контракт ответа | Интеграционный тест | Высокий |
| Данные | Схема или миграция | Пробный прогон | Высокий |
Нельзя считать большой проект проверенным только потому, что один локальный тест зелёный. Проверки должны соответствовать уровню риска: контракт требует интеграционного сценария, миграция — тестовой базы и сравнения результата, пользовательский поток — проверки от входа до отображения.
Не смешивайте исследование и необратимые действия
На первом этапе агент может читать файлы, запускать безопасные тесты и строить план. Публикация, удаление, отправка внешнего запроса или изменение секретов должны быть отдельным шагом. Перед таким действием проверьте актуальное состояние: не выполнено ли оно уже другим процессом, не изменился ли target и не устарел ли план.
Если в проекте есть сгенерированные файлы, выясните источник истины. Ручная правка результата генерации может исчезнуть при следующем запуске. В отчёте укажите, какой исходный файл изменён и какой командой воспроизводится производный артефакт.
Проведите финальную проверку как приёмку
Финальная проверка должна подтверждать не только отсутствие ошибок компиляции. Сверьте список изменённых файлов с областью задачи, запустите обязательные тесты, проверьте один счастливый и два граничных сценария, а затем перечитайте итоговый diff. Для модернизации полезно сравнить старый и новый результат на одной учебной выборке: совпадение должно быть определено заранее, включая допустимые различия.
Итоговый отчёт можно сделать коротким:
- какой поток изменён и почему;
- какие файлы затронуты;
- какие команды выполнены и с каким результатом;
- какие риски или ограничения остались;
- нужен ли отдельный ручной шаг.
Такой формат превращает работу с большим проектом из угадывания контекста в последовательность наблюдаемых решений. Codex может ускорить поиск, планирование и реализацию, но качество зависит от границ задачи и доказательств результата.
Различайте источник истины и копии
В большом репозитории один и тот же объект может встречаться в исходниках, сгенерированных файлах, документации и тестовых фикстурах. Перед изменением определите источник истины. Если поменять только копию, следующий генератор вернёт старое значение. Если поменять исходник без обновления производного файла, сборка может быть зелёной локально, но отличаться в CI.
Учебный способ проверки — найти команду генерации и выполнить её на отдельной рабочей ветке или временном каталоге. Сравните diff и убедитесь, что обновились только ожидаемые производные файлы. В отчёте зафиксируйте, какие артефакты намеренно не менялись и почему.
Согласуйте зависимости между командами и пакетами
Большой проект часто содержит несколько пакетов с разными правилами версий. Изменение общего типа или клиента может повлиять на десятки потребителей, даже если локальный тест проходит. Найдите импорты, публичные экспорты и места, где результат сериализуется. Проверяйте не только прямых вызывающих, но и адаптеры, которые скрывают зависимость за общим интерфейсом.
Если контракт меняется, сначала опишите совместимый переход: новый вариант поля, период поддержки старого формата или миграцию по этапам. Не объединяйте в один diff обновление библиотеки, рефакторинг и изменение поведения без причины. Разделение помогает понять, какая часть вызвала падение.
Работайте с устаревшими тестами осторожно
Старый тест может быть частью контракта, а может проверять случайную деталь реализации. Перед удалением выясните, какое пользовательское или системное поведение он защищает. Если тест устарел из-за намеренного изменения, обновите его вместе с описанием причины. Если он нестабилен, сначала зафиксируйте минимальное воспроизведение и отделите исправление flaky-теста от функционального изменения.
Полезная последовательность: запустить тест отдельно, запустить в группе, повторить на чистом окружении и посмотреть, зависит ли результат от порядка. Так агент получает фактические данные, а не строит вывод по имени теста.
Проверьте интеграционный путь после локального успеха
Локальный юнит-тест подтверждает небольшую часть логики. В большом проекте отказ часто появляется на стыке: неверная конфигурация, несовпадающая версия схемы, другой формат времени или потеря заголовка. Поэтому после узкой проверки выберите один сквозной сценарий и проследите его через реальные границы модулей.
Сквозная проверка может быть учебной и не должна требовать производственных секретов. Используйте тестовые ключи, изолированную базу и ограниченный набор данных. Зафиксируйте, какие внешние зависимости были заменены заглушками, чтобы не выдавать симуляцию за полноценную проверку.
Сверяйте контекст перед каждым новым срезом
Контекст большого проекта меняется во время работы: другой разработчик может обновить ветку, появиться новый коммит или измениться правило каталога. Поэтому перед каждым значимым срезом перечитайте статус рабочей копии и проверьте, не устарел ли план. Это особенно важно перед конфликтным слиянием, миграцией и массовой заменой.
Не нужно повторно читать весь репозиторий. Достаточно проверить изменившиеся файлы, связанные инструкции и тесты, которые описывают затронутое поведение. Если новый diff расширяет область, остановитесь на исследовании и обновите план. Такая пауза дешевле, чем исправление результата, сделанного на устаревших предположениях.
Удобно разделить найденный контекст на факты и гипотезы. Факт подтверждён исходником, тестом или документацией. Гипотеза требует запуска, поиска потребителей или вопроса владельцу. В отчёте не смешивайте их: это помогает понять, какие решения уже обоснованы, а какие ещё нельзя превращать в изменение.
Если проект разделён на сервисы, добавьте к карте зависимости по времени: какой компонент публикует событие, кто его читает и сколько длится совместимость. Ошибка часто возникает не из-за неверного кода, а из-за неправильного порядка выката. Даже простой список «сначала поставщик, затем потребитель» помогает агенту не предложить несовместимый одномоментный переход.
После завершения сравните фактический результат с первоначальной картой. Новые найденные зависимости не нужно автоматически включать в scope. Их следует записать как отдельные риски или будущие задачи. Так исследование большого проекта расширяет понимание системы, но не превращает текущую работу в бесконечный рефакторинг.
При передаче работы другому человеку оставьте не только diff, но и маршрут проверки. Укажите, с какого файла начинать чтение, какой сценарий воспроизвести и какие команды запускать. Это снижает зависимость от памяти автора и позволяет повторить проверку после обновления ветки. Для большой системы такая воспроизводимость часто ценнее ещё одного длинного комментария в коде.
Для сервисной архитектуры добавьте временной порядок изменений: какой поставщик контракта выкатывается первым, сколько длится совместимость и когда удаляется старый путь. Даже простой порядок «сначала принимаем оба формата, затем переключаем потребителей, затем удаляем старый» помогает не перепутать техническую готовность с безопасным релизом.
После завершения полезно сравнить фактическую карту с исходной. Новые зависимости запишите как будущие задачи или риски, но не включайте автоматически в текущий scope. Так исследование даёт пользу проекту, не превращая каждую задачу в бесконечный рефакторинг.
В финальном отчёте разделяйте подтверждённые факты и гипотезы. Факт подтверждён кодом, тестом или документацией; гипотеза требует дополнительного запуска или вопроса владельцу. Эта граница не даёт большому контексту превратиться в уверенный, но неподтверждённый рассказ.
Перед передачей результата другому разработчику приложите минимальный маршрут воспроизведения. Укажите версию, команду, тестовый вход и ожидаемый выход. В большом проекте это экономит больше времени, чем ещё один общий абзац о том, что «всё проверено».