Inženýrství harnessu: využití nástroje Codex ve světě agentů

V uplynulých pěti měsících náš tým prováděl experiment: vytvořil a odeslal interní beta verzi softwarového produktu s 0 řádky ručně napsaného kódu.

Produkt má interní každodenní uživatele a externí alfa testery. Dodává se, nasazuje, rozbíjí se a opravuje. Liší se v tom, že každý řádek kódu – logika aplikace, testy, konfigurace CI, dokumentace, pozorovatelnost a interní nástroje – byl napsán nástrojem Codex. Odhadujeme, že jsme ho vytvořili přibližně za desetinu času, který by bylo nutné věnovat ručnímu psaní kódu.

Lidé řídí. Agenti vykonávají.

Toto omezení jsme zvolili záměrně, abychom postavili to, co je nutné pro zvýšení rychlosti návrhu o několik řádů. Měli jsme několik týdnů na to, abychom dodali něco, co nakonec představovalo milion řádků kódu. K tomu jsme potřebovali pochopit, co se změní, když hlavním úkolem týmu softwarových inženýrů už není psát kód, ale navrhovat prostředí, specifikovat záměry a vytvářet zpětnovazební smyčky, které umožňují agentům Codex spolehlivě pracovat.

Tento příspěvek je o tom, co jsme se naučili při vytváření zcela nového produktu s týmem agentů – co se pokazilo, co se navzájem posilovalo a jak maximalizovat náš jediný skutečně vzácný zdroj: čas a pozornost lidí.

První commit do prázdného úložiště proběhl koncem srpna 2025.

Počáteční konstrukce – struktura úložiště, konfigurace CI, pravidla formátování, nastavení správce balíčků a aplikační rámec – byl vygenerován pomocí rozhraní příkazového řádku Codex s použitím GPT‑5, přičemž se řídil malou sadou existujících šablon. Dokonce i úvodní soubor AGENTS.md, který agentům určuje, jak pracovat v úložišti, napsal Codex.

Neexistoval žádný předchozí kód napsaný člověkem, který by systém ukotvil. Úložiště bylo od počátku utvářeno agentem.

O pět měsíců později obsahuje úložiště řádově milion řádků kódu napříč aplikační logikou, infrastrukturou, nástroji, dokumentací a interními vývojářskými nástroji. Za tu dobu bylo otevřeno a sloučeno zhruba 1500 pull requestů, přičemž Codex řídil malý tým pouhých tří vývojářů. To znamená průměrný výkon 3,5 PR na vývojáře za den a překvapivě se tento výkon zvýšil, protože teď se tým rozrostl na sedm vývojářů. Důležité je, že nešlo o výstup pro výstup: produkt interně používaly stovky uživatelů, včetně interních pokročilých uživatelů každý den.

Během celého procesu vývoje lidé nikdy přímo nepřispěli žádným kódem. To se stalo základní filozofií týmu: žádný ručně psaný kód.

Žádné praktické kódování lidmi vedlo k jinému druhu vývojářské práce, zaměřené na systémy, konstrukci a využití.

Počáteční pokrok byl pomalejší, než jsme očekávali, ne proto, že by Codex nebyl schopen, ale proto, že prostředí nebylo dostatečně specifikováno. Agent postrádal nástroje, abstrakce a vnitřní strukturu, které jsou nutné k dosažení cílů na vysoké úrovni. Hlavním úkolem našeho vývojářského týmu se stalo umožnit agentům vykonávat užitečnou práci.

V praxi to znamenalo, že se pracovalo do hloubky: větší cíle se rozdělily na menší stavební bloky (návrh, kód, revize, testování atd.), agentovi byl zadán prompt, aby tyto bloky sestavil, a pomocí nich se zpřístupnily složitější úkoly. Když se něco nepodařilo, téměř nikdy se to nespravilo slovy „víc se snaž“. Protože jediným způsobem, jak dosáhnout pokroku, bylo přimět Codex k práci, lidští vývojáři vždy vstoupili do úkolu a zeptali se: „Jaká schopnost chybí a jak ji pro agenta udělat srozumitelnou a vymahatelnou?“.

