Cum să faceți revizuire de cod prin agent

Imaginați-vă o pagină cu o listă de cumpărături: se deschide, articolele se adaugă, butoanele arată normal. Dar un ecran gata încă nu înseamnă că în cod totul este bine gândit. Dezvoltatorii fac o examinare separată a codului pentru a găsi erorile scăpate și a discuta soluțiile. Această muncă poate fi încredințată unui agent, iar el se va descurca excelent cu ea. Trebuie doar să-i explicați sarcina.

1. Cum se verifică codul într-o echipă

Într-o echipă mică, un dezvoltator a primit sarcina: să facă o listă de cumpărături în care se pot adăuga înregistrări și din care se pot șterge una câte una. A scris codul, a încercat să adauge pâine și lapte, a șters pâinea. Totul a funcționat. Înainte de a transmite munca mai departe, dezvoltatorul și-a mai recitit o dată modificările: a eliminat o bucată uitată, a corectat o denumire neclară. Aceasta este autoverificarea.

Apoi a rugat un coleg să se uite peste cod. Colegul cunoaște limbajul de programare și citește cum este organizată adăugarea, cum selectează programul înregistrarea pentru ștergere, ce se întâmplă cu restul listei. O astfel de examinare se numește revizuire de cod, sau code review, iar persoana care verifică se numește reviewer.

Colegul observă: programul selectează cumpărătura pentru ștergere după nume. Dacă vor fi două înregistrări "Lapte" în listă, apăsarea pe una le poate șterge pe amândouă. Autorul a încercat cu pâine și lapte. Un astfel de caz pur și simplu nu i-a ieșit în cale.

Reviewerul lasă un comentariu lângă secțiunea corespunzătoare a codului: "Acum se șterg toate cumpărăturile cu acest nume. Permitem înregistrări identice? Dacă da, trebuie să ștergem doar pe cea selectată". Autorul clarifică cerința: înregistrările identice sunt permise, pentru că ar fi putut fi adăugate pentru persoane diferite. După discuție, el schimbă modul de selectare a înregistrării. Colegul se uită din nou la corectare și se convinge că observația a fost luată în considerare.

Schema arată trecerea prin revizuire cu observații: codul trece de la autor la coleg, apoi se întoarce pentru corectare. Dacă după reexaminare rămân întrebări, discuția și corecturile se repetă. Când nu mai sunt observații esențiale, colegul aprobă modificarea.

Iată ciclul obișnuit de lucru: codul e scris, arătat, primește o observație, se discută, se corectează. Uneori sunt mai multe observații, uneori nu sunt deloc. Se întâmplă și ca autorul să explice soluția, iar colegul să renunțe la întrebare. Revizuirea nu presupune acordul cu fiecare comentariu.

În această revizuire se discută și claritatea codului: dacă următorul dezvoltator îl va putea înțelege, dacă nu cumva aceeași regulă trebuie schimbată în mai multe locuri. În același timp, colegul află cum este organizată noua parte a programului. Cunoștințele despre proiect se împart treptat între oameni în loc să rămână doar la autor.

Aici este ușor să confundați revizuirea cu testarea. Când o persoană adaugă două cumpărături și apasă butonul, verifică comportamentul programului în funcțiune. Când citește codul ștergerii și înțelege ce înregistrări va selecta, el face o revizuire. În timpul revizuirii, puteți rula programul pentru a verifica o presupunere. Aceste metode se completează reciproc.

2. Cum să încredințați revizuirea unui agent

Acum imaginați-vă că lista de cumpărături a fost scrisă de Claude Code pe baza descrierii dumneavoastră. Puteți explica ce trebuie să se întâmple pe pagină, dar nu puteți citi logica programului. Partea tehnică a revizuirii poate fi încredințată tot unui agent: el va citi fișierele și vă va explica observațiile cu cuvinte obișnuite.

Rolurile din povestea echipei rămân aceleași. Există autorul codului și există un verificator căruia i s-a dat o sarcină separată. În Claude Code, pentru aceasta puteți folosi un subagent: un asistent căruia agentul principal îi încredințează o sarcină concretă. În cazul nostru, el citește codul și returnează observații.

Este util și să-i cereți autorului să-și verifice încă o dată propria muncă. Un reviewer separat adaugă o altă perspectivă: primește sarcina de a evalua rezultatul. Transmiteți-i cerințele pentru ca el să înțeleagă ce soluții sunt acceptabile. De exemplu, interzicerea cumpărăturilor identice va rezolva formal problema ștergerii, dar va schimba comportamentul intenționat al paginii.

În recomandările Claude Code privind revizuirea se sugerează un verificator separat și criterii explicite. Acolo se recomandă, de asemenea, să vă concentrați pe observațiile care afectează funcționarea corectă și respectarea cerințelor. Să aplicăm acest lucru pe o mică parte a proiectului.

