Інженерія harness: Codex у світі, орієнтованому на агентів

За останні п'ять місяців наша команда проводила експеримент: створення та випуск внутрішньої бета-версії програмного продукту з 0 рядків вручну написаного коду.

Продукт має внутрішніх щоденних користувачів та зовнішніх альфа-тестерів. Він випускається, розвертається, ламається та виправляється. Відмінність полягає в тому, що кожен рядок коду — логіка програми, тести, конфігурація CI, документація, спостереження та внутрішні інструменти — була написана Codex. За нашими оцінками, ми створили цей продукт приблизно за 1/10 часу, який би знадобився для написання коду вручну.

Люди керують. Агенти виконують.

Ми навмисно обрали це обмеження, аби створити те, що було необхідно для збільшення швидкості розробки на порядок. У нас було кілька тижнів, щоб випустити те, що зрештою виявилося мільйоном рядків коду. Щоб зробити це, нам потрібно було зрозуміти, що змінюється, коли основне завдання команди розробки програмного забезпечення змінюється з написання коду на проєктування середовищ, встановлення намірів та вибудовування контурів зворотного зв'язку, які дозволяють агентам Codex виконувати надійну роботу.

Цей допис про те, чого ми навчилися, створюючи абсолютно новий продукт із командою агентів — що зламалося, що посилилося і як максимально ефективно використовувати наш єдиний по-справжньому дефіцитний ресурс: людський час та увагу.

Перший коміт до порожнього репозиторію було зроблено наприкінці серпня 2025 року.

Початкова форма — структура репозиторію, конфігурація CI, правила форматування, налаштування менеджера пакетів і фреймворк програми — була згенерована Codex CLI з використанням GPT‑5 та невеликого набору існуючих шаблонів. Навіть вихідний файл AGENTS.md, який вказує агентам, як працювати у репозиторії, був написаний самим Codex.

Не було заздалегідь написаного людиною коду, на який система могла б спиратися. Із самого початку репозиторій був сформований агентом.

Через п'ять місяців репозиторій вже містив близько мільйона рядків коду, що охоплюють логіку програми, інфраструктуру, інструменти, документацію та внутрішні утиліти для розробників. За цей період було відкрито та об'єднано приблизно 1500 pull request'ів, при цьому Codex розвивала невелика команда всього з трьох інженерів. Це відповідає середній пропускній здатності 3,5 PR на інженера на день; що дивно, пропускна спроможність підвищилася у міру того, як команда зросла і тепер налічує сім інженерів. Це не було результатом заради результату: продукт використовувався сотнями користувачів усередині компанії, у тому числі активно й щодня.

Протягом усього процесу розробки люди ніколи не писали код. Це стало основною філософією команди: ані рядка коду, написаного вручну.

Відсутність практичного програмування людьми привнесла інший тип інженерної роботи, яка зосереджена на системах, інфраструктурі та оптимізації.

На ранніх етапах прогрес був повільнішим, ніж ми очікували: не тому, що Codex був нездатний, а тому, що середовище було недооцінене. Агенту бракувало інструментів, абстракцій та внутрішньої структури, необхідних для досягнення прогресу на шляху до високорівневих цілей. Основне завдання нашої команди полягало в тому, щоб надати агентам можливість виконувати корисну роботу.

На практиці це означало роботу за принципом глибинного пошуку: розбиття більших цілей на менші блоки (дизайн, код, перевірка, тестування тощо), спонукання агента збирати ці блоки та використання їх для розблокування складніших завдань. Коли щось не вдавалося, рішення майже ніколи не полягало в тому, щоб «старатися більше». Оскільки єдиним способом домогтися прогресу було змусити Codex виконувати роботу, інженери завжди бралися за завдання і запитували: «Якої можливості не вистачає і як зробити її одночасно зрозумілою та обов'язковою для агента?»

