Harness engineering v praxi: AI agent od issue po PR

Harness engineering je kód okolo AI agenta, ktorý rozhoduje, akú úlohu agent zoberie, kedy je práca hotová a kto ju skontroluje. Model iba robí prácu. AI agent, ktorý píše kód, je lacný. Drahý je agent, ktorého pull requesty vaši seniori zmergujú bez prerábania. Tento rozdiel preklenie harness.

Takú slučku púšťame každý deň na vlastných repozitároch. AI dnes píše všetok náš kód a za to, čo ide do produkcie, ručí senior. Nižšie je, ako slučka funguje, riadky kódu, ktoré ju nesú, a čo sa nám cestou pokazilo.

Čo znamená harness engineering v praxi?

Agent je model plus harness, rámec, v ktorom pracuje. Model si prenajímate. Harness je váš: pravidlá, kontext, kontroly, limity a odovzdanie človeku. Z čoho sa harness skladá, je v článku Čo je harness AI agenta? Agent = model + rámec. Tento článok je prax: jedna slučka, ktorá beží každý deň.

Jediné pravidlo návrhu máme na začiatku skriptu dispečera:

# Deterministic on purpose: code decides WHAT to take and WHEN it is done, models only do the work.

Vyplývajú z neho tri veci:

• Prácu vyberá kód. Bash dispečer číta GitHub issues pridelené agentovi, zoradené podľa labelu priority. O štarte nerozhoduje žiadny model.
• Najprv strojová kontrola. Typecheck, lint, testy a naša brána bežia skôr, než má model akýkoľvek názor.
• Kto prácu robil, ten ju nehodnotí. Výsledok posudzuje nové volanie modelu, ktoré smie iba čítať.

Čo robí vývojár, keď kód píše agent?

U nás to začalo menšou úlohou, ktorú agent dotiahol až po merge. Vtedy sme sa zamysleli, čo vlastne vývojár dnes robí.

Kód už nepíšeme. Staráme sa o to, aby výsledok naozaj fungoval. A riešime väčšie problémy, s odstupom, nie riadok po riadku.

V praxi to sú štyri kroky:

Ako naša slučka dotiahne issue do PR?

Jedno issue na beh: jeden git worktree, jedna vetva, jedna Claude Code session, jeden pull request.

1. READY. Volanie modelu iba na čítanie overí issue voči kódu ešte pred štartom. Platí jeho predpoklad, so súborom a riadkom? Aký je to typ úlohy? Čo dokáže, že je hotovo: test, alebo iba človek, ktorý sa pozrie? Ak chýba rozhodnutie, agent sa opýta v issue a zastaví.
2. BUILD. Claude Code session na pozadí robí prácu vo vlastnom worktree. Pri kóde najprv napíše jeden test, ktorý na nezmenenom kóde padne, a až potom implementuje.
3. VERIFY. Dve vrstvy. Najprv gate.sh, obyčajný bash s exit kódmi. Potom nový recenzent, ktorého jedinou úlohou je prácu vyvrátiť. Jeho zistenia idú späť do tej istej BUILD session.
4. CI. CI repozitára musí prejsť na pushnutom commite. Kontrola, ktorá padá aj na hlavnej vetve, je hlásená ako existujúca chyba, nie vina vetvy.
5. HANDOFF. PR je označený ako pripravený, človek je vyžiadaný ako recenzent a komentár nesie dôkazy.

Východy sú iba dva: review (hotovo, s dôkazmi) alebo blocked (otázka na GitHube). Keď človek odpovie a odstráni blocked, pokračuje tá istá session s celým kontextom.

Ktoré riadky kódu slučku nesú?

Väčšinu práce robia tri krátke kúsky.

Každé volanie modelu vracia typovanú JSON odpoveď. Žiadna odpoveď znamená zlyhanie, nikdy predvolenú hodnotu. Skrátené:

# one read-only model call with a typed answer; no object back = failure, never a default
ask() {
    ( cd "$tree" && claude -p "$prompt" --tools "Read,Grep,Glob,WebFetch" \
        --json-schema "$(cat "$schema")" --output-format json ) > "$out.raw"
    jq -e 'select(.subtype == "success") | .structured_output // empty' "$out.raw" > "$out" && [ -s "$out" ]
}

Červenú strojovú kontrolu nikto neprehlási za zelenú:

verdict=$(jq -r .verdict "$R/verify-$round.json")
[ "$mrc" != 0 ] && [ "$verdict" = pass ] && verdict=fix   # a red executable check is never overruled to pass

A slučka, ktorá sa nehýbe dopredu, sa zastaví. Ak recenzent nahlási to isté zistenie dvakrát po sebe, úloha ide človeku aj s tým zistením. Ďalšie kolo by ho neopravilo.

Ešte jeden detail: nedôveryhodný text sa ohraničí. Text issue a komentáre v PR prídu modelu označené ako dáta, nie pokyny, a HTML komentáre sa najprv odstránia. Práve tam sa vložené pokyny rady schovávajú.

Prečo agentovi nestačia pravidlá v texte?

Ešte nedávno mal agent pravidlá len v rules súboroch. Niekedy ich nedodržal. Tak sme z nich spravili kontroly, ktoré sa nedajú obísť: ESLint, testy architektúry, kontrola typov pred pushom a všetko znova v CI.

Každá ďalšia brána zužuje cestu: testy architektúry, kontrola, či je kód úplný, povinné súbory. Čím viac brán, tým menej má agent kam uhnúť. Ostane mu len povolená cesta.

Má to aj vedľajší efekt:

Kde do toho vstupuje človek?

V troch momentoch a nikde inde:

Úzke hrdlo je review, nie agent. Preto dispečer nespustí novú úlohu, kým na ľudí čakajú PR od agenta. Rozbehnutá úloha môže pokračovať. Merge, push do main, odosielanie a nasadenie blokujú hooky, ktoré agent nemôže zmeniť.

Čo sa nám cestou pokazilo?

Viac, než sme čakali. Toto stojí za to poznať:

• Dispečer potichu prestal spúšťať úlohy. Zmena limitu pre review presunula počítanie do rúry medzi jq a while read, ktorá bežala v podprocese. Slučka potom čítala prázdny vstup a nespustila sa žiadna úloha. Nič nezlyhalo, nič neupozornilo. Našiel to audit. Oprava prišla s testom dispečera nad podvrhnutým gh, červeným na starom kóde a zeleným na novom.
• Výpadky infraštruktúry končili u človeka ako blocked. Keď session skončila v prvých minútach, išlo o chýbajúci login alebo token, nie o zlú prácu. Dnes sa pri ďalšom behu skúsi znova.
• CI, ktoré nedobehlo, sa rátalo ako zelené. Dnes je to vrátenie človeku. Nedobehnuté nie je prejdené.
• Kontrola pripravenosti prišla neskoro. Overenie predpokladu voči kódu sme pridali až neskôr. Dnes je to prvý krok a tam by sme začali.

Najťažší býva posledný krok: overiť, že to naozaj funguje od začiatku do konca. Brány a skutočné testy. Najviac práce dá udržať prostredia zladené, aby kontroly bežali vždy. Osvedčil sa nám jeden trik: agenta pošleme do funkcie ako typ zákazníka, personu, nech ju sám preskúma.

Pred touto slučkou sme skúsili dve iné podoby. Jedna bola pipeline z GitHub Actions workflowov riadená labelmi. Druhou boli jednorazové zmienky @claude v issues. Obe sme zmazali. Bezstavové CI joby sa nehodia, keď robotník potrebuje pokračovať v session a uprostred úlohy sa opýtať človeka.

Kde nesúhlasíme s tým, ako sa o harness engineeringu píše?

Väčšina textov rieši nástroje. Podľa nás rozhoduje, kde v procese stojí človek.

Dá sa to pustiť aj vo vašom tíme?

Začnite kontrolami kvality. Ak ich tím nemá, začnite tam. Naša slučka READY → BUILD → VERIFY → CI → HANDOFF je jednoduchá a funguje. Každý systém však potrebuje trochu inú.

Samotná slučka je viazaná na naše prostredie. To najdôležitejšie z nej nie. Zverejnili sme to ako malý verejný repozitár: Claude Code production starter. Má pravidlá pre agenta, hooky, ktoré zastavia nebezpečné príkazy, Stop hook, ktorý nepustí „hotovo“, kým sú kontroly červené, a CI bránu s red-proof testami. Licencia MIT. Naklonujte si ho, nechajte si nástroje a aplikáciu vymeňte.

Čo z toho už váš tím má?

Čo patrí do pravidiel, ktoré takýto harness kŕmia, rozoberáme v článku Pravidlá pre AI kód v tíme. Kedy tímu stačí plánovací režim agenta, rozoberáme v článku Claude Code plan mode.

Chcete takýto harness vo vašom repozitári?

Takúto slučku staviame priamo v repozitári tímu v rámci služby AI-native SDLC pre vývojové tímy. Chýbajú vášmu tímu skôr ruky než pravidlá? Pozrite si seniorského vývojára do tímu. Od roku 2023 sme dodali 15+ produkčných projektov. Senior sa pripojí do vášho repozitára a pull requestov od prvého týždňa.

Ozveme sa do dvoch pracovných dní a spolu vyberieme, čo vyriešime ako prvé.

Ak sa chcete najprv porozprávať, dohodnite si meeting na 15 minút s Filipom.

Čo dnes robí váš agent, keď si nie je istý: pýta sa, alebo háda?

Časté otázky

Čo znamená harness engineering v praxi?

Stavba kódu okolo AI agenta: akú úlohu zoberie, aké nástroje a pravidlá dostane, čo skontroluje jeho prácu a kedy prácu preberá človek. Prácu robí model. Kedy je práca hotová, rozhoduje harness.

Čo je agent harness?

Pevná slučka, v ktorej AI agent beží. Naša je bash dispečer a runner. Číta GitHub issues, pre každé spustí jednu Claude Code session, pustí spustiteľné kontroly a nového recenzenta a PR odovzdá človeku.

Prečo nenechať jednu dlhú session agenta rozhodnúť, kedy je hotovo?

Lebo agent, ktorý prácu robil, ju hodnotí príliš mierne. V našej slučke o konci rozhoduje kód: najprv exit kódy, potom recenzent, ktorý kód nepísal a nemôže ho meniť.

Merguje agent svoje pull requesty sám?

Nie. Merguje iba človek. Merge, push do hlavnej vetvy, odosielanie a nasadenie blokujú hooky pod agentom, ktoré agent nemôže zmeniť.

Potrebujem na začiatok celé vaše nastavenie?

Nie. Začnite verejným Claude Code production starterom: pravidlá pre agenta, hooky, Stop hook a CI brána s red-proof testami. Slučku pridajte, keď vám jedna session na úlohu prestane stačiť.