Lidé komunikují se systémem téměř výhradně prostřednictvím promptů: vývojář popíše úkol, spustí agenta a umožní mu otevřít pull request. K dokončení PR dáváme nástroji Codex pokyn, aby lokálně zkontroloval své vlastní změny, vyžádal si další revize konkrétních agentů lokálně i v cloudu, reagoval na jakoukoli zpětnou vazbu od člověka nebo agenta a iteroval ve smyčce, dokud nejsou všichni revizoři z řad agentů spokojeni (prakticky se jedná o smyčku Ralpha Wigguma⁠(otevře se v novém okně)). Codex přímo využívá naše standardní vývojové nástroje (gh, místní skripty a dovednosti integrované do úložiště) ke shromažďování kontextu bez nutnosti kopírování a vkládání do rozhraní příkazového řádku.

Lidé mohou pull requesty kontrolovat, ale dělat to nemusí. Postupem času jsme téměř veškeré kontrolní úsilí přesunuli na práci mezi jednotlivými agenty.

S rostoucím výkonem kódu se naším úzkým místem stala lidská kapacita pro kontrolu kvality. Protože pevným omezením byl lidský čas a pozornost, pracovali jsme na přidání dalších možností do agenta tím, že jsme věci jako uživatelské rozhraní aplikace, protokoly a samotné metriky aplikací zpřístupnili přímo nástroji Codex.

Aplikaci jsme například zpřístupnili ke spuštění pro každý strom git worktree, takže Codex mohl spouštět a řídit jednu instanci pro každou změnu. Také jsme do běhového prostředí agenta propojili protokol Chrome DevTools a vytvořili dovednosti pro práci se snapshoty, snímky obrazovky a navigací v DOM. Díky tomu mohl Codex reprodukovat chyby, ověřovat opravy a přímo zdůvodňovat chování uživatelského rozhraní.

Stejně jsme postupovali i v případě nástrojů pro pozorovatelnost. Protokoly, metriky a stopy jsou systému Codex zpřístupněny prostřednictvím lokálního zásobníku pozorovatelnosti, který je pro daný pracovní strom dočasný. Codex pracuje s plně izolovanou verzí této aplikace – včetně jejích protokolů a metrik, které se po dokončení úlohy odstraní. Agenti se mohou dotazovat na protokoly pomocí LogQL a na metriky pomocí PromQL. S tímto kontextem jsou prompty typu „zajisti, aby se spuštění služby dokončilo za méně než 800 ms“ nebo „žádný úsek v těchto čtyřech kritických uživatelských cestách nepřekročí dvě sekundy“ snadno uchopitelné.

Pravidelně vidíme, že jednotlivé běhy nástroje Codex pracují na jednom úkolu až šest hodin (často v době, kdy lidé spí).

Řízení kontextu je jednou z největších výzev při zajišťování efektivity agentů při řešení rozsáhlých a složitých úkolů. Jedna z prvních lekcí, kterou jsme se naučili, byla jednoduchá: dát nástroji Codex mapu, ne tisícistránkový návod k použití.

Vyzkoušeli jsme přístup „jednoho velkého souboru AGENTS.md⁠(otevře se v novém okně)“. To selhalo předvídatelnými způsoby:

• Kontext je vzácným zdrojem. Obří soubor s instrukcemi zahltí úlohu, kód a příslušné dokumenty, takže agent buď přehlédne klíčová omezení, nebo začne optimalizovat na nesprávná omezení.
• Z příliš obsáhlého vedení se stává žádné vedení. Když je všechno „důležité“, není nic důležité. Agenti nakonec místo záměrné navigace používají lokální porovnávání vzorů.
• Okamžitě ztratí užitek. Monolitický manuál se promění v hřbitov zastaralých pravidel. Agenti nedokážou říct, co je ještě pravda, lidé ho přestanou udržovat a soubor se nenápadně stane atraktivní obtíží.
• Ověřování je těžké. Jedna velká hromada se nedá mechanicky kontrolovat (pokrytí, čerstvost, vlastnictví, křížové vazby), takže posun je nevyhnutelný.

Místo toho, abychom se k souboru AGENTS.md chovali jako k encyklopedii, budeme s ním zacházet jako s obsahem.

Znalostní báze úložiště je uložena ve strukturovaném adresáři docs, který je považován za záznamový systém. Krátký soubor AGENTS.md (zhruba 100 řádků) je vložen do kontextu a slouží především jako mapa s odkazy na hlubší zdroje pravdy jinde.

