Un TASK_SPEC care poate fi verificat

"Fă un calculator care să arate cât datorează fiecare la restaurant". Cererea pare clară până începeți să o analizați. Împărțim nota în mod egal sau fiecare își plătește felurile? Bacșișul este deja inclus? Ce afișăm dacă suma nu se împarte egal la toți?

Vom formula sarcina împreună cu Claude Code: dumneavoastră o explicați și luați deciziile, agentul le consemnează într-un fișier, iar dumneavoastră verificați ce a scris. Începem cu o cerere scurtă și ajungem treptat la un TASK_SPEC pe care vă puteți baza.

"Fă-o cum trebuie" nu e o sarcină

Imaginați-vă: voiați să împărțiți rapid nota, iar agentul a adăugat crearea de conturi și un istoric al restaurantelor. Ca să stocheze bonurile, a avut nevoie de un server. Vă așteptați să deschideți un singur fișier în browser, iar acum trebuie să aflați cum se pornește și să eliminați ce nu vă trebuie. Fiecare adaos pare util în parte, dar rezultatul s-a îndepărtat deja mult de ce aveați în minte.

În lucrul cu codul, lucrurile nespuse se pot transforma în modificări reale ale fișierelor. Lanțul arată cam așa:

Diagrama arată cum o decizie lipsă se transformă în muncă suplimentară. Agentul poate cere lămuriri, dar e mai bine să depistați neclaritățile înainte de modificări. Chiar prima formulare poate stabili direcția și limitele:

Încă neclar:
Fă un calculator care să arate cât datorează fiecare la restaurant.

Mai concret:
O singură pagină: introducem totalul notei și numărul de persoane,
vedem suma fiecăruia. Împărțim în mod egal.
Fără conturi, istoric al notelor sau împărțire pe feluri de mâncare.

A doua cerere încă nu răspunde la toate întrebările. Dar exclude deja câteva produse diferite care ar fi putut rezulta din prima. De aici, agentul vă va ajuta să găsiți lacunele rămase și să vă consemnați deciziile.

Sarcina într-un singur fișier

TASK_SPEC este o înregistrare a condițiilor pentru o sarcină: ce rezultat doriți, unde se încheie lucrul și cum îl veți verifica. De obicei, se salvează într-un fișier Markdown, TASK_SPEC.md, în folderul proiectului. Numele nu presupune un format special sau o comandă dedicată. Puteți transmite condițiile și într-un mesaj, dar fișierul e mai ușor de recitit și actualizat.

Nu e nevoie să scrieți TASK_SPEC de mână. E mai simplu să-l construiți împreună cu agentul și să verificați cum v-a consemnat deciziile. Puteți descrie sarcina în cuvinte obișnuite, răspunde la întrebări și cere reformulări. Agentul actualizează fișierul, iar dumneavoastră îi verificați sensul.

1. descrieți ce rezultat doriți și discutați aspectele neclare;
2. agentul propune opțiuni, iar dumneavoastră o alegeți pe cea potrivită;
3. agentul consemnează decizia în TASK_SPEC și vă arată fragmentul adăugat sau modificat;
4. citiți fragmentul în fișier: sensul e păstrat, nu au apărut condiții în plus, iar fragmentul nu contrazice înregistrările anterioare. Dacă ceva nu e în regulă, cereți o corectare și verificați din nou.

După fiecare decizie, e suficient să verificați rândurile afectate și condițiile legate de ele. Înainte de implementare, recitiți întregul fișier: luate separat, înregistrările pot părea corecte, dar împreună pot cere lucruri incompatibile. Mesajul "am actualizat specificația" nu vă arată încă ce a ajuns în document.

TASK_SPEC se deosebește de CLAUDE.md prin scop. "Toate etichetele din proiect sunt în română" e o regulă generală a proiectului. "În această sarcină adăugăm calculul bacșișului" e o condiție pentru o anumită lucrare. Prima se potrivește în CLAUDE.md, a doua în TASK_SPEC.

Dimensiunea documentului depinde de sarcină. Dacă trebuie să corectați o greșeală de tipar pe o pagină gata făcută, ajunge o formulare ca aceasta:

Pe pagina de împărțire a notei, corectează eticheta butonului:
"Calculeaza" → "Calculează". Nu schimba nimic altceva.
Verifică dacă noua etichetă este vizibilă și butonul încă face calculul.

Acesta e un TASK_SPEC scurt, numit uneori tiny spec. Aici aproape că nu e nimic de discutat. În schimb, un calculator nou poate avea mai multe variante de comportament, așa că două rânduri nu mai ajung. Merită să consemnați deciziile care influențează rezultatul; numărul de titluri, în sine, nu garantează nimic.

