Планирование сложной задачи с Codex
Автор: Казачкин Даниил Михайлович · Обновлено
Он полезен, когда задача неоднозначна, затрагивает несколько подсистем, требует миграции или содержит решения с разной ценой.
План нужен не для каждой правки. Он полезен, когда задача неоднозначна, затрагивает несколько подсистем, требует миграции или содержит решения с разной ценой. Хороший план связывает наблюдаемое текущее состояние с проверяемым результатом и обновляется по мере появления доказательств.
Когда сначала нужен план
Запросите план, если выполняется хотя бы одно условие:
- неизвестна причина дефекта;
- изменение затрагивает API, базу и интерфейс;
- есть несколько совместимых архитектурных вариантов;
- требуется поэтапный rollout или обратная совместимость;
- работа не помещается в один короткий цикл;
- критерий готовности ещё нужно согласовать.
Для небольшой локальной правки отдельный план создаёт лишнюю церемонию. Агент может сразу исследовать, изменить и проверить код.
Из чего состоит исполняемый план
Практичный план отвечает на семь вопросов:
- Как ведёт себя система сейчас и чем это подтверждено?
- Какое поведение требуется?
- Какие файлы, данные и внешние контракты затронуты?
- В каком порядке безопасно делать изменения?
- Как проверяется каждый этап?
- Какие решения ещё не приняты?
- Как откатить или остановить работу?
Пункт «изменить 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;
- определить тесты и сигнал отката;
- перечислить вопросы, требующие решения владельца.
Проверьте, что каждый пункт плана можно завершить и подтвердить независимо. Лишь после этого разрешайте первый этап реализации.
Что важно запомнить
- План нужен для неопределённости и риска, а не для каждой мелкой правки.
- Сначала исследуйте реальную систему, затем выбирайте решение.
- Каждая веха должна иметь наблюдаемый результат и проверку.
- План остаётся живым журналом решений, статуса и открытых вопросов.
Частые вопросы
Должен ли план перечислять все будущие файлы?
Нет. До исследования точный список может быть выдуманным. Называйте подтверждённые точки входа и обновляйте список после чтения кода.
Нужно ли утверждать каждый шаг?
Только шаги с продуктовыми, архитектурными или необратимыми последствиями. Технические действия внутри согласованной границы агент может выполнять автономно, если критерии и разрешения это допускают.
Что делать, если во время реализации план оказался неверным?
Остановить затронутый этап, записать новый факт, пересмотреть зависимости и проверки. Не продолжать механически ради соответствия старому тексту: ценность плана в управляемом изменении, а не в неизменности.