Spec-driven development s AI agenty: naše zadání v issue

Spec-driven development znamená, že dřív než AI agent napíše první řádek kódu, sepíšete, co postavit a podle čeho poznáte, že je hotovo. GitHub Spec Kit to shrnuje takto: „Define what to build and why, then turn the specification into a plan, tasks, and working code.“ Tedy: definujte, co a proč, a ze specifikace udělejte plán, úlohy a funkční kód. My používáme lehčí verzi: specifikace je GitHub issue s typem úlohy a kritérii přijetí a strojová brána ověří, že slíbený výstup existuje.

Dnes za nás píše AI veškerý kód. Naše práce se proto přesunula do specifikace a kontrol kolem ní. Níže je naše zadání v issue, kód, který ho čte, a co jsme se naučili, když byla specifikace špatně.

Co je spec-driven development s AI agenty?

Myšlenka je stará: před stavbou se domluvit, co znamená hotovo. U AI agentů na tom záleží víc, protože agent něco postaví tak jako tak. Bez specifikace vyplní mezery odhady a ty odhady vypadají hotově.

Spec Kit to pouští jako příkazy v chatu s agentem: zásady projektu, specifikace, plán, úlohy, implementace. Jiné nástroje to mají po svém. Jedno mají společné. Specifikace je před kódem a zůstává měřítkem při review.

Kam patří context engineering: kontext je všechno, co agent vidí, od souborů s pravidly po výstupy nástrojů. Specifikace je ta část kontextu, která říká, co znamená hotovo. Víc kontextu bez ní přinese jen sebevědomější špatný výsledek.

Proč GitHub issue místo dlouhého dokumentu?

Naše issues jsou fronta, kterou lidé čtou každé ráno. Pravidlo pro ně začíná třemi slovy: „Queue items, not specs.“ Položky ve frontě, ne specifikace. Dlouhá specifikace jde do propojeného dokumentu. Issue je to, co jeden člověk nebo jeden agent vezme a dotáhne.

Méně a větších issues sedí i agentům. Naše pravidlo: jeden hotový výsledek na issue a na pull request. I velký výsledek je jeden PR, s jedním commitem na vrstvu, aby ho člověk četl v pořadí, v jakém vznikal.

Co obsahuje naše zadání v issue?

Povinné jsou tři věci: název se slovesem a konkrétním objektem, jeden štítek priority a co je potřeba udělat. U jednoduché práce stačí samotný název. Sekce jako ## What, ## Acceptance a ## Output se objeví, jen když nesou obsah. Prázdné ## Acceptance: TBD je zakázané.

Typ úlohy určuje, co musí na konci existovat:

Na typ nikdo nedává štítek. Kdo issue vezme, odvodí si ho. Chybějící ## Output nebo ## Acceptance doplní jako vyslovený předpoklad, nikdy potichu.

Jak stroj kontroluje specifikaci?

Dvakrát: před prací a po ní.

Před prací: READY. Volání modelu, které jen čte, projde issue i kód a vrátí odpověď s pevnou strukturou. Zkráceno z našeho schématu:

{
  "ready": true,
  "type": "code",
  "done_when": ["criteria a reviewer can answer yes or no"],
  "verifiable": "test",
  "confirmation": ["the test that carries the proof"],
  "premise": "verified against <file:line>",
  "question": ""
}

Nejvíc času nám ušetří premise. Kontrola porovná s kódem každé tvrzení, které issue říká o dnešním chování, i se souborem a řádkem. Když z issue už nic neplatí, navrhne ho zavřít. verifiable říká, jestli nejrizikovější kritérium dokáže test, nebo jen člověk, který se podívá. Když chybí produktové rozhodnutí, question položí jednu otázku se dvěma možnostmi a doporučením a práce nezačne.

Po práci: brána. Obyčejný bash s exit kódy, jedna větev na typ úlohy. U kódu spustí vlastní typecheck, lint, testy a build repozitáře a k tomu red-proof: změněný zdrojový kód potřebuje změněný test a ten test musí na základní větvi selhat. U rešerše otevře každou URL zdroje a hledá na stránce citaci. Parafráze neprojde. Tuhle část nikdy nehodnotí model.

