TASK_SPEC, který lze ověřit

"Vytvoř kalkulačku, která spočítá, kolik kdo dluží v restauraci." Jasné zadání - dokud se nad ním nezačnete zamýšlet. Rozdělíme účet rovným dílem, nebo každý zaplatí za svá jídla? Je spropitné už v účtu? Co ukázat, když částka nejde rozdělit beze zbytku?

Zadání sestavíme společně s Claude Code: vysvětlíte úkol a zvolíte řešení, agent je zapíše do souboru a vy zápis zkontrolujete. Začneme stručnou žádostí a postupně vytvoříme TASK_SPEC, podle kterého lze pracovat.

"Udělej to pořádně" není zadání

Představte si, že jste chtěli rychle rozdělit účet, ale agent přidal registraci a historii restaurací. Aby mohl účtenky ukládat, potřeboval server. Počítali jste s tím, že otevřete jeden soubor v prohlížeči, a teď musíte řešit spuštění a odstraňovat zbytečnosti. Každé rozšíření samo o sobě vypadá užitečně, ale výsledek už se od vašeho záměru vzdálil.

Při práci s kódem se neúplné zadání může proměnit ve skutečné změny souborů. Vzniká takový řetězec:

Schéma ukazuje, jak opomenuté rozhodnutí přidává práci navíc. Agent se může doptat, ale lepší je odhalit nejasnosti ještě před úpravami. Už první formulace může určit směr a hranice:

Zatím nejasné:
Vytvoř kalkulačku, která spočítá, kolik kdo dluží v restauraci.

Konkrétnější:
Potřebujeme jednu stránku: zadáme celkovou částku účtu a počet lidí,
uvidíme částku pro každého. Rozdělíme ji rovným dílem.
Uživatelské účty, historii účtenek ani rozdělení podle jídel dělat nebudeme.

Druhá žádost ještě neodpovídá na všechny otázky. Už ale vylučuje několik různých produktů, které by mohly vzniknout z té první. Agent pak pomůže najít zbývající mezery a zapsat vaše rozhodnutí.

Zadání v jednom souboru

TASK_SPEC je zápis podmínek jednoho úkolu: jaký výsledek potřebujete, kde práce končí a jak ji ověříte. Obvykle se ukládá do souboru Markdown TASK_SPEC.md vedle projektu. Za tímto názvem se neskrývá žádný zvláštní formát ani speciální příkaz. Podmínky můžete poslat i jako zprávu, ale soubor se snáz čte a aktualizuje.

TASK_SPEC nemusíte psát ručně. Pohodlnější je sestavit ho s agentem a zkontrolovat, jak vaše rozhodnutí zapsal. Úkol můžete popsat vlastními slovy, odpovídat na otázky a žádat o úpravu formulací. Agent spravuje soubor a vy kontrolujete jeho smysl.

1. popíšete, jakého výsledku chcete dosáhnout, a proberete nejasná místa;
2. agent navrhne možnosti a vy vyberete tu vhodnou;
3. agent zapíše rozhodnutí do TASK_SPEC a ukáže přidanou nebo změněnou část;
4. tuto část si přečtete v souboru: smysl zůstal zachován, nepřibyly žádné podmínky navíc a zápis není v rozporu s předchozími. Pokud něco nesedí, požádáte o opravu a znovu ji zkontrolujete.

Po každém jednotlivém rozhodnutí stačí zkontrolovat dotčené řádky a související podmínky. Před implementací si přečtěte celý soubor: jednotlivé zápisy mohou vypadat správně, ale dohromady si odporovat. Zpráva "specifikaci jsem aktualizoval" ještě neukazuje, co přesně v dokumentu přibylo.

Od souboru CLAUDE.md se liší účelem. "Všechny popisky v projektu budou česky" je obecné pravidlo projektu. "V tomto úkolu přidáme výpočet spropitného" je podmínka konkrétní práce. První patří do CLAUDE.md, druhá do TASK_SPEC.

Rozsah dokumentu závisí na úkolu. Pokud stačí opravit překlep na hotové stránce, může zadání vypadat takto:

Na stránce pro dělení účtu oprav popisek tlačítka:
"Vypočíta" → "Vypočítat". Nic dalšího neměň.
Ověř, že je nový popisek vidět a tlačítko stále počítá.

Tohle je krátký TASK_SPEC, někdy se mu říká tiny spec. Téměř není co probírat. Nová kalkulačka ale nabízí několik možností chování, takže dva řádky nestačí. Je užitečné zapisovat rozhodnutí, která ovlivňují výsledek; samotný počet nadpisů nic nezaručuje.

