Планирование сложной задачи с Codex

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

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

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

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

Когда сначала нужен план

Запросите план, если выполняется хотя бы одно условие:

• неизвестна причина дефекта;
• изменение затрагивает API, базу и интерфейс;
• есть несколько совместимых архитектурных вариантов;
• требуется поэтапный rollout или обратная совместимость;
• работа не помещается в один короткий цикл;
• критерий готовности ещё нужно согласовать.

Для небольшой локальной правки отдельный план создаёт лишнюю церемонию. Агент может сразу исследовать, изменить и проверить код.

Из чего состоит исполняемый план

Практичный план отвечает на семь вопросов:

1. Как ведёт себя система сейчас и чем это подтверждено? 2. Какое поведение требуется? 3. Какие файлы, данные и внешние контракты затронуты? 4. В каком порядке безопасно делать изменения? 5. Как проверяется каждый этап? 6. Какие решения ещё не приняты? 7. Как откатить или остановить работу?

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

Исследование должно предшествовать решению

План нельзя строить только по названиям файлов. Сначала Codex должен прочитать релевантный код, найти существующие паттерны и проверить команды. Поэтому хороший запрос звучит так:

Сначала исследуй текущий поток загрузки изображений от admin API до UI.
Не меняй код. Зафиксируй формат хранения, лимиты, обработку ошибок,
fallback на клиенте и существующие тесты. После этого предложи план миграции,
в котором старые записи продолжают работать.

В результате должны быть не общие пожелания, а ссылки на конкретные участки кода и открытые вопросы.

Вехи и доказательства

Для длительной работы разбейте результат на вехи:

Веха Наблюдаемый результат Проверка

Контракт API описывает original и compressed schema/typecheck

Хранилище обе версии создаются идемпотентно integration test

Клиент серверное изображение имеет приоритет component test

Миграция старые assets перенесены повторяемо dry run и повторный запуск

Интерфейс fallback работает без изображения browser scenario

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

Режим Plan и execution plan

В интерактивных поверхностях Codex режим Plan помогает собрать контекст, задать вопросы и предложить подход до редактирования. Для продолжительной задачи можно хранить план в отдельном документе репозитория, если команда договорилась о таком процессе.

Сам документ не является доказательством выполнения. Он должен содержать команды проверки, критерии перехода между этапами и актуальный статус. Избегайте процентов «готово на 80%»: перечисляйте завершённые артефакты и оставшиеся проверки.

Практика: план без реализации

Выберите изменение схемы данных и попросите Codex только:

• построить текущий путь чтения и записи;
• найти все потребители поля;
• указать обратную совместимость;
• предложить последовательность expand → migrate → contract;
• определить тесты и сигнал отката;
• перечислить вопросы, требующие решения владельца.

Проверьте, что каждый пункт плана можно завершить и подтвердить независимо. Лишь после этого разрешайте первый этап реализации.

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

Должен ли план перечислять все будущие файлы?

Нет. До исследования точный список может быть выдуманным. Называйте подтверждённые точки входа и обновляйте список после чтения кода.

Нужно ли утверждать каждый шаг?

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

Что делать, если во время реализации план оказался неверным?

Остановить затронутый этап, записать новый факт, пересмотреть зависимости и проверки. Не продолжать механически ради соответствия старому тексту: ценность плана в управляемом изменении, а не в неизменности.

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

• План нужен для неопределённости и риска, а не для каждой мелкой правки.
• Сначала исследуйте реальную систему, затем выбирайте решение.
• Каждая веха должна иметь наблюдаемый результат и проверку.
• План остаётся живым журналом решений, статуса и открытых вопросов.

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