Dokumentace návrhu je katalogizována a indexována, včetně stavu ověření a souboru základních pravd, které definují principy fungování založeného na agentech. Dokumentace architektury⁠(otevře se v novém okně) poskytuje mapu domén a vrstev balíčků na nejvyšší úrovni. Dokument kvality hodnotí každou doménu produktu a architektonickou vrstvu a v průběhu času sleduje nedostatky.

Plány jsou považovány za špičkové artefakty. Pro malé změny se používají dočasné krátké plány, zatímco komplexní práce se zachycují v plánech provádění⁠(otevře se v novém okně) s protokoly o průběhu a rozhodnutích, které jsou ukládány do úložiště. Aktivní plány, dokončené plány a známé technické dluhy jsou verzovány a umístěny společně, což agentům umožňuje pracovat bez závislosti na vnějším kontextu.

To umožňuje postupné informování: agenti začínají s malým, stabilním vstupním bodem a jsou poučeni o tom, kam se mají dále podívat, místo aby byli od začátku zahlceni.

To prosazujeme mechanicky. Specializované úlohy linters a CI ověřují, zda je znalostní báze aktuální, vzájemně provázaná a správně strukturovaná. Pravidelně se opakující agent „doc-gardening“ vyhledává zastaralou nebo neaktuální dokumentaci, která neodráží skutečné chování kódu, a otevírá pull requesty.

Jak se vyvíjela kódová základna, musel se vyvíjet i rámec Codex pro rozhodování o návrhu.

Protože je úložiště generováno výhradně agenty, je optimalizováno především na srozumitelnost pro Codex. Stejně jako se týmy snaží nově přijatým vývojářům usnadnit orientaci v kódu, cílem našich lidských vývojářů bylo umožnit agentovi uvažovat o celé obchodní doméně přímo ze samotného úložiště.

Z pohledu agenta neexistuje nic, k čemu nemůže přistupovat v kontextu během efektivního běhu. Znalosti, které se nacházejí v dokumentech Google, chatových vláknech nebo v hlavách lidí, nejsou systému přístupné. Vidí pouze artefakty, které jsou lokálně v úložišti, a s verzí (např. kód, markdown, schémata, spustitelné plány).

Zjistili jsme, že postupem času musíme do úložiště vkládat stále více kontextu. Ta diskuse na Slacku, ve které se tým shodl na vzoru architektury? Pokud ji agent nemůže najít, je nesrozumitelná stejně, jako by ji neznal nový zaměstnanec, který se k týmu připojil o tři měsíce později.

Dát nástroji Codex více kontextu znamená uspořádat a vystavit správné informace tak, aby nad nimi agent mohl uvažovat, a ne ho zahlcovat ad hoc pokyny. Stejně jako při seznamování nového člena týmu s principy produktu, vývojářskými normami a týmovou kulturou (včetně preferencí emoji) vede poskytování těchto informací agentovi k lepšímu sladění výstupů.

Toto vymezení objasnilo mnoho kompromisů. Upřednostňovali jsme závislosti a abstrakce, které bylo možné plně internalizovat a zdůvodnit v rámci úložiště. Technologie, které jsou často označovány jako „nudné“, bývají pro agenty snadněji modelovatelné díky jejich složitelnosti, stabilitě rozhraní a zastoupení v trénovací množině. V některých případech bylo levnější nechat agenta reimplementovat podmnožiny funkcí než pracovat s neprůhledným chováním veřejných knihoven. Například místo toho, abychom použili obecný balíček ve stylu p-limit, implementovali jsme vlastní pomocný balíček map-with-concurrency: je úzce integrován s naší instrumentací OpenTelemetry, má pokrytí 100 % testů a chová se přesně tak, jak náš runtime očekává.

Vytažení větší části systému do podoby, kterou může agent přímo kontrolovat, ověřovat a upravovat, zvyšuje pákový efekt – nejen pro Codex, ale i pro ostatní agenty (např. Aardvark), kteří na kódové základně také pracují.

Samotná dokumentace neumožňuje udržet plně agentem generovanou kódovou základnu koherentní. Vynucováním invariantů, nikoliv mikromanagementem implementací, umožňujeme agentům rychlé dodávání, aniž bychom podkopávali základy. Například požadujeme, aby Codex analyzoval datové tvary na hranici⁠(otevře se v novém okně), ale nepředepisujeme, jak se to má stát (zdá se, že model má rád Zod, ale tuto konkrétní knihovnu jsme nespecifikovali).

