Cum să gestionați o sarcină mare: context și etape verificabile

O sarcină mare începe de obicei cu o cerere care pare rezonabilă: "Creează un catalog de locale: o listă, o funcție de căutare și un filtru după țară, cu un aspect îngrijit." O oră mai târziu, aveți în față o pagină cu lista făcută pe jumătate, căutarea care nu acoperă toate câmpurile și un design schimbat deja de două ori. Conversația s-a lungit atât de mult, încât nu mai e clar ce rezultat a fost verificat și ce a fost doar promis.

Un motiv posibil este că sarcina nu a fost împărțită în părți cu rezultate clare. Asta nu exclude erorile din cod, dar le face mai ușor de verificat atunci când știți ce ar trebui să funcționeze acum. Să vedem cum împărțiți lucrul în etape verificabile, ce informații îi dați agentului pentru etapa curentă și ce notați ca să reveniți mâine la sarcină, în aceeași conversație sau într-una nouă, fără să reconstruiți totul din memorie.

Așa ar trebui să arate catalogul: o listă cu funcție de căutare, iar fiecare rând să conțină codul localei, limba, țara, moneda și domeniul. Țineți minte acest model: în exercițiu vă va servi drept exemplu de stil, nu doar drept ilustrație.

Sarcini mari și conversații lungi

O sarcină lungă se poate bloca înainte să apară vreo eroare în cod: procesul își pierde forma. Contextul crește, ipotezele se amestecă cu deciziile luate, iar pe lângă căutare apare pe nesimțite și refacerea designului. Fereastra de context are o limită, dar problema principală e că devine neclar ce facem acum și ce este deja gata.

TASK_SPEC stabilește scopul, limitele și verificarea întregii sarcini. Apoi, lucrul se împarte în etape verificabile - milestones. Fiecare are un rezultat și limite clare: de exemplu, adăugați căutarea fără să schimbați datele sau designul. Astfel, Claude se poate concentra pe sarcină, iar dumneavoastră vedeți în ce stadiu se află.

Dacă sarcina nu este încă bine definită, prima etapă poate fi o explorare: citiți două-trei fișiere importante, enumerați variantele de soluționare și riscurile, apoi clarificați descrierea sarcinii și etapele următoare.

Încheiați fiecare etapă cu verificări și un rezumat scurt (summary): ce s-a făcut, cum s-a verificat și ce urmează. Dacă proiectul este gestionat în Git, salvați modificările verificate într-un commit mic. Rezumatul păstrează deciziile, iar commitul, versiunea codului; împreună vă ajută să verificați rezultatul și să reluați lucrul după o pauză.

Ce înseamnă o etapă

Milestone, adică un reper, este punctul în care sarcina are un rezultat intermediar care poate fi verificat. Vom numi în continuare etapă lucrul până la acel punct.

O etapă are trei componente obligatorii:

• rezultat - ce anume va începe să funcționeze;
• limite - ce nu atingem de data aceasta;
• verificare - ce veți examina ca să vă convingeți.

Diferența se vede în formulare. "Să lucrăm la căutare" nu are un punct clar de finalizare: puteți lucra la nesfârșit, iar oricine poate decide când e "gata". "Căutarea găsește înregistrarea după codul localei, iar o căutare goală afișează întreaga listă" are un rezultat concret, vizibil în browser în jumătate de minut.

Nu există o limită universală de timp sau de număr de fișiere. Totuși, dimensiunea contează: dacă o etapă amestecă mai multe modificări independente și nu puteți verifica rezultatul într-o singură parcurgere clară, merită s-o micșorați. Orientați-vă după cel mai apropiat rezultat util pe care îl puteți obține și verifica separat.

Împărțiți rezultatul în părți funcționale

Să luăm un catalog didactic de locale. Înregistrările au aceleași câmpuri ca în modelul de mai sus: codul localei, limba, țara, moneda și domeniul. Ca să simplificăm exemplul, tabloul cu date este direct în app.js, inclus în index.html. Pagina nu încarcă datele printr-o cerere separată, așa că o puteți deschide în browser fără server. Iată datele:

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

Cerința completă sună astfel: o listă, căutare și filtru după țară. Nu transformăm "un design îngrijit" din introducere într-o etapă separată: pagina primește aspectul de bază odată cu lista de la M1, iar la "pentru mai târziu" ajunge doar designul nou, adică schimbarea temei. Să împărțim cerința în trei etape.

Mai întâi avem nevoie de o listă funcțională: pe ea puteți verifica ușor filtrarea înregistrărilor. Puteți adăuga căutarea și filtrul în orice ordine; aici începem cu căutarea, iar la M3 verificăm cum funcționează împreună. Săgeata dintre etape arată că rezultatul anterior a fost verificat, iar M3 verde este etapa după care cerința este îndeplinită complet.

