Хернес инженерство: користење на Codex каде е агентите се први

Во изминативе пет месеци, нашиот тим спроведуваше експеримент: создавање и испорака на внатрешна бета верзија на софтверски производ со 0 линии рачно напишан код.

Производот има внатрешни дневни корисници и надворешни алфа тестери. Се испорачува, се распоредува, се расипува и се поправа. Она што е различно е дека секоја линија код – логика на апликацијата, тестови, CI конфигурација, документација, набљудливост и внатрешни алатки – ја напиша Codex. Проценуваме дека го изградивме ова за околу една десетина од времето што би било потребно за да се напише кодот рачно.

Луѓето управуваат. Агентите извршуваат.

Намерно го избравме ова ограничување за да го изградиме она што беше неопходно за да ја зголемиме инженерската брзина повеќекратно. Имавме неколку недели да испорачаме нешто што на крајот стана милион редови код. За да го направиме тоа, требаше да разбереме што се менува кога примарната задача на тимот за софтверско инженерство повеќе не е да пишува код, туку да дизајнира околини, да специфицира намери и да гради повратни јамки што им овозможуваат на агентите на Codex да вршат сигурна работа.

Оваа објава е за тоа што научивме при градењето на сосема нов производ со тим од агенти – што се расипа, што се наталожи и како да го максимизираме нашиот единствен навистина оскуден ресурс: човечкото време и внимание.

Првиот комит во празен репозиториум беше направен кон крајот на август 2025 година.

Првичната структура – структура на складиштето, конфигурација на CI, правила за форматирање, поставување на менаџерот на пакети и рамка на апликации – беше генерирана од Codex CLI користејќи GPT‑5, водена од мал сет на постоечки шаблони. Дури и почетната датотека AGENTS.md, која ги насочува агентите како да работат во репозиториумот, беше напишана од Codex.

Немаше претходно постоечки код напишан од луѓе на кој системот можеше да се потпре. Од самиот почеток, репозиториумот го обликуваше агентот.

Пет месеци подоцна, репозиториумот содржи околу милион редови код во логиката на апликацијата, инфраструктурата, алатките, документацијата и внатрешните развивачки алатки. Во тој период, приближно 1.500 pull request беа отворени и споени, при што мал тим од само тројца инженери го движеше Codex. Ова се преведува во просечен капацитет од 3,5 PRs по инженер дневно и изненадувачки, капацитетот се зголемил како што тимот пораснал и сега има седум инженери. Важно е да се истакне дека ова не беше резултат само заради резултат: производот го користат стотици внатрешни корисници, вклучувајќи и секојдневни напредни корисници.

Во текот на процесот на развој, луѓето никогаш не придонесоа директно со код. Ова стана основна филозофија за тимот: без рачно напишан код.

Недостигот од практично човечко кодирање воведе поинаков вид инженерска работа, фокусирана на системи, структура и искористување.

Раниот напредок беше побавен отколку што очекувавме, не затоа што Codex беше неспособен, туку затоа што околината беше недоволно специфицирана. Агентот немаше алатки, апстракции и внатрешна структура потребни за напредок кон високи цели. Главната задача на нашиот инженерски тим стана да им овозможи на агентите да извршуваат корисна работа.

Во пракса, ова значеше работа со пристап од длабочина: разложување на поголемите цели на помали градежни блокови (дизајн, код, преглед, тестирање и сл.), поттикнување на агентот да ги изгради тие блокови и нивно користење за отклучување на посложени задачи. Кога нешто ќе не успееше, решението речиси никогаш не беше „обиди се повеќе“. Бидејќи единствениот начин да се постигне напредок беше да се натера Codex да ја заврши работата, човечките инженери секогаш се вклучуваа во задачата и прашуваа: „која способност недостасува, и како да ја направиме и разбирлива и спроведлива за агентот?“

