Harness инженеринг: използване на Codex в свят на агенти

През последните пет месеца нашият екип провежда експеримент: създаване и пускане на вътрешна бета версия на софтуерен продукт с 0 реда ръчно написан код.

Продуктът има вътрешни ежедневни потребители и външни алфа тестери. Изпраща се, внедрява се, чупи се и се поправя. Разликата е, че всеки ред код—логика на приложението, тестове, конфигурация на CI, документация, наблюдаемост и вътрешни инструменти—е написан от Codex. Смятаме, че създадохме това за около 1/10 от времето, което би отнело да напишем кода ръчно.

Хората насочват. Агентите изпълняват.

Умишлено избрахме това ограничение, за да изградим необходимото за увеличаване на инженерната скорост многократно. Имахме седмици, за да доставим това, което в крайна сметка се оказа милион реда код. За да направим това, трябваше да разберем какво се променя, когато основната задача на екип по софтуерно инженерство вече не е да пише код, а да проектира среди, да определя намерения и да изгражда цикли за обратна връзка, които позволяват на агентите на Codex да вършат надеждна работа.

Тази публикация е за това какво научихме, създавайки изцяло нов продукт с екип от агенти—какво се повреди, какво се натрупа и как да извлечем максимума от единствения наистина оскъден ресурс: човешкото време и внимание.

Първият ангажимент в празно хранилище беше направен в края на август 2025 г.

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

Нямаше предварително съществуващ код, написан от хора, който да служи като основа за системата. От самото начало хранилището беше оформено от агента.

Пет месеца по-късно хранилището съдържа приблизително един милион реда код, обхващащи логиката на приложението, инфраструктурата, инструментите, документацията и вътрешните помощни програми за разработчици. През този период бяха отворени и слети приблизително 1 500 pull request, като малък екип от само трима инженери движеше Codex. Това се превежда като средна производителност от 3,5 PRs на инженер на ден и изненадващо производителността е нараснала, тъй като екипът се е разраснал до седем инженери. Важно е да се отбележи, че това не беше резултат само заради самия резултат: продуктът е бил използван вътрешно от стотици потребители, включително от ежедневни вътрешни опитни потребители.

През целия процес на разработка хората никога не са допринесли директно с никакъв код. Това стана основна философия за екипа: никакъв ръчно написан код.

Липсата на практическо човешко кодиране въведе различен вид инженерна работа, фокусирана върху системи, структури и лостове.

Ранният напредък беше по-бавен, отколкото очаквахме, не защото Codex беше неспособен, а защото средата не беше достатъчно специфицирана. На агента му липсваха инструментите, абстракциите и вътрешната структура, необходими за постигане на напредък към високите цели. Основната задача на нашия инженерен екип стана да улесни агентите в извършването на полезна работа.

На практика това означаваше да работим в дълбочина: да разбиваме по-големите цели на по-малки градивни елементи (дизайн, код, преглед, тестване и т.н.), да подканваме агента да конструира тези елементи и да ги използваме, за да отключваме по-сложни задачи. Когато нещо се провалеше, решението почти никога не беше „опитайте по-усилено“. Тъй като единственият начин за постигане на напредък беше Codex да свърши работата, човешките инженери винаги се включваха в задачата и питаха: „Коя способност липсва и как да я направим едновременно разбираема и приложима за агента?“

Хората взаимодействат със системата почти изцяло чрез подкани: инженер описва задача, стартира агента и му позволява да отвори pull request. За да завършим PR, инструктираме Codex да прегледа собствените си промени локално, да поиска допълнителни конкретни прегледи от агенти както локално, така и в облака, да отговори на всяка обратна връзка, предоставена от човек или агент, и да итерара в цикъл, докато всички агенти-рецензенти не са удовлетворени (на практика това е Ralph Wiggum Loop⁠(отваря се в нов прозорец)). Codex използва нашите стандартни инструменти за разработка директно (gh, локални скриптове и умения, вградени в хранилището), за да събира контекст, без хората да копират и поставят в CLI.

Хората могат да преглеждат pull request, но не са задължени. С течение на времето насочихме почти всички усилия по прегледа към обработка от агент на агент.

С увеличаването на производителността на кода, нашето тясно място стана капацитетът на човешкия QA. Тъй като фиксираното ограничение е човешкото време и внимание, работихме да добавим повече възможности към агента, като направим елементи като потребителския интерфейс на приложението, логовете и метриките на приложението директно четими за Codex.