Agenti jsou nejúčinnější v prostředí s přísnými hranicemi a předvídatelnou strukturou⁠(otevře se v novém okně), takže jsme aplikaci postavili na pevném architektonickém modelu. Každá obchodní doména je rozdělena na pevně danou sadu vrstev s přísně ověřenými směry závislostí a omezenou sadou přípustných hran. Tato omezení jsou vynucována mechanicky pomocí vlastních linterů (samozřejmě generovaných nástrojem Codex!) a strukturálních testů.

Níže uvedený diagram znázorňuje pravidlo: v rámci každé obchodní domény (např. Nastavení aplikace) může mít kód pouze „dopředné“ závislosti prostřednictvím pevně dané sady vrstev (typy → konfigurace → úložiště → služba → runtime → uživatelské rozhraní). Průřezové záležitosti (autentizace, konektory, telemetrie, příznaky funkcí) vstupují přes jediné explicitní rozhraní: poskytovatele. Cokoli jiného je zakázáno a vymáháno mechanicky.

Tento typ architektury se obvykle odkládá, dokud nemáte stovky vývojářů. U kódovacích agentů je to předpoklad už zpočátku: omezení jsou tím, co umožňuje rychlost bez rozpadu nebo posuvu architektury.

V praxi tato pravidla prosazujeme pomocí vlastních linterů a strukturálních testů a malé sady „invariant vkusu“. Například staticky vynucujeme strukturované protokolování, konvence pojmenování schémat a typů, limity velikosti souborů a požadavky na spolehlivost specifické pro danou platformu pomocí vlastních lintů. Protože jsou linty vlastní, píšeme chybové zprávy, aby do kontextu agenta vložily pokyny k nápravě.

V pracovním procesu, který je zaměřen na člověka, mohou tato pravidla působit pedantsky nebo omezujícím dojmem. U agentů se stávají multiplikátory: jakmile jsou zakódovány, platí všude najednou.

Zároveň jasně říkáme, kde jsou omezení důležitá a kde ne. To se podobá vedení velké technické organizace: centrálně prosazovat hranice, lokálně umožnit autonomii. Hodně záleží na hranicích, správnosti a reprodukovatelnosti. V rámci těchto hranic mají týmy – nebo agenti – značnou volnost při vyjadřování řešení.

Výsledný kód ne vždy odpovídá stylistickým preferencím lidí a to je v pořádku. Pokud je výstup správný, udržovatelný a srozumitelný pro budoucí spuštění agenta, splňuje požadavky.

Lidský vkus je průběžně do systému přidáván. Připomínky k revizím, požadavky na refaktorizaci a chyby zaměřené na uživatele jsou zachyceny jako aktualizace dokumentace nebo zakódovány přímo do nástrojů. Pokud dokumentace nestačí, přesuneme pravidlo do kódu

S rostoucím výkonem nástroje Codex se mnohé konvenční technické normy staly kontraproduktivními.

Úložiště pracuje s minimálním blokováním slučovacích bran. Pull requesty jsou krátkodobé. Testy s nejasným výsledkem se často řeší opakovaným spuštěním, místo aby se postup blokoval na neurčito. V systému, kde je výkon agentů mnohem vyšší než pozornost lidí, jsou opravy levné a čekání drahé.

V prostředí s nízkým výkonem by to bylo nezodpovědné. Tady je to často ten správný kompromis.

Když říkáme, že kódová základna je generována agenty Codex, myslíme tím úplně všechno v kódové základně.

Agenti produkují:

• Kód produktu a testy
• Konfiguraci CI a nástroje pro vydání
• Interní nástroje pro vývojáře
• Historii dokumentace a návrhu
• Hodnoticí harnessy
• Komentáře a odpovědi na revize
• Skripty, které spravují úložiště samotné
• Definiční soubory produkčního řídicího panelu

Lidé zůstávají stále v obraze, ale pracují na jiné úrovni abstrakce než dříve. Stanovujeme priority, převádíme zpětnou vazbu od uživatelů na kritéria přijatelnosti a ověřujeme výsledky. Když má agent potíže, považujeme to za signál: zjistíme, co chybí – nástroje, mantinely, dokumentace – a vrátíme to zpět do úložiště, vždy tak, že Codex sám napíše opravu.