Začneme výsledkem

Představme si, že zatím žádný projekt nemáme. Parta přátel chce otevřít stránku v prohlížeči, zadat částku na účtence a zjistit, kolik má každý zaplatit. Požádáme agenta, aby připravil návrh:

Vytvoř TASK_SPEC.md pro stránku na rozdělení účtu.
Projekt zatím neexistuje. Zadáme částku na účtence a počet lidí,
po kliknutí na "Vypočítat" uvidíme částku pro každého.
Výsledkem má být index.html, který se otevře v prohlížeči bez instalace.
Zapiš dohodnuté podmínky a neznámé označ jako otázky.
Ukaž zapsaný text. Kód stránky zatím nepiš.

Tady je ukázka první části souboru:

## KONTEXT
Parta přátel v restauraci chce rychle rozdělit společný účet.
Projekt ještě neexistuje a pracovní složka je prázdná.

## POŽADOVANÉ CHOVÁNÍ
Uživatel zadá částku na účtence a počet lidí.
Po kliknutí na "Vypočítat" uvidí částku pro každého.
Výsledkem práce bude stránka index.html,
kterou lze otevřít v prohlížeči bez instalace.

Otevřete TASK_SPEC.md v editoru a porovnejte zápis se žádostí: jsou tam obě vstupní hodnoty, akce i výsledek pro každého účastníka? Pokud agent přidal zadávání jmen nebo povinnou registraci, jde o neschválené podmínky. Požádejte ho, aby je ze souboru odstranil, a zkontrolujte opravu.

Teď víme, kdo stránku používá a co získá. Zároveň jsme určili artefakt, tedy konkrétní výsledek práce agenta: soubor stránky. U jiného úkolu by to mohl být rozbor chyby nebo plán změn bez kódu. Je lepší to říct přímo.

Všimněte si, že jsme zatím nevybírali funkce JavaScriptu ani nepředepisovali, jak ukládat účastníky. To jsou rozhodnutí o implementaci. V zadání je důležitější stanovit, co uvidí člověk: vstup, akci a výsledek.

Kde úkol končí

Teď určíme, kde končí první verze. Požádáme agenta, aby zapsal dohodnuté hranice a ukázal aktualizovanou část:

## SCOPE
Jedna stránka: zadání částky a počtu lidí,
rovné rozdělení celkové částky a zobrazení podílu každého.

## NON-GOALS
Bez uživatelských účtů a historie účtenek: data není třeba ukládat.
Bez rozdělení podle jídel: v první verzi dělíme rovným dílem.
Omezení implementace: jeden HTML soubor se styly a skriptem
uvnitř, bez serveru a externích knihoven.
Stránka se musí otevřít dvojklikem.

V této části nekontrolujeme jen to, zda jsou uvedené zákazy: rovné rozdělení musí zůstat součástí úkolu a rozdělení podle jídel mimo jeho rozsah. Pokud je agent zaměnil, opravíme dokument ještě před prací na stránce.

Scope popisuje rozsah práce. Lze ho vymezit pomocí obrazovky a scénáře, jako tady. Přesné cesty se hodí, když je znáte, ale seznamem souborů začínat nemusíte. Pokud měníte existující projekt a nevíte, kde stránku hledat, požádejte Claude Code, aby ji nejprve našel bez úprav a vysvětlil, proč vybral právě tento soubor. Pak cestu přidejte do zadání. Neznámé je v pořádku, vymyšlené ne.

Non-goals jsou věci, které jsme vědomě vyloučili. "Bez historie účtenek" vymezuje hranici lépe než "nedělej nic navíc". Stručné vysvětlení se hodí i vám: za týden bude jasné, že jsme o ukládání dat uvažovali a rozhodli se ho vynechat.

Omezení implementace odpovídají na jinou otázku: které způsoby řešení nám vyhovují. Uživatelské účty jsou zbytečná funkce, kdežto server je způsob řešení, který jsme tady vyloučili. V krátkém dokumentu lze tyto podmínky uvést v jednom bloku, jen je jasně označte jako omezení.

Hranice musí umožnit dosáhnout výsledku. Pokud později budeme potřebovat společné uživatelské účty s historií dostupnou na více zařízeních, bude nutné požadavek na "jeden lokální HTML soubor" přehodnotit. Nelze zároveň požadovat novou možnost a ponechat zákaz, který ji znemožňuje.

Haléř, na který jsme zapomněli

Zatím se vše zdá dostatečně jasné. Ověřme zadání ještě před psaním kódu: účet pro tři lidi je 1000. Kolik ukážeme každému?