Например, направихме приложението да може да се стартира за всеки git worktree, така че Codex да може да стартира и управлява по един екземпляр за всяка промяна. Също така интегрирахме протокола Chrome DevTools в средата за изпълнение на агента и създадохме умения за работа със снимки на DOM, екранни снимки и навигация. Това позволи на Codex да възпроизвежда грешки, да проверява поправки и да анализира директно поведението на потребителския интерфейс.

Направихме същото и за инструментите за наблюдаемост. Логовете, метриките и следите се предоставят на Codex чрез локален стек за наблюдаемост, който е временен за всяко дадено работно дърво. Codex работи с напълно изолирана версия на това приложение, включително неговите регистри и метрики, които се премахват, след като задачата бъде завършена. Агентите могат да правят заявки към дневниците с LogQL и към метриките с PromQL. С наличието на този контекст, подкани като „гарантирайте, че стартирането на услугата завършва за под 800 ms“ или „нито един обхват в тези четири критични потребителски пътеки не надвишава две секунди“ стават изпълними.

Редовно наблюдаваме как единични изпълнения на Codex работят по една задача в продължение на повече от шест часа (често докато хората спят).

Управлението на контекста е едно от най-големите предизвикателства за ефективността на агентите при изпълнение на големи и сложни задачи. Един от най-ранните уроци, които научихме, беше прост: да дадем на Codex карта, а не 1000-странично ръководство с инструкции.

Опитахме „един голям AGENTS.md⁠(отваря се в нов прозорец)“ Подход. Това се провали по предсказуеми начини:

• Контекстът е ограничен ресурс. Гигантски файл с инструкции измества задачата, кода и съответната документация—така Агентът или пропуска ключови ограничения, или започва да оптимизира за неправилните.
• Твърде много насоки се превръщат в ненасоки. Когато всичко е „важно“, нищо не е важно. Агентите в крайна сметка започват да съпоставят шаблони локално, вместо да навигират целенасочено.
• То се разваля мигновено. Монолитното ръководство се превръща в гробище на остарели правила. Агентите не могат да определят какво все още е вярно, хората спират да го поддържат и файлът тихомълком се превръща в привлекателна неприятност.
• Трудно е да се провери. Един-единствен blob не подлежи на механични проверки (покритие, актуалност, собственост, кръстосани връзки), така че отклоненията са неизбежни.

Така че вместо да третираме AGENTS.md като енциклопедия, го третираме като съдържание.

Базата знания на хранилището се намира в структурирана директория docs/, която се третира като основна система за запис. Кратък AGENTS.md (около 100 реда) се вмъква в контекста и служи предимно като карта, с указания към по-задълбочени източници на истина на други места.

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

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

Това позволява постепенно разкриване: агентите започват с малка, стабилна отправна точка и се обучават къде да търсят следващото, вместо да бъдат претоварени още в началото.

Ние прилагаме това механично. Специализирани линтери и CI задачи проверяват дали базата знания е актуална, кръстосано свързана и правилно структурирана. Периодичен Агент „doc-gardening“ сканира за остаряла или неактуална документация, която не отразява реалното поведение на кода, и отваря pull request за корекции.

С развитието на кодовата база, рамката на Codex за вземане на дизайнерски решения също трябваше да се развива.

Тъй като хранилището е изцяло генерирано от Агент, то е оптимизирано първо за четимостта на Codex. По същия начин, по който екипите се стремят да подобрят навигацията в кода си за новоназначени инженери, целта на нашите инженери беше да направят възможно един агент да разсъждава за целия бизнес домейн директно от самото хранилище.

От гледна точка на агента, всичко, до което той няма достъп в контекста по време на изпълнение, на практика не съществува. Знанията, които се съхраняват в Google Docs, чат нишки или в съзнанието на хората, не са достъпни за системата. Локални за хранилището, версионирани артефакти (напр., код, markdown, схеми, изпълними планове) са всичко, което може да види.

Научихме, че с времето трябваше да добавяме все повече контекст в хранилището. Онази дискусия в Slack, която обедини екипа около архитектурен модел? Ако не е откриваемо за агента, то е нечетливо по същия начин, по който би било непознато за нов служител, който се присъединява три месеца по-късно.

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

Това рамкиране изясни много отстъпки. Предпочетохме зависимости и абстракции, които можеха да бъдат изцяло усвоени и осмислени в рамките на хранилището. Технологиите, често описвани като „скучни“, обикновено са по-лесни за агентите да моделират поради композиционност, стабилност на API и представяне в обучаващия набор. В някои случаи беше по-евтино Агентът да преизпълни подмножества от функционалност, отколкото да се заобикаля непрозрачното поведение на публични библиотеки. Например, вместо да използваме общ пакет в стил p-limit, внедрихме собствен помощен инструмент за map-with-concurrency: той е тясно интегриран с нашата инструментализация на OpenTelemetry, има 100% тестово покритие и се държи точно по начина, по който нашата среда за изпълнение очаква.

