AI není jasnovidec. Potřebuje pořádný brief.
Proč nestačí "letět od boku"
Představ si to: máš v hlavě jasnou představu o nové funkci. Otevřeš svůj oblíbený AI coding agent, napíšeš rychlý požadavek a sleduješ, jak se s jistotou pustí do přepisování poloviny tvého kódu. O hodinu později zíráś na PR, který řeší problém, který jsi vlastně nechtěl řešit – a způsobem, který rozbíjí věci, které jsi rozbít neplánoval.
Nezní ti to povědomě? Nejsi sám. AI coding agenty se posunuly od jednoduchého odpovídání na otázky k aktivnímu editování kódu. A ukazuje se, že stejný ležérní přístup k promptům, který funguje u chatbota, najednou nestačí.
Řešení ale není v detailnějších prompteche. Jde o úplně jiný způsob myšlení o tom, jaké dokumenty těmto agentům vůbec posíláme.
Prompt versus specifikace – v čem je rozdíl
Prompty jsou skvělé pro rychlé vysvětlení, dočasné skripty nebo experimentální konverzace. Žijí v chatovací session, můžou používat zkratky a často předpokládají kontext, který zná jen autor.
To je v pohodě, když jen pokládáš otázky.
Ale když má AI agent editovat sdílený kód, spouštět terminálové příkazy a vytvářet větve, které si prohlédnou kolegové? Tvůj improvizovaný prompt se najednou stává zadáním. A zadání potřebujou víc než jen pěkně formulovanou větu. Potřebujou správný kontext, jasné hranice, konkrétní příklady a kritéria pro ověření výsledků.
Tady přichází na řadu specifikace.
Specifikace není vychytanější prompt. Je to strukturovaný dokument, který zachytává, jaký problém řešíš, jaké chování se má změnit, co má zůstat stejné, a jak poznáš, že je práce hotová. Narozdíl od promptu, který zmizí ve chvíli, kdy agent začne pracovat, specifikace zůstává viditelná po celou dobu workflow. Pomáhá agentovi, informuje revidující a usnadňuje budoucím maintainerům pochopit, proč byly rozhodnutí udělány zrovna takhle.
Co by nemělo chybět v dobré specifikaci pro AI agenta
Nemusíš psát dvacetistránkový dokument. Stačí pět klíčových prvků:
1. Kontext: Proč se tento úkol vůbec děje? Jaký problém uživatelů nebo technický dluh ho驱动uje? Jaká omezení v kódu by měl agent znát?
2. Chování k změně: Jakou konkrétní funkcionalitu měnit, přidat nebo odebrat? Buď konkrétní – "uživatelé dostanou email, když se stane X" je lepší než "vylepši notifikační systém."
3. Omezení k zachování: Co se absolutně nesmí změnit? Jaké existující funkce, API kontrakty nebo výkonnostní charakteristiky musí zůstat nedotčené?
4. Příklady správného řešení: Konkrétní scénáře ukazující, jak má výsledek vypadat. Formát Given/When/Then se osvědčil, ale i pár explicitních test casů pomůže agentovi pochopit tvá očekávání.
5. Validační kritéria: Jak revidující pozná, že je práce hotová? Co má kontrolovat? Na co se ptát?
Tahle struktura ti možná připomíná BDD scénáře, issue šablony s acceptance kritérii nebo design dokumenty. Konkrétní formát není tak důležitý jako to, že máš správné informace ve sdíletelném a revidovatelném formátu.
Kde specifikace žijí ve tvém workflow
Jedna z nejlepších věcí na specifikacích je jejich flexibilita. Nemusí to být oddělené dokumenty, které tě zpomalují. Specifikace může žít kdekoliv, co dává smysl pro tvůj tým:
- GitHub issue s explicitními acceptance kritérii
- PR description, která pojmenovává měněné chování
- BDD scénář ve tvých feature souborech
- Lehký design note před implementací
- Nástroje jako OpenSpec nebo GitHub Spec Kit, které tento pattern formalizují
Klíčové je, aby kontext a revizní kritéria byly viditelné a perzistentní. Tvá specifikace by neměla zmizet, když skončí chat session. Měla by cestovat s prací a dát kolegům něco konkrétního k hodnocení.
Vrstva zadání: oddělení záměru od provedení
Tady to začíná být opravdu zajímavé.
Nejsilnější specifikace fungují jako malé behaviorální kontrakty. Oddělují tři různé otázky:
- Jaké chování se má změnit? (Požadavek)
- Jaká omezení nebo příklady definují správné řešení? (Acceptance kritéria)
- Jaká implementační cesta se teď jeví jako vhodná? (Technický přístup)
Tyto otázky spolu souvisí, ale neměly by se slít v jednu změť instrukcí.
Proč je to důležité pro AI coding agenty? Když smícháš záměr a implementaci příliš brzy, agent může optimalizovat pro špatnou věc. Může věrně následovat navrhovaný implementační detail, ale přitom minout skutečné chování, které jsi potřeboval. Nebo může vyprodukovat kód, který je technicky zajímavý, ale neřeší deklarovaný problém.
Vrstva zadání drží požadavek stabilní, zatímco umožňuje implementaci evolvovat. Když agent čte kód, objevuje komplikace a upřesňuje svůj přístup, specifikace zůstává měřítkem: "Splnila práce toto?"
To je obzvlášť cenné pro existující codebases. Většina inženýrské práce není greenfield – měníš chování, které už existuje. Dobrá specifikace říká: tady je současné chování, a tady je to, co se má změnit. Revidující nemusí mentálně rekonstruovat tvůj záměr z implementačních detailů.
Jak na tu změnu přejít
Pokud jsi zvyklý používat AI coding agenty jako překotné vyhledávače, může ti to připadat jako zbytečné komplikace. Ale zamysli se nad alternativou: nekontrolované změny sdíleného kódu, PR, které se špatně revidujou, a práce, která úplně neodpovídá tomu, cos měl v hlavě.
Přechod na specifikace řízenou spolupráci s AI není o byrokracii. Je to o tom dát lidem i strojům jasnost, kterou potřebujou k efektivní spolupráci.
Začni malé. Příště, než pošleš AI coding agenta do repository, zastav se na pět minut a napiš kontext, chování k změně a kritéria úspěchu. Dej to někam na viditelné místo – klidně rovnou do PR description.
Tvá budoucí já a tvoji kolegové ti poděkujou.
Závěrem: AI coding agenty jsou mocní spolupracovníci. Ber je jako spolupracovníky. Dej jim pořádnej brief a dostaneš práci, která stojí za revizi.