Pentru a organiza o revizuire, aveți nevoie de puțin: descrieți comportamentul dorit și alegeți ce probleme confirmate doriți să corectați. Citirea logicii programului, căutarea cauzei și analiza obiecțiilor tehnice pot fi încredințate agenților.

Pe schemă sunt trei roluri: dumneavoastră stabiliți cerințele și alegeți corecturile, agentul principal organizează munca și corectează codul, verificatorii studiază codul și observațiile. Agentul principal le transmite materialele necesare și vă returnează rezultatele. Dacă nu există probleme confirmate, pașii de corectare se omit. Mai jos vom parcurge această succesiune cu trei solicitări.

La final aveți o explicație clară a problemei, rezultatul reverificării ei și un raport despre corectare. Iar dacă observația s-a dovedit greșită, există și atunci un rezultat util: ați evitat o modificare inutilă.

Dacă doriți să configurați un asistent permanent pentru asemenea revizuiri, vă va fi util materialul despre crearea și lansarea subagentului. Cum se pregătește o sarcină mai detaliată pentru el este explicat în articolul despre brief și formatul rezultatului.

Solicitarea 1. Verificarea codului scris

Lansați Claude Code în folderul proiectului. Următoarele trei solicitări le trimiteți în sesiunea principală: agentul principal transmite singur munca asistenților. Aici și mai departe folosim lista de cumpărături din exemplu; pentru propriul dumneavoastră proiect, înlocuiți descrierea comportamentului.

Încredințează unui subagent separat revizuirea codului listei
de cumpărături din proiectul curent. Verifică adăugarea și ștergerea înregistrărilor.
Cerințe: denumirile identice sunt permise; se șterge doar
înregistrarea selectată; o cumpărătură goală nu poate fi adăugată.

Citește codul curent și părțile conexe ale proiectului.
Caută erori care încalcă aceste cerințe.
Nu schimba codul. Nu adăuga funcționalități noi.
Pentru fiecare observație, explică în cuvinte simple:
ce poate merge prost, la ce acțiune și de ce ai ajuns la această concluzie.
Indică locul din cod, ca un alt agent să-l poată verifica ulterior.
Dacă nu găsești probleme, scrie asta. Enumeră ce a fost verificat
și ce a rămas necunoscut. Salvează raportul în REVIEW_REPORT.md.
Nu cunosc limbajul de programare: explică rezultatul fără să fie nevoie să citesc codul.

Fișierul REVIEW_REPORT.md va fi un raport text obișnuit. Numele l-am ales noi, merge și oricare altul: e nevoie de el pentru ca în solicitarea următoare să fie clar ce observații trebuie reverificate. Cerința "nu schimba codul" separă examinarea de corectare; scrierea raportului este totuși permisă.

Un răspuns util în exemplul nostru ar putea suna așa: "Dacă adăugați două cumpărături cu același nume, ștergerea uneia le va elimina pe amândouă. Codul selectează înregistrările după nume, deci le afectează pe ambele potriviri". Acesta este un exemplu didactic de răspuns, nu rezultatul verificării proiectului dumneavoastră.

Consecința vă este clară: omul va pierde înregistrarea pe care voia să o păstreze. Numele fișierului și locul din cod îi trebuie agentului următor ca să găsească cauza. Nu este nevoie să analizați personal această porțiune de cod.

3. Cum să reverificați observațiile

Și agentul reviewer greșește uneori. De exemplu, scrie: "În listă se poate adăuga o cumpărătură goală". Sună convingător. Dar verificarea pentru textul gol există deja într-o altă parte a programului, pe care nu a citit-o. Observația descrie o problemă care nu există.

O asemenea afirmație sigură, dar inventată, se numește adesea alucinație IA. Într-o revizuire, este deosebit de neplăcută: agentul poate sugera o corectare, iar dumneavoastră veți pierde timp modificând cod care funcționa deja corect. De aceea, este util să reverificați atât codul după ce a fost scris, cât și observațiile despre el.

Am făcut deja primul pas: am dat altcuiva munca autorului spre verificare. Acum îi dăm unui alt verificator raportul împreună cu proiectul actual. Sarcina lui: să afle dacă fiecare observație se confirmă. Are voie să nu fie de acord cu primul reviewer.

Solicitarea 2. Verificarea raportului reviewerului

Cere unui alt subagent să reverifice REVIEW_REPORT.md
pe baza codului curent al proiectului și a cerințelor din solicitarea anterioară.
Transmite-i aceste cerințe explicit.

