Разбор дизайна harness в Codex

Codex от OpenAI, возможно, теснее всех четырёх продуктов связан с фундаментальной идеей harness. Статья «Harness Engineering», давшая название всей области, основана на опыте команды OpenAI по созданию продуктов с помощью Codex. Поэтому разбор дизайна harness в Codex — в значительной степени разбор инженерной практики, стоящей за этой статьёй.

Философию Codex можно выразить одним предложением: репозиторий — источник истины (repository as the system of record), AGENTS.md — лишь страница-оглавление, а ценность инженерной работы состоит в проектировании среды, выражении намерения и построении циклов обратной связи.

Позиционирование в одном предложении

За несколько недель команда OpenAI с помощью Codex создала продукт, который в итоге вырос до более чем миллиона строк кода, и каждая строка была написана Codex — см. раздел «Designing for growth» в оригинальной статье Harness Engineering. Эта практика отвечает на вопрос: как организовать систему, когда роль инженера меняется с «написания кода» на «проектирование harness». Сам Codex CLI — монолитный бинарный файл с открытым исходным кодом, реализованный на Rust (github.com/openai/codex), но его главный вклад в harness связан с соглашениями (convention) и инженерией контекста, а не с эффектными точками расширения.

Подсистема инструкций: AGENTS.md — страница-оглавление, а не энциклопедия

Это самое влиятельное дизайнерское решение Codex для теории harness:

Один гигантский файл инструкций плохо поддаётся механизированным проверкам — покрытия, актуальности, владения и перекрёстных ссылок, — поэтому расхождение с реальностью неизбежно. В результате мы перестали считать AGENTS.md энциклопедией и стали использовать его как страницу-оглавление. Знания о кодовой базе находятся в структурированной документации, а AGENTS.md указывает на неё.

(Это прямой пересказ раздела «AGENTS.md should be a directory page» из оригинальной статьи Harness Engineering.)

Лекция 4 объясняет, почему «один гигантский файл инструкций не работает», а Codex предлагает прямое решение: держать AGENTS.md в пределах примерно 100 строк — оригинальная статья рекомендует около 100 строк и советует при приближении к пределу переносить материал в docs/. Всё, что не помещается, разделяется на документы в каталоге docs/, которые agent читает по требованию. Именно отсюда происходит авторитетная формулировка «дайте карту, а не инструкцию».

