Zadání pro agenta: jak z nápadu udělat úkol

Dva požadavky na agenta, jeden po druhém. První: "postav stránku podle zadání ze souboru SPEC_LANDING.md". Za pár minut se ve složce objeví index.html a vypadá přesně tak, jak měl. Druhý, ještě ten večer: "postav hru 2048". A agent teď buď položí pět otázek za sebou, nebo potichu postaví pole 5×5 s tlačítkem pro vrácení tahu, o které nikdo nežádal.

Rozdíl není v agentovi. Rozdíl je v tom, co dostal na vstupu. V tomhle článku si rozebereme, z čeho se skládá zadání pro malý úkol, kde vzít obsah, který do něj zapíšete, co dělat, když znáte jen směr, a proč po "hotovo" kontrolujete výsledek podle stejných řádků, které jste napsali před začátkem.

1. Nápad ještě není úkol

"Chci 2048". "Udělej hezkou stránku". "Udělej novou hru, nějakou zajímavější". To všechno jsou nápady a mají jednu společnou potíž: v hlavě máte celý obrázek, ale v textu jsou dvě slova. Agent vidí jen text.

S prázdným místem v požadavku má agent dvě možnosti. První je zeptat se. Druhá je doplnit ho sám: zvolit velikost pole, vymyslet pravidlo, přidat tlačítko. Druhá cesta je tišší, a proto nebezpečnější. nevšimnete si, že za vás někdo rozhodl, dokud neuvidíte výsledek. Každé nevyplněné místo v požadavku je rozhodnutí, které někdo přijme, a ve výchozím stavu to nebudete vy.

"Každý ví, jak se hraje 2048" - to je ve vaší hlavě. Agent tohle "každý ví" nepřečte. Jaké pole? Odkud se berou nové dlaždice a kdy? Které se slučují a v co? Kdy je výhra, kdy konec? Pro vás je to jedno slovo, pro něj prázdné místo, dokud se nerozloží na pravidla. V chatu to vypadá takhle:

Vy:    postav hru 2048
Agent: Než začnu, upřesním pár věcí:
       1. Jaké pole, 4×4?
       2. Co se počítá jako výhra?
       3. Má jít vrátit tah?

To je ten dobrý výsledek. Na stejný požadavek ale může přijít i jiný:

Vy:    postav hru 2048
Agent: Hotovo. Hra je v souboru index.html:
       - pole 5×5
       - tlačítko pro vrácení posledního tahu
       - tabulka rekordů v localStorage

To není chyba agenta. To jsou tři vaše prázdná místa, která se zaplnila bez vás.

Takhle vypadá cesta od nápadu k výsledku, kterému se dá věřit. Článek po ní jde zleva doprava. A poslední krok vede zpátky ke třetímu: zkontrolovali jste, našli díru, dopsali řádek do zadání a dali ho agentovi znovu.

2. Odkud se bere obsah

Kostru stránky nebo hry agent postaví za pár minut a to opravdu není ta nejtěžší část. Těžké je vědět, co má na stránce být a co to vlastně hrajeme. To v kódu není. Je to v hlavách lidí, někdy i ve vaší vlastní, a něco ví i agent. Získává se to otázkami a zdroje jsou tři: lidé, vy sami, agent.

Lidé, to je ten, kdo si věc objednal, a ten, kdo ji bude používat. Otázky jim je lepší posílat najednou. Seznam pěti nebo šesti bodů naráz, ne po jedné otázce denně. Vypadá to dotěrně, já vím. Ve skutečnosti to všem ušetří týden psaní sem a tam.

Když jste zadavatelem vy sami (vlastní hra, vlastní stránka), ptáte se sami sebe a tady je největší pokušení odpovědět "no to je přece jasné". Jasné věci se zapisují stejně jako ty nejasné. "Pole 4×4" jsou dvě vteřiny psaní a agentovi to uzavře celou jednu odbočku.

Třetím zdrojem je agent a tady je past, o které je dobré vědět předem: nemůžete se zeptat na to, o čem nevíte. Počítá se jako tah i pohyb, který nic neposunul? Je potřeba swipe na telefonu? Ukazovat skóre? Tyhle otázky člověka nenapadnou, dokud nemá hru před očima. Agent ale viděl tisíc takových her a ví, kde se obvykle zakopává. Proto je někdy užitečnější místo "postav" začít s "pojďme to probrat":

Chci postavit hru 2048 v prohlížeči. Zatím nic nepiš.
Polož mi otázky, bez kterých nemůžeš začít. Všechny najednou, v seznamu.
Já odpovím a pak dáme zadání dohromady do souboru SPEC_2048.md.