Aici împărțim lucrul după rezultat. În fiecare etapă există citirea codului, modificări și verificare. Un plan de tipul "mai întâi tot HTML-ul, apoi tot JS-ul și verificăm la final" amână verificarea comportamentului până la sfârșit. Și un markup gata făcut poate fi un rezultat intermediar util, dar nu arată încă dacă funcționează căutarea.

Țineți cont că agentul tinde să propună tocmai un astfel de plan, pe straturi: mai întâi tot markupul, apoi toată logica. Vorbesc despre asta și cei care lucrează mult cu agenți AI, de exemplu Matt Pocock în atelierul despre procesul său. Un astfel de plan apare chiar și atunci când îi cereți explicit să împartă lucrul după rezultate. Așadar, verificați etapele propuse de agent după un criteriu: puteți să deschideți ceva la finalul fiecărei etape și să vedeți că funcționează?

Iar cele trei etape de aici sunt un exemplu, nu o regulă. Pot fi două sau șase.

Dați contextul etapei curente

După ce ați ales etapa, agentul are nevoie de informațiile relevante pentru ea, nu de întregul proiect. O cerere pentru M2 în catalogul didactic ar putea arăta așa:

Adăugăm căutarea în lista de locale.
Lista cu patru înregistrări funcționează deja. Păstrează câmpurile și designul,
nu modifica datele din tabloul inițial. Adaugă doar elementele pentru căutare.

Citește @index.html și @app.js.

Avem nevoie de:
- un câmp de căutare deasupra listei;
- căutare după codul localei și numele limbii;
- căutările de-DE și German găsesc înregistrarea de-DE;
- căutarea zzz nu lasă niciun rând în listă;
- o căutare goală afișează întreaga listă.

De data aceasta nu adăugăm filtrul după țară.
Dacă ai nevoie de alt fișier, numește-l și citește-l.
Mai întâi numește rezultatul și limitele etapei; deocamdată nu modifica fișierele.

Dacă limitele propuse vi se par potrivite, cereți-i în mesajul următor să execute M2 și să enumere verificările din browser. Cereți-i și să separe ce a verificat singur de ce mai trebuie să verificați dumneavoastră.

Căile din exemplu sunt orientative, fișierele dumneavoastră vor fi altele. Dacă agentul are nevoie de o sursă care nu apare în cerere, trebuie s-o numească și s-o citească. Nu are rost să ghicească ce conține un fișier doar după nume și nici să-i cereți asta.

Designul este un tip separat de informație și, în etapa aceasta, tocmai el trebuie păstrat. Uneori e invers: aspectul vizual face parte din rezultatul etapei, de exemplu când pagina apare pentru prima dată. Nu îl puteți descrie în cuvinte - o cerere precum "fă-l frumos" nu oferă criterii verificabile, iar decizia rămâne la agent. Atașați atunci un model: o machetă, o captură de ecran sau un fișier mic cu culori și nume de clase.

Mai e bine să țineți minte ce nu înseamnă o astfel de formulare. Linia "de data aceasta nu adăugăm filtrul" este o instrucțiune, nu o barieră tehnică. Indică direcția, dar nu blochează nimic, așa că tot dumneavoastră verificați rezultatul.

Când e cazul să micșorați etapa

Etapele au tendința să crească pe măsură ce lucrați. Ați început cu căutarea, iar pe parcurs a devenit clar că ar fi bine să schimbați structura datelor, să actualizați și designul și să adăugați o navigare în partea de sus. Sună cunoscut.

Pentru fiecare cerință suplimentară, întrebați-vă dacă este necesară pentru rezultatul ales. O temă de culori nouă și navigarea pot aștepta, dar câmpul vizibil de căutare este necesar. Dacă în înregistrări lipsesc datele după care trebuie să căutați, clarificați mai întâi limitele: puteți completa datele în etapa curentă sau puteți face din pregătirea lor o etapă verificabilă separată. Interdicția de a modifica datele nu poate fi anulată pe tăcute în timpul lucrului.

O cerere de clarificare poate fi scurtă:

De data aceasta nu schimbăm datele, designul sau navigarea.
Notează-le separat pentru mai târziu.
Păstrăm căutarea după cod și limbă: câmpul de intrare, potrivirile, căutarea goală.

O etapă se încheie când ați obținut rezultatul convenit și l-ați verificat. Dacă verificarea nu a trecut, ocupați-vă mai întâi de etapa curentă; trecerea la următoarea ar adăuga doar incertitudine.