Agenti používají přímo naše standardní vývojové nástroje. Stahují zpětnou vazbu, reagují na ni přímo, posílají aktualizace a často také spojují a slučují své vlastní pull requesty.

Jak se do systému přímo zakódovalo více částí vývojového cyklu – testování, validace, kontrola, zpracování zpětné vazby a oprava – úložiště nedávno překročilo významný práh, kdy Codex dokáže od začátku do konce zařídit novou funkci.

Na základě jediného prompty teď agent dokáže:

• Ověřit současný stav kódové základny
• Reprodukovat nahlášenou chybu
• Nahrát video ukazující chybu
• Implementovat opravu
• Ověřit opravu spuštěním aplikace
• Nahrát druhé video ukazující řešení
• Otevřít pull request
• Reagovat na zpětnou vazbu od agenta a lidí
• Zjistit a opravit chyby sestavení
• Eskalovat na člověka jen tehdy, když je potřeba jeho úsudek
• Sloučit změnu

Toto chování do značné míry závisí na konkrétní struktuře a nástrojích tohoto úložiště a nemělo by se předpokládat, že lze bez podobných investic zobecnit – alespoň zatím ne.

Plná autonomie agenta také přináší nové problémy. Codex replikuje vzory, které už v úložišti existují – i ty nerovnoměrné nebo neoptimální. Časem to nevyhnutelně vede k posunu.

Zpočátku lidé tento problém řešili ručně. Náš tým trávil každý pátek (20 % týdne) uklízením „AI slopu“. Není překvapením, že to nelze škálovat.

Místo toho jsme začali kódovat to, čemu říkáme „zlaté principy“, přímo do úložiště a vytvořili jsme opakovaný proces čištění. Tyto zásady jsou zaměřená mechanická pravidla, která udržují kódovou základnu srozumitelnou a konzistentní pro budoucí běhy agenta. Například: (1) dáváme přednost sdíleným balíčkům utilit před ad hoc pomocnými nástroji, abychom udrželi centralizované invarianty, a (2) nekontrolujeme data ve „stylu YOLO“ – ověřujeme hranice nebo se spoléháme na typované sadě SDK, aby agent nemohl omylem stavět na odhadech. V pravidelných intervalech máme sadu úkolů Codex na pozadí, které vyhledávají odchylky, aktualizují známky kvality a otevírají cílené pull requesty na refaktorizaci. Většinu z nich lze zkontrolovat za méně než minutu a automatizovat.

Funguje to jako čištění. S technickým dluhem je to jako s půjčkou na vysoký úrok: téměř vždy je lepší ho splácet průběžně po malých krocích, než ho nechat narůstat a řešit ho v bolestivých záchvěvech činnosti. Lidský vkus je zachycen jednou a poté je průběžně vynucován na každém řádku kódu. To nám také umožňuje každý den zachytit a vyřešit špatné vzory, místo abychom je nechali šířit v kódové základně několik dní nebo týdnů.

Tato strategie se zatím osvědčila až do interního spuštění a zavedení ve společnosti OpenAI. Vytvoření skutečného produktu pro skutečné uživatele nám pomohlo ukotvit naše investice v realitě a nasměrovat nás k dlouhodobé udržovatelnosti.

Zatím nevíme, jak se v průběhu let vyvíjí architektonická koherence v systému plně generovaném agenty. Stále se učíme, kde má lidský úsudek největší vliv a jak tento úsudek zakódovat, aby vedl k přidané hodnotě. Také nevíme, jak se bude tento systém vyvíjet, protože modely se postupem času stále zdokonalují.

Co je jasné: vývoj softwaru stále vyžaduje disciplínu, ale ta se projevuje spíše v konstrukci než v samotném kódu. Stále důležitější jsou nástroje, abstrakce a zpětnovazební smyčky, které udržují kódovou základnu koherentní.

Naše nejtěžší úkoly se nyní soustředí na návrh prostředí, zpětnovazebních smyček a řídicích systémů, které agentům pomohou dosáhnout našeho cíle: vytvořit a udržovat komplexní a spolehlivý software v širokém měřítku.

S tím, jak budou agenti jako Codex přebírat větší část životního cyklu softwaru, budou tyto otázky ještě důležitější. Doufáme, že vám sdílení některých prvních zkušeností pomůže uvážit, kam investovat své úsilí, abyste mohli prostě budovat.