Люди взаємодіють із системою майже виключно через промпти: розробник описує завдання, запускає агента та дозволяє йому відкрити pull request. Щоб довести PR до завершення, ми інструктуємо Codex локально перевіряти свої зміни, запитувати додаткові конкретні перевірки у агентів як локально, так і в хмарі, відповідати на будь-які відгуки, надані людиною або агентом, і повторювати цей цикл до тих пір, поки всі агенти-рецензенти не будуть задоволені (фактично це цикл Ральфа Віґґума⁠(відкривається у новому вікні)). Codex безпосередньо використовує наші стандартні інструменти розробки (gh, локальні скрипти та навички, вбудовані в репозиторій), щоб збирати контекст без необхідності копіювання та вставки даних у CLI вручну.

Люди можуть переглядати pull request'и, але не зобов'язані цього робити. Згодом ми направили майже всі зусилля на те, щоб перевірка здійснювалася безпосередньо агентами.

У міру збільшення пропускної спроможності коду нашим вузьким місцем стала пропускна здатність людського QA. Оскільки фіксованим обмеженням були людський час і увага, ми працювали над тим, щоб додати агенту більше можливостей, зробивши такі елементи, як інтерфейс користувача, логи і метрики програми, безпосередньо зрозумілими для Codex.

Наприклад, ми зробили застосунок завантажуваним для кожного git worktree, щоб Codex міг запускати та керувати одним екземпляром на кожну зміну. Ми також інтегрували протокол Chrome DevTools у середу виконання агента та розробили навички для роботи з DOM-знімками, скріншотами та навігацією. Це дозволило Codex відтворювати помилки, перевіряти виправлення і безпосередньо аналізувати поведінку інтерфейсу користувача.

Те ж саме ми зробили для інструментів спостереження. Журнали, метрики та трасування доступні Codex через локальний стек спостереження, який є тимчасовим для кожного окремого worktree. Codex працює з повністю ізольованою версією цієї програми, включаючи його журнали та метрики, які видаляються після завершення завдання. Агенти можуть запитувати журнали за допомогою LogQL та метрики за допомогою PromQL. За наявності цього контексту такі промпти, як «переконайся, що запуск сервісу завершується менш ніж за 800 мс» або «жоден інтервал у цих чотирьох критично важливих сценаріях користувача не повинен перевищувати двох секунд», стають здійсненними.

Ми регулярно спостерігаємо, як за один запуск Codex виконує одне завдання понад шість годин (часто — поки люди сплять).

Управління контекстом — одна з найбільших проблем забезпечення ефективності агентів при виконанні великих і складних завдань. Один із найперших уроків, які ми засвоїли, був простим: Codex треба дати мапу, а не інструкцію на 1000 сторінок.

Спочатку ми випробували варіант «один великий файл AGENTS.md⁠(відкривається у новому вікні)». Це не спрацювало, причому з досить передбачуваних причин:

