/goal в Codex и Claude Code: почему промпт должен быть коротким, а роадмап — подробным

Коротко: команда /goal в Codex и Claude Code — это не место для длинного ТЗ. Держите сам промпт максимально коротким, а всю сложность выносите заранее в документацию и роадмап с чекпоинтами. Тогда /goal превращается в одну строчку вида «выполни весь план реализации по roadmap.md», а чекпоинты становятся теми самыми условиями завершения, по которым агент сам себя проверяет.

• Проблема: длинная цель в промпте «плывёт» — после компакции контекста агент теряет нить и повторяет шаги.
• Решение: вынести план из промпта в файл, который агент перечитывает.
• Формула: документация → роадмап с чекпоинтами → короткий /goal.
• Итог: предсказуемый автономный прогон вместо лотереи «на сколько часов хватит контекста».

## Что такое /goal и откуда он взялся

Обычный запрос к агенту — это один ход: ты пишешь, агент делает, останавливается и ждёт следующего сообщения. /goal меняет режим: ты задаёшь цель с условием завершения, и агент работает по кругу plan → act → test → review → iterate, пока условие не выполнится.

В Codex команда приехала в CLI версии 0.128.0 (30 апреля 2026). Под капотом — не «фоновая автономия без границ», а, как формулирует сама OpenAI, scoped, user-controlled completion contract: ты определяешь исход, Codex работает против доказательств в треде, а цель можно поставить на паузу, возобновить или очистить (/goal pause, /goal resume, /goal status, /goal clear). Состояние цели хранится отдельно (одна цель на тред, статусы active / paused / budget_limited / complete), поэтому она переживает продолжение сессии.

В Claude Code /goal устроен похоже: ты задаёшь цель и измеримое условие завершения, Claude планирует, выполняет, проверяет и повторяет сам, а отдельная быстрая модель после каждого хода решает, выполнено условие или нет. Это встроенная версия тех самых «keep-going» циклов, которые раньше собирали руками. Рядом живут /loop (по расписанию), routines и система чекпоинтов с откатом через /rewind.

Главное, что стоит понять: /goal не «помнит твою простыню» — он раз за разом сверяется с условием завершения. И вот от того, где это условие живёт, зависит всё.

## Почему длинный /goal — плохая идея

Соблазн очевиден: раз агент будет работать часами сам, давай запихнём в /goal подробнейшее ТЗ на три экрана. На практике это стреляет в ногу по трём причинам.

Контекст компактится, а с ним плывёт цель. Длинные автономные прогоны упираются в лимит контекста. При компакции агент теряет часть истории — и, как жалуются пользователи в тредах OpenAI, начинает повторно планировать и выполнять одни и те же шаги, потеряв прогресс. Чем больше цели вы держали только в промпте, тем больше теряется при сжатии.

Промпт — не якорь. Условие завершения проверяется на каждом ходу. Если оно сформулировано как размытая простыня, маленькой проверяющей модели не за что зацепиться: она не может однозначно сказать «готово». Короткое, конкретное условие проверяется надёжнее длинного.

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

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

## Главная идея: короткий /goal + роадмап с чекпоинтами

Рабочая связка выглядит так:

1. Документация — коротко описываем, что и зачем строим, стек и ограничения.
2. Роадмап с чекпоинтами — режем работу на фазы, у каждой фазы измеримое условие «готово».
3. Короткий /goal — одной строкой отправляем агента выполнять план по роадмапу.

Смысл в том, что вся сложность и все решения зафиксированы в файлах, которые агент перечитывает, а не в одноразовом промпте, который сожмётся и забудется. Чекпоинты из роадмапа при этом работают как готовые условия завершения для проверяющей модели: «фаза 3 закрыта, когда тесты X зелёные». Агенту не нужно угадывать, что вы считаете успехом, — вы это уже написали.

## Шаг 1. Документация

Прежде чем звать /goal, положите в проект короткий документ (или обновите AGENTS.md), который отвечает на вопросы:

• Что строим и зачем. Одна-две фразы про цель фичи.
• Стек и границы. Какие технологии, какие папки можно трогать, какие нельзя.
• Правила. Стиль, какие библиотеки предпочитать, что запрещено (например, «не добавляй новые зависимости без причины»).
• Что считается «сделано». Тесты проходят, линтер чистый, сборка зелёная.

Это не роман на 20 страниц. Задача — убрать неоднозначность, чтобы агент не принимал продуктовые решения на ходу. По сути это тот же принцип, что и в spec-driven development: сначала контракт, потом код.

## Шаг 2. Роадмап с чекпоинтами

Роадмап — это сердце подхода. Здесь план превращается в последовательность фаз, у каждой из которых есть проверяемый чекпоинт. Не «сделать бэкенд», а конкретные шаги с условием завершения, которое можно проверить командой.

Пример roadmap.md:

# Roadmap: экспорт заказов в CSV

## Фаза 1. Модель и миграция
- [ ] Добавить таблицу orders_export_log
- Чекпоинт: `npm run migration:lint` проходит, миграция применяется на чистой БД

## Фаза 2. Сервис экспорта
- [ ] Функция buildOrdersCsv(period, role)
- [ ] Права: только manager и выше, иначе 403
- Чекпоинт: `npm test -- orders-export` — все тесты зелёные

## Фаза 3. Эндпоинт и лимиты
- [ ] POST /api/orders/export
- [ ] До 50 000 строк синхронно, больше — фоном
- Чекпоинт: e2e-тест на 403, на пустой период и на лимит проходит

## Фаза 4. Готово
- Чекпоинт: build:ci зелёный, покрытие не упало, roadmap полностью отмечен

Ключевое здесь — каждый чекпоинт машинно-проверяем. «Тесты зелёные», «сборка проходит», «эндпоинт возвращает 403» — это то, что проверяющая модель может подтвердить по выводу команды, а не по ощущению. Именно чекпоинты не дают агенту зациклиться или объявить «готово» раньше времени.

## Шаг 3. Короткий /goal

Когда документация и роадмап на месте, сам /goal становится почти тривиальным. Вся мысль уже в файлах — команде остаётся указать на них и задать правило остановки.

Минимальный вариант:

/goal выполни весь план реализации по roadmap.md

Чуть более защищённый — с явным правилом остановки и порядком:

/goal реализуй roadmap.md по фазам сверху вниз.
После каждой фазы прогоняй её чекпоинт и отмечай пункты.
Стоп на первом упавшем чекпоинте — не иди дальше.

Обратите внимание: даже «защищённый» вариант — это три коротких предложения. Всё остальное живёт в roadmap.md, который агент перечитывает на каждой фазе.

Разница между инструментами небольшая, но полезно держать в голове:

• Codex. Проверьте, что /goal включён в config.toml, иначе его не будет в списке команд TUI. Управляйте прогоном через /goal status, /goal pause, /goal resume. Помните про окно в 5 часов и статус budget_limited.
• Claude Code. Условие завершения после каждого хода проверяет отдельная быстрая модель, поэтому формулируйте чекпоинты так, чтобы их можно было подтвердить объективно. Перед большими прогонами убедитесь, что работает система чекпоинтов и /rewind — это ваша страховка от неудачной итерации.

## Почему это работает

Связка «короткий /goal + роадмап с чекпоинтами» бьёт в три слабых места автономных прогонов сразу.

Чекпоинты = условия завершения. Проверяющей модели не нужно интерпретировать ваши намерения — у неё есть конкретный критерий: команда прошла или нет. Это резко снижает и ложные «готово», и бесконечные циклы.

Файл переживает компакцию контекста. Даже когда история сжалась и агент «забыл» начало, roadmap.md никуда не делся. Агент перечитывает его и восстанавливает, где остановился, по отмеченным чекбоксам. Это прямое лекарство от той самой потери прогресса, на которую жалуются пользователи.