Pro takový rozhovor platí dvě pravidla, jinak nikdy neskončí. První: diskuse je u konce, když jsou vyplněné čtyři pilíře z další sekce, a jejím výsledkem je soubor, ne chat. Druhé: otázky agenta jsou možnosti, ne požadavky. Klidně se zeptá "a tabulku rekordů děláme?" a "ne" je úplně normální odpověď. I takové "ne" je řádek zadání, jen v části "neděláme".

A v každém případě - ať jste se zeptali vy, nebo agent - odpověď se zapisuje do souboru se zadáním, nezůstává jako zpráva v chatu. Jinak další požadavek začne se stejnou dírou.

Tři zdroje vlevo, jeden cíl vpravo. Přerušovaná šipka dolů je cesta, kudy odpovědi odcházejí nejčastěji: zůstaly v chatu a o deset zpráv později už je nenajdete. Šipka ve schématu je, ale soubor na jejím konci chybí.

Agenta můžete požádat i o víc: nejen ať se ptá, ale ať podle vašich odpovědí sám načrtne koncept zadání a doplní, co jste neřekli. Co pak dělat s tím, co si domyslel, najdete v sekci 4. Nejdřív ale o tom, z čeho se zadání skládá.

3. Čtyři pilíře zadání

Pro malý úkol má zadání šest až osm řádků. Stojí na čtyřech pilířích: cíl, co se má dít, co v první verzi nebude, jak to ověříme. Tady je celé, pro hru:

# Zadání: 2048

CÍL:        hra 2048 v prohlížeči, otevírá se ze souboru, bez instalace.
            HTML, CSS a JavaScript, bez sestavování

PRAVIDLA:   pole 4×4
            na začátku a po každém tahu se objeví nová dlaždice: 2 nebo 4
            šipky posunou všechny dlaždice jedním směrem, až na doraz
            dvě stejné dlaždice se při srážce sloučí do jedné se součtem
            výhra: na poli se objevila dlaždice 2048
            prohra: nejsou tahy, pole je plné, nic se nedá sloučit

NEDĚLÁME:   tabulku rekordů, animace, vrácení tahu

KONTROLA:   otevřít index.html v prohlížeči, vidět pole a startovní dlaždice
            udělat tři tahy šipkami, po každém se objeví nová dlaždice
            spojit dvě dvojky, dostat čtyřku
            dohrát do konce, vidět obrazovku prohry

Dál projdeme jeden pilíř po druhém a každý ukážeme na dvou úkolech: na hře a na stránce s pozvánkou na setkání klubu deskových her.

Cíl

První řádek. Když ho člověk přečte, má si představit výsledek, ne kód. "Hra 2048 v prohlížeči, otevírá se ze souboru, bez instalace". "Stránka s pozvánkou na setkání klubu: člověk pochopí, o jaké setkání jde, a přihlásí se tlačítkem".

Test cíle: pokud při jeho čtení vidíte kód, a ne to, co uvidí člověk, už to cíl není. "Napsat funkci pro slučování dlaždic" není cíl, to je kus práce.

Sem patří i jeden řádek o tom, "v čem to stavíme": HTML, CSS a JavaScript, bez sestavování. Bez toho řádku si agent vybere sám a není jisté, že vybere něco, co umíte spustit.

A "udělej to hezky" cílem být nemůže. Není jasné, komu se to má líbit a kde se to dá uvidět.

Co se má dít

Nejdelší pilíř a pro hru je už napsaný výše. Pravidlo je jediné: řádek je dobrý, když se na něj po spuštění dá podívat a říct "ano", nebo "ne". "Pole 4×4" - ano, nebo ne. "Dvě stejné dlaždice se sloučí do jedné se součtem" - ano, nebo ne. "Něco zajímavějšího" - ani ano, ani ne, a takový řádek do zadání nepatří.

Jedna myšlenka na řádek. "Dlaždice se objevují a slučují" jsou dvě kontroly, takže dva řádky.

U stránky je to stejné, jen místo pravidel píšete, co na ní je: "záhlaví s názvem a datem", "tři bloky: co bude, pro koho, kde", "tlačítko Přihlásit se vede na adresu formuláře". Každou věc můžete otevřít a vidět.

Takový seznam vedle nápadu vypadá nudně. Nudné je přesně to, co chcete. nudné se dá zkontrolovat.

Co v první verzi nebude

Jediný pilíř, na který se obvykle zapomíná, a proto ten nejcennější. Prázdné místo agent zaplní sám a nejraději tím, že něco přidá. Tabulka rekordů, animace dlaždic, tlačítko pro vrácení tahu, tmavý motiv. Všechno užitečné a o nic z toho jste nežádali.