Луѓето комуницираат со системот речиси целосно преку промптови: инженерот опишува задача, го извршува агентот и му дозволува да отвори pull request. За да се заврши еден pull request, му даваме инструкции на Codex да ги прегледа своите промени локално, да побара дополнителни прегледи од агенти и локално и во облакот, да одговори на повратни информации од луѓе или агенти и да повторува во циклус додека сите агенти-прегледувачи не бидат задоволни (во суштина, ова е Ralph Wiggum Loop⁠(се отвора во нов прозорец)). Codex ги користи нашите стандардни алатки за развој директно (gh, локални скрипти и вештини вградени во репозиториумот) за да собере контекст без луѓето да копираат и вметнуваат во CLI.

Луѓето може да ги прегледуваат pull request-ите, но не се обврзани да го прават тоа. Со текот на времето, ги насочивме речиси сите напори за преглед кон тоа да се спроведуваат од агент до агент.

Како што се зголемуваше протокот на код, нашето тесно грло стана човечкиот капацитет за контрола на квалитетот. Бидејќи фиксното ограничување е човечкото време и внимание, работевме на додавање повеќе можности на агентот, правејќи ги UI-то на апликацијата, дневниците и показателите на апликацијата директно читливи за Codex.

На пример, ја направивме апликацијата да може да се подигне по git работните папки, за Codex да може да стартува и управува со една инстанца по промена. Исто така, го интегриравме Chrome DevTools Protocol во извршувачкото опкружување на агентот и развивме вештини за работа со DOM снимки, слики од екранот и навигација. Ова му овозможи на Codex да ги репродуцира грешките, да ги потврди поправките и директно да размислува за однесувањето на корисничкиот интерфејс.

Го направивме истото и за алатките за набљудливост. Дневниците, показателите и трагите се достапни на Codex преку локален стек за набљудливост кој е привремен за секоја дадена работна папка. Codex работи на целосно изолирана верзија на таа апликација, вклучувајќи ги нејзините дневници и показатели, кои се отстрануваат откако задачата ќе биде завршена. Агентите можат да пребаруваат дневници со LogQL и показатели со PromQL. Со овој контекст достапен, промпти како „обезбедете стартувањето на услугата да заврши за помалку од 800 ms“ или „ниеден временски интервал во овие четири критични кориснички патувања не надминува две секунди“ стануваат остварливи.

Често гледаме како поединечни извршувања на Codex работат на една задача повеќе од шест часа (често додека луѓето спијат).

Управувањето со контекстот е еден од најголемите предизвици за да се направат агентите ефективни при големи и сложени задачи. Една од најраните лекции што ги научивме беше едноставна: дај му на Codex мапа, а не прирачник со инструкции од 1.000 страници.

Го пробавме пристапот „едно големо AGENTS.md⁠(се отвора во нов прозорец)“ . Не успеа на предвидливи начини:

• Контекстот е ограничен ресурс. Огромна датотека со инструкции ја потиснува задачата, кодот и релевантните документи, па агентот или ги пропушта клучните ограничувања или почнува да оптимизира за погрешните.
• Кога има премногу насокин на крај нема вистинска насока. Кога сè е „важно“, ништо не е важно. Агентите на крајот завршуваат со локално препознавање на шеми наместо со намерно навигирање.
• Се расипува веднаш. Монолитен прирачник се претвора во гробница на застарени правила. Агентите не можат да утврдат што сè уште е точно, луѓето престануваат да го одржуваат, а датотеката тивко станува привлечна замка.
• Тешко е да се провери. Еден единствен блоб не е погоден за механички проверки (покриеност, ажурност, сопственост, меѓусебни врски), па отстапувањето е неизбежно.

Значи, наместо да го третираме AGENTS.md како енциклопедија, го третираме како табела на содржини.

Базата на знаење на репозиториумот е сместена во структурирана директорија docs/, која се третира како систем на евиденција. Краток AGENTS.md (приближно 100 реда) се вметнува во контекст и служи првенствено како мапа, со насоки кон подлабоки извори на вистина на друго место.

