Spec-driven development s AI agentmi: naše zadanie v issue

Spec-driven development znamená, že skôr než AI agent napíše prvý riadok kódu, spíšete, čo postaviť a podľa čoho spoznáte, že je hotovo. GitHub Spec Kit to zhŕňa takto: „Define what to build and why, then turn the specification into a plan, tasks, and working code.“ Teda: definujte, čo a prečo, a zo špecifikácie urobte plán, úlohy a funkčný kód. My používame ľahšiu verziu: špecifikácia je GitHub issue s typom úlohy a kritériami prijatia a strojová brána overí, že sľúbený výstup existuje.

Dnes za nás píše AI všetok kód. Naša práca sa preto presunula do špecifikácie a kontrol okolo nej. Nižšie ukazujeme naše zadanie v issue, kód, ktorý ho číta, a čo sme sa naučili, keď bola špecifikácia zlá.

Čo je spec-driven development s AI agentmi?

Myšlienka je stará: pred stavbou sa dohodnúť, čo znamená hotovo. Pri AI agentoch na tom záleží viac, lebo agent niečo postaví tak či tak. Bez špecifikácie vyplní medzery odhadmi a tie odhady vyzerajú ako hotová vec.

Spec Kit to rozkladá na príkazy v chate s agentom: zásady projektu, špecifikácia, plán, úlohy, implementácia. Iné nástroje to majú po svojom. Jedno majú spoločné. Špecifikácia je pred kódom a ostáva meradlom pri review.

Kam patrí context engineering: kontext je všetko, čo agent vidí, od súborov s pravidlami po výstupy nástrojov. Špecifikácia je tá časť kontextu, ktorá hovorí, čo znamená hotovo. Viac kontextu bez nej prinesie len sebavedomejší zlý výsledok.

Prečo GitHub issue namiesto dlhého dokumentu?

Naše issues sú rad, ktorý ľudia čítajú každé ráno. Pravidlo pre ne začína tromi slovami: „Queue items, not specs.“ Položky v rade, nie špecifikácie. Dlhá špecifikácia ide do prepojeného dokumentu. Issue je to, čo jeden človek alebo jeden agent zoberie a dotiahne.

Menej, ale väčších issues vyhovuje aj agentom. Naše pravidlo: jeden hotový výsledok na issue a na pull request. Aj veľký výsledok je jeden PR, s jedným commitom na vrstvu, aby ho človek čítal v poradí, v akom vznikal.

Čo obsahuje naše zadanie v issue?

Povinné sú tri veci: názov so slovesom a konkrétnym objektom, jeden štítok priority a čo treba urobiť. Pri jednoduchej práci stačí samotný názov. Sekcie ako ## What, ## Acceptance a ## Output sa objavia, len keď nesú obsah. Prázdne ## Acceptance: TBD je zakázané.

Typ úlohy určuje, čo musí na konci existovať:

Na typ nikto nedáva štítok. Kto issue zoberie, odvodí si ho. Chýbajúce ## Output alebo ## Acceptance doplní ako vyslovený predpoklad, nikdy potichu.

Ako stroj kontroluje špecifikáciu?

Dvakrát: pred prácou a po nej.

Pred prácou: READY. Volanie modelu, ktoré len číta, prejde issue aj kód a vráti odpoveď s pevnou štruktúrou. Skrátené z našej schémy:

{
  "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": ""
}

Najviac času nám ušetrí premise. Kontrola porovná s kódom každé tvrdenie, ktoré issue hovorí o dnešnom správaní, aj so súborom a riadkom. Ak z issue už nič neplatí, navrhne ho zavrieť. verifiable hovorí, či najrizikovejšie kritérium dokáže test, alebo len človek, ktorý sa pozrie. Ak chýba produktové rozhodnutie, question položí jednu otázku s dvoma možnosťami a odporúčaním a práca sa nezačne.

Po práci: brána. Obyčajný bash s exit kódmi, jedna vetva na typ úlohy. Pri kóde spustí vlastný typecheck, lint, testy a build repozitára a k tomu red-proof: zmenený zdrojový kód potrebuje zmenený test a ten test musí na základnej vetve padať. Pri rešerši otvorí každú URL zdroja a hľadá na stránke citát. Parafráza neprejde. Túto časť nikdy nehodnotí model.