Píše se jmenovitě. Ne "nic navíc" - to není hranice, ale přání - nýbrž "neděláme: tabulku rekordů, animace, vrácení tahu". Pro stránku: "neděláme: samotný přihlašovací formulář, platby, fotogalerii". Tři položky obvykle stačí, deset stejně nikdo nenapíše.

Proč je to důležité pro vás, a ne pro agenta. Čím méně se postaví, tím méně je co kontrolovat. A tím jasnější je, odkud se vzalo to, co se rozbilo: v šesti řádcích se hledá snáz než v šesti obrazovkách. Znamení, že hranice chybí: ve vašem požadavku nebo v odpovědi agenta se začalo často objevovat slovo "rovnou".

Jak to ověříme

Každý řádek z části "co se má dít" je jedna kontrola poté, co agent řekl "hotovo". Otevřeli jste hru - pole 4×4, ano. Stiskli šipku - dlaždice se posunuly, objevila se nová, ano. Spojili dvě dvojky - čtyřka, ano. Seznam kontrol nepíšete zvlášť, ten už napsaný je.

K tomu dva až tři řádky "kontrola" přímo v zadání: co přesně udělat ručně. "Otevřít soubor v prohlížeči, udělat tři tahy, prohrát až do konce". Tyhle řádky se píšou před požadavkem, ne potom. Až bude výsledek hotový, nenápadně se přizpůsobí tomu, co vzniklo - děje se to samo od sebe a stane se to i vám.

"Hotovo" od agenta je replika, ne kontrola. Kontrola je vaše, podle vašich řádků.

Teď praxe. Vezměte požadavek "udělej hezkou stránku pro setkání klubu deskových her" a rozložte ho na čtyři pilíře, jeden až dva řádky na každý. Odpověď je hned níž, porovnejte:

# Zadání: stránka s pozvánkou

CÍL:          stránka s pozvánkou na setkání klubu deskových her:
              člověk pochopí, o jaké setkání jde, kdy a kde, a přihlásí se tlačítkem.
              jeden soubor HTML, styly uvnitř

NA STRÁNCE:   záhlaví s názvem klubu a datem setkání
              tři bloky: co bude, pro koho, kde
              tlačítko "Přihlásit se" vede na adresu formuláře

NEDĚLÁME:     samotný přihlašovací formulář, platby, fotogalerii

KONTROLA:     otevřít v prohlížeči, vidět záhlaví a tři bloky
              kliknout na tlačítko, dostat se na adresu formuláře

Všimněte si, že slovo "hezkou" se do zadání vůbec nedostalo. Nedá se ověřit. Pokud na vzhledu opravdu záleží, rozloží se na řádky stejně jako všechno ostatní: "jeden obrázek v záhlaví", "nejvýš dvě barvy", "všechno se vejde na obrazovku telefonu". To už se dá otevřít a podívat se.

Názvy bloků se v obou příkladech liší: u hry "pravidla", u stránky "na stránce". Na tom nezáleží, pojmenujte je, jak vám to vyhovuje. Důležité je, že každý má čtyři pilíře:

4. Čí je to rozhodnutí

V zadání se objevují rozhodnutí, která nikdo neodsouhlasil, a děje se to dvěma způsoby. První: dovolili jste agentovi zalepit díry "něčím rozumným", abyste měli koncept hned, a ne až po odpovědích v úterý. Druhý: rozhodli jste sami za zadavatele, protože nebylo koho nebo kdy se zeptat.

Obojí je v pořádku. V pořádku není zapomenout, že jde o předpoklad. Za týden si nikdo nevzpomene, kdo vymyslel, že tlačítko vede na e-mail, a ne na formulář, a přít se budou právě o tohle.

Pro první případ vypadá požadavek na agenta takhle:

Podle těchto odpovědí dej dohromady koncept zadání pro stránku s pozvánkou.
Kde odpovědi chybí, vymysli něco rozumného a v samostatném seznamu
vypiš, co sis vymyslel sám. Zapiš to do souboru SPEC_INVITE.md.

Seznam domyšlených věcí čtete jako první, ještě před samotným zadáním. Jsou to rozhodnutí přijatá za vás: každé buď půjde k odsouhlasení někomu, kdo se v tom vyzná, nebo zůstane v zadání s poznámkou.

Pro druhý případ poznámka přímo v souboru. Slovo "předpoklad:" před rozhodnutím nebo jen otazník na konci řádku: "tlačítko vede na e-mail klubu (?)". Až odpověď dorazí, hned je vidět, co změnit. a není třeba vzpomínat, odkud se to vzalo.

Poznámka funguje oběma směry. Agent, který dostane zadání s otazníky, se na ně obvykle zeptá jako první: je to pro něj stejný signál jako pro vás.

5. Pískoviště místo otázek