Въвличането на по-голяма част от системата във форма, която агентът може да инспектира, валидира и променя директно, увеличава възможностите—не само за Codex, но и за други агенти (напр. Aardvark) които също работят по кодовата база.

Само документацията не може да поддържа последователността на изцяло генерирана от агент кодова база. Като налагаме инварианти, вместо да се занимаваме с микроменажиране на имплементациите, позволяваме на агентите да доставят бързо, без да подкопават основата. Например, изискваме Codex да анализира формите на данните на границата⁠(отваря се в нов прозорец), но не предписваме как точно да се случва това (изглежда, че моделът предпочита Zod, но не сме посочили конкретно тази библиотека).

Агентите са най-ефективни в среди със строги граници и предвидима структура⁠(отваря се в нов прозорец), затова изградихме приложението около твърд архитектурен модел. Всеки бизнес домейн е разделен на фиксиран набор от слоеве, със строго валидирани посоки на зависимост и ограничен набор от допустими връзки. Тези ограничения се прилагат механично чрез персонализирани линтери (разбира се, генерирани от Codex!) и структурни тестове.

Диаграмата по-долу показва правилото: в рамките на всеки бизнес домейн (напр. Настройки на приложението), кодът може да зависи само „напред“ през фиксиран набор от слоеве (Types → Config → Repo → Service → Runtime → UI). Крос-функционални аспекти (удостоверяване, конектори, телеметрия, флагове за функционалности) влизат през един-единствен изричен интерфейс: Providers. Всичко останало е забранено и се прилага автоматично.

Това е видът архитектура, който обикновено отлагате, докато не разполагате със стотици инженери. При агентите за кодиране това е ранно изискване: ограниченията са тези, които позволяват бързина без влошаване или архитектурно отклонение.

На практика прилагаме тези правила с персонализирани линтери и структурни тестове, плюс малък набор от „вкусови инварианти“. Например, ние статично прилагаме структурирано логване, конвенции за именуване на схеми и типове, ограничения за размера на файловете и специфични за платформата изисквания за надеждност с персонализирани линтове. Тъй като lint-овете са персонализирани, пишем съобщенията за грешка, за да вмъкнем инструкции за отстраняване в контекста на агента.

В работен процес, който поставя човека на първо място, тези правила може да изглеждат педантични или ограничаващи. С агентите те стават множители: след като бъдат кодирани, те се прилагат навсякъде едновременно.

В същото време ние ясно посочваме къде ограниченията са от значение и къде не са. Това прилича на ръководене на голяма инженерна платформа: налагайте граници централно, позволявайте автономност локално. Вие се интересувате дълбоко от границите, коректността и възпроизводимостта. В рамките на тези граници Вие предоставяте на екипите или агентите значителна свобода в начина, по който се изразяват решенията.

Полученият код не винаги съответства на човешките стилистични предпочитания, и това е нормално. Стига резултатът да е правилен, поддържаем и четим за бъдещи изпълнения на агенти, той отговаря на изискванията.

Човешкият вкус се връща обратно в системата непрекъснато. Коментарите от прегледа, рефакториращите pull request-и и бъговете, видими за потребителите, се отразяват като актуализации на документацията или се интегрират директно в инструментите. Когато документацията не е достатъчна, ние въвеждаме правилото в кода.

С увеличаването на производителността на Codex, много от конвенционалните инженерни норми станаха контрапродуктивни.

Хранилището работи с минимално блокиращи merge врати. Pull request-и са краткотрайни. Нестабилните тестове често се решават с последващи изпълнения, вместо да се блокира напредъкът за неопределено време. В система, в която производителността на агентите далеч надхвърля човешкото внимание, корекциите са евтини, а чакането е скъпо.

Това би било безотговорно в среда с ниска производителност. Тук често е правилният компромис.

Когато казваме, че кодовата база е генерирана от агенти на Codex, имаме предвид цялото съдържание на кодовата база.

Агентите създават:

• Код на продукта и тестове
• Конфигурация на CI и инструменти за издаване
• Вътрешни инструменти за разработчици
• История на документацията и дизайна
• Оценъчни свръзки
• Коментари и отговори на прегледа
• Скриптове, които управляват самото хранилище
• Файлове с дефиниции за производствения табло