Дизајнерската документација е каталогизирана и индексирана, вклучувајќи го статусот на верификација и збирот на основни верувања што ги дефинираат принципите на работа со приоритет на агентот. Документација за архитектура⁠(се отвора во нов прозорец) обезбедува мапа на високо ниво на домени и слоеви на пакети. Документот за квалитет ги оценува секој домен на производот и архитектонскиот слој, следејќи ги празнините со текот на времето.

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

Ова овозможува постепено откривање: агентите започнуваат со мала, стабилна почетна точка и се учат каде да погледнат следно, наместо да бидат преоптоварени уште на почетокот.

Ова го спроведуваме механички. Посветени линтери и CI задачи потврдуваат дека базата на знаење е ажурирана, меѓусебно поврзана и правилно структурирана. Повторувачки агент за „одржување на документација“ скенира за застарена или застарена документација што не го одразува реалното однесување на кодот и отвора pull request-и за поправки.

Како што еволуираше базата на кодови, требаше да еволуира и рамката на Codex за одлуки за дизајн.

Бидејќи репозиториумот е целосно генериран од агент, тој е оптимизиран најпрво за читливоста на Codex. На ист начин како што тимовите се стремат да ја подобрат навигацијата низ својот код за новите инженерски вработувања, целта на нашите човечки инженери беше да овозможат агент да може да расудува за целиот деловен домен директно од репозиториумот.

Од перспектива на агентот, сè што не може да се пристапи во контекст додека работи ефикасно, не постои. Знаењето што се наоѓа во Google Docs, во нишки за разговор или во главите на луѓето не е достапно за системот. Локални артефакти во репозиториумот, кои се верзионирани (на пр., код, markdown, шеми, извршни планови), се сè што може да види.

Научивме дека со текот на времето требаше да внесуваме сè повеќе контекст во репотозиториумот. Онаа дискусија на Slack што го усогласи тимот околу архитектонска шема? Ако не може да се најде од страна на агентот, тоа е исто толку нечитливо како што би било непознато за нововработен кој се приклучува три месеци подоцна.

Давањето повеќе контекст на Codex значи организирање и изложување на вистинските информации за агентот да може да расудува врз нив, наместо да го преоптоваруваме со ад-хок инструкции. На ист начин како што би вовел нов член на тимот во принципите на производот, инженерските норми и културата на тимот (вклучувајќи ги и преференциите за емотикони), давањето на агентот овие информации води до подобро усогласен резултат.

Оваа рамка разјасни многу компромиси. Ние дадовме предност на зависности и апстракции што можеа целосно да се интернализираат и да се анализираат во рамките на репозиториумот. Технологиите кои често се опишуваат како „здодевни“ обично им се полесни на агентите за моделирање поради нивната составливост, стабилноста на API и застапеноста во збирката за обука. Во некои случаи, беше поевтино агентот повторно да имплементира подмножества од функционалност отколку да се заобиколи нејасното однесување на повисоко ниво од јавни библиотеки. На пример, наместо да вклучиме генерички пакет во стилот на p-limit, имплементиравме сопствен помошник за мапирање со конкурентност: тој е тесно интегриран со нашата OpenTelemetry инструментализација, има 100 % покриеност со тестови и се однесува точно како што очекува нашето време на извршување.

Внесувањето на поголем дел од системот во форма што агентот може да ја прегледа, валидира и директно да ја измени ја зголемува моќта – не само за Codex, туку и за други агенти (на пр. Aardvark) кои исто така работат на базата на кодови.

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

Агентите се најефективни во средини со строги граници и предвидлива структура⁠(се отвора во нов прозорец), па затоа ја изградивме апликацијата околу цврст архитектонски модел. Секој деловен домен е поделен на фиксен сет на слоеви, со строго проверени насоки на зависности и ограничен број на дозволени врски. Овие ограничувања се спроведуваат механички преку прилагодени линтери (генерирани од Codex, се разбира!) и структурни тестови.