333,33 + 333,33 + 333,33 = 999,99

Jeden haléř chybí. Můžeme ho přidat prvnímu účastníkovi, poslednímu nebo nechat uživatele vybrat. Věta "rozdělíme rovným dílem" to neřeší. A tohle je otázka pro vás, ne pro znalost JavaScriptu.

Pro naši stránku zvolíme toto pravidlo: podíly se liší nejvýše o haléř; zbytek se rozdělí po jednom haléři prvním účastníkům v seznamu. Pro částku 1000 a tři lidi tedy dostaneme 333,34; 333,33; 333,33. U částky 1000,01 zbývají dva haléře: 333,34; 333,34; 333,33. Rozdělili jsme všechny peníze a součet podílů odpovídá účtu.

Teď požádáme agenta, aby vybrané rozhodnutí zapsal do dokumentu:

Zapiš pravidlo zaokrouhlování do požadovaného chování v TASK_SPEC.md.
Ukaž změněné řádky. Kód zatím neměň.

Zkontrolujeme, že se v souboru objevilo toto:

Součet podílů přesně odpovídá celkové částce.
Rozdíl mezi podíly není větší než 0,01.
Zbývající haléře dostávají první účastníci, po jednom;
na stránce je vysvětlení tohoto pravidla.

Obzvlášť pozorně čteme slova "první účastníci, po jednom". Pokud agent zapíše "celý zbytek dostane první", změní tím naše rozhodnutí: při dvou zbývajících haléřích by první zaplatil o 0,02 víc než ostatní. Požádáme ho o opravu a znovu se podíváme do souboru. Kontrolujeme smysl, přesná shoda formulací není nutná.

Právě proto se hodí dosadit do zadání konkrétní čísla. Chybějící rozhodnutí jsme našli dřív, než agent zvolil vlastní variantu a napsal podle ní kód. Zatím jsme opravili jen pár řádků.

Nechte Claude, ať se zeptá

Ne všechny mezery odhalíte sami. Předejte agentovi návrh a požádejte ho, aby pomohl právě se zadáním:

Přečti @TASK_SPEC.md. Pomoz najít chybějící podmínky.
Ptej se vždy na jednu věc a ke každé navrhni odpověď.
Nepovažuj svůj návrh za schválený, dokud neodpovím.
Po každém dohodnutém rozhodnutí aktualizuj TASK_SPEC.md
a ukaž změněnou část, abych ji mohl zkontrolovat.
Kód zatím nepiš.

Níže je ukázka takového rozhovoru. Ve vaší relaci mohou být otázky jiné; důležité je sledovat, jak odpovědi mění dokument.

Claude: "Je spropitné součástí účtu, nebo se přidává zvlášť? Navrhuji samostatné pole pro procento, výchozí hodnota 0."
Vy: "Zvlášť. Procento počítej z částky na účtence, spropitné přičti navíc a pak rozděl celkovou částku. Na stránce ukaž spropitné i celkový součet."

Claude: "Co když spropitné vyjde na zlomek haléře, jak ho zaokrouhlit? Navrhuji na nejbližší haléř, přesnou polovinu nahoru."
Vy: "Ano. Nejdřív zaokrouhli spropitné, pak ho přičti k účtu. Potom rozděl celkovou částku podle našeho pravidla."

Claude: "Jaké hodnoty přijímáme? Navrhuji kladnou částku s tečkou nebo čárkou, počet lidí jako celé číslo od jedné a celé nezáporné procento. Při chybě zobrazit nápovědu u pole."
Vy: "To vyhovuje. Částka může mít nejvýše dvě desetinná místa, bez mezer mezi tisíci. Pokud je pole prázdné nebo hodnota neplatná, výsledek skryj, i když jsme už předtím počítali."

Upřesnili jsme nejen spropitné. Teď jsou stanovené povolené vstupy, pořadí zaokrouhlování i chování při chybě. Po zapsání odpovědí porovnáme aktualizovanou část souboru:

Spropitné: samostatné pole s celým procentem od 0, výchozí hodnota 0.
Spropitné počítáme z účtu a zaokrouhlujeme na nejbližší haléř;
přesnou polovinu haléře zaokrouhlíme nahoru.
Zaokrouhlené spropitné přičteme k účtu a pak rozdělíme celek.
Zobrazíme spropitné, celkovou částku i podíl každého.
Při prázdné nebo neplatné hodnotě se výsledek skryje,
u příslušného pole se zobrazí nápověda.

