Как собирается промпт: инструкции, инструменты, кэш

Каждый ход Codex — это запрос к Responses API, собранный по строгим правилам. Если знать эти правила, многие решения по harness перестают быть вопросом вкуса: становится видно, что попадёт в контекст, с каким приоритетом и во что обойдётся смена настроек посреди сессии. Основа урока — статья Майкла Болина «Unrolling the Codex agent loop» (OpenAI, январь 2026) и справочник конфигурации Codex.

Три поля запроса

Запрос к модели состоит из трёх крупных частей:

• instructions — базовые инструкции. Берутся из файла, указанного в model_instructions_file в ~/.codex/config.toml, а если ключа нет — из инструкций модели, которые поставляются вместе с CLI.
• tools — список инструментов: shell, update_plan, инструменты Responses API вроде веб-поиска, инструменты MCP-серверов.
• input — упорядоченный список сообщений и элементов.

Роли сообщений имеют приоритет: system > developer > user > assistant. По Болину, содержимое system-сообщения и порядок первых элементов input контролирует сервер, а tools и instructions — клиент.

Порядок элементов input

Три наблюдения, которые полезно держать в голове.

AGENTS.md — это пользовательское сообщение, а не системный промпт. Права песочницы приходят раньше и с более высокой ролью. Инструкцией в AGENTS.md нельзя «разрешить» то, что запрещает песочница, — и это хорошо.

У цепочки AGENTS.md есть потолок. Ключ project_doc_max_bytes, по умолчанию 32 KiB. Документация говорит, что после достижения лимита следующие файлы не добавляются. Поскольку склейка идёт от корня к cwd, отрезанными окажутся самые специфичные, вложенные файлы. Подробнее — в уроке об AGENTS.md как оглавлении.

Навыки в начальном промпте представлены только метаданными: именем, описанием и путём. Под этот список, по документации, отводится не больше 2% контекстного окна, а если размер окна неизвестен — 8000 символов. Полный SKILL.md подгружается, когда навык выбран. Это встроенная реализация постепенного раскрытия (progressive disclosure).

Промпт растёт как префикс

Ответ модели приходит потоком. Элементы рассуждений (с зашифрованным содержимым), вызовы инструментов и их результаты дописываются в input следующего запроса. Болин формулирует ключевое свойство так: старый промпт — точный префикс нового. Это сделано намеренно, ради кэширования.

Почему это важно. Codex не просит сервер хранить разговор, и объём отправляемого JSON растёт квадратично (подробно в уроке об агентном цикле). Кэш промптов превращает квадратичную стоимость сэмплирования в линейную, но только при точном совпадении префикса.

Что сбрасывает кэш

По Болину, промах кэша дают:

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

Он приводит реальный баг: ранняя поддержка MCP перечисляла инструменты в нестабильном порядке, и запросы промахивались мимо кэша. Отдельно названо уведомление MCP notifications/tools/list_changed посреди длинного разговора — оно тоже ведёт к дорогому промаху.

Поэтому harness Codex меняет конфигурацию посреди сессии дописыванием, а не правкой: при смене прав появляется новое developer-сообщение, при смене папки — новый environment_context. Старые элементы не трогаются, префикс сохраняется насколько возможно.

Решения для внешнего harness

Наши выводы — что делать с этим знанием в команде:

Про изменчивое в AGENTS.md поясним. Цепочка собирается один раз на сессию, поэтому внутри треда кэш она не сломает. Но если корневой AGENTS.md меняется от сессии к сессии, теряется общий стабильный префикс, а заодно и смысл файла: текущая задача живёт в задаче и плане исполнения, а не в постоянных инструкциях.

Для техлида главный вывод: настройки Codex в команде — это не только про качество, но и про экономику. Нестабильный набор инструментов или привычка переключать модель туда-сюда в длинных сессиях — прямые потери на каждом запросе. Управление стоимостью на уровне компании разобрано в курсе для техдиров, урок «Стоимость».

Как заглянуть внутрь

Ничего не нужно угадывать — промпт можно увидеть:

• codex debug prompt-input (экспериментальная команда) печатает точный список элементов, видимых модели, в JSON.
• codex --sandbox read-only --ask-for-approval never "Summarize the current instructions." — быстрый способ проверить, какие инструкции подхватились.
• В codex exec --json событие turn.completed содержит usage с полями input_tokens и cached_input_tokens.
• В TUI /status показывает модель, политику, доступные на запись папки и токены.

codex debug prompt-input "проверка" > prompt.json
less prompt.json

codex exec --json "Опиши структуру каталога src" > run1.jsonl
codex exec --json resume --last "Теперь перечисли точки входа HTTP" > run2.jsonl
jq -r 'select(.type=="turn.completed") | .usage | "\(.cached_input_tokens) из \(.input_tokens)"' run1.jsonl run2.jsonl