• Контекст — дефіцитний ресурс. Величезний файл із інструкціями витісняє завдання, код та відповідну документацію, тому агент або упускає ключові обмеження, або починає оптимізовувати непотрібні.
• Занадто масштабний посібник — це безглуздий посібник. Коли «важливим» вважається все, втрачається сама концепція «важливості». Агенти в підсумку починають локально зіставляти дані шаблонів, замість того, щоб вибудовувати навігацію.
• Із часом інструкція руйнується. Монолітний посібник поступово перетворюється на цвинтар застарілих правил. Агенти не можуть визначити, що в ньому лишається актуальним, люди перестають його підтримувати, і посібник втрачає свою корисність.
• Посібник важко перевірити. Один величезний файл практично не піддається механічним перевіркам (на покриття, актуальність, володіння, перехресні зв'язки), і відхилення неминуче.

Отже, замість того, щоб ставитися до AGENTS.md як до енциклопедії, ми ставимося до нього як до змісту.

База знань репозиторію перебуває у структурованому каталозі docs/, який сприймається як система запису. Короткий AGENTS.md (близько 100 рядків) впроваджується в контекст і служить в основному мапою, із покажчиками більш глибоких джерел інформації в інших місцях.

Проєктна документація каталогізується та індексується, включаючи статус перевірки та набір основних переконань, що визначають принципи роботи, орієнтовані на агента. Архітектурна документація⁠(відкривається у новому вікні) надає мапу доменів верхнього рівня та структуру шарів пакетів. Документ із якості оцінює кожен домен продукту й архітектурний шар, відстежуючи прогалини з часом.

Плани сприймаються як повноцінні артефакти. Ефемерні полегшені плани використовуються для невеликих змін, тоді як складна робота фіксується у планах виконання⁠(відкривається у новому вікні) з журналами прогресу та рішень, що заносяться до репозиторію. Активні плани, завершені плани та відомі технічні недоробки — для цього встановлюється версія, і все це зберігається разом, дозволяючи агентам працювати без необхідності спиратися на зовнішній контекст.

Це забезпечує поступове розкриття: агенти починають з невеликої, стабільної точки входу, і їх навчають, куди дивитися далі замість того, щоб одразу перевантажувати їх.

Ми забезпечуємо це механічно. Виділені лінтери та завдання CI перевіряють, що база знань актуальна, містить перехресні зв'язки та правильно структурована. Періодичний агент «doc-gardening» сканує застарілу або неактуальну документацію, яка не відображає реальну поведінку коду, і відкриває pull request для внесення виправлень.

У міру розвитку кодової бази мала розвиватися й структура Codex для прийняття проєктних рішень.

Оскільки репозиторій повністю створений агентом, його оптимізовано насамперед для читабельності Codex. Так само, як команди прагнуть покращити навігацію за своїм кодом для нових інженерів, наша мета як розробників-людей полягала в тому, щоб дати агенту можливість розмірковувати про всю предметну область безпосередньо з самого репозиторію.

З точки зору агента, усе, до чого він не може отримати доступ у контексті під час виконання, фактично не існує. Знання, які знаходяться в Google Docs, чатах або головах людей, недоступні системі. Локальні для репозиторію артефакти, що версіонуються (наприклад, код, розмітка, схеми, виконувані плани) — це все, що він може бачити.

Згодом ми зрозуміли, що нам необхідно додавати до репозиторію дедалі більше контексту. Скажімо, у Slack пройшло обговорення, яке допомогло команді узгодити патерн архітектури. Якщо агент не може його виявити, це обговорення буде для нього приблизно так само марно, як для нового співробітника, який прийде до компанії через три місяці.

Надання Codex більшого контексту означає організацію й розкриття потрібної інформації, щоб агент міг розмірковувати на її основі, а не перевантаження його розрізненими інструкціями. Так само, як ви вводите в курс справи нового члена команди стосовно принципів продукту, інженерних норм та культури команди (включно з уподобаннями по емоджі), надання агенту цієї інформації призводить до більш узгодженого результату.

Це формулювання прояснило багато компромісів. Ми віддавали перевагу залежностям та абстракціям, які можна було повністю інтегрувати та осмислити у репозиторії. Технології, які часто називають «нудними», як правило, легше моделювати агентам завдяки композиційності, стабільності API та представленості в навчальному наборі. У деяких випадках було дешевше доручити агенту заново реалізувати підмножини функціональності, ніж оминати неочевидну поведінку вищих компонентів з публічних бібліотек. Наприклад, замість підключати універсальний пакет у стилі p-limit, ми реалізували власний допоміжний метод map-with-concurrency: він тісно інтегрований з нашою системою OpenTelemetry, має 100% покриття тестами і поводиться так, як очікується для нашого середовища виконання.

Переведення системи у форму, яку агент може перевіряти, валідувати та змінювати безпосередньо, збільшує важіль впливу — не тільки для Codex, але й для інших агентів (наприклад, Aardvark), які працюють над кодовою базою.

Одна лише документація не підтримує узгодженість повністю згенерованої агентом кодової бази. Забезпечуючи дотримання інваріантів, а не контролюючи кожну деталь реалізації, ми дозволяємо агентам швидко випускати зміни, не підриваючи основи. Наприклад, ми вимагаємо, щоб Codex розбирав форми даних на межі⁠(відкривається у новому вікні), але не наказуємо, як саме це має відбуватися (моделі, схоже, подобається Zod, але ми не вказували конкретно цю бібліотеку).

Агенти найбільш ефективні в середовищах зі строгими межами та передбачуваною структурою⁠(відкривається у новому вікні), тому ми розробили застосунок на основі жорсткої архітектурної моделі. Кожна предметна область розділена на фіксований набір шарів із строго перевіреними напрямками залежностей та обмеженим набором допустимих зв'язків. Ці обмеження механічно застосовуються за допомогою лінтерів (авжеж, згенерованих Codex!) і структурних тестів.

Схема нижче показує правило: у межах кожного предметного домену (наприклад, Налаштування програми), код може показувати лише послідовну залежність через фіксований набір шарів (Types → Config → Repo → Service → Runtime → UI). Наскрізні аспекти (аутентифікація, конектори, телеметрія, прапори функцій) входять через єдиний інтерфейс: Providers. Решта заборонено й контролюється механічно.

Це той тип архітектури, який зазвичай відкладають доти, доки у вас не набереться десь сотня інженерів. З агентами програмування це рання попередня умова: обмеження дозволяють підтримувати швидкість без погіршення чи дрейфу архітектури.

На практиці ми забезпечуємо дотримання цих правил за допомогою лінтерів і структурних тестів, а також невеликого набору «переважних інваріантів». Наприклад, ми статично забезпечуємо дотримання структурованого логування, угод про іменування для схем і типів, обмежень на розмір файлів та специфічних для платформи вимог до надійності за допомогою лінтерів. Оскільки лінтери налаштовуються, ми формулюємо повідомлення про помилки так, щоб впроваджувати інструкції з усунення несправностей у контекст агента.

У робочому процесі, орієнтованому на людину, ці правила можуть здаватися педантичними або такими, що обмежують. З агентами вони стають множниками: після застосування вони застосовуються скрізь одночасно.

У той же час ми чітко вказуємо, де обмеження мають значення, а де — ні. Це схоже на керівництво великою інженерною платформною організацією: централізовано встановлювати кордони, надавати автономію на місцевому рівні. Вам надзвичайно важливі межі, коректність та відтворюваність. В рамках цих кордонів ви надаєте командам або агентам значну свободу в тому, як формулюються рішення.

Отриманий код не завжди відповідає людським стилістичним уподобанням, і це нормально. Поки результат коректний, підтримується та читається для майбутніх запусків агента, він відповідає вимогам.

Людські вподобання безперервно передаються у систему. Коментарі до перевірки, рефакторинг pull request'ів та помилки, видимі користувачам, фіксуються як оновлення документації або кодуються безпосередньо до інструментів. Коли документації бракує, ми впроваджуємо правило коду.

У міру збільшення пропускної спроможності Codex багато традиційних інженерних норм стали контрпродуктивними.

Репозиторій працює з мінімальною кількістю блокуючих merge-гейтів. Pull request'и недовговічні. Нестабільні тести часто усуваються повторними прогонами, а не блокують прогрес на невизначений термін. У системі, де пропускна спроможність агента значно перевищує можливості людської уваги, виправлення коштують дешево, а очікування — дорого.

Це було б безвідповідально серед з низькою пропускною спроможністю. Тут часто це є правильним компромісом.

Коли говоримо, що кодова база створена агентами Codex, ми маємо на увазі всю кодову базу.

Агенти створюють:

• Код продукту й тести
• Налаштування CI та інструменти випуску
• Внутрішні інструменти розробника
• Історію документації та проєктування
• Системи оцінки
• Коментарі до перевірки та відповіді
• Скрипти, які керують самим репозиторієм
• Файли визначення панелі керування для продакшену

Люди завжди залишаються в процесі, але працюють на іншому рівні абстракції, ніж раніше. Ми розставляємо пріоритети в роботі, перетворюємо відгуки користувачів у критерії прийнятності та перевіряємо результати. Коли агент зазнає труднощів, ми сприймаємо це як сигнал: визначаємо, чого не вистачає (інструментів? обмежувачів? документації?), і повертаємо це до репозиторію, завжди доручаючи самому Codex написати виправлення.

Агенти безпосередньо використовують наші стандартні інструменти розробки. Вони збирають відгуки, відповідають в обговореннях, відправляють оновлення та часто об'єднують свої власні pull request'и.

У міру того, як все більше елементів циклу розробки кодувалося безпосередньо в систему — тестування, валідація, перевірка, обробка зворотного зв'язку та відновлення — репозиторій нещодавно подолав важливий поріг, у якому Codex може керувати створенням нової функції.

Отримавши один промпт, агент тепер може:

• Перевірити поточний стан кодової бази
• Відтворити зафіксовану помилку
• Записати відеопідтвердження помилки
• Реалізувати виправлення
• Перевірити виправлення, запустивши програму
• Записати друге відео з підтвердженням вирішення проблеми
• Відкрити pull request
• Відповідь на відгуки від агента та людей
• Виявити та усунути проблеми у збірці
• Передати проблему на розгляд людині — лише в тих випадках, коли потрібна людська думка
• Об'єднати зміни

Ця поведінка багато в чому залежить від конкретної структури та інструментів цього репозиторію і не повинна вважатися узагальнюється без порівнянних вкладень (принаймні поки що).

Так, повна автономія агента створює нові виклики. Codex відтворює шаблони, які вже існують у репозиторії навіть нерівномірні або неоптимальні. Згодом це неминуче призводить до відхилень.

Спочатку люди вирішували це завдання вручну. Раніше наша команда витрачала щоп'ятниці (а це 20% тижня) на прибирання «ШІ-сміття». Не дивно, що це не прижилося.

Натомість ми почали кодувати те, що ми називаємо «золотими принципами», безпосередньо в репозиторій і створили регулярний процес очищення. Ці принципи — це суб'єктивні механічні правила, які підтримують кодову базу придатною для читання та послідовною для майбутніх запусків агента. Наприклад: (1) ми віддаємо перевагу загальним пакетам утиліт перед самописними хелперами, щоб інваріанти залишалися централізованими, і (2) ми не перевіряємо дані навмання — ми валідуємо кордони або покладаємося на типізовані SDK, щоб агент не міг почати працювати на вгаданих структурах. На регулярній основі ми маємо набір фонових завдань Codex, які сканують відхилення, оновлюють оцінки якості та відкривають цільові pull request для рефакторингу. Більшість із них можна перевірити менш ніж за хвилину та автоматично об'єднати.

Це працює як збирання сміття. Технічні недоробки — це як кредит із високою процентною ставкою: майже завжди краще погашати його поступово та невеликими частинами, ніж дозволяти боргу накопичуватися та розбиратися з ним болючими ривками. Уподобання людини фіксуються один раз, а потім безперервно застосовуються до кожного рядка коду. Це також дозволяє нам щодня виявляти та усувати неприйнятні шаблони замість того, щоб дозволяти їм поширюватися в кодовій базі протягом декількох днів або тижнів.

Ця стратегія досі добре працювала аж до внутрішнього запуску та впровадження в OpenAI. Створення реального продукту для реальних користувачів допомогло закріпити наші інвестиції у реальності та спрямувати нас до довгострокової підтримки.

Чого ми поки що не знаємо, то це того, як архітектурна цілісність розвивається протягом багатьох років у повністю згенерованій агентами системі. Ми все ще аналізуємо, де людське судження дає найбільший ефект, і як формалізувати це судження так, щоб воно накопичувалося. Крім того, ми ще не знаємо, як ця система розвиватиметься зі зростанням продуктивності моделей з часом.

Що стало очевидним: розробка програмного забезпечення, як і раніше, вимагає дисципліни, але ця дисципліна проявляється більше в структурі, ніж у коді. Інструменти, абстракції та цикли зворотного зв'язку, які підтримують зв'язок кодової бази, стають все більш важливими.

Наші найскладніші завдання зараз зосереджені на проектуванні середовищ, контурів зворотного зв'язку та систем управління, які допомагають агентам досягати нашої мети: створювати та підтримувати складне, надійне програмне забезпечення у масштабах.

У міру того, як такі агенти, як Codex, беруть на себе все більш значні частини життєвого циклу програмного забезпечення, ці питання згодом будуть ще актуальнішими. Ми сподіваємося, що, поділившись деякими ранніми уроками, ми допоможемо вам зрозуміти, куди варто вкласти зусилля, щоб зосередитись на створенні того, що просто працює.