Хората винаги остават в процеса, но работят на различно ниво на абстракция от това, на което сме свикнали. Ние даваме приоритет на работата, превръщаме обратната връзка от потребителите в критерии за приемане и валидираме резултатите. Когато Агентът изпитва затруднения, ние го приемаме като сигнал: идентифицираме какво липсва—инструменти, предпазни механизми, документация—и го връщаме обратно в хранилището, като винаги оставяме самия Codex да напише поправката.

Агентите използват директно нашите стандартни инструменти за разработка. Те извличат обратна връзка от прегледа, отговарят директно в контекста, публикуват актуализации и често обединяват и сливат собствените си pull requests.

Тъй като все повече от цикъла на разработка беше кодиран директно в системата—тестване, валидиране, преглед, обработка на обратна връзка и възстановяване—хранилището наскоро премина значим праг, при който Codex може да управлява нова функционалност от край до край.

При дадена единствена подкана, Агентът вече може да:

• Проверете текущото състояние на кодовата база
• Възпроизведете докладвана грешка
• Запишете видео, демонстриращо неизправността
• Извършете корекция
• Проверете корекцията, като управлявате приложението
• Запишете второ видео, демонстриращо резолюцията
• Отворете pull request
• Отговаряйте на обратната връзка от агент и хора
• Открийте и отстранете грешки при компилация
• Ескалирайте към човек само когато е необходима човешка преценка
• Слейте промяната

Това поведение зависи в голяма степен от конкретната структура и инструментариум на това хранилище и не бива да се приема, че може да се обобщи без подобна инвестиция—поне засега.

Пълната автономия на Агентите също въвежда нови проблеми. Codex възпроизвежда модели, които вече съществуват в хранилището, дори неравномерни или неоптимални. С течение на времето това неизбежно води до отклонение.

Първоначално хората се занимаваха с това ръчно. Екипът ни преди прекарваше всеки петък (20% от седмицата) в почистване на „AI бъркотия“. Не е изненадващо, това не се разшири.

Вместо това започнахме да кодираме това, което наричаме „златни принципи“ директно в хранилището и изградихме повтарящ се процес на почистване. Тези принципи са категорични, механични правила, които поддържат кодовата база четима и последователна за бъдещи изпълнения на агент. Например: (1) предпочитаме споделени пакети с помощни функции пред саморъчно написани помощни функции, за да държим инвариантите централизирани, и (2) не сондираме данни „в YOLO-стил“ – валидираме границите или разчитаме на типизирани SDK, така че агентът да не може случайно да надгражда върху предположени структури. На равни интервали имаме набор от фонови задачи на Codex, които сканират за отклонения, актуализират качествени оценки и отварят целеви pull request-и за рефакториране. Повечето от тях могат да бъдат прегледани за по-малко от минута и автоматично обединени.

Това функционира като събиране на паметта. Техническият дълг е като заем с висока лихва: почти винаги е по-добре да го изплащате непрекъснато на малки стъпки, отколкото да го оставите да се натрупва и да се заемете с него на болезнени тласъци. Човешкият вкус се улавя веднъж и след това се прилага непрекъснато на всеки ред код. Това също ни позволява да улавяме и отстраняваме лоши модели ежедневно, вместо да им позволяваме да се разпространяват в кодовата база с дни или седмици.

Тази стратегия досега се е доказала като успешна до вътрешното стартиране и приемането в OpenAI. Създаването на истински продукт за истински потребители помогна да закрепим инвестициите си в реалността и да ни насочи към дългосрочна устойчивост.

Това, което все още не знаем, е как архитектурната съгласуваност се развива през годините в система, изцяло генерирана от агент. Все още се учим къде човешката преценка има най-голямо въздействие и как да кодифицираме тази преценка, така че да се натрупва. Също така не знаем как тази система ще се развива, докато моделите продължават да стават по-способни с времето.

Какво стана ясно: изграждането на софтуер все още изисква дисциплина, но дисциплината се проявява повече в скелето, отколкото в кода. Инструментите, абстракциите и циклите на обратна връзка, които поддържат кода последователен, стават все по-важни.

Най-големите ни предизвикателства в момента са свързани с проектирането на среди, обратни връзки и системи за управление, които помагат на агентите да постигнат нашата цел: изграждане и поддържане на сложен, надежден софтуер в голям мащаб.

Тъй като агенти като Codex поемат по-големи части от жизнения цикъл на софтуера, тези въпроси ще станат още по-важни. Надяваме се, че споделянето на някои ранни уроци ще Ви помогне да прецените къде да вложите усилията си, така че да можете просто да създавате неща.