Se mai întâmplă ca o etapă să nu înainteze: îi corectați agentului direcția, el reface, dar rezultatul tot nu e bun. Încercările nereușite rămân în conversație, iar următoarea încercare se bazează deja pe ele. Documentația Claude Code oferă o regulă practică simplă: dacă a trebuit să corectați același lucru de mai mult de două ori, începeți o conversație nouă, cu o cerere care include tot ce ați aflat între timp. De exemplu: "varianta cu un tablou separat pentru căutare nu funcționează, fiindcă diferă de datele inițiale; caută direct în tabloul principal". De obicei, o astfel de cerere e mai eficientă decât a treia corectură la rând. Dacă nici ea nu ajută, probabil etapa e prea mare și merită împărțită.

Păstrați un punct de reluare

Ramura din stânga vă întoarce la modificările aceleiași etape: rezultatul nu este încă confirmat. Cea din dreapta duce la notarea stării și la etapa următoare. În notă, păstrați atât verificările reușite, cât și lucrurile pe care acestea nu le-au acoperit.

Ați verificat rezultatul? Notați starea. Nota nu este pentru raportare, ci ca să nu reconstituiți din conversație, peste o zi sau într-o discuție nouă, tot istoricul lucrului.

Numele fișierului nu contează; puteți folosi și o notă de lucru existentă. Să-i spunem PROGRESS.md. Mai jos este un exemplu didactic după verificarea M1. În nota dumneavoastră scrieți doar ce ați făcut și observat cu adevărat:

# Catalog de locale

## Realizat
M1: pagina afișează lista de locale din tabloul din app.js.

## Verificat
Am deschis index.html în browser: 4 înregistrări, toate cele cinci câmpuri
ale fiecărui rând corespund tabloului inițial din app.js.

## Neverificat
Ce afișează pagina când setul de date este gol.
Această verificare nu făcea parte din criteriile M1; comportamentul cu un tablou gol nu este încă cunoscut.

## Decizii
Păstrăm datele într-un tablou din app.js, fără încărcare separată.
La adăugarea căutării, păstrăm înregistrările și designul.

## Eliminat
Încărcarea datelor dintr-un fișier JSON separat: fără server, browserul
nu îl va putea citi, iar pagina trebuie să se deschidă ca fișier.

## Fișiere
index.html, app.js

## Etape rămase
M2: căutarea funcționează după codul localei sau numele limbii.
Verificare: de-DE și German găsesc înregistrarea de-DE;
zzz nu găsește nicio înregistrare; o căutare goală le afișează pe toate patru.

M3: filtrul după țară funcționează împreună cu căutarea.
Verificare: Canada + French lasă fr-CA;
Canada + German dau o listă goală;
resetarea ambelor condiții readuce patru înregistrări.

## Pasul următor
Executați M2. Deocamdată nu adăugați filtrul după țară.

Secțiunea esențială este "Verificat". Nota "totul funcționează" nu vă spune nimic peste o săptămână, dar "am deschis în browser, sunt 4 înregistrări, câmpurile corespund" vă spune. Secțiunea separată pentru ce nu a fost verificat este utilă tocmai fiindcă mâine s-ar putea să nu mai țineți minte diferența.

Secțiunea "Eliminat" poate părea inutilă, fiindcă notează ceva ce nu există în proiect. Dar într-o conversație nouă agentul nu știe nimic despre încercările anterioare și poate propune din nou aceeași soluție. O singură linie cu motivul vă scutește de o tură întreagă.

Puteți cere agentului să scrie nota, dar comparați-o cu fișierele actuale și rezultatele verificărilor. S-ar putea baza pe istoricul conversației, unde planurile apar alături de acțiunile efectuate. Pentru observațiile făcute în browser, notați cine le-a făcut; nu-i atribuiți agentului o verificare pe care nu a rulat-o.

Două limite. Starea temporară a sarcinii nu se mută în CLAUDE.md - acolo sunt regulile permanente ale proiectului, nu lucrurile la care lucrați azi. Iar nota nu salvează versiunea codului: descrie starea, nu este o copie a fișierelor.

Continuați cu informațiile necesare

Limita dintre etape este un moment potrivit să decideți în ce conversație veți lucra mai departe. Întrebarea e simplă: conversația curentă vă ajută la pasul următor sau a început să vă încurce?

Dacă vă ajută, continuați în ea; nu trebuie să faceți nimic special. Nu există o regulă care să vă oblige să "curățați conversația după fiecare etapă" și nici un prag procentual după care ar trebui să o luați de la capăt.