Co se změnilo, když jsme přestali úlohy odhadovat velikostí?

Kdysi jsme úlohy bodovali podle velikosti a podle toho je směrovali. Nahradili jsme to připraveností: je předpoklad ověřený vůči kódu, je pojmenovaný důkaz, zbývá něco k rozhodnutí?

Brány jsou druhá polovina specifikace. Issue říká, co znamená hotovo. Kontroly zajistí, že nikdo, člověk ani agent, to nevyhlásí jinak.

Co se nám u specifikací rozbilo?

• Kontrola připravenosti přišla pozdě. Nejdřív agent vzal issue tak, jak bylo napsané. Kontrolu předpokladu vůči kódu jsme přidali až později. Dnes je to první fáze a tam bychom začali.
• Špatný komentář není špatné issue. Starý plán v komentáři způsobil, že kontrola vyvracela dobrá issues. Dnes se počítá jen tvrzení v těle issue. Vyvrácené tělo jde k člověku, který odpoví OK dřív, než práce začne.
• Zelená brána, která nic nedokázala. V jednom monorepu red-proof spouštěl testy bez správného prostředí. Každé „selže na základní větvi“ byl test, který se vůbec nespustil, ne skutečná červená. Pár dní tam každý red-proof prošel falešně. Dnes testy běží přes správce balíčků repozitáře, po balíčcích, na zafixované verzi Node.

Poslední bod opakujeme nejčastěji: kontrola, která nemůže selhat, není kontrola. Víc v článku Red-green TDD s AI agentem: test musí nejdřív selhat.

Jak napsat issue, které agent dotáhne?

Poslední krok týmy vynechávají. Přitom je nejlevnější: jedno volání modelu, které jen čte, dřív než existuje první řádek kódu.

Jak vypadá zbytek výbavy agenta, od pravidel po hooky, je v článku Co je harness AI agenta? Agent = model + rámec. Kdy místo specifikace stačí vestavěný plánovací režim, rozebíráme v článku Claude Code plan mode.

Je vaše issue připravené pro agenta?

Chcete smyčku od specifikace k PR ve svém týmu?

Takové zadání a kontroly za ním stavíme přímo v repozitáři týmu v rámci služby AI-native SDLC pro vývojové týmy. Chybí vám spíš ruce než proces? Podívejte se na seniorního vývojáře do týmu. Od roku 2023 jsme dodali 15+ produkčních projektů.

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 znamenalo „hotovo“ v posledním issue vašeho týmu a kdo to ověřil?

Časté otázky

Co je spec-driven development?

Dřív než někdo napíše kód, sepíšete, co postavit, proč a podle čeho poznáte, že je hotovo. Z toho vznikne plán, úlohy a kód. U AI agentů je specifikace zároveň kontext, ze kterého agent pracuje.

Potřebuji dlouhý dokument se specifikací?

Ne. Na většinu práce nám stačí GitHub issue: název, typ úlohy, kritéria přijetí a kam půjde výstup. Dlouhá specifikace patří do propojeného dokumentu, ne do issue.

Jaký je rozdíl mezi spec-driven development a context engineeringem?

Context engineering je všechno, co agent vidí: pravidla, soubory, nástroje, historii. Specifikace je ta část, která říká, co znamená hotovo. Bez ní víc kontextu přinese jen sebevědomější špatný výsledek.

Jak ověříte, že agent specifikaci splnil?

Kódem, ne názorem. Před prací kontrola, která jen čte, porovná issue s kódem. Po práci brána ověří, že slíbený výstup existuje: PR s testem, který před změnou selže a po ní projde, zdroje s doslovnými citacemi, QA report.

Kdy se specifikace nevyplatí?

U opravy jednoho řádku je specifikací název issue. Kde výsledek umí posoudit jen člověk, třeba text nebo vizuál, specifikace to řekne a práce jde k tomu člověku.