Începem cu rezultatul

Să presupunem că proiectul încă nu există. Un grup de prieteni vrea să deschidă o pagină în browser, să introducă suma notei și să afle cât plătește fiecare. Îi cerem agentului să creeze o ciornă:

Creează TASK_SPEC.md pentru o pagină de împărțit nota.
Proiectul încă nu există. Introducem suma notei și numărul de persoane,
după apăsarea butonului "Calculează" vedem partea fiecăruia.
Rezultatul trebuie să fie un index.html care se deschide în browser fără instalare.
Consemnează condițiile stabilite, iar necunoscutele marchează-le cu întrebări.
Arată-mi textul scris. Deocamdată nu scrie codul paginii.

Iată un exemplu de prim fragment din fișier:

## CONTEXT
Un grup de prieteni vrea să împartă rapid nota la restaurant.
Proiectul încă nu există, folderul de lucru este gol.

## COMPORTAMENTUL DORIT
Utilizatorul introduce suma notei și numărul de persoane.
După apăsarea butonului "Calculează", vede suma fiecărui participant.
Rezultatul este o pagină index.html
care se poate deschide în browser fără instalare.

Deschideți TASK_SPEC.md în editor și comparați înregistrarea cu cererea: apar ambele câmpuri, acțiunea și rezultatul pentru fiecare participant. Dacă agentul a adăugat introducerea numelor sau înregistrarea obligatorie, sunt condiții pe care nu le-ați stabilit. Cereți să le elimine din fișier și verificați corectarea.

Acum e clar cine folosește pagina și ce primește. Am numit totodată și artefactul, adică rezultatul concret al lucrului agentului: fișierul paginii. Pentru o altă sarcină ar putea fi analiza unei erori sau un plan de modificări fără cod. E mai bine să spuneți asta explicit.

Observați că încă nu am ales funcții JavaScript și nici nu am dictat cum să fie stocați participanții. Aceste decizii țin de implementare. În formularea sarcinii contează mai mult să stabilim ce va vedea omul: datele introduse, acțiunea și rezultatul.

Unde se termină sarcina

Acum să stabilim unde se oprește prima versiune. Îi cerem agentului să consemneze limitele convenite și să ne arate blocul actualizat:

## SCOPE
O singură pagină: introducerea sumei și a numărului de persoane,
împărțirea egală a totalului și afișarea părții fiecăruia.

## NON-GOALS
Fără conturi și istoric al notelor: nu e nevoie să stocăm date.
Fără împărțire pe feluri: în prima versiune împărțim egal.
Constrângere de implementare: un singur fișier HTML, cu stilurile și scriptul
în interior, fără server și biblioteci externe.
Pagina trebuie să se deschidă cu dublu clic.

În acest fragment verificăm nu doar dacă excluderile sunt prezente: împărțirea egală trebuie să rămână în sarcină, iar împărțirea pe feluri să fie în afara ei. Dacă agentul le-a inversat, corectăm documentul înainte să lucrăm la pagină.

Scope descrie volumul de lucru. Îl puteți stabili printr-un ecran și un scenariu, ca aici. Căile exacte ajută atunci când le cunoașteți, dar nu e obligatoriu să începeți cu o listă de fișiere. Dacă modificați un proiect existent și nu știți unde se află pagina necesară, cereți-i lui Claude Code să o găsească mai întâi fără modificări și să explice de ce a ales acel fișier. Apoi adăugați calea în specificație. Necunoscutele sunt în regulă; lucrurile inventate, nu.

Non-goals sunt lucrurile excluse intenționat. "Fără istoric al notelor" explică limita mai bine decât "nu face nimic în plus". Și un motiv scurt vă ajută: peste o săptămână veți vedea că stocarea datelor a fost luată în calcul și respinsă.

Constrângerile de implementare răspund la altă întrebare: ce metode ni se potrivesc. Conturile sunt o funcție inutilă aici, iar serverul este o modalitate de a construi soluția pe care am exclus-o. Într-un document scurt puteți ține aceste condiții într-un singur bloc, marcând clar constrângerile.

Limitele trebuie să permită obținerea rezultatului. Dacă mai târziu veți avea nevoie de conturi comune cu istoric disponibil pe mai multe dispozitive, cerința "un singur fișier HTML local" va trebui revizuită. Nu puteți cere o funcție nouă și, în același timp, să păstrați o interdicție care o face imposibilă.

Bănuțul uitat