Dacă nu știți cât spațiu ocupă istoricul, apelați /context și vedeți cât din fereastra de context este folosită. Raportați cifra la lucrul curent: de care dintre ieșirile lungi ale comenzilor și discuții mai are nevoie etapa următoare? Comanda vă ajută să estimați volumul, dar nu decide în locul dumneavoastră ce informații sunt utile.

Dacă s-au adunat informații care nu mai sunt relevante și ați decis să începeți o conversație nouă, salvați mai întâi nota. Comanda /clear pornește o conversație nouă: istoricul anterior nu mai face parte din contextul ei de lucru, fișierele sursă rămân pe disc, iar instrucțiunile proiectului se încarcă în continuare. Nu șterge definitiv conversația veche: puteți reveni la ea cu /resume. Totuși, pentru a continua într-o sesiune nouă, transmiteți explicit deciziile de care aveți nevoie.

Cele două săgeți se întâlnesc înainte să continuați lucrul. Nota transmite deciziile și rezultatele verificărilor, iar fișierele arată codul actual. Agentul citește ambele surse și rezumă starea; verificați răspunsul înainte să-i dați M2.

Într-o conversație nouă, puteți începe simplu:

Citește @PROGRESS.md, @index.html și @app.js.
Spune cu cuvintele tale ce este gata și verificat și ce a rămas.
Deocamdată, nu modifica fișierele.

Citiți cu atenție răspunsul. Dacă agentul spune că este gata ceva ce nu ați făcut, comparați ce spune cu nota, fișierele și rezultatele verificărilor. Cauza poate fi o notă imprecisă, un cod învechit sau o greșeală a agentului. Corectați neconcordanța înainte de alte modificări: o conversație nouă nu repară singură o cerință formulată greșit și nici nu garantează că a fost înțeleasă corect.

Parcurgeți întregul catalog

Explicația s-a încheiat; acum lucrați singuri la același catalog, de la un folder gol până la un M2 verificat și un punct de reluare. Cei patru pași urmează ordinea articolului. Încercați mai întâi să formulați singuri promptul, apoi deschideți varianta noastră ca a doua opinie. Ideea este să decideți de ce informații are nevoie agentul, nu să copiați o frază.

Pasul 1. Plan fără cod

Încă nu există un proiect și primul impuls este să cereți "creează un catalog". Atunci fișierele vor apărea înainte să luați decizii despre ele. Scopul pasului este opus: obțineți un plan și niciun fișier. Înainte să scrieți, gândiți-vă la patru lucruri:

• cum să împiedicați agentul să înceapă imediat să scrie cod;
• ce informații să-i dați în locul fișierelor care încă nu există;
• ce limite tehnice să precizați ca să nu apară un instrument în plus;
• ce să-i cereți ca rezultat, dacă încă nu e nimic de creat.

Iată varianta noastră:

Vreau un catalog didactic de locale: o listă de înregistrări, o funcție de căutare
și un filtru după țară. Încă nu există proiectul.

Pagina trebuie să se deschidă în browser ca fișier, fără server sau build:
doar index.html, styles.css și app.js. Fiecare înregistrare are câmpurile codul localei (en-US),
limba, țara, moneda și domeniul.

Mai întâi, fă un plan:
- numește scopul, limitele și metoda de verificare pentru întreaga sarcină;
- împarte lucrul în trei etape;
- pentru fiecare, numește rezultatul și ce voi vedea la verificare;
- spune-mi ce informații îți lipsesc;
- enumeră fișierele pe care le-ai crea.

Deocamdată, nu crea fișiere.

Comparați etapele propuse cu tabelul M1-M3 de mai sus; e în regulă și altă ordine. Dacă agentul a împărțit lucrul în "tot markupul, apoi tot JS-ul", cereți-i să refacă planul astfel încât pagina să facă ceva după fiecare etapă. Iar dacă nu a numit un comportament observabil pentru o etapă, clarificați formularea acum: înainte de prima linie de cod, ajunge un singur mesaj.

Pasul 2. Doar M1, cu un model vizual

Limitele sunt înguste: pagina afișează patru înregistrări și atât. Fără căutare și fără filtru. Aspectul nu poate fi amânat, fiindcă pagina apare pentru prima dată și tot va avea un design. Atașați-i un model: salvați în folderul proiectului mockup.html, cu markup static fără JavaScript, doar culori și nume de clase.

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- rând de exemplu; rândurile reale sunt generate de app.js -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>

Câmpul de căutare este deja desenat în model, dar nu îl mutăm pe pagina M1: un câmp gol, care nu face nimic, e greu de verificat. Stilul lui este în clasa .search și va fi util la M2.