Pentru fiecare observație, stabilește dacă problema descrisă există.
Verifică părțile conexe ale codului: poate că tratarea necesară există deja.
Nu considera primul raport o dovadă. Dacă pentru o concluzie e nevoie
de o verificare prin rulare, efectueaz-o cu mijloacele disponibile.
Nu schimba codul proiectului.

Pentru fiecare punct, indică: confirmat, infirmat
sau deocamdată nu s-a putut stabili. Explică temeiul pe înțelesul meu.
Separă concluziile din citirea codului de rezultatele verificărilor efectuate.
Nu prezenta o verificare neefectuată drept efectuată.
Salvează rezultatul în REVIEW_CHECK.md și explică-mi-l pe scurt.

După aceasta veți avea REVIEW_CHECK.md cu rezultatul reverificării. În exemplul nostru, al doilea agent poate confirma problema numelor identice și infirma observația despre textul gol: "Șirul gol este respins înainte de adăugarea înregistrării. Primul reviewer nu a observat această verificare".

Asta ajută deja la alegerea pasului următor. Problema ștergerii poate fi trimisă la corectare. Tratarea textului gol nu trebuie schimbată din cauza acestei observații. Dacă agentul scrie "deocamdată nu s-a putut stabili", cereți-i să explice ce date i-au lipsit. Uneori aceasta este o întrebare pentru dumneavoastră: de exemplu, dacă înregistrările identice trebuie să fie considerate o cumpărătură sau două.

Verificarea repetată ajută la filtrarea observațiilor inventate, dar nu le garantează dispariția completă. Doi agenți pot repeta aceeași eroare. De aceea, răspunsul trebuie să conțină temeiuri: ce anume a găsit verificatorul în proiect sau ce rezultat a obținut la rulare. Un simplu "sunt de acord cu agentul anterior" nu ajunge.

4. Corectare și revizuire repetată

Acum alegeți ce să corectați. Pentru asta este suficient să înțelegeți cum afectează problema funcționarea intenționată a paginii. În exemplul nostru, ștergerea unei cumpărături în plus deranjează vizibil, așa că luăm acest punct. Sugestia de a adăuga sortare poate fi lăsată pe mai târziu. cu corectarea ștergerii oricum nu are legătură.

Transmiteți agentului observația aleasă în întregime, ca să nu fie nevoit să ghicească ce ați vrut să spuneți prin "corectează prima eroare". Cereți-i ca după modificare să verifice din nou rezultatul. Este continuarea poveștii echipei: colegul se uită deja la versiunea corectată.

Solicitarea 3. Corectarea și verificarea rezultatului

Corectează problema confirmată din REVIEW_CHECK.md:
la ștergerea unei cumpărături dispar toate înregistrările cu același nume.
Trebuie ștearsă doar înregistrarea selectată. Denumirile identice sunt permise.
Deocamdată nu implementa celelalte sugestii din revizuire.

După corectare, verifică prin mijloacele disponibile adăugarea
și ștergerea cumpărăturilor, inclusiv a două cu același nume.
Apoi încredințează unui subagent separat revizuirea repetată a codului corectat:
dacă a fost eliminată cauza și dacă adăugarea și ștergerea funcționează în continuare.
Transmite-i cerințele inițiale și descrierea problemei corectate.

Explică-mi în cuvinte simple ce s-a schimbat, ce verificări
au fost efectuate și ce a arătat revizuirea repetată.
Dacă ceva nu s-a putut verifica, spune asta separat.
Nu extinde sarcina cu îmbunătățiri noi.

Pentru propriul proiect, înlocuiți paragraful despre cumpărături cu observația confirmată din raportul dumneavoastră. Restul succesiunii poate rămâne la fel: corectare, verificare, examinare separată a rezultatului.

Un rezultat bun spune ceva concret: "Acum fiecare înregistrare se șterge separat. Verificarea cu două denumiri identice a lăsat a doua înregistrare la locul ei. Revizuirea repetată nu a mai găsit cauza erorii". Așa ceva se poate scrie doar după verificările corespunzătoare. Dacă agentul doar a citit codul, trebuie să precizeze acest lucru.

Puteți, de asemenea, să deschideți pagina și să încercați acțiunile obișnuite. Pentru asta nu trebuie să cunoașteți limbajul. Este o verificare suplimentară a rezultatului vizibil; revizuirea tehnică a corectării rămâne în seama agentului. Dacă mijloacele lui de rulare n-au fost suficiente, în raport va rămâne o limitare clar formulată, nu promisiunea "sigur merge totul".

Nu este obligatoriu să transformați fiecare trecere într-o finisare fără sfârșit. Dacă problema aleasă este eliminată, verificată, iar examinarea repetată nu a scos la iveală erori conexe, această sarcină poate fi încheiată. Și atât. Dorințele noi merită o discuție separată.