Stává se, že se čtyři pilíře prostě nechtějí napsat, ať nad tím sedíte, jak dlouho chcete. "Chci něco jako 2048, ale nevím, jestli je potřeba skóre, jestli swipe a jestli je to vůbec 4×4". To není zadání a vlastně ani nápad v obvyklém smyslu. Je to orientační bod: směr je jasný, výsledek ne. Otázky tu nepomůžou: odpovědi zatím nemáte vy ani zadavatel a varianty od agenta nemáte s čím porovnat.

V takovém případě je nejlevnější se podívat. Postavit pískoviště: tu nejjednodušší verzi, na kterou se dá podívat a osahat si ji, abyste pochopili, co vlastně chcete. S agentem to stojí deset minut a kvůli deseti minutám není škoda výsledek zahodit.

I pro pískoviště se píše zadání na čtyři pilíře, jen s jiným cílem:

# Zadání: pískoviště 2048

CÍL:        podívat se, jak se 2048 hraje v prohlížeči, a pochopit, co chci.
            HTML, CSS a JavaScript, bez sestavování

PRAVIDLA:   pole 4×4
            šipky posouvají dlaždice, stejné se slučují
            po tahu se objeví nová dlaždice

NEDĚLÁME:   všechno ostatní: výhru, prohru, skóre, swipe, vzhled

KONTROLA:   hrát pět minut a zapsat, co chybí a co je navíc

Podívejte se, co se změnilo. Cílem není hra, ale pochopení. "Neděláme" je nejdelší řádek, je v něm všechno, čím si nejste jistí. A kontrola není "funguje to?", ale "co teď vím". Pět minut hraní - a otázky, které se na začátku položit nedaly, se objeví samy: swipe není potřeba, u počítače se hraje šipkami; skóre potřeba je, bez něj je to nuda; 4×4 je málo, chce to zkusit 5×5; prohru je třeba ukázat, jinak není poznat, že hra skončila.

Tohle je výsledek pískoviště. Ne kód, ale odpovědi. Z nich se napíše skutečné zadání a podle něj se hra postaví od nuly, v čisté složce, jednou větou: "postav hru podle zadání ze souboru". Pískoviště svou práci odvedlo.

Je to stejný řetězec jako v první sekci, jen krok "Otázky" tu nahradila smyčka: když není na co se ptát, nejdřív se díváme a potom zapisujeme. Dolů, do zadání, jde jediná věc - odpovědi. Z pískoviště nevede šipka k agentovi a není to přehlédnutí: skutečnou verzi agent staví v čisté složce, od nuly. dál už všechno jde podle řetězce.

6. Zadání patří do souboru

Proč soubor, a ne konverzace. Konverzace se ztrácí: o deset zpráv později už pravidlo o slučování dlaždic nenajdete. Soubor leží ve složce projektu vedle kódu, agent si ho přečte sám, když na něj ukážete, a když ho upravíte, předáte ho znovu stejnou větou. Název může být jakýkoli: SPEC_2048.md, SPEC_LANDING.md, klidně i zadani.txt. Je to obyčejný textový soubor, žádný zvláštní formát nemá.

Předává se jednou větou. Porovnejte:

Předtím: "postav hru 2048, no víš jakou, nějakou zajímavější".

Potom: "postav hru podle zadání ze souboru SPEC_2048.md".

Druhý požadavek je kratší než první, ale informací je v něm desetkrát víc - jsou v souboru. Text zadání do chatu kopírovat nemusíte, agent si soubor otevře sám.

Co měnit v souboru a co stačí říct slovy. Vodítko je takové: změnilo se pravidlo nebo hranice - upravíte soubor a předáte ho znovu ("výhra při 2048, ne při 1024" patří do souboru). Změnila se drobnost ve vzhledu, která pravidla neovlivňuje - to jde říct slovy ("udělej tlačítko modré"). Pokud si nejste jistí, do souboru: řádek navíc je levnější než zapomenuté pravidlo.

K velikosti. Pro malý úkol je to šest až osm řádků, jako blok pro 2048 výše. Pokud se zadání na hru na jeden večer natáhlo na dvě stránky, nejspíš se do něj dostalo to, co mělo skončit v "neděláme".

A poslední věc, než soubor dáte agentovi: přečtěte si ho jednou, jako by ho psal někdo jiný. Řádek, který nejde ověřit, se najde skoro vždycky. já ho najdu pokaždé.

7. Co agent se zadáním udělá a co zůstává na vás

Shrňme si všechno dohromady: co v tomhle schématu dělá Claude Code a co zůstává na vaší straně. Po dvojicích.

Smysl zadání není v tom, aby agent pochopil. Něco postaví i ze dvou slov. Smysl je v tom, abyste sami věděli, co jste objednali, a mohli to zkontrolovat.