Încă un detaliu: trebuie să-i dați agentului datele explicit. Fără ele, va inventa propriul set, iar verificările din tabel - cele patru rânduri, de-DE și Canada - nu se vor mai potrivi. Acum formulați promptul: gândiți-vă cum îl mențineți pe agent în limitele unei singure etape, ce îi cereți să vă arate înainte de modificări și cum veți verifica rezultatul.

Executăm doar M1: pagina afișează lista de locale
din tabloul din app.js. De data aceasta nu există căutare sau filtru,
nu adăuga încă nici câmpul de căutare din model.

Datele sunt acest tablou cu patru înregistrări; nu-i modifica conținutul:
[inserați tabloul din articol]

Folosește aspectul din @mockup.html: culorile și numele claselor de acolo,
nu inventa altele.

Mai întâi arată planul fișierelor și spune unde te vei opri.
Nu crea fișiere până nu aprob planul.
După modificări, spune-mi ce să deschid și cu ce să compar.

Oprește-te după M1; nu trece la M2 fără acordul meu.

Planul s-a extins? Nu-l aprobați; mai întâi restrângeți etapa la un singur rezultat verificabil. Dacă planul e bun, aprobați modificările, apoi deschideți pagina și comparați cele patru rânduri cu tabloul. Aspectul de bază este acum stabilit: îl păstrați mai departe, iar schimbarea completă a temei rămâne pe lista lucrurilor amânate.

Pasul 3. M2 și o notă sinceră

Promptul pentru M2 a fost deja analizat la secțiunea "Dați contextul etapei curente". Reveniți la el și înlocuiți căile cu ale dumneavoastră. În exemplu sunt două fișiere, dar după M1 aveți trei: pe lângă index.html și app.js, aveți și styles.css. Includeți-l și pe acesta. Adăugați o singură linie: acum păstrăm aspectul, nu îl mai definim.

Aspectul a fost stabilit la M1 pe baza @mockup.html - păstrează-l neschimbat,
formatează câmpul de căutare cu clasa .search de acolo.

Agentul a numit corect limitele? Aprobați modificările. A început să lucreze la filtru sau la structura datelor? Cereți-i să clarifice înainte să continue. După ce au trecut cele trei verificări ale căutării, notați starea în PROGRESS.md după modelul de mai sus, dar acum după M2 și cu lista dumneavoastră de fișiere.

Verificați și cât de utilă este nota. Imaginați-vă că în locul secțiunii "Verificat" scrie "aproape totul e gata, a mai rămas puțin". Peste o săptămână, asta nu vă va spune nimic. Completați nota astfel încât să vă ajute să reluați lucrul: ce ați deschis și ce ați văzut, ce a rămas în afara verificărilor, care este pasul următor. De exemplu: "M2: căutările de-DE și German găsesc de-DE, zzz nu găsește nimic, o căutare goală afișează patru înregistrări", "nu am verificat comportamentul cu un set de date gol", "pasul următor: M3, filtrul după țară".

Pasul 4. Continuați într-o conversație nouă

Ultimul pas verifică nota, nu codul. Începeți o conversație nouă și cereți-i agentului să rezume starea pe baza fișierului PROGRESS.md și a tuturor celor trei fișiere actuale, inclusiv styles.css. Apoi comparați rezumatul cu ce ați făcut. Agentul spune că e gata ceva ce nu ați verificat? Probabil nota este prea vagă, iar soluția este s-o corectați, nu să începeți altă conversație. Verificați și fișierele: cauza poate fi în cod sau într-o greșeală a agentului. Dacă totul corespunde, aveți M1 și M2 verificate și un punct de pornire pentru M3.

Cum treceți la etapa următoare

În final, succesiunea e scurtă:

1. alegeți cel mai apropiat rezultat care poate fi verificat;
2. dați-i agentului sursele necesare pentru etapa respectivă și precizați limitele;
3. executați etapa curentă; notați separat cerințele noi;
4. faceți verificarea convenită; în exemplul nostru, verificați comportamentul paginii în browser;
5. notați starea: ce s-a făcut, ce s-a verificat și ce nu, ce a fost eliminat, pasul următor;
6. decideți dacă continuați în conversația curentă sau începeți una nouă.

O etapă nu înseamnă un singur mesaj. Pot fi trei sau chiar cincisprezece, și e în regulă. Numărul etapelor nu este egal nici cu cel al conversațiilor: două etape alăturate pot continua fără probleme în aceeași conversație, iar una dificilă se poate întinde uneori pe două.

În schimb, la fiecare pas veți putea spune ce funcționează deja și cum a fost verificat. Pentru o sarcină mare, probabil acesta e cel mai important lucru.