TASK_SPEC, ktorý možno overiť

"Vytvor kalkulačku, ktorá vypočíta, koľko kto dlhuje v reštaurácii." Jasná požiadavka, kým sa nad ňou nezačnete zamýšľať. Rozdelíme účet rovnomerne, alebo každý zaplatí za svoje jedlá? Je prepitné už zahrnuté v účte? Čo zobraziť, ak sa suma nedá rozdeliť rovnomerne?

Pripravíme zadanie spolu s Claude Code: vy vysvetlíte úlohu a vyberiete riešenia, agent ich zapíše do súboru a vy skontrolujete záznam. Začneme krátkou požiadavkou a postupne vytvoríme TASK_SPEC, podľa ktorého sa dá pracovať.

"Urob to poriadne" nie je zadanie

Predstavte si, že ste chceli rýchlo rozdeliť účet, no agent pridal registráciu a históriu reštaurácií. Na uchovávanie účteniek potreboval server. Vy ste čakali, že otvoríte jeden súbor v prehliadači, a teraz sa musíte zaoberať spúšťaním a odstraňovať zbytočnosti. Každé doplnenie samo osebe vyzerá užitočne, ale výsledok sa už výrazne vzdialil od vášho zámeru.

Pri práci s kódom sa neúplné zadanie môže zmeniť na skutočné úpravy súborov. Vznikne takýto reťazec:

Schéma ukazuje, ako vynechané rozhodnutie pridá ďalšiu prácu. Agent sa môže dopytovať, no nejasnosti je lepšie odhaliť ešte pred úpravami. Už prvé znenie môže určiť smer a hranice:

Zatiaľ nejasné:
Vytvor kalkulačku, ktorá vypočíta, koľko kto dlhuje v reštaurácii.

Konkrétnejšie:
Potrebujeme jednu stránku: zadáme celkovú sumu účtu a počet ľudí,
uvidíme sumu pre každého. Delíme rovnomerne.
Používateľské účty, históriu účteniek ani rozdelenie podľa jedál nerobíme.

Druhá požiadavka ešte neodpovedá na všetky otázky. Už však vylučuje niekoľko rôznych produktov, ktoré by sa dali vytvoriť podľa prvej. Agent potom pomôže nájsť zvyšné nejasnosti a zapísať vaše rozhodnutia.

Zadanie v jednom súbore

TASK_SPEC je záznam podmienok jednej úlohy: aký výsledok potrebujete, kde sa práca končí a ako ho overíte. Zvyčajne sa ukladá do súboru Markdown TASK_SPEC.md vedľa projektu. Za týmto názvom sa neskrýva žiadny špeciálny formát ani príkaz. Podmienky môžete poslať aj v správe, no súbor sa ľahšie číta a aktualizuje.

TASK_SPEC nemusíte písať ručne. Pohodlnejšie je zostaviť ho s agentom a overiť, ako zapísal vaše rozhodnutia. Úlohu môžete opísať bežnými slovami, odpovedať na otázky a požiadať o úpravu formulácií. Agent spravuje súbor a vy kontrolujete, či obsah zodpovedá tomu, čo ste mysleli.

1. opíšete, čo chcete dosiahnuť, a prediskutujete nejasné miesta;
2. agent navrhne možnosti a vy vyberiete tú správnu;
3. agent zapíše rozhodnutie do TASK_SPEC a ukáže doplnenú alebo zmenenú časť;
4. prečítate si túto časť v súbore: význam zostal zachovaný, nepribudli zbytočné podmienky a nič neodporuje starším záznamom. Ak niečo nesedí, požiadate o opravu a znova ju skontrolujete.

Po každom jednotlivom rozhodnutí stačí skontrolovať dotknuté riadky a súvisiace podmienky. Pred implementáciou si prečítajte celý súbor: jednotlivé záznamy môžu vyzerať správne, no spolu si odporovať. Správa "aktualizoval som špecifikáciu" ešte neukazuje, čo sa v dokumente naozaj zmenilo.

Od súboru CLAUDE.md sa líši účelom. "Všetky popisky v projekte sú po slovensky" je všeobecné pravidlo projektu. "V tejto úlohe pridávame výpočet prepitného" je podmienka konkrétnej práce. Prvé patrí do CLAUDE.md, druhé do TASK_SPEC.

Rozsah dokumentu závisí od úlohy. Ak treba na hotovej stránke opraviť preklep, stačí takéto zadanie:

Na stránke s rozdelením účtu oprav popisok tlačidla:
"Vypočit" → "Vypočítať". Ostatné nemeň.
Over, že sa nový popisok zobrazuje a tlačidlo stále počíta.

Je to krátky TASK_SPEC, niekedy sa mu hovorí tiny spec. Takmer niet čo prediskutovať. Nová kalkulačka však môže fungovať viacerými spôsobmi, takže dva riadky už nestačia. Oplatí sa zaznamenať rozhodnutia, ktoré ovplyvňujú výsledok; samotný počet nadpisov nič nezaručuje.

Začnime výsledkom

Predstavme si, že projekt ešte neexistuje. Partia priateľov chce otvoriť stránku v prehliadači, zadať sumu účtu a zistiť, koľko má každý zaplatiť. Požiadajme agenta, aby vytvoril návrh:

Vytvor TASK_SPEC.md pre stránku na rozdelenie účtu.
Projekt ešte neexistuje. Zadáme sumu účtu a počet ľudí,
po kliknutí na "Vypočítať" uvidíme podiel každého.
Výsledkom má byť index.html, ktorý sa otvorí v prehliadači bez inštalácie.
Zapíš dohodnuté podmienky a neznáme označ otázkami.
Ukáž zapísaný text. Kód stránky zatiaľ nepíš.

Takto môže vyzerať prvá časť súboru ako učebný príklad:

## KONTEXT
Partia priateľov chce rýchlo rozdeliť spoločný účet v reštaurácii.
Projekt ešte neexistuje, pracovný priečinok je prázdny.

## POŽADOVANÉ SPRÁVANIE
Používateľ zadá sumu účtu a počet ľudí.
Po kliknutí na "Vypočítať" uvidí sumu pre každého.
Výsledkom práce je stránka index.html,
ktorú možno otvoriť v prehliadači bez inštalácie.

Otvorte TASK_SPEC.md v editore a porovnajte záznam s požiadavkou: sú tam obe polia, akcia aj výsledok pre každého účastníka? Ak agent pridal zadávanie mien alebo povinnú registráciu, ide už o nedohodnuté podmienky. Požiadajte ho, aby ich zo súboru odstránil, a skontrolujte opravu.

Teraz je jasné, kto stránku používa a čo získa. Zároveň sme pomenovali artefakt, teda konkrétny výsledok práce agenta: súbor stránky. Pri inej úlohe by to mohla byť analýza chyby alebo plán zmien bez kódu. Radšej to povedzte priamo.

Všimnite si, že sme zatiaľ nevyberali funkcie JavaScriptu ani neurčovali, ako ukladať účastníkov. To patrí k implementácii. V zadaní je dôležitejšie zachytiť, čo človek uvidí: vstup, akciu a výsledok.

Kde sa úloha končí

Teraz určme, kde sa končí prvá verzia. Požiadajme agenta, aby zapísal dohodnuté hranice a ukázal aktualizovanú časť:

## SCOPE
Jedna stránka: zadanie sumy a počtu ľudí,
rovnomerné rozdelenie celkovej sumy, zobrazenie podielu každého.

## NON-GOALS
Bez používateľských účtov a histórie účteniek: údaje netreba uchovávať.
Bez rozdelenia podľa jedál: v prvej verzii delíme rovnomerne.
Obmedzenie implementácie: jeden HTML súbor so štýlmi a skriptom
vnútri, bez servera a externých knižníc.
Stránka sa musí otvoriť dvojklikom.

V tejto časti kontrolujeme nielen to, či sú zákazy uvedené: rovnomerné rozdelenie musí zostať súčasťou úlohy a rozdelenie podľa jedál mimo nej. Ak ich agent zamenil, opravme dokument ešte pred prácou na stránke.

Scope opisuje rozsah práce. Možno ho určiť cez obrazovku a scenár, ako v tomto príklade. Presné cesty pomôžu, keď ich poznáte, ale nemusíte začínať zoznamom súborov. Ak upravujete existujúci projekt a neviete, kde sa nachádza potrebná stránka, požiadajte Claude Code, aby ju najskôr našiel bez úprav a vysvetlil, prečo vybral práve tento súbor. Potom cestu doplňte do zadania. Neznáme je v poriadku, vymýšľať si nie.

Non-goals sú veci, ktoré ste zámerne vylúčili. "Bez histórie účteniek" vysvetľuje hranicu lepšie než "nerob nič navyše". Stručný dôvod pomôže aj vám: o týždeň bude jasné, že ste zvážili ukladanie údajov a rozhodli sa ho vynechať.

Obmedzenia implementácie odpovedajú na inú otázku: ktoré spôsoby riešenia nám vyhovujú. Používateľské účty sú nadbytočná funkcia, kým server je spôsob vytvorenia riešenia, ktorý sme tu vylúčili. V krátkom dokumente môžu byť tieto podmienky v jednej časti, ak sú obmedzenia jasne označené.

Hranice musia umožniť dosiahnuť výsledok. Ak neskôr budete potrebovať spoločné používateľské účty s históriou dostupnou na rôznych zariadeniach, požiadavku "jeden lokálny HTML súbor" bude treba prehodnotiť. Nemožno žiadať novú možnosť a zároveň ponechať zákaz, ktorý jej realizáciu znemožňuje.

Cent, na ktorý sa zabudlo

Zatiaľ je všetko pomerne jasné. Ešte pred písaním kódu si overme zadanie: v reštaurácii sú traja ľudia a účet je 1000. Akú sumu zobrazíme každému?

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

Jeden cent chýba. Môžeme ho pridať prvému účastníkovi, poslednému alebo nechať výber na používateľovi. Veta "delíme rovnomerne" to nerieši. A to už závisí od vášho rozhodnutia, nie od znalosti JavaScriptu.

Pre našu stránku zvoľme toto pravidlo: podiely sa líšia najviac o jeden cent; zvyšok sa rozdelí po jednom cente medzi prvých účastníkov v zozname. Pri sume 1000 pre troch teda dostaneme 333,34; 333,33; 333,33. Pri sume 1000,01 zostanú dva centy: 333,34; 333,34; 333,33. Všetky peniaze sa rozdelia a súčet podielov sa rovná účtu.

Teraz požiadajme agenta, aby zapísal zvolené rozhodnutie do dokumentu:

Zapíš pravidlo zaokrúhľovania do požadovaného správania v TASK_SPEC.md.
Ukáž zmenené riadky. Kód zatiaľ nemeň.

Skontrolujeme, či sa v súbore objavil takýto záznam:

Súčet podielov sa presne rovná celkovej sume.
Podiely sa líšia najviac o 0,01.
Zvyšné centy dostanú prví účastníci, po jednom;
stránka obsahuje vysvetlenie tohto pravidla.

Osobitne pozorne čítame slová "prví účastníci, po jednom". Ak agent zapísal "celý zvyšok prvému", zmenil vaše rozhodnutie: pri dvoch zvyšných centoch by prvý zaplatil o 0,02 viac než ostatní. Požiadajme ho o opravu riadka a znova sa pozrime do súboru. Kontrolujeme význam, presná zhoda formulácie slovo za slovom nie je potrebná.

Preto sa oplatí dosadiť do zadania konkrétne čísla. Chýbajúce rozhodnutie sme našli skôr, než agent vybral vlastný spôsob a napísal podľa neho kód. Zatiaľ sme opravili iba pár riadkov.

Nechajte Claude klásť otázky

Nie všetky nejasnosti si všimnete sami. Odovzdajte agentovi návrh a požiadajte ho, aby pomohol práve so zadaním:

Prečítaj @TASK_SPEC.md. Pomôž nájsť chýbajúce podmienky.
Pýtaj sa po jednej otázke a ku každej navrhni odpoveď.
Nepovažuj svoj návrh za dohodnutý, kým neodpoviem.
Po každom dohodnutom rozhodnutí aktualizuj TASK_SPEC.md
a ukáž zmenenú časť, aby som ju mohol skontrolovať.
Kód zatiaľ nepíš.

Nižšie je príklad takéhoto rozhovoru. Vo vašej relácii môžu byť otázky iné; dôležité je sledovať, ako odpovede menia dokument.

Claude: "Je prepitné zahrnuté v účte alebo sa pripočítava osobitne? Navrhujem samostatné pole s percentom, predvolene 0."
Vy: "Osobitne. Percento vypočítame zo sumy účtu, prepitné pripočítame a všetko rozdelíme spolu. Na stránke zobraz sumu prepitného aj celkovú sumu."

Claude: "Ako zaokrúhliť prepitné, ak vyjde zlomok centa? Navrhujem zaokrúhliť na najbližší cent a presnú polovicu nahor."
Vy: "Áno. Najprv zaokrúhlime sumu prepitného a potom ju pripočítame k účtu. Až potom rozdelíme celkovú sumu podľa nášho pravidla."

Claude: "Aké hodnoty prijímame? Navrhujem kladnú sumu s bodkou alebo čiarkou, počet ľudí ako celé číslo od 1 a celé nezáporné percento. Pri chybe zobrazíme upozornenie pri poli."
Vy: "To vyhovuje. Suma môže mať najviac dve desatinné miesta, bez medzier medzi tisíckami. Ak je pole prázdne alebo hodnota neplatná, výsledok skryjeme, aj keď sme už predtým počítali."

Spresnili sme nielen prepitné. Teraz poznáme povolené vstupy, poradie zaokrúhľovania aj správanie pri chybe. Po zapísaní odpovedí skontrolujeme aktualizovanú časť súboru:

Prepitné: samostatné pole s celým percentom od 0, predvolená hodnota 0.
Suma prepitného sa vypočíta z účtu a zaokrúhli na najbližší cent;
presná polovica centa sa zaokrúhli nahor.
Zaokrúhlené prepitné sa pripočíta k účtu a potom sa rozdelí celková suma.
Zobrazí sa suma prepitného, celková suma a podiel každého.
Pri prázdnej alebo neplatnej hodnote sa výsledok skryje,
pri príslušnom poli sa zobrazí upozornenie.

Kontrolujeme poradie: najprv sa zaokrúhli prepitné, potom sa pripočíta k účtu a napokon sa rozdelí celková suma. Rovnaké slová v inom poradí by znamenali inú požiadavku. Požiadajme agenta, aby aktualizoval aj scope: k prvej verzii pribudlo pole prepitného a výpočet celkovej sumy. Skontrolujme, či naozaj zmenil obe časti a iba to nepotvrdil v chate.

Výsledok a spôsob overenia

"Súčet podielov sa rovná celkovej sume" je požiadavka na výsledok. "Zadať 1000, troch ľudí a 0 % prepitného, kliknúť na tlačidlo a vidieť 333,34, 333,33 a 333,33" je kontrola. Určuje akciu aj očakávaný výsledok.

Požiadajme agenta, aby do súboru pridal niekoľko takýchto kontrol ešte pred implementáciou. Očakávané čísla si overíme sami. Inak ľahko prijmeme výsledok a nebadane prispôsobíme očakávania hotovej stránke.

Riadok s hodnotou 10,05 overuje poradie krokov: 10 % je 1,005 a po zaokrúhlení 1,01. Ak zaokrúhlite v inom kroku, výsledok sa môže líšiť. Na kontrolu formátu skúste to isté s bodkou: 10.05 má dať rovnaký výsledok. Osobitne skúste zápornú sumu, necelý počet ľudí, záporné alebo desatinné percento a prázdne pole prepitného: výpočet sa nesmie vykonať.

Každá dôležitá podmienka má svoj pozorovateľný výsledok. To, že sa "stránka otvorila", ešte nedokazuje, že sú sumy správne; podobne ani správna adresa odkazu nedokazuje, že sa načítala potrebná stránka. Overujte správanie, pre ktoré ste úlohu zadali.

Zostavme TASK_SPEC

Agent priebežne zapisoval rozhodnutia do súboru. Teraz si ho prečítajme celý: sú v ňom zohľadnené odpovede, zodpovedajú kontroly požiadavkám a nezostali v ňom staré podmienky? Takto vyzerá výsledný dokument nášho príkladu. Má šesť oporných častí: kontext, požadované správanie, scope, non-goals, plán overenia a bezpečný začiatok. Názvy pomáhajú rýchlo nájsť potrebnú časť, ale obsah vzišiel z rozboru úlohy.

# TASK_SPEC.md

## KONTEXT
Partia priateľov chce rozdeliť účet v reštaurácii.
Nový projekt ešte neexistuje; pracovný priečinok je prázdny okrem TASK_SPEC.md.

## POŽADOVANÉ SPRÁVANIE
Výsledkom práce je index.html, ktorý sa otvorí dvojklikom,
a krátky opis overenia.
Na stránke sú tri polia a tlačidlo "Vypočítať":
- suma účtu väčšia ako 0, najviac dve desatinné miesta;
  oddeľovač je bodka alebo čiarka, bez oddeľovačov tisícov;
- počet ľudí je celé číslo od 1;
- percento prepitného je celé číslo od 0, predvolená hodnota 0.
Prepitné sa vypočíta z účtu a zaokrúhli na najbližší cent;
presná polovica centa sa zaokrúhli nahor.
Zaokrúhlené prepitné sa pripočíta k účtu a potom sa rozdelí celková suma.
Zobrazí sa prepitné, celková suma a očíslované podiely účastníkov.
Súčet podielov sa rovná celkovej sume, rozdiel medzi podielmi je najviac 0,01.
Zvyšok sa rozdelí po jednom cente medzi prvých účastníkov;
stránka obsahuje vysvetlenie tohto pravidla.
Pri prázdnej alebo neplatnej hodnote sa výsledok skryje,
pri nesprávne vyplnenom poli sa zobrazí upozornenie.

## SCOPE
Jedna stránka: tri polia, výpočet, upozornenia a zobrazenie súm.
Celkovú sumu delíme rovnomerne podľa opísaného pravidla rozdelenia zvyšku.

## NON-GOALS
Používateľské účty ani história účteniek nie sú potrebné: údaje neukladáme.
Rozdelenie podľa jedál nerobíme: to je iná verzia kalkulačky.
Obmedzenie: štýly a skript sú vnútri index.html,
bez servera a externých knižníc, aby sa súbor dal otvoriť lokálne.

## PLÁN OVERENIA
Otvoriť index.html dvojklikom. Kliknúť na "Vypočítať":
- 1000 / 3 ľudia / 0 % → 333,34; 333,33; 333,33;
- 1000,01 / 3 / 0 % → 333,34; 333,34; 333,33;
- 1000 / 3 / 10 % → prepitné 100,00, celková suma 1100,00,
  podiely 366,67; 366,67; 366,66;
- 10,05 / 3 / 10 % → prepitné 1,01, celková suma 11,06,
  podiely 3,69; 3,69; 3,68; pri zadaní 10.05 je výsledok rovnaký;
- 1000 / 1 / 0 % → jeden podiel 1000,00.
V každom prípade sčítať podiely a porovnať ich s celkovou sumou.
Overiť nulu a necelý počet ľudí, zápornú sumu,
záporné a desatinné percento, viac než dve desatinné miesta
v sume a postupne každé prázdne pole:
upozornenie pri poli, výsledok skrytý, aj po predchádzajúcom výpočte.
Overiť číslovanie podielov a vysvetlenie rozdelenia centov.

## BEZPEČNÝ ZAČIATOK
Prečítať zadanie a pozrieť obsah pracovného priečinka.
Ak už obsahuje súbory projektu, zastaviť sa a spresniť úlohu;
existujúce súbory neprepisovať ani nemažať.
Najprv otázky a plán bez kódu, potom počkať na schválenie.
Ak implementácia vyžaduje zmeny mimo scope,
spresniť zadanie ešte pred týmito zmenami.

Dokument narástol vďaka rozhodnutiam, ktoré boli naozaj potrebné. Neobsahuje podrobný návod na písanie JavaScriptu, no jasne hovorí, čo robiť s prepitným a ako overiť centy. Vo vašej úlohe môže byť detailov menej.

Keď budete pripravovať vlastné zadanie, poslúži vám táto stručná pomôcka:

Ak sa podmienky zmenia

Teraz krátka kontrolná otázka. Používateľ si prečítal zadanie a hovorí: "Percento mi nevyhovuje. Chcem zadať sumu prepitného, napríklad 100." Ktoré časti TASK_SPEC bude treba aktualizovať? Skúste ich pomenovať skôr, než si prečítate rozbor.

V požadovanom správaní sa pole s percentom nahradí sumou prepitného: nezápornou, s bodkou alebo čiarkou a najviac dvoma desatinnými miestami. Predvolená hodnota zostane 0. Vzorec percenta a zaokrúhľovanie vypočítaného prepitného odstránime: zadanú sumu jednoducho pripočítame k účtu. V scope sa zmení výpočet, v pláne overenia vstupné údaje a prípady neplatného zadania. Rozdelenie celkovej sumy a non-goals zostanú rovnaké.

Kontrola "účet 1000, prepitné 100, traja účastníci" dá známy výsledok 366,67; 366,67; 366,66. Podľa týchto čísel však nemožno odlíšiť novú verziu od pôvodnej s 10 % prepitným. Pridajte iný účet: 500 plus pevná suma 100, dvaja účastníci. Každému má vyjsť 300; pôvodných 10 % by dalo 275. Táto kontrola odhalí zmenu pravidla.

Požiadajte agenta, aby aktualizoval požadované správanie, scope a kontroly a potom ukázal všetky zmenené časti. Otvorte súbor a overte, že pôvodný vzorec percenta zmizol a nové kontroly zodpovedajú zadávaniu sumy. Nenechávajte tam súčasne pôvodný vzorec a novú poznámku "teraz sumou": zadanie musí dávať jednu odpoveď. V hlavnom príklade vyššie sme ponechali pôvodný variant s percentom; tu sme rozobrali samostatnú zmenu.

Ako to funguje s Claude Code

Po kontrole jednotlivých zmien si pred spustením implementácie znova prečítajte celý TASK_SPEC. Overte, či cieľ, hranice a kontroly opisujú tú istú úlohu. Potom súbor výslovne odovzdajte agentovi:

Prečítaj @TASK_SPEC.md. Najprv skontroluj, či si podmienky
neodporujú alebo či netreba niečo ešte spresniť.
Ukáž stručný plán a zoznam súborov, ktoré vytvoríš alebo zmeníš.
Kým plán neschválim, kód nemeň.

Ešte pred implementáciou už máte čo kontrolovať. Ak sa v pláne objaví server na uchovávanie účteniek, vráťte plán na prepracovanie: história je vylúčená a stránka sa má otvárať lokálne. Ak plán vyhovuje, povoľte implementáciu. Potom otvorte výsledný súbor a prejdite zapísané scenáre vrátane neplatného vstupu po úspešnom výpočte.

Non-goals zostávajú textovými podmienkami a technicky zmenám nezabránia. Preto je dôležité skontrolovať plán aj výsledok. Správa agenta "hotovo" pomôže zistiť, čo urobil, no nenahrádza vaše kontrolné čísla.

Ak po dokončení uložíte TASK_SPEC do projektu, označte úlohu ako uzavretú. Kým sa na nej pracuje, udržiavajte rozhodnutia v súbore aktuálne. Agentovi zverte formulácie a zápis, rozhodnutia overujte priamo v dokumente: zmenenú časť po diskusii, celý súbor pred implementáciou.