Cum să încredințați o revizuire unui subagent și să verificați raportul

Cererea "Verifică pagina" îi lasă reviewer-ului destule decizii de luat: să caute erori de comportament, să evalueze aspectul sau să propună alt mod de a scrie codul. Ca răspuns puteți primi o listă îngrijită de observații care aproape nu vă ajută cu sarcina dumneavoastră. Să vedem cum îi transmiteți unui subagent Claude Code o sarcină clară și cum verificați apoi dacă a fost îndeplinită.

Dacă rolul reviewer nu este încă configurat, mai întâi creați-l și faceți prima rulare. Aici ne concentrăm pe sarcina în sine și pe completitudinea răspunsului.

1. Ce îi transmiteți reviewer-ului

Reviewer-ul verifică munca altcuiva și returnează observații cu justificări. În exemplele noastre, acesta este un subagent personalizat, deja configurat, cu numele reviewer, care are acces doar la citirea și căutarea în fișiere: Read, Grep, Glob. Studiază codul, dar nu îl corectează și nu deschide pagina în browser. Numele reviewer nu creează automat un astfel de rol: se presupune că rolul este deja configurat în proiectul dumneavoastră.

La o rulare nouă obișnuită, un astfel de subagent nu primește automat tot istoricul conversației dumneavoastră. Agentul principal, cu care comunicați, alcătuiește pentru el o sarcină separată. De aceea, o cerință importantă precum "două cumpărături cu același nume sunt înregistrări diferite" trebuie să ajungă în sarcină sau într-un document pe care reviewer-ul are indicația să-l citească. Acest mecanism este descris în documentația despre contextul subagenților; aici e vorba de rularea unui rol personalizat, nu de un fork cu o copie a conversației.

Comparați "Uită-te la proiect" și "Verifică ștergerea înregistrărilor și actualizarea contorului; nu modifica codul". În al doilea caz e deja clar unde să se uite și ce acțiune nu așteptați. Rămâne de precizat ce se consideră rezultat corect.

Pentru o verificare scurtă, făcută o singură dată, ajunge un mesaj. Dacă sunt multe criterii sau verificarea se va repeta după corecturi, e mai comod să salvați un brief: o descriere scurtă a sarcinii, ținută lângă proiect. Nu o specificație separată de zece pagini. Câteva condiții fără de care reviewer-ul ar fi nevoit să ghicească.

Nu veți putea anticipa toate întrebările și nici nu e nevoie. Când datele de intrare nu ajung, reviewer-ul trebuie să semnaleze golul în raport. Agentul principal îl va putea lămuri cu dumneavoastră. O sarcină bine formulată reduce interpretările diferite, dar nu garantează un răspuns bun: modelul poate greși și când sarcina e clară.

2. Patru părți ale sarcinii

Scopul răspunde la întrebarea ce comportament trebuie verificat. Pentru pagina cu lista de cumpărături, asta înseamnă adăugarea, ștergerea și contorul de înregistrări. "Fă proiectul mai bun" e prea larg: nu e clar ce îmbunătățire contează acum.

Intrarea indică fișierele și comportamentul așteptat. Doar calea către app.js nu ajunge dacă din cod nu reiese dacă numele identice sunt permise. Această decizie de produs trebuie comunicată explicit. Tot aici precizați cu ce se face verificarea: la noi, doar prin citirea codului, fără browser.

Limitele separă această verificare de sarcinile vecine. De exemplu, stilurile, afișarea pe mobil și salvarea listei între sesiuni nu le analizăm acum. fișierele nu le modificăm. Dacă un fișier necesar lipsește, oprim partea verificării care depinde de el și semnalăm asta, în loc să-i inventăm conținutul.

Rezultatul descrie ce vreți să primiți: ce s-a verificat, constatările argumentate și limitările. Nu cereți să se găsească neapărat cinci erori. În recomandările Claude Code pentru revizuire este semnalat separat riscul unei asemenea formulări: cererea de a căuta defecte împinge spre observații chiar și acolo unde munca e făcută corect.

Fiecare ramură aduce ceva ce celelalte nu dau: calea către fișier nu stabilește comportamentul așteptat, iar scopul nu impune interdicția de a face modificări. Puneți aceste condiții laolaltă, ca reviewer-ul să le poată corela în timpul verificării.

Așadar, în loc de "Verifică pagina cu lista de cumpărături", transmitem următoarea sarcină. O puteți trimite ca mesaj sau o puteți salva în REVIEW_BRIEF.md, în rădăcina proiectului:

# Verificarea listei de cumpărături
Scop: verifică în cod adăugarea, ștergerea și contorul.
Intrare: index.html și app.js în rădăcina proiectului.
Așteptat: articolul adăugat apare în listă;
contorul este egal cu numărul de articole; ștergerea unei înregistrări
nu șterge altă înregistrare cu același nume.
Limite: nu modifica fișierele; stilurile, afișarea pe mobil și salvarea
listei între sesiuni nu intră în această verificare.
Dacă lipsește un fișier sau o cerință necesară, semnalează golul,
nu-l completa din imaginație și returnează rezultatul pentru partea disponibilă.
Rezultat: urmează formatul reviewer; indică ce a fost verificat
și ce a rămas neverificat. Lipsa constatărilor este acceptabilă.

Formatul reviewer îl discutăm imediat mai jos. Dacă rolul dumneavoastră nu are încă un format permanent, îl puteți include în același mesaj unic. Numele câmpurilor nu sunt obligatorii: contează informațiile pe care vă ajută să nu le uitați.

O cerere precum "în raport arată mai întâi cele mai importante trei constatări" limitează volumul răspunsului, nu profunzimea verificării. Dacă aveți nevoie de o asemenea limită, cereți să se precizeze separat dacă mai există și alte constatări. Reviewer-ul nu are voie să se oprească după a treia observație și să declare sarcina verificată.

3. Ce păstrați în fișiere

Condițiile unei sarcini concrete se schimbă: azi verificăm contorul, mâine salvarea listei. Locul lor e în brief. În schimb, cererea de a arăta locul erorii și justificarea e necesară la aproape orice revizuire. Pe aceasta e mai comod s-o notați o singură dată în instrucțiunile rolului.

Output contract, sau contractul rezultatului, înseamnă aici un format de răspuns convenit. Sună mai solid decât este de fapt: sunt instrucțiuni obișnuite pentru reviewer, nu o setare specială a Claude Code și nici o verificare automată a calității. Formatul vă ajută să găsiți informațiile necesare în raport, dar nu le face mai demne de încredere.

Cele două ramuri de sus răspund de lucruri diferite: brieful stabilește conținutul verificării, iar instrucțiunile rolului stabilesc, printre altele, forma raportului. Ca reviewer-ul să folosească brieful salvat, cereți-i să citească fișierul. Singur nu se va uita acolo. Jos rezultă un raport ale cărui justificări și completitudine trebuie încă evaluate.

Iată o secțiune pe care o puteți adăuga în partea de text a fișierului de rol existent .claude/agents/reviewer.md, după setările lui:

## Formatul rezultatului
Indică fișierele și criteriile verificate.
Pentru fiecare constatare: locul, comportamentul așteptat, justificarea,
condițiile verificării și impactul; explică prioritatea.
Separă ce este confirmat de cod de presupunerile neverificate.
Numește separat limitările și datele lipsă.
Dacă nu ai găsit probleme după criterii, scrie exact asta.

Acesta este un fragment din instrucțiuni, nu fișierul complet al subagentului. Rolul nostru are doar citire și căutare, așa că un câmp permanent "fișiere modificate" nu îi trebuie. Într-un raport mai amplu, informațiile despre modificări trebuie să reflecte faptele: nu se poate prescrie dinainte rândul "fișiere modificate: niciunul", indiferent de ce s-a întâmplat.

După ce brieful este salvat, trimiteți agentului principal o cerere ca aceasta:

Cere-i lui reviewer să citească REVIEW_BRIEF.md din rădăcina proiectului
și să verifice fișierele indicate după criteriile de acolo.
Returnează raportul final integral.

Am cerut explicit citirea documentului, nu doar i-am menționat numele. Dar fișierul în sine nu garantează nimic: reviewer-ul tot poate omite o condiție. Brieful salvat e util pentru că puteți compara rezultatul cu el și repeta verificarea. Când cerințele se schimbă, actualizați mai întâi documentul, altfel următoarea trecere va evalua sarcina veche.

4. Cum verificați raportul

Mai întâi, uitați-vă la ce a fost verificat cu adevărat. În brief erau adăugarea, ștergerea, contorul și independența înregistrărilor cu același nume. Dacă raportul vorbește doar despre contor, acesta nu e încă un rezultat pentru toată sarcina. Chiar dacă singura constatare este perfect corectă.

E util să puneți fiecare criteriu din brief față în față cu răspunsul. De exemplu, într-un raport parțial, dat ca exemplu didactic, a ieșit așa:

Lipsa unui rând despre numele identice nu înseamnă că nu există erori. Totodată, o constatare întemeiată despre contor nu acoperă partea omisă din sarcină. Returnați raportul cu o cerere concretă de precizare:

În brief apare ștergerea uneia dintre două înregistrări cu același nume.
Raportul nu acoperă acest criteriu. Verifică-l cu mijloacele disponibile
și indică justificarea rezultatului sau motivul pentru care nu l-ai putut verifica.
Celelalte concluzii nu trebuie repetate fără modificări. Nu modifica codul.