Kontrolujeme pořadí: nejprve zaokrouhlíme spropitné, pak ho přičteme k účtu a nakonec rozdělíme celkovou částku. Stejná slova v jiném pořadí by znamenala jiný požadavek. Požádáme agenta, aby aktualizoval i scope: k první verzi přibylo pole pro spropitné a výpočet celkové částky. Ověříme, že skutečně změnil obě části, nejen že to potvrdil v chatu.

Výsledek a způsob ověření

"Součet podílů odpovídá celkové částce" je požadavek na výsledek. "Zadat částku 1000, tři lidi a 0 % spropitného, kliknout na tlačítko a vidět 333,34, 333,33 a 333,33" je ověření. Určuje akci a očekávaný výsledek.

Požádáme agenta, aby do souboru přidal několik takových ověření ještě před implementací. Očekávaná čísla zkontrolujeme sami. Jinak se snadno smíříme s tím, co vzniklo, a nenápadně přizpůsobíme očekávání hotové stránce.

Řádek s částkou 10,05 ověřuje pořadí výpočtu: 10 % je 1,005 a po zaokrouhlení 1,01. Pokud zaokrouhlíme v jiné fázi, výsledek se může lišit. Formát ověříme opakováním s tečkou: 10.05 má dát stejný výsledek. Zkuste také zápornou částku, desetinný počet lidí, záporné nebo desetinné procento a prázdné pole pro spropitné: výpočet se nesmí provést.

Každá důležitá podmínka má své ověřitelné pozorování. To, že "se stránka otevřela", ještě nedokazuje správnost částek, stejně jako správná adresa odkazu nedokazuje, že se načetla požadovaná stránka. Ověřujte chování, kvůli kterému jste úkol zadali.

Sestavíme TASK_SPEC

Agent zapisoval rozhodnutí do souboru postupně, jak jsme je probírali. Teď si ho přečteme celý: jsou zohledněné odpovědi, odpovídají ověření požadavkům a nezůstaly v něm staré podmínky? Takto vypadá hotový dokument našeho příkladu. Má šest opěrných bodů: kontext, požadované chování, scope, non-goals, plán ověření a bezpečný začátek. Podle názvů rychle najdete příslušnou část, obsah ale vzešel z rozboru úkolu.

# TASK_SPEC.md

## KONTEXT
Parta přátel chce rozdělit účet v restauraci.
Nový projekt zatím neexistuje; pracovní složka obsahuje jen TASK_SPEC.md.

## POŽADOVANÉ CHOVÁNÍ
Výsledkem práce bude index.html, který se otevře dvojklikem,
a stručný popis ověření.
Na stránce budou tři pole a tlačítko "Vypočítat":
- částka na účtence větší než 0, nejvýše dvě desetinná místa;
  oddělovač je tečka nebo čárka, bez oddělovačů tisíců;
- počet lidí je celé číslo od 1;
- procento spropitného je celé číslo od 0, výchozí hodnota 0.
Spropitné počítáme z účtu a zaokrouhlujeme na nejbližší haléř;
přesnou polovinu haléře zaokrouhlíme nahoru.
Zaokrouhlené spropitné přičteme k účtu a pak rozdělíme celek.
Zobrazí se spropitné, celková částka a očíslované podíly účastníků.
Součet podílů odpovídá celku, rozdíl mezi nimi je nejvýše 0,01.
Zbytek se rozděluje po jednom haléři prvním účastníkům;
na stránce je vysvětlení tohoto pravidla.
Při prázdné nebo neplatné hodnotě se výsledek skryje,
u nesprávně vyplněného pole se zobrazí nápověda.

## SCOPE
Jedna stránka: tři pole, výpočet, nápovědy a zobrazení částek.
Celkovou částku rozdělíme rovným dílem podle popsaného pravidla pro zbytek.

## NON-GOALS
Uživatelské účty ani historii účtenek nepotřebujeme: data neukládáme.
Rozdělení podle jídel dělat nebudeme: to je jiná verze kalkulačky.
Omezení: styly i skript budou uvnitř index.html,
bez serveru a externích knihoven, aby šel soubor otevřít lokálně.

## PLÁN OVĚŘENÍ
Otevřít index.html dvojklikem. Klikat na "Vypočítat":
- 1000 / 3 lidé / 0 % → 333,34; 333,33; 333,33;
- 1000,01 / 3 / 0 % → 333,34; 333,34; 333,33;
- 1000 / 3 / 10 % → spropitné 100,00, celkem 1100,00,
  podíly 366,67; 366,67; 366,66;
- 10,05 / 3 / 10 % → spropitné 1,01, celkem 11,06,
  podíly 3,69; 3,69; 3,68; při zadání 10.05 stejný výsledek;
- 1000 / 1 / 0 % → jeden podíl 1000,00.
V každém případě sečíst podíly a porovnat je s celkem.
Ověřit nulu a desetinné číslo u počtu lidí, zápornou částku,
záporné a desetinné procento, více než dvě desetinná místa
u částky a postupně každé prázdné pole:
nápověda u pole, výsledek skrytý, i po předchozím výpočtu.
Ověřit číslování podílů a vysvětlení rozdělení haléřů.

## BEZPEČNÝ ZAČÁTEK
Přečíst zadání a prohlédnout obsah pracovní složky.
Pokud už obsahuje soubory projektu, zastavit se a upřesnit úkol;
stávající soubory nepřepisovat ani nemazat.
Nejprve otázky a plán bez kódu, pak počkat na schválení.
Pokud implementace vyžaduje změny mimo scope,
nejprve zadání upřesnit.

Dokument se rozrostl o rozhodnutí, která jsme skutečně potřebovali. Neobsahuje návod krok za krokem, jak napsat JavaScript, ale je jasné, jak naložit se spropitným a ověřit haléře. Ve vašem úkolu může být podrobností méně.

Při sestavování vlastního zadání se hodí projít tento stručný tahák:

Když se podmínky změní

Teď krátká otázka pro vás. Uživatel si přečetl zadání a říká: "Procenta mi nevyhovují. Chci zadávat spropitné jako částku, třeba 100." Které části TASK_SPEC bude potřeba aktualizovat? Zkuste je vyjmenovat dřív, než si přečtete rozbor.

V požadovaném chování nahradíme pole s procentem částkou spropitného: nezápornou hodnotou s tečkou nebo čárkou a nejvýše dvěma desetinnými místy. Výchozí hodnota zůstane 0. Vzorec pro procenta i zaokrouhlování vypočteného spropitného odstraníme: zadanou částku jednoduše přičteme k účtu. Ve scope se změní výpočet a v plánu ověření vstupní data i případy neplatného vstupu. Rozdělení celkové částky a non-goals zůstávají beze změny.

Ověření "účet 1000, spropitné 100, tři účastníci" dá známých 366,67; 366,67; 366,66. Z těchto čísel ale nepoznáme novou verzi od původní se spropitným 10 %. Přidejte jiný příklad: účet 500 plus pevné spropitné 100, dva účastníci. Každý má zaplatit 300; původních 10 % by dalo 275. Tohle ověření změnu pravidla odhalí.

Požádejte agenta, aby aktualizoval požadované chování, scope a ověření a ukázal všechny změněné části. Otevřete soubor a zkontrolujte, že původní vzorec pro procenta zmizel a nová ověření odpovídají zadávání částky. Nenechávejte vedle sebe starý vzorec a novou poznámku "teď částkou": zadání musí mít jediný výklad. V hlavním příkladu výše jsme ponechali původní variantu s procentem; tady jsme probrali samostatnou změnu.

Jak to funguje s Claude Code

Po kontrole jednotlivých změn si před spuštěním implementace znovu přečtěte celý TASK_SPEC. Ověřte, že cíl, hranice i ověření popisují tentýž úkol. Pak agentovi výslovně předejte soubor:

Přečti @TASK_SPEC.md. Nejdřív zkontroluj, zda si podmínky
neodporují nebo zda není něco potřeba upřesnit.
Ukaž stručný plán a seznam souborů, které vytvoříš nebo změníš.
Kód neupravuj, dokud plán neschválím.

Teď můžeme kontrolovat plán ještě před implementací. Pokud v něm agent navrhl server pro ukládání účtenek, požádejte ho o přepracování: historie je vyloučená a stránka se musí otevřít lokálně. Pokud plán vyhovuje, povolte implementaci. Pak otevřete výsledný soubor a projděte zaznamenané scénáře včetně neplatného vstupu po úspěšném výpočtu.

Non-goals zůstávají textovými podmínkami, změnám technicky nebrání. Proto je důležité zkontrolovat plán i výsledek. Zpráva agenta "hotovo" vám pomůže pochopit, co udělal, ale nenahradí vaše kontrolní čísla.

Pokud po dokončení ponecháte TASK_SPEC v projektu, označte úkol jako uzavřený. Dokud práce pokračuje, udržujte rozhodnutí v souboru aktuální. Nechte agenta navrhnout formulace a zapsat je, rozhodnutí ale kontrolujte přímo v dokumentu: po diskusi změněnou část, před implementací celý soubor.