Дијаграмот подолу го прикажува правилото: во рамките на секој деловен домен (на пр. Поставки на апликацијата), кодот може да зависи „нанапред“ само преку фиксен сет на слоеви (Types → Config → Repo → Service → Runtime → UI). Попречни аспекти (автентикација, конектори, телеметрија, знаменца за функционалности) влегуваат преку единствен експлицитен интерфејс: Провајдери. Сè друго е забрането и се спроведува автоматски.

Ова е вид на архитектура што обично ја одложуваш додека не имаш стотици инженери. Со агентите за кодирање, тоа е рана предуслов: ограничувањата се она што овозможува брзина без деградација или архитектонско отстапување.

Во пракса, ги спроведуваме овие правила со сопствени линтери и структурни тестови, плус мал сет на „инваријанти на вкусот.“ На пример, статички спроведуваме структурирано логирање, конвенции за именување на шеми и типови, ограничувања на големината на датотеките и барања за доверливост специфични за платформата со сопствени линтови. Бидејќи прилагодените линтови, ги пишуваме пораките за грешка за да вметнеме упатства за решавање на проблемите во контекстот на агентот.

Во работен процес што ги става луѓето на прво место, овие правила може да изгледаат педантни или ограничувачки. Со агенти, тие стануваат множители: откако ќе се кодираат, се применуваат насекаде одеднаш.

Во исто време, јасно кажуваме каде ограничувањата се важни и каде не се. Ова е слично на водење на голема инженерска платформа: централизирано поставувајте граници, дозволете локална автономија. Многу се грижиш за границите, точноста и репродуктивноста. Во рамките на тие граници, им дозволуваш на тимовите – или на агентите – значителна слобода во начинот на кој се изразуваат решенијата.

Добиениот код не секогаш се совпаѓа со човечките стилски преференции, и тоа е во ред. Сè додека излезот е точен, одржлив и читлив за идните извршувања на агентите, ги исполнува критериумите.

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

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

Репозиториумот функционира со минимални блокирачки порти за спојување. Pull request-ите се краткотрајни. Нестабилностите во тестовите често се решаваат со последователни извршувања наместо да се блокира напредокот на неодредено време. Во систем каде што капацитетот на агентот далеку го надминува човечкото внимание, корекциите се евтини, а чекањето е скапо.

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

Кога велиме дека базата на кодови е генерирана од Codex агенти, мислиме на сè во базата на кодови.

Агентите произведуваат:

• Код на производ и тестови
• Конфигурација на CI и алатки за објавување
• Внатрешни алатки за развивачи
• Историја на документација и дизајн
• Проценувачки системи
• Прегледај ги коментарите и одговорите
• Скрипти кои управуваат со самиот репозиториум
• Датотеки со дефиниции за продукциската контролна табла

Луѓето секогаш остануваат вклучени, но работат на поинаков слој на апстракција од порано. Ние ја приоритизираме работата, ги претвораме повратните информации од корисниците во критериуми за прифаќање и ги валидираме резултатите. Кога агентот се мачи, го третираме тоа како сигнал: идентификувај што недостасува – алатки, заштитни мерки, документација – и врати го тоа во репозиториумот, секогаш така што самиот Codex ќе ја напише поправката.

Агентите ги користат нашите стандардни развојни алатки директно. Тие ги извлекуваат повратните информации од прегледот, одговараат во линија, објавуваат ажурирања и често ги спојуваат и обединуваат своите pull request-и.

Како што сè повеќе од развојниот циклус беше кодиран директно во системот – тестирање, валидација, преглед, обработка на повратни информации и опоравување – репозиториумот неодамна премина значаен праг каде што Codex може целосно да води нова функционалност.

