Розбір дизайну 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».)

У четвертій лекції курсу сказано, що «один гігантський файл інструкцій не працює», а Codex дає пряму відповідь: обмежувати AGENTS.md приблизно 100 рядками (оригінальна стаття рекомендує близько 100 рядків, а за наближення до межі — переносити матеріал до docs/), розділяти решту в каталозі docs/ і дозволяти agent читати її за потреби. Саме звідси походить авторитетний принцип «дайте карту, а не інструкцію».

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

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

Інженерію контексту Codex можна узагальнити чотирма стратегіями. Спільнота сформулювала цей фреймворк після того, як «context engineering» стала окремою дисципліною, а потім зіставила його з Codex (джерело фреймворку — Context Engineering for Codex CLI):

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

Codex також має тонко продуманий контекст середовища: аналіз вихідного коду в спільнотному проєкті codex-harness-internals показує, що build_environment_update_item виводить лише змінені поля (CWD, гілка git, файлова система) і тільки коли середовище змінюється, а не вставляє повний системний контекст у кожному циклі. Це інженерна деталь принципу «не тримати повторювані token у контексті».

Інструменти та межі: ізоляція через worktree + subagent

Два основні механізми harness у Codex:

1. Ізоляція середовища через git worktree. У розділі «Environment» оригінальної статті «Harness Engineering» сказано: кожне завдання виконується в окремому git worktree разом із локальним стеком спостережуваності (журналами, метриками, трасуванням), щоб кожну зміну можна було перевірити в незалежному середовищі. Це фізичне втілення принципу сьомої лекції «чітко окреслювати межі кожного завдання для agent»: межі забезпечуються не проханням в інструкціях, а примусовою ізоляцією середовища. Підсистема середовища (environment) тут реалізована як жорстка ізоляція.

2. Subagent на рівні ядра. spawn_agent / wait_agent у Codex — інструменти рівня ядра: модель явно створює subagent, надає йому окрему історію сесії та набір інструментів і чекає на результат. Subagent успадковує інструкції AGENTS.md від батьківського рівня, але працює у власному контексті. Конфігурація зберігається в .codex/agents/*.toml і дає змогу задавати різні моделі та інструкції (детальніше див. розділ Sub-agents у Context Engineering for Codex CLI). Це безпосереднє втілення «ізоляції контексту» й водночас духу дванадцятої лекції про «передавання роботи»: кожен subagent є робочою одиницею з чіткими межами.

Підсистема зворотного зв’язку: команди перевірки в специфікації

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

Політики підтвердження (approval policies) і режим планування (plan mode) забезпечують інший напрям зворотного зв’язку: перед ризикованими діями спочатку створюється план і запитується підтвердження, а «межі завдання» та «право людини ухвалювати рішення» стають засобами контролю runtime.

Відповідність фреймворку курсу

Підсистема	Реалізація Codex	Оцінка
Інструкції	AGENTS.md як сторінка-покажчик + поділ у docs/ + забезпечення інваріантів	Еталонний підхід, що визначив принцип «дайте карту, а не інструкцію»
Інструменти	Ізоляція через worktree + subagent через spawn_agent	Межі жорстко забезпечуються середовищем — дуже сильна реалізація
Середовище	Окремий worktree + стек спостережуваності	Ізоляція через worktree — його візитівка
Стан	Стратегія Write (стан записується у файли/документацію)	Спирається на домовленості, а не вбудовану пам’ять
Зворотний зв’язок	Команди перевірки у специфікації + політики підтвердження + plan mode	Стандартизований шлях зворотного зв’язку, який варто запозичити

Порівняння Codex і Claude Code доволі показове: Claude Code діє через «додавання» — вбудовує пам’ять, дозволи та subagent у ядро; Codex — через «віднімання»: стримує ядро й покладає більше відповідальності на домовленості репозиторію та інженерію контексту. Саме тому спільнота часто каже, що «філософія harness у Codex цінніша за його код».

Проєктні рішення, які варто запозичити

1. Пишіть AGENTS.md як сторінку-покажчик: обмежуйте його приблизно 100 рядками, посилайтеся на подробиці в docs/ і забезпечте можливість автоматизованої перевірки.
2. Записуйте лише інваріанти, не мікрокеруйте реалізацією: жорсткі обмеження + команди перевірки, а решту залишайте моделі.
3. Використовуйте worktree для ізоляції середовища: межі завдання забезпечує середовище, а не прохання в інструкціях.
4. Передавайте лише зміни контексту середовища: у кожному циклі виводьте тільки змінені поля, а не повторюйте весь системний контекст.
5. Використовуйте subagent для ізоляції контексту: поділяйте контекст разом із завданням, щоб підзавдання не забруднювали головний цикл.

Джерела (оригінали / вихідний код)

Кожне твердження можна простежити до наведеного нижче оригінального тексту або вихідного коду, щоб уникнути переказу з пам’яті:

• OpenAI «Harness Engineering»: AGENTS.md як сторінка-покажчик і рекомендація близько 100 рядків, execute 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

Пов’язані лекції: Лекція 03 · Як зробити репозиторій єдиним джерелом правди ｜ Лекція 04 · Як розподілити інструкції між різними файлами ｜ Лекція 07 · Як чітко окреслити межі кожного завдання для agent