Patru tipuri de sarcini pentru agent

"Terminați pagina principală a portalului" poate ascunde mai multe lucruri diferite. În lista de promoții lipsește un filtru. Butonul bannerului duce în altă parte. Pregătirea datelor pentru clasament este scrisă de două ori, iar fiecare modificare costă de două ori mai mult. Iar de unde vine, de fapt, adresa promoției nu mai știe nimeni cu siguranță.

Cel mai probabil, o persoană ar cere lămuriri. Și Claude Code poate face asta, dar adesea completează singur golurile cu o soluție plauzibilă pe care nimeni n-a cerut-o. Iar pentru fiecare tip de sarcină soluția în plus arată altfel: filtrul primește și o căutare, repararea linkului vine la pachet cu un design nou, refactoringul "repară" și sortarea, iar cercetarea se încheie cu modificări.

Ce trebuie să se schimbe

Cel mai simplu este să deosebiți tipurile după ce va fi diferit la finalul lucrului:

• apare un comportament care nu exista înainte - feature, o funcție nouă;
• comportamentul devine cel așteptat -bugfix, repararea unei erori. Aici intră și ceva deja implementat, dar care n-a funcționat niciodată cum s-a convenit;
• în exterior totul e ca înainte, dar codul din interior e organizat diferit - refactoring;
• primiți răspunsul la o întrebare despre proiect, iar fișierele sursă rămân neschimbate - research, cercetare.

Tipul vă sugerează ce să precizați în solicitare și ce să verificați. Câtă libertate îi dați agentului depinde și de costul unei erori și de dimensiunea sarcinii: o modificare în cod folosit de oameni cere mai multă atenție decât o pagină nouă într-un proiect didactic. Uneori, sarcina combină mai multe tipuri, de pildă cercetare urmată de o modificare. Atunci fiecare etapă are propriul rezultat și propria limită.

O funcție nouă

În lista de promoții e nevoie de un comutator care să le lase doar pe cele active. Stabilim condițiile de la început: o promoție e activă dacă are indicatorul active: true; promoțiile A și C au indicatorul activat, iar B nu. Datele sunt didactice, iar solicitările de mai jos sunt exemple pe care le puteți adapta la proiectul dumneavoastră.

Agentul va executa probabil solicitarea "Adaugă filtrul pentru promoțiile active" și va face chiar mai mult. Rezultatul ar putea arăta așa: apare comutatorul, lângă el și un câmp de căutare "dacă tot filtrăm", plus o sortare după data de încheiere. Fiecare adaos pare rezonabil de unul singur. Împreună, transformă o singură funcție într-un mic subsistem pe care nimeni nu l-a cerut și pe care va trebui să-l verificați.

Adaosurile în plus se văd, măcar, pe pagină. Mai rău e când agentul ia în tăcere o decizie pe care nu ați luat-o dumneavoastră. Andrej Karpathy a povestit despre proiectul său MenuGen: autentificarea se face prin Google, plata prin Stripe, iar agentul a asociat achiziția cu contul după adresa de e-mail. Dacă adresele diferă în cele două servicii, plata nu ajunge în cont. Deciziile despre date - după ce criteriu asociem înregistrările și ce facem cu cele deja existente în proiect - vă aparțin, așa că e mai bine să le precizați direct în solicitare. La noi întrebarea e mai simplă: ce facem cu o promoție căreia îi lipsește indicatorul active?

O altă sursă de inițiative nesolicitate este exemplul. Agentul caută cod asemănător în proiect și îl imită, iar locul găsit poate fi tocmai cel pe care toată lumea vrea de mult să-l rescrie. Dacă proiectul are un exemplu bun, indicați-l chiar dumneavoastră.

O funcție nouă are nevoie de un singur scenariu pentru utilizator și de o listă explicită cu ce nu intră în sarcină:

Adaugă în lista de promoții de pe pagina principală un comutator "Doar active".
O promoție activă are active: true; dacă lipsește câmpul, promoția este inactivă.
Verificare pe datele actuale: activat - se văd A și C; dezactivat - A, B și C.
Nu adăuga căutare, sortare sau alte filtre; sunt sarcini separate.
Dacă proiectul are deja un comutator asemănător, procedează la fel
și spune pe care l-ai luat ca model.
Mai întâi descrie într-o propoziție scenariul pe care îl vei implementa
și așteaptă răspunsul meu. Deocamdată nu modifica fișierele.

Ultimele două rânduri costă puțin, dar sunt utile: dacă rezumatul scenariului diferă de ce aveți în minte, observați asta înainte de modificări. Când agentul vă arată planul, întrebați-l pe scurt dacă soluția nu e prea complicată sau incompletă și de ce crede asta. Întrebarea e utilă pentru orice plan, dar mai ales la un feature, fiindcă tocmai aici se ascund adaosurile. La final, verificați ambele stări ale comutatorului și vedeți dacă nu a apărut ceva în plus pe pagină.

Repararea unei erori

Butonul bannerului de pe pagina principală ar trebui să deschidă pagina /campaign/, cu condițiile promoției, dar duce la /old/.

Cea mai scurtă cale pentru agent este să introducă direct /campaign/ în linkul butonului. Dacă adresa era chiar în link, asta poate fi suficient. Dar dacă vine din date comune folosite și de alte butoane, înlocuirea ascunde doar simptomul: butonul acesta va funcționa, însă datele vor rămâne greșite. O altă inițiativă tipică este să schimbe spațierea și culoarea bannerului, fiindcă tot a deschis fișierul.

Doar din buton nu vă puteți da seama în care situație sunteți; asta se vede doar din cod.

Înainte să cereți ceva, reproduceți problema: apăsați butonul și vedeți unde duce. Dacă nu reușiți s-o reproduceți, nu închideți în grabă sarcina; clarificați mai întâi pașii și datele cu care a fost observată. După ce reproduceți problema, trebuie să-i aflați cauza. Nu știți de unde ia butonul adresa? E în regulă, aceasta este chiar prima întrebare pentru agent:

Butonul bannerului de pe pagina principală duce la /old/, dar ar trebui să ducă la /campaign/.
Mai întâi găsește de unde preia butonul adresa și arată-mi locul.
Deocamdată nu modifica fișierele.
După ce confirm, repară adresa acolo unde este definită.
Nu schimba designul bannerului.

După modificare, repetați acțiunea inițială: apăsați butonul, verificați adresa și asigurați-vă că pe pagină apar condițiile promoției. Dacă ați schimbat datele comune pentru adrese, verificați și un alt element care le folosește.

Schimbarea organizării codului

Pregătirea datelor pentru clasament este scrisă de două ori, aproape identic, iar orice modificare trebuie făcută în ambele locuri. Scopul este să rămână o singură versiune, fără să se schimbe tabelul.

Ceea ce trebuie să rămână neschimbat după modificare se numește invariant. Aici, invariantul este ordinea participanților și valorile din tabel pentru aceleași date.

O problemă de refactoring poate trece neobservată. Se schimbă sortarea participanților cu același punctaj, rotunjirea devine alta, iar niciun mesaj de eroare nu apare: tabelul doar afișează altceva. După ce unește cele două versiuni, agentul poate declara că "comportamentul nu s-a schimbat" fără să ruleze nimic. Sau poate "îmbunătăți" și sortarea, fiindcă cea veche i s-a părut ciudată.

Să luăm valorile în această ordine: A cu 10 puncte, C cu 20, B cu 20, D cu 15.5. În prezent, tabelul arată C: 20, B: 20, D: 15.5, A: 10. Tocmai acest rezultat al codului actual este referința pentru refactoring, chiar dacă ați prefera altceva. Ordinea e aleasă intenționat. C apare înaintea lui B, așa că dacă versiunea nouă începe să sorteze punctajele egale după nume, B va trece în față. Iar valoarea zecimală arată dacă se schimbă rotunjirea.

Solicitarea care evită ambele probleme:

Pregătirea datelor pentru clasament este duplicată; păstrează o singură versiune.
Nu schimba comportamentul tabelului, chiar dacă ceva pare ciudat;
notează separat aceste lucruri.
Înainte de modificare, rulează verificările existente și afișează tabelul
pentru setul A: 10, C: 20, B: 20, D: 15.5. Păstrează ambele rezultate.
După modificare, repetă aceeași verificare și compară rezultatele.
În raport, arată unde se află acum pregătirea datelor.

Comparați singuri rezultatele păstrate, nu vă bazați doar pe cuvântul "identic" din raport. Potrivirea arată doar că, pentru aceste date, comportamentul s-a păstrat. Iar ultimul rând din solicitare verifică sarcina propriu-zisă: un tabel identic nu înseamnă neapărat că duplicarea a fost eliminată.

Și aici, o soluție pe jumătate e mai rea decât niciuna. Să presupunem că o copie a rămas, iar o parte dintre apeluri folosește noua versiune. Tabelul e același, dar acum există două moduri de pregătire a datelor, iar la următoarea solicitare agentul poate folosi varianta veche: nu știe pe care s-o considere corectă. Dacă ați început să le uniți, duceți treaba până la o singură versiune; dacă nu reușiți, opriți-vă mai devreme și notați ce a rămas.

Cercetare fără modificări

Research se deosebește cel mai mult de celelalte tipuri: rezultatul este un răspuns, nu un proiect modificat. Întrebarea din portalul nostru este de unde se alege adresa la care duce butonul promoției. E aceeași întrebare de la care a pornit repararea erorii, doar că aici nu cerem deloc modificarea. Așa arată o sarcină combinată: mai întâi cercetare, apoi, într-o etapă separată, reparare.

Aici agentul poate deraia în două feluri tipice. Primul: începe să repare pe parcurs. Găsește o bucată problematică și i se pare mai ieftin s-o modifice decât s-o descrie. Așa, cercetarea devine o schimbare fără o sarcină formulată și fără verificare. Al doilea e mai subtil. Agentul citește codul și povestește sigur pe el cum funcționează pagina, deși n-a pornit-o; pentru cine citește răspunsul, descrierea codului pare la fel cu o observație directă.

A treia problemă începe chiar din solicitare. Dacă scrieți ce intenționați să faceți în continuare, agentul își va potrivi răspunsul cu acel scop: în loc de descrierea situației actuale, veți primi o părere despre varianta mai bună. De aceea, în research întrebați cum funcționează acum și lăsați intenția pentru etapa următoare. Solicitarea de mai jos nu spune nimic despre repararea ulterioară a adresei.

Găsește de unde preia adresa butonul bannerului de pe pagina principală. Nu repara nimic.
În răspuns: fișierele și locurile din cod, cum se leagă între ele,
ce ai stabilit prin citire și ce ai stabilit prin rulare,
și ce nu știi încă.

Un răspuns bun la o astfel de solicitare ar putea arăta așa: "În pages/home.html, adresa butonului vine din promo.url; valoarea /old/ este definită în data/promo.json. Am stabilit asta citind cele două fișiere. Nu am pornit pagina și nu am verificat dacă scripturile schimbă adresa". Legătura poate fi verificată, iar limita informațiilor cunoscute este menționată clar.

Dacă observați ceva suspect pe parcurs, includeți-l separat în răspuns: ce se vede și ce informație lipsește pentru a trage o concluzie. Repararea ține deja de etapa următoare, cu propria formulare a sarcinii.

Primul pas și limitele

Totul, într-un singur tabel.

A treia coloană arată ce merită să limitați chiar în solicitare. A patra, ce să verificați singuri sau să cereți să apară în răspuns.

Și reversul e important: numele tipului nu autorizează nimic de la sine. "E doar refactoring" nu e un motiv să rescrieți jumătate de modul, iar "e un bugfix" nu dă dreptul să schimbați și designul. Tipul sugerează întrebarea și verificarea, dar dumneavoastră stabiliți în continuare limitele.

Rescrieți șase solicitări