Человек сохраняет контроль. План лежит в git: его видно, его можно поправить между фазами, к нему можно вернуться. Автономность перестаёт быть «чёрным ящиком на пять часов» и становится управляемым процессом с точками входа.

## Реальные проблемы

Даже с роадмапом автономный прогон — не «запустил и ушёл на выходные». Вот что реально ломается, по опыту сообщества.

• Лимит времени. У Codex есть окно использования (около 5 часов). Планируйте фазы так, чтобы между ними были естественные точки остановки, — тогда budget_limited не застанет вас на середине незакоммиченного изменения.
• Дрейф после компакции. Классическая жалоба: длинный прогон + повторные сжатия контекста → агент теряет прогресс и переделывает сделанное. Роадмап с отмеченными чекбоксами снижает риск, но всё равно проверяйте прогресс глазами.
• Ложное «готово». Если чекпоинт сформулирован размыто («работает»), проверяющая модель может закрыть фазу зря. Спасают только машинно-проверяемые условия.
• Молчаливый scope creep. Агент «на всякий случай» делает больше, чем в роадмапе. Помогает правило в промпте: «делай только то, что в roadmap.md, ничего сверх».
• Незакоммиченный прогресс. Просите отмечать чекбоксы и коммитить после каждой закрытой фазы — иначе откат по чекпоинтам или обрыв по времени сотрёт часы работы.

## Чеклист перед запуском /goal

• Есть короткая документация или актуальный AGENTS.md.
• Роадмап разбит на фазы, у каждой машинно-проверяемый чекпоинт.
• Понятно правило остановки: где агент обязан прекратить и позвать вас.
• Указано, что делать НЕ нужно (границы scope).
• Сам /goal — это 1–3 коротких предложения, а не ТЗ.
• Для Codex: команда включена в config.toml.
• Для Claude Code: чекпоинты и /rewind работают как страховка.
• Договорились: агент коммитит после каждой закрытой фазы.

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

А если просто дать /goal с подробным ТЗ — разве не сработает? На короткой задаче сработает. На длинной — начнёт плыть: контекст сожмётся, агент потеряет часть цели и может пойти по кругу. Файл с планом это лечит, потому что его можно перечитать.

Чем /goal отличается от обычного промпта? Обычный промпт — это один ход и остановка. /goal — это цикл plan → act → test → review, который крутится до выполнения условия завершения. Поэтому условие должно быть проверяемым, а не «сделай хорошо».

Что писать в чекпоинт? То, что можно проверить командой: «тесты X зелёные», «build проходит», «эндпоинт отдаёт 403». Всё, что проверяется «на глаз», — плохой чекпоинт.

Это то же самое, что spec-driven development? Родственные подходы. SDD — про то, как формализовать требования до кода. Здесь мы берём готовый план и отдаём его автономному циклу /goal. Роадмап с чекпоинтами — естественное продолжение спеки.

Codex или Claude Code? Механика близка. Codex даёт явное управление целью (pause/resume/status) и требует включения в config.toml. Claude Code проверяет условие отдельной быстрой моделью и подстрахован системой чекпоинтов с /rewind. Выбирайте по тому, в чём уже работаете.

## Вывод

/goal — мощный режим, но он усиливает и порядок, и хаос. Если высыпать в него длинное ТЗ, вы получите автономный генератор проблем, который к тому же теряет нить на длинной дистанции. Если же вложиться в короткую документацию и роадмап с машинно-проверяемыми чекпоинтами, то сам /goal схлопывается до одной честной строчки: «выполни план по roadmap.md».

Правило, которое стоит запомнить: вся сложность — в файлах, в промпте — только указатель. Чем короче ваш /goal и чем подробнее роадмап, тем предсказуемее результат.

## Что читать дальше

• Spec-driven development: как писать ТЗ, чтобы ИИ-агент не додумывал
• AGENTS.md: единый источник истины для ИИ-агентов
• Memory Bank: хранение контекста для ИИ в разработке проектов
• Как писать тесты через ИИ