С этим связан принцип «обеспечивайте инварианты, не занимайтесь микроменеджментом реализации» (в оригинале: «don't micromanage the implementation; focus on invariants»): AGENTS.md содержит только жёсткие ограничения, которые нельзя нарушать, и команды верификации, а конкретную реализацию выбирает модель. Это напрямую соответствует принципу лекции 2 «ограничения вместо микроменеджмента».

Подсистема контекста: Write-Select-Compress-Isolate

Инженерию контекста Codex можно описать четырьмя стратегиями. Этот фреймворк был сформулирован сообществом после того, как «context engineering» стала самостоятельной дисциплиной, а затем сопоставлен с Codex; источник — Context Engineering for Codex CLI:

• Write (вынести наружу): сохранять контекст за пределами окна — выводы записывать в документацию, состояние в файлы, а не оставлять их в разговоре. Это соответствует принципу «репозиторий — источник истины».
• Select (выбрать для загрузки): помещать в окно только необходимые token — AGENTS.md указывает путь, а файлы читаются по требованию вместо загрузки всего репозитория.
• Compress (compaction): сохранять действительно важное. В Codex есть автоматическая compaction и ручная команда /compact; compact_prompt можно настроить (см. Context Engineering for Codex CLI).
• Isolate (изолировать): разделять контекст по разным границам — использовать subagent для изоляции контекста отдельных задач, чтобы, например, frontend-subagent никогда не видел database schema backend.

У Codex есть ещё одна тонкая деталь дизайна контекста среды. Анализ исходного кода в сообщественном проекте codex-harness-internals показывает, что build_environment_update_item выводит только изменившиеся поля — CWD, ветвь git, файловую систему — и только при изменении среды, а не вставляет полный системный контекст на каждом раунде. Это практическая реализация принципа «не держать в контексте повторяющиеся token».

Инструменты и границы: изоляция worktree + subagent

У Codex есть два ключевых механизма harness:

1. Изоляция среды с помощью git worktree. В разделе «Environment» оригинальной статьи Harness Engineering прямо сказано: каждая задача выполняется в отдельном git worktree вместе с локальным стеком наблюдаемости — логами, метриками и трассировками, — чтобы каждое изменение проверялось в независимой среде. Это физическая реализация принципа лекции 7 «Задавайте agent чёткие границы каждой задачи»: границы принудительно обеспечиваются изоляцией среды, а не просьбой в инструкциях. Подсистема среды здесь реализована как жёсткая изоляция.

2. Subagent на уровне ядра. spawn_agent / wait_agent в Codex — инструменты уровня ядра: модель явно создаёт subagent, выделяет ему отдельную историю session и набор инструментов, а затем ждёт результат. Subagent наследует инструкции AGENTS.md родителя, но работает в собственном контексте. Конфигурация хранится в .codex/agents/*.toml, где можно задать разные модели и инструкции; подробности см. в разделе Sub-agents статьи Context Engineering for Codex CLI. Это непосредственная реализация «изоляции контекста» и одновременно духа «handoff» из лекции 12: каждый subagent — рабочая единица с чёткими границами.

Подсистема обратной связи: команды верификации как часть стандарта

Практика OpenAI особо подчёркивает один принцип: явно перечисляйте команды верификации в AGENTS.md, чтобы способ проверки правильности стал частью репозитория. В инженерном процессе Codex тесты, CI, документация и конфигурация наблюдаемости создаются самим Codex и образуют исполняемые пути верификации. Решение проблемы «модель мощная, но ненадёжная» состоит не в надежде на сознательность модели, а в том, чтобы путь верификации стал стандартным компонентом harness.

Политики подтверждения (approval policies) и режим планирования (plan mode) обеспечивают ещё одно направление обратной связи: перед высокорисковыми операциями сначала составляется план и запрашивается подтверждение. Так «границы задачи» и «право человека принимать решения» становятся средствами управления runtime.

Сопоставление с фреймворком курса

Подсистема	Реализация Codex	Оценка
Инструкции	AGENTS.md как страница-оглавление + разделение по docs/ + инварианты выполнения	Эталонная реализация принципа «дайте карту, а не инструкцию»
Инструменты	Изоляция worktree + subagent через spawn_agent	Границы жёстко изолированы средой; очень мощная реализация
Среда	Отдельный worktree + стек наблюдаемости	Изоляция worktree — отличительная черта Codex
Состояние	Стратегия Write (состояние записывается в файлы и документацию)	Опирается на соглашения, а не на встроенную память
Обратная связь	Команды верификации в стандарте + политики подтверждения + plan mode	Путь обратной связи задан по умолчанию и заслуживает заимствования

Сравнение Codex и Claude Code особенно интересно. Claude Code следует «сложению», встраивая память, permissions и subagent в ядро. Codex следует «вычитанию»: ядро остаётся сдержанным, а больше ответственности возлагается на соглашения репозитория и инженерию контекста. Поэтому сообщество часто говорит, что «философия harness в Codex ценнее его кода».

Дизайнерские решения, которые стоит перенять

1. Пишите AGENTS.md как страницу-оглавление: держите его примерно в пределах 100 строк, ссылайтесь на подробности в docs/ и обеспечьте возможность механизированной проверки.
2. Фиксируйте только инварианты, не занимайтесь микроменеджментом реализации: жёсткие ограничения и команды верификации, остальное — модели.
3. Используйте worktree для изоляции среды: границы задач должны принудительно задаваться средой, а не просьбами в инструкциях.
4. Передавайте только приращения контекста среды: выводите на каждом раунде лишь изменившиеся поля, не вставляя заново полный системный контекст.
5. Используйте subagent для изоляции контекста: разделяйте не только задачи, но и контекст, чтобы подзадачи не загрязняли основной цикл.

Источники (оригинальные материалы / исходный код)

Каждое утверждение можно проверить по приведённому ниже оригинальному материалу или исходному коду — мы не пересказываем по памяти:

• OpenAI «Harness Engineering»: AGENTS.md как страница-оглавление и рекомендация примерно 100 строк, executive invariants / don't micromanage, изоляция worktree + стек наблюдаемости, включение команд верификации в стандарт, пример продукта объёмом более миллиона строк, политики подтверждения и plan mode. Основной источник всех ключевых тезисов статьи.
  https://openai.com/index/harness-engineering/
• Официальная спецификация OpenAI «AGENTS.md» (AGENTS.md как стандарт соглашений между инструментами):
  https://openai.com/index/agents-md/
• Репозиторий исходного кода Codex CLI (монолитный бинарный файл, реализованный на Rust):
  https://github.com/openai/codex
• Context Engineering for Codex CLI (сообщество): фреймворк Write-Select-Compress-Isolate, /compact и compact_prompt, subagent spawn_agent / wait_agent и конфигурация .codex/agents/*.toml.
  https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/
• codex-harness-internals (сообщественный анализ исходного кода): подробности реализации, включая инкрементальный контекст среды в build_environment_update_item.
  https://github.com/AlexKenbo/codex-harness-internals

Связанные лекции: лекция 3 «Как сделать репозиторий единственным источником истины» ｜ лекция 4 «Как разделить инструкции между разными файлами» ｜ лекция 7 «Как задать agent чёткие границы каждой задачи»