Mai jos sunt șase solicitări în forma lor obișnuită. Pentru fiecare, identificați tipul și rescrieți solicitarea ca agentul să aibă mai puține lucruri de presupus: rezultat, limită, verificare. Analiza urmează imediat, așa că încercați mai întâi singuri.

1. "Adăugați exportul clasamentului în CSV".
2. "Uneori, clasamentul afișează de două ori același participant. Reparați".
3. "Împărțiți pages/home.html în mai multe fișiere, e prea mare".
4. "De ce se încarcă atât de încet pagina principală?"
5. "Reparați linkul și, totodată, rescrieți designul".
6. "Îmbunătățiți portalul".

Iată una dintre analizele posibile. Formulările dumneavoastră pot fi diferite; important e să includă aceleași repere.

1. Exportul clasamentului.
Feature. Lipsește scenariul: ce coloane intră în fișier, în ce ordine apar rândurile și unde este butonul de export. Mai e și o întrebare despre date, ușor de trecut cu vederea: intră în fișier participanții fără puncte? Decideți dumneavoastră, altfel va decide agentul. Precizați separat ce nu trebuie făcut: import, alegerea coloanelor sau alte formate. Verificarea e simplă: exportați datele pentru A, B, C, D și comparați rândurile cu tabelul de pe ecran.

2. Participantul apare de două ori.
Bugfix, dar cuvântul important e "uneori", nu "reparați". Dacă nu se știe când apare duplicatul, agentul nu are ce repara; cel mai probabil va elimina duplicatele înainte să afișeze tabelul. Acesta e simptomul ascuns. Aflați mai întâi după ce acțiune și pe ce date se dublează rândul, apoi cereți-i agentului să găsească locul unde se întâmplă, fără modificări. Verificarea folosește același scenariu care producea duplicatul.

3. Împărțirea unui fișier mare.
Refactoring, dar invariantul nu e precizat și nu există o bază pentru a verifica dacă "nu s-a stricat nimic". Adăugați: pagina trebuie să arate și să funcționeze ca înainte - bannerul, lista promoțiilor și clasamentul - și notați rezultatul verificărilor înainte de modificare. Limitați și tentația de a schimba altceva: când împarte marcajul în fișiere, agentul poate ajusta și spațierea sau redenumi clasele.

4. Pagina se încarcă greu.
Research: e o întrebare, nu o cerere de accelerare. Dar agentul o poate interpreta ușor drept "fă-o mai rapidă", iar fără indicația "nu schimba nimic" răspunsul poate fi o optimizare la întâmplare. Cereți-i să distingă ce a măsurat de ce a dedus din cod: "imaginile ocupă câțiva megabyți" e un fapt dacă l-a verificat, iar "probabil scriptul încetinește pagina" e o presupunere. Repararea vine într-o etapă următoare, după ce se cunoaște cauza.

5. Repararea linkului și rescrierea designului.
O singură solicitare, două rezultate. Repararea linkului e un bugfix. Designul nou nu se încadrează tocmai bine în cele patru tipuri: comportamentul rămâne la fel, se schimbă aspectul. Cel mai apropiat e un feature, doar că rezultatul e descris printr-un exemplu, cum ar fi un mockup sau o captură de ecran, nu printr-un scenariu. Începeți cu repararea, folosind solicitarea din secțiunea despre bugfix; după ce o verificați, treceți la design:

Acum modifică designul bannerului după mockup-ul @banner-mockup.png.
Nu schimba adresa butonului și textele.

6. Îmbunătățiți portalul.
Nu se poate identifica tipul și nu are rost să-l ghicim. Solicitarea se transformă într-o întrebare pentru persoana care a formulat-o: ce anume vă încurcă acum? Dacă ați formulat-o chiar dumneavoastră, puneți-vă singuri întrebarea. Puteți să-i cereți și agentului să vă ajute:

Înainte să schimbi ceva, adresează-mi până la cinci întrebări
care te-ar ajuta să înțelegi ce anume trebuie îmbunătățit.
Nu modifica fișierele.

De obicei, tipul sarcinii devine clar din răspunsuri.