Separat, evaluați cât de întemeiate sunt constatările importante: comparați locul indicat, cerința și justificarea concluziei. Un exemplu detaliat găsiți în articolul despre citirea raportului de revizuire. Aici sunt necesare ambele verificări: acoperirea sarcinii și temeinicia rezultatului. Un scenariu de rulare propus nu echivalează cu un test deja executat.

La prima ramificație decidem dacă s-a verificat suficient pentru sarcina noastră. Dacă nu, cerem ce lipsește sau acceptăm doar partea verificată, după ce îi evaluăm și ei justificările. La a doua ramificație separăm concluziile întemeiate de cele discutabile și greșite. O justificare neclară merită lămurită; o observație dovedit greșită sau un sfat care nu ține de sarcină poate fi respins.

Și un raport fără constatări poate trece această verificare. De exemplu: "Am verificat căile de adăugare și ștergere, independența înregistrărilor identice și actualizarea contorului în index.html și app.js. După aceste criterii nu am găsit probleme; nu am rulat în browser". Un asemenea rezultat nu promite că proiectul nu are nicio eroare. Raportează rezultatul în limitele numite, iar dacă e nevoie, verificați singur căile principale.

În schimb, "Nu am găsit app.js la calea indicată, nu am putut verifica comportamentul ștergerii" înseamnă lipsă de date, nu lipsă de erori. Aici trebuie transmisă calea corectă și continuată verificarea. Un răspuns scurt și onest e mai util decât un raport lung în care golul e ascuns.

A accepta raportul nu înseamnă a cere corectarea a tot ce e enumerat. Ați recunoscut rezultatul verificării ca întemeiat; ce modificări faceți acum decideți separat.

5. Când e nevoie de încă o trecere

Dacă în raport lipsește o justificare, nu e obligatoriu să reluați revizuirea de la zero. Returnați golul concret. De exemplu, o variantă prescurtată a constatării despre contor conține doar numele erorii, fără analiza apelurilor. Atunci cererea către agentul principal poate arăta așa:

Trimite-i lui reviewer raportul înapoi pentru precizări: în constatarea despre contor
nu este indicată calea prin care se actualizează după ștergere.
Să verifice această cale și să adauge justificarea concluziei.
Codul nu se modifică.

Dacă se dovedește că actualizarea are loc deja în altă funcție, observația trebuie retrasă. Nu căutați alta în locul ei doar ca să păstrați același număr de puncte. Dacă eroarea se confirmă, puteți să-i cereți agentului principal corectarea printr-o cerere separată, indicând constatarea concretă și volumul permis de modificări.

După corectare e utilă încă o trecere după același brief:

Cere-i lui reviewer să recitească REVIEW_BRIEF.md și să verifice
codul actual pentru ștergere și contor. Constatarea anterioară:
după ștergere, contorul nu se actualiza.
Să indice dacă problema a fost eliminată și pe ce se bazează concluzia,
și să verifice dacă nu a fost afectată independența înregistrărilor
cu același nume. Codul nu se modifică.

Acum căutăm răspunsul la o întrebare concretă: a fost eliminată problema și nu s-a stricat comportamentul vecin pe care l-ar fi putut atinge modificarea? Pentru a confirma comportamentul paginii, repetați același scenariu în browser. Dacă revizuirea repetată s-a făcut doar pe cod, această limitare rămâne și în noul raport.

Raportul poate deveni mai scurt, mai lung sau poate să nu conțină constatări noi. Nu asta înseamnă succes. Important e ca defectul anterior să fie eliminat, concluzia să se sprijine pe codul actual, iar părțile neverificate să rămână vizibile. Ați decis să amânați corectarea? Atunci păstrați constatarea confirmată și motivul amânării; nu are rost să repetați revizuirea codului nemodificat doar pentru un răspuns nou.

6. De la sarcină la rezultatul verificat

În lucrul cu Claude Code, brieful vă ajută să vă păstrați așteptările cât timp agentul principal transmite sarcina reviewer-ului. Formatul permanent ușurează citirea răspunsului. Dar tot va trebui să participați, și iată unde:

• agentul principal alcătuiește sarcina și o transmite rolului potrivit; dumneavoastră stabiliți comportamentul așteptat și limitele;
• reviewer-ul studiază fișierele și returnează justificările concluziilor; acoperirea și constatările importante le verificați însă dumneavoastră;
• agentul principal poate preciza raportul sau corecta o eroare confirmată, printr-o cerere separată; dumneavoastră decideți ce se modifică și cum se confirmă rezultatul.

Pentru lista de cumpărături, rezultatul nu va fi doar sfatul "adaugă un apel de funcție", ci o explicație verificată: la ce acțiune numărul rămânea în urmă, unde se strica actualizarea și ce s-a schimbat după corectare. Cu un asemenea rezultat se poate lucra.