Čo sa zmenilo, keď sme prestali úlohy odhadovať podľa veľkosti?

Kedysi sme úlohy bodovali podľa veľkosti a podľa toho ich smerovali. Nahradili sme to pripravenosťou: je predpoklad overený voči kódu, je pomenovaný dôkaz, ostáva niečo na rozhodnutie?

Brány sú druhá polovica špecifikácie. Issue hovorí, čo znamená hotovo. Kontroly zabezpečia, že nikto, človek ani agent, to nevyhlási inak.

Čo sa nám pri špecifikáciách pokazilo?

• Kontrola pripravenosti prišla neskoro. Najprv agent zobral issue tak, ako bolo napísané. Kontrolu predpokladu voči kódu sme pridali až neskôr. Dnes je to prvá fáza a tam by sme začali.
• Zlý komentár nie je zlé issue. Starý plán v komentári spôsobil, že kontrola vyvracala dobré issues. Dnes sa počíta len tvrdenie v tele issue. Vyvrátené telo ide k človeku, ktorý odpovie OK skôr, než sa práca začne.
• Zelená brána, ktorá nič nedokázala. V jednom monorepe red-proof spúšťal testy bez správneho prostredia. Za každým „padá na základnej vetve“ bol test, ktorý sa vôbec nespustil, nie skutočná červená. Pár dní tam každý red-proof prešiel falošne. Dnes testy bežia cez správcu balíkov repozitára, po balíkoch, na zafixovanej verzii Node.

Posledný bod opakujeme najčastejšie: kontrola, ktorá nemôže zlyhať, nie je kontrola. Viac v článku Red-green TDD s AI agentom.

Ako napísať issue, ktoré agent dotiahne?

Posledný krok tímy vynechávajú. Pritom je najlacnejší: jedno volanie modelu, ktoré len číta, skôr než existuje prvý riadok kódu.

Ako vyzerá zvyšok výbavy agenta, od pravidiel po hooky, je v článku Čo je harness AI agenta? Agent = model + rámec. Kedy namiesto spec stačí zabudovaný plánovací režim, rozoberáme v článku Claude Code plan mode.

Je vaše issue pripravené pre agenta?

Chcete slučku od špecifikácie po PR vo svojom tíme?

Takéto zadanie a kontroly za ním staviame priamo v repozitári tímu v rámci služby AI-native SDLC pre vývojové tímy. Chýbajú vám skôr ruky než proces? Pozrite si seniorského vývojára do tímu. Od roku 2023 sme dodali 15+ produkčných projektov.

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 znamenalo „hotovo“ v poslednom issue vášho tímu a kto to overil?

Časté otázky

Čo je spec-driven development?

Skôr než niekto napíše kód, spíšete, čo postaviť, prečo a podľa čoho spoznáte, že je hotovo. Z toho vznikne plán, úlohy a kód. Pri AI agentoch je špecifikácia zároveň kontext, z ktorého agent pracuje.

Potrebujem dlhý dokument so špecifikáciou?

Nie. Na väčšinu práce nám stačí GitHub issue: názov, typ úlohy, kritériá prijatia a kam pôjde výstup. Dlhá špecifikácia patrí do prepojeného dokumentu, nie do issue.

Aký je rozdiel medzi spec-driven development a context engineeringom?

Context engineering je všetko, čo agent vidí: pravidlá, súbory, nástroje, históriu. Špecifikácia je tá časť, ktorá hovorí, čo znamená hotovo. Bez nej viac kontextu prinesie len sebavedomejší zlý výsledok.

Ako overíte, že agent špecifikáciu splnil?

Kódom, nie názorom. Pred prácou kontrola, ktorá len číta, porovná issue s kódom. Po práci brána overí, že sľúbený výstup existuje: PR s testom, ktorý pred zmenou padá a po nej prejde, zdroje s doslovnými citátmi, QA report.

Kedy sa špecifikácia neoplatí?

Pri oprave jedného riadku je špecifikáciou názov issue. Kde výsledok vie posúdiť len človek, napríklad text alebo vizuál, špecifikácia to povie a práca ide k tomu človeku.