Со еден промпт, агентот сега може:

• Да ја провери тековната состојба на базата на кодови
• Да повтори пријавена грешка
• Да сними видео кое го покажува неуспехот
• Да аомплементира поправка
• Да ја потврди поправката со управување на апликацијата
• Да снними второ видео што демонстрира резолуција
• Да отвори pull request
• Да одговори на повратни информации од агентот и луѓето
• Да открие и поправи грешки при градење
• Да ескалира до човек само кога е потребна проценка
• Да ја спои промената

Ова однесување во голема мера зависи од конкретната структура и алатките на овој репозиториум и не треба да се претпостави дека може да се генерализира без слична инвестиција – барем не засега.

Целосната автономија на агентот исто така носи нови проблеми. Codex ги реплицира шемите што веќе постојат во репозиториумот – вклучувајќи и нерамномерни или неоптимални. Со текот на времето, ова неизбежно води до отстапување.

На почетокот, луѓето го решаваа ова рачно. Нашиот тим секој петок (20% од неделата) го поминуваше чистејќи „нечистотија од вештачката интелигенција“. Не е изненадувачки, тоа не се зголеми.

Наместо тоа, почнавме да ги кодираме таканаречените „златни принципи“ директно во репозиториумот и изградивме повторлив процес на чистење. Овие принципи се јасни, механички правила што ја одржуваат кодната база читлива и доследна за идните извршувања на агентот. На пример: (1) претпочитаме споделени пакети за корисни функции наместо рачно напишани помошни функции за да ги држиме инваријантите централизирани и (2) не ги сондираме податоците „YOLO-стил“ – ги валидираме границите или се потпираме на типизирани SDK-ови за агентот да не може случајно да гради врз претпоставени структури. На редовни интервали, имаме сет од позадински задачи на Codex кои скенираат за отстапувања, ги ажурираат оценките за квалитет и отвораат таргетирани pull request-и за рефакторирање. Повеќето од овие може да се прегледаат за помалку од една минута и автоматски да се обединат.

Ова функционира како собирање на отпад. Техничкиот долг е како заем со висока камата: речиси секогаш е подобро да се отплаќа континуирано во мали чекори отколку да се дозволи да се наталожи и да се справува со него во болни налети. Човечкиот вкус се доловува еднаш, а потоа постојано се применува на секој ред код. Ова исто така ни овозможува секојдневно да откриваме и решаваме лоши шеми, наместо да дозволиме да се шират во базата со денови или недели.

Оваа стратегија досега функционираше добро до интерното лансирање и усвојување во OpenAI. Изградбата на вистински производ за вистински корисници ни помогна да ги втемелиме нашите инвестиции во реалноста и да нè насочи кон долгорочна одржливост.

Она што сè уште не го знаеме е како архитектонската кохерентност се развива со текот на годините во систем што е целосно генериран од агенти. Сè уште учиме каде човечката проценка додава најмногу влијание и како да ја кодираме таа проценка за да се зголемува. Исто така, не знаеме како ќе се развива овој систем додека моделите продолжуваат да стануваат сè поспособни со текот на времето.

Она што е јасно: градењето софтвер сè уште бара дисциплина, но дисциплината повеќе се гледа во потпорната структура отколку во кодот. Алатките, апстракциите и циклусите на повратни информации што ја одржуваат кохерентноста на базата на кодови стануваат сè поважни.

Нашите најтешки предизвици сега се насочени кон дизајнирање на средини, повратни јамки и контролни системи кои им помагаат на агентите да ја остварат нашата цел: да создадат и одржуваат сложен и доверлив софтвер на големо ниво.

Како што агентите како Codex преземаат поголеми делови од животниот циклус на софтверот, овие прашања ќе станат уште поважни. Се надеваме дека споделувањето на некои рани лекции ќе ти помогне да размислиш каде да го вложиш твојот труд за да можеш едноставно да создаваш работи.