Harness engineering v praxi: AI agent od issue k PR

Harness engineering je kód kolem AI agenta, který rozhoduje, jakou úlohu agent vezme, kdy je práce hotová a kdo ji zkontroluje. Model jen dělá práci. AI agent, který píše kód, je levný. Drahý je agent, jehož pull requesty vaši senioři zmergují bez předělávání. Právě tenhle rozdíl zavírá harness.

Takovou smyčku pouštíme každý den na vlastních repozitářích. AI dnes píše veškerý náš kód a za to, co jde do produkce, ručí senior. Níže je, jak smyčka funguje, řádky kódu, které ji nesou, a co se nám cestou rozbilo.

Co znamená harness engineering v praxi?

Agent je model plus harness, rámec, ve kterém pracuje. Model si pronajímáte. Harness je váš: pravidla, kontext, kontroly, limity a předání člověku. Z čeho se harness skládá, je v článku Co je harness AI agenta? Agent = model + rámec. Tenhle článek je praxe: jedna smyčka, která běží každý den.

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

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

Plynou z něj tři věci:

• Práci vybírá kód. Bash dispečer čte GitHub issues přidělené agentovi, seřazené podle labelu priority. O startu nerozhoduje žádný model.
• Nejdřív strojová kontrola. Typecheck, lint, testy a naše brána běží dřív, než má model jakýkoli názor.
• Kdo práci dělal, ten ji nehodnotí. Výsledek posuzuje nové volání modelu, které smí jen číst.

Co dělá vývojář, když kód píše agent?

U nás to začalo menší úlohou, kterou agent dotáhl až po merge. Tehdy jsme se zamysleli, co vlastně vývojář dnes dělá.

Kód už nepíšeme. Staráme se o to, aby výsledek opravdu fungoval. A řešíme větší problémy, s odstupem, ne řádek po řádku.

V praxi jsou to čtyři kroky:

Jak naše smyčka dotáhne issue do PR?

Jedno issue na běh: jeden git worktree, jedna větev, jedna Claude Code session, jeden pull request.

1. READY. Volání modelu jen pro čtení ověří issue proti kódu ještě před startem. Platí jeho předpoklad, se souborem a řádkem? Jaký je to typ úlohy? Co dokáže, že je hotovo: test, nebo jen člověk, který se podívá? Pokud chybí rozhodnutí, agent se zeptá v issue a zastaví.
2. BUILD. Claude Code session na pozadí dělá práci ve vlastním worktree. U kódu nejdřív napíše jeden test, který na nezměněném kódu selže, a teprve potom implementuje.
3. VERIFY. Dvě vrstvy. Nejdřív gate.sh, obyčejný bash s exit kódy. Potom nový recenzent, jehož jediným úkolem je práci vyvrátit. Jeho zjištění jdou zpět do stejné BUILD session.
4. CI. CI repozitáře musí projít na pushnutém commitu. Kontrola, která padá i na hlavní větvi, se hlásí jako existující chyba, ne jako vina větve.
5. HANDOFF. PR je označený jako připravený, člověk je vyžádaný jako recenzent a komentář nese důkazy.

Východy jsou jen dva: review (hotovo, s důkazy) nebo blocked (otázka na GitHubu). Když člověk odpoví a odstraní blocked, pokračuje stejná session s celým kontextem.

Které řádky kódu smyčku nesou?

Většinu práce dělají tři krátké kousky.

Každé volání modelu vrací typovanou JSON odpověď. Žádná odpověď znamená selhání, nikdy výchozí hodnotu. Zkráceně:

# 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" ]
}

Červenou strojovou kontrolu nikdo nepřemluví na zelenou:

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

A smyčka, která se nehýbe dopředu, se zastaví. Když recenzent nahlásí stejné zjištění dvakrát po sobě, úloha jde člověku i s tím zjištěním. Další kolo by ho neopravilo.

Ještě jeden detail: nedůvěryhodný text dostane plot. Text issue a komentáře v PR přijdou modelu označené jako data, ne pokyny, a HTML komentáře se nejdřív odstraní. Právě tam se vložené pokyny rády schovávají.

Proč agentovi nestačí pravidla v textu?

Ještě nedávno měl agent pravidla jen v rules souborech. Někdy je nedodržel. Tak jsme z nich udělali kontroly, které nejde obejít: ESLint, testy architektury, kontrola typů před pushem a všechno znovu v CI.

Každá další brána zužuje cestu: testy architektury, kontrola, jestli je kód úplný, povinné soubory. Čím víc bran, tím míň má agent kam uhnout. Zbude mu jen povolená cesta.

Má to i vedlejší efekt:

Kde do toho vstupuje člověk?

Ve třech momentech a nikde jinde:

Úzké hrdlo je review, ne agent. Proto dispečer nespustí novou úlohu, dokud na lidi čekají PR od agenta. Rozběhnutá úloha může pokračovat. Merge, push do main, odesílání a nasazení jsou zablokované pod agentem, v hoocích, které nemůže upravit.

Co se nám cestou rozbilo?

Víc, než jsme čekali. Tohle stojí za to znát:

• Dispečer potichu přestal spouštět úlohy. Změna limitu pro review dala počítání mezi jq | a while read. Smyčka pak četla prázdný vstup a nespustila se žádná úloha. Nic neselhalo, nic neupozornilo. Našel to audit. Oprava přišla s testem dispečera nad podvrženým gh, červeným na starém kódu a zeleným na novém.
• Infrastruktura padala na člověka jako blocked. Session, která skončila v prvních minutách, byl chybějící login nebo token, ne špatná práce. Dnes se při dalším běhu zkusí znovu.
• CI, které nedoběhlo, se počítalo jako zelené. Dnes je to vrácení člověku. Nedoběhnuté není prošlé.
• Kontrola připravenosti přišla pozdě. Ověření předpokladu proti kódu jsme přidali až později. Dnes je to první krok a tam bychom začali.

Nejtěžší bývá poslední krok: ověřit, že to opravdu funguje od začátku do konce. Brány a skutečné testy. Nejvíc práce dá udržet prostředí sladěná, aby kontroly běžely vždy. Osvědčil se nám jeden trik: agenta pošleme do funkce jako typ zákazníka, personu, ať ji sám prozkoumá.

Před touhle smyčkou jsme zkusili dvě jiné podoby. Jedna byla pipeline z GitHub Actions workflowů řízená labely. Druhá byly jednorázové zmínky @claude v issues. Obě jsme smazali. Bezstavové CI joby se nehodí, když pracovník potřebuje pokračovat v session a uprostřed úlohy se zeptat člověka.

Kde nesouhlasíme s tím, jak se o harness engineeringu píše?

Většina textů řeší nástroje. Podle nás rozhoduje, kde v procesu stojí člověk.

Dá se to pustit i ve vašem týmu?

Začněte kontrolami kvality. Pokud je tým nemá, začněte tam. Naše smyčka READY → BUILD → VERIFY → CI → HANDOFF je jednoduchá a funguje. Každý systém ale potřebuje trochu jinou.

Samotná smyčka je vázaná na naše prostředí. To nejdůležitější z ní ne. Zveřejnili jsme to jako malý veřejný repozitář: Claude Code production starter. Má pravidla pro agenta, hooky, které zastaví nebezpečné příkazy, Stop hook, který nepustí „hotovo“, dokud jsou kontroly červené, a CI bránu s red-proof testy. Licence MIT. Naklonujte si ho, nechte si nástroje a aplikaci vyměňte.

Co z toho už váš tým má?

Co patří do pravidel, která takový harness krmí, rozebíráme v článku Pravidla pro AI kód v týmu. Kdy týmu stačí plánovací režim agenta, rozebíráme v článku Claude Code plan mode.

Chcete takový harness ve svém repozitáři?

Takovou smyčku stavíme přímo v repozitáři týmu v rámci služby AI-native SDLC pro vývojové týmy. Chybí vašemu týmu spíš ruce než pravidla? Podívejte se na seniorního vývojáře do týmu. Od roku 2023 jsme dodali 15+ produkčních projektů. Senior se připojí do vašeho repozitáře a pull requestů hned první den.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Co dnes dělá váš agent, když si není jistý: ptá se, nebo hádá?

Časté otázky

Co znamená harness engineering v praxi?

Stavba kódu kolem AI agenta: jakou úlohu vezme, jaké nástroje a pravidla dostane, co zkontroluje jeho práci a kdy přebírá člověk. Práci dělá model. Kdy je práce hotová, rozhoduje harness.

Co je agent harness?

Pevná smyčka, ve které AI agent běží. Naše je bash dispečer a runner. Čte GitHub issues, pro každé spustí jednu Claude Code session, pustí spustitelné kontroly a nového recenzenta a PR předá člověku.

Proč nenechat jednu dlouhou session agenta rozhodnout, kdy je hotovo?

Protože agent, který práci dělal, ji hodnotí příliš mírně. V naší smyčce o konci rozhoduje kód: nejdřív exit kódy, potom recenzent, který kód nepsal a nemůže ho měnit.

Merguje agent své pull requesty sám?

Ne. Merguje jen člověk. Merge, push do hlavní větve, odesílání a nasazení blokují hooky pod agentem, které agent nemůže změnit.

Potřebuji na začátek celé vaše nastavení?

Ne. Začněte veřejným Claude Code production starterem: pravidla pro agenta, hooky, Stop hook a CI brána s red-proof testy. Smyčku přidejte, až vám jedna session na úlohu přestane stačit.