Până acum, totul pare destul de clar. Să verificăm formularea înainte să scriem cod: trei persoane, o notă de 1000. Ce sumă afișăm pentru fiecare?

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

Lipsește un ban. Îl puteți adăuga primei persoane, ultimei sau puteți lăsa utilizatorul să aleagă. Formularea "împărțim egal" nu rezolvă asta. Iar acum e o decizie pentru dumneavoastră, nu o întrebare despre JavaScript.

Pentru pagina noastră alegem următoarea regulă: diferența dintre părți nu depășește un ban; restul se distribuie câte un ban primilor participanți din listă. Astfel, pentru 1000 împărțit la trei obținem 333,34; 333,33; 333,33. Pentru 1000,01 sunt doi bani rămași: 333,34; 333,34; 333,33. Toți banii sunt distribuiți, iar suma părților corespunde notei.

Acum îi cerem agentului să adauge decizia aleasă în document:

Adaugă regula de rotunjire la comportamentul dorit din TASK_SPEC.md.
Arată-mi rândurile modificate. Deocamdată nu schimba codul.

Verificăm dacă fișierul conține o înregistrare de felul acesta:

Suma părților este exact egală cu totalul.
Diferența dintre părți nu depășește 0,01.
Banii rămași se distribuie câte unul primilor participanți;
pagina explică această regulă.

Citiți cu atenție formularea "câte unul primilor participanți". Dacă agentul a scris "tot restul primei persoane", a schimbat decizia: cu doi bani rămași, prima persoană ar plăti cu 0,02 mai mult decât celelalte. Cereți-i să corecteze rândul și verificați din nou fișierul. Contează sensul, nu reproducerea cuvânt cu cuvânt.

Iată de ce merită să testați specificația pe numere concrete. Am găsit decizia lipsă înainte ca agentul să-și aleagă varianta și să scrie codul pentru ea. Până acum am corectat doar câteva rânduri.

Lăsați-l pe Claude să pună întrebări

Nu veți observa singur toate lacunele. Dați-i ciorna agentului și cereți-i să vă ajute cu formularea sarcinii:

Citește @TASK_SPEC.md. Ajută-mă să găsesc condițiile lipsă.
Pune întrebările pe rând, una câte una, și propune un răspuns pentru fiecare.
Nu considera propunerea ta acceptată până nu răspund.
După fiecare decizie convenită, actualizează TASK_SPEC.md
și arată-mi fragmentul modificat ca să-l pot verifica.
Deocamdată nu scrie cod.

Mai jos este un exemplu de astfel de conversație. În sesiunea dumneavoastră întrebările pot fi altele; important e să urmăriți cum răspunsurile modifică documentul.

Claude: "Bacșișul este inclus în suma notei sau se adaugă separat? Propun un câmp separat pentru procent, cu valoarea inițială 0".
Dumneavoastră: "Separat. Calculăm procentul din suma notei, adăugăm bacșișul și împărțim totul împreună. Afișează pe pagină suma bacșișului și totalul".

Claude: "Dacă bacșișul include o fracțiune de ban, cum rotunjim? Propun rotunjirea la cel mai apropiat ban, iar exact jumătate de ban în sus".
Dumneavoastră: "Da. Mai întâi rotunjim suma bacșișului, apoi o adăugăm la notă. După aceea împărțim totalul după regula noastră".

Claude: "Ce valori acceptăm? Propun o sumă pozitivă cu punct sau virgulă, un număr întreg de persoane de la unu în sus și un procent întreg, nenegativ. La o eroare, afișăm un indiciu lângă câmp".
Dumneavoastră: "E bine. Suma poate avea cel mult două cifre după separator, fără separatori între mii. Dacă un câmp e gol sau valoarea e greșită, ascundem rezultatul, chiar dacă s-a calculat deja".

Am clarificat mai mult decât bacșișul. Acum sunt definite valorile acceptate, ordinea rotunjirii și comportamentul la eroare. După ce consemnăm răspunsurile, verificăm fragmentul actualizat:

Bacșiș: câmp separat cu procent întreg de cel puțin 0, valoare inițială 0.
Calculăm bacșișul din notă și îl rotunjim la cel mai apropiat ban;
exact jumătate de ban se rotunjește în sus.
Adăugăm bacșișul rotunjit la notă, apoi împărțim totalul.
Afișăm suma bacșișului, totalul și partea fiecăruia.
Dacă o valoare lipsește sau nu este validă, ascundem rezultatul,
iar lângă câmpul respectiv apare un indiciu.

Verificăm ordinea: mai întâi se rotunjește bacșișul, apoi se adaugă la notă, iar la final se împarte totalul. Aceleași cuvinte într-o altă ordine ar duce la o cerință diferită. Îi cerem agentului să actualizeze și scope-ul: în prima versiune au apărut câmpul pentru bacșiș și calculul totalului. Verificăm dacă a modificat într-adevăr ambele blocuri, nu doar a confirmat în chat.

Rezultatul și metoda de verificare

"Suma părților este egală cu totalul" e o cerință pentru rezultat. "Introducem 1000, trei persoane și bacșiș de 0%; apăsăm butonul; vedem 333,34, 333,33 și 333,33" e o verificare. Ea stabilește acțiunea și observația așteptată.

Îi cerem agentului să adauge acum câteva verificări de acest fel în fișier, înainte de implementare. Numerele așteptate le verificăm noi înșine. Altfel, e ușor să acceptăm ce a ieșit și să ne ajustăm pe nesimțite așteptările după pagina gata făcută.

Rândul cu 10,05 verifică ordinea operațiilor: 10% dau 1,005, care se rotunjește la 1,01. Dacă rotunjim în alt moment, totalul poate fi diferit. Pentru a verifica formatul, repetați testul cu punct: 10.05 ar trebui să dea același rezultat. Încercați separat o sumă negativă, un număr fracționar de persoane, un procent negativ sau fracționar și un câmp gol pentru bacșiș: nu ar trebui să se facă niciun calcul.

Fiecare condiție importantă are o observație asociată. "Pagina s-a deschis" nu dovedește încă faptul că sumele sunt corecte, la fel cum adresa corectă a unui link nu dovedește că s-a încărcat pagina dorită. Verificați comportamentul pentru care ați început sarcina.

Asamblăm TASK_SPEC

Agentul a strâns deciziile în fișier pe măsură ce le-am discutat. Acum îl recitim integral: sunt incluse răspunsurile, corespund verificările cerințelor, au rămas condiții vechi? Așa arată documentul final din exemplul nostru. Are șase repere: contextul, comportamentul dorit, scope, non-goals, planul de verificare și pornirea în siguranță. Titlurile vă ajută să găsiți repede secțiunea potrivită, iar conținutul a apărut din analiza sarcinii.

# TASK_SPEC.md

## CONTEXT
Un grup de prieteni vrea să împartă nota de la restaurant.
Proiectul încă nu există; folderul de lucru este gol, în afară de TASK_SPEC.md.

## COMPORTAMENTUL DORIT
Rezultatul este index.html, care se deschide cu dublu clic,
și o scurtă descriere a verificării.
Pagina are trei câmpuri și un buton "Calculează":
- suma notei mai mare decât 0, cu cel mult două zecimale;
  separatorul este punct sau virgulă, fără separatori pentru mii;
- numărul de persoane este întreg și cel puțin 1;
- procentul bacșișului este întreg și cel puțin 0, valoare inițială 0.
Bacșișul se calculează din notă și se rotunjește la cel mai apropiat ban;
exact jumătate de ban se rotunjește în sus.
Bacșișul rotunjit se adaugă la notă, apoi se împarte totalul.
Se afișează bacșișul, totalul și părțile numerotate ale participanților.
Suma părților este egală cu totalul, iar diferența dintre ele nu depășește 0,01.
Restul se distribuie câte un ban primilor participanți;
pagina explică această regulă.
Dacă o valoare lipsește sau nu este validă, rezultatul e ascuns,
iar câmpul completat incorect afișează un indiciu.

## SCOPE
O singură pagină: trei câmpuri, calcul, indicii și afișarea sumelor.
Împărțim totalul în mod egal, distribuind restul conform regulii descrise.

## NON-GOALS
Nu avem nevoie de conturi sau istoric al notelor: nu stocăm date.
Nu împărțim nota pe feluri: aceasta e o altă versiune a calculatorului.
Constrângere: stilurile și scriptul rămân în index.html,
fără server și biblioteci externe, pentru a deschide fișierul local.

## PLAN DE VERIFICARE
Deschideți index.html cu dublu clic. Apăsați "Calculează" pentru:
- 1000 / 3 persoane / 0% → 333,34; 333,33; 333,33;
- 1000,01 / 3 / 0% → 333,34; 333,34; 333,33;
- 1000 / 3 / 10% → bacșiș 100,00, total 1100,00,
  părți 366,67; 366,67; 366,66;
- 10,05 / 3 / 10% → bacșiș 1,01, total 11,06,
  părți 3,69; 3,69; 3,68; introducerea lui 10.05 dă același rezultat;
- 1000 / 1 / 0% → o singură parte de 1000,00.
În fiecare caz, adunați părțile și comparați-le cu totalul.
Verificați zero și un număr fracționar de persoane, o sumă negativă,
un procent negativ sau fracționar, mai mult de două zecimale
în sumă și, pe rând, fiecare câmp lăsat gol:
indiciu lângă câmp, rezultat ascuns, inclusiv după un calcul.
Verificați numerotarea părților și explicația distribuirii banilor.

## PORNIRE ÎN SIGURANȚĂ
Citiți specificația și verificați conținutul folderului de lucru.
Dacă există deja fișiere de proiect, opriți-vă și clarificați sarcina;
nu suprascrieți și nu ștergeți fișierele existente.
Mai întâi întrebări și plan fără cod, apoi așteptați aprobarea.
Dacă implementarea necesită modificări în afara scope-ului,
clarificați specificația înainte de a le face.

Documentul a crescut datorită deciziilor care chiar au fost necesare. Nu conține o rețetă pas cu pas pentru JavaScript, dar arată ce facem cu bacșișul și cum verificăm banii mărunți. În sarcina dumneavoastră pot fi mai puține detalii.

Când vă formulați propria specificație, vă ajută să parcurgeți această scurtă fișă:

Dacă se schimbă condițiile

Acum o mică verificare pentru dumneavoastră. Utilizatorul a citit specificația și spune: "Procentul e incomod. Vreau să introduc bacșișul ca sumă, de exemplu 100". Ce secțiuni din TASK_SPEC trebuie actualizate? Încercați să le numiți înainte să citiți explicația.

La comportamentul dorit, câmpul procentului devine un câmp pentru suma bacșișului: nenegativă, cu punct sau virgulă și cel mult două zecimale. Valoarea inițială rămâne 0. Eliminăm formula procentului și rotunjirea bacșișului calculat: adăugăm pur și simplu suma introdusă la notă. În scope se schimbă calculul, iar în planul de verificare se schimbă datele de intrare și cazurile cu valori incorecte. Împărțirea totalului și non-goals rămân la fel.

Testul "notă 1000, bacșiș 100, trei participanți" va da valorile cunoscute: 366,67; 366,67; 366,66. Dar doar după aceste numere nu putem deosebi versiunea nouă de cea veche, cu bacșiș de 10%. Adăugați o altă notă: 500 plus un bacșiș fix de 100, pentru două persoane. Fiecare ar trebui să primească 300; vechiul procent de 10% ar da câte 275. Iată un test care surprinde schimbarea regulii.

Cereți-i agentului să actualizeze comportamentul dorit, scope-ul și verificările, apoi să vă arate toate fragmentele modificate. Deschideți fișierul și asigurați-vă că formula procentului a fost eliminată, iar noile verificări corespund introducerii unei sume. Nu păstrați formula veche lângă o mențiune nouă "acum ca sumă": specificația trebuie să dea un singur răspuns. În exemplul principal de mai sus am păstrat varianta inițială cu procent; aici am analizat o modificare separată.

Cum funcționează împreună cu Claude Code

După ce verificați modificările individuale, recitiți întregul TASK_SPEC înainte de a începe implementarea. Asigurați-vă că obiectivul, limitele și verificările descriu aceeași sarcină. Apoi indicați-i explicit fișierul agentului:

Citește @TASK_SPEC.md. Mai întâi verifică dacă există contradicții
sau condiții care mai trebuie clarificate.
Arată-mi un plan scurt și lista fișierelor pe care le vei crea sau modifica.
Nu schimba codul până nu aprob planul.

Acum aveți ce verifica înainte de implementare. Dacă planul include un server pentru stocarea notelor, cereți refacerea lui: istoricul este exclus, iar pagina trebuie să se deschidă local. Dacă planul vi se potrivește, aprobați implementarea. Apoi deschideți fișierul rezultat și parcurgeți scenariile consemnate, inclusiv introducerea unei valori incorecte după un calcul reușit.

Non-goals rămân condiții textuale, nu blochează tehnic modificările. De aceea sunt importante atât examinarea planului, cât și verificarea rezultatului. Mesajul agentului "gata" vă ajută să înțelegeți ce a făcut, dar nu înlocuiește valorile de control.

Dacă păstrați TASK_SPEC în proiect după încheierea lucrului, marcați sarcina ca închisă. Cât timp lucrarea e în desfășurare, mențineți deciziile din fișier actualizate. Lăsați agentul să formuleze și să consemneze, iar dumneavoastră verificați deciziile direct în document: fragmentul modificat după discuție și întregul fișier înainte de implementare.