Subagentul ca o fereastră de atenție separată

1. Ce este un subagent și de ce este util

Un subagent este un asistent specializat căruia Claude Code îi transmite o sarcină: acesta lucrează în propria fereastră de context și returnează sesiunii dumneavoastră un rezumat scurt. Citirile de fișiere, căutările și apelurile de instrumente rămân în contextul acestuia.

De ce să faceți asta: atunci când lucrați în sesiunea principală, mesajele, fișierele citite și rezultatele comenzilor ocupă spațiu într-o singură fereastră, iar volumul acesteia nu este infinit. Pe măsură ce se umple, Claude Code scurtează istoricul, iar unele detalii pot fi pierdute. Un subagent vă permite să mutați munca intermediară într-o fereastră separată, lăsând doar rezultatul acesteia în conversația principală.

Cel mai simplu subagent

Pentru prima rulare, este suficient un mesaj obișnuit în Claude Code: cereți în mod explicit apelarea unui subagent și descrieți sarcina acestuia. Nu este necesar să creați un fișier de rol personalizat în avans; un asistent încorporat este potrivit pentru o asemenea sarcină. De exemplu:

Apelează un subagent care să citească fișierul index.html.
Să alcătuiască o hartă scurtă a fișierului: secțiunile principale
și ce face fiecare dintre ele. Apoi să scrie un rezumat scurt
al conținutului în 3-5 propoziții.
Fișierul nu se modifică. Returnează răspunsul subagentului în această sesiune.

Agentul principal va transmite sarcina asistentului și după execuție vă va arăta răspunsul acestuia în conversația dumneavoastră. Atunci când rulează în fundal, sub câmpul de intrare va apărea o bară cu numele subagentului și starea muncii acestuia. Faceți clic pe ea pentru a deschide sesiunea subagentului și a vedea ce citește și face. Verificați pe parcursul muncii că apare o lansare separată a subagentului: o cerere în text obișnuit direcționează alegerea lui Claude, dar nu garantează delegarea.

Ce primește un subagent

Dacă aceeași sarcină trebuie repetată cu reguli constante, puteți descrie propriul rol într-un fișier. La start, un subagent personalizat ca acesta are două intrări principale:

• instrucțiunea rolului din fișierul dumneavoastră de configurare - specializarea și regulile de comportament;
• descrierea sarcinii, pe care agentul principal o compune în funcție de cererea dumneavoastră.

La acestea, Claude Code adaugă de la sine un fundal comun: fișierele CLAUDE.md ale proiectului, un instantaneu git status și informații despre mediu. Conversația dumneavoastră cu agentul principal nu se află printre ele.

În diagramă contează un singur lucru: subagentul execută sarcina în fereastra sa, iar în conversația principală returnează un rezumat. Agentul principal nu trebuie să încarce toate citirile și căutările intermediare. Rezumatul în sine ocupă, de asemenea, spațiu în contextul principal.

Această separare are și un revers: rezumatul nu arată tot drumul până la concluzie. Din el puteți să nu observați ce date i-au lipsit asistentului sau ce a lăsat neverificat. De aceea răspunsul trebuie să conțină justificări și limitări, iar concluziile lui merită verificate.

De ce Claude nu-și amintește totul

Fereastra de context - informațiile de care dispune modelul când pregătește următorul răspuns: instrucțiuni, istoricul disponibil al conversației, codul citit, rezultatele comenzilor. De aceea agentul poate conta pe o decizie pe care ați discutat-o cu câteva mesaje în urmă. Fereastra are o limită; nu stochează întreaga conversație în toate detaliile pentru totdeauna.

În captura de ecran, comanda /context arată 4k/200k tokens (2%): aproximativ 4 mii de tokeni din 200 mii disponibili sunt ocupați. Un token este un mic fragment de text: un cuvânt, o parte a unui cuvânt sau un semn. Prin urmare, 200 de mii de tokeni nu sunt egali cu 200 de mii de cuvinte. Aceasta este dimensiunea ferestrei sesiunii afișate; cu alt model sau altă configurație, aceasta poate diferi.

Mai jos puteți vedea ce ocupă spațiu: System prompt - instrucțiuni de sistem, Memory files - fișiere de memorie și reguli încărcate, Skills - informații despre skills, Messages - mesaje. Aici aproape că nu există conversație, dar o parte a ferestrei este deja ocupată de instrucțiuni. Linia Free space: 196k (98.0%) arată spațiul liber rămas. Pe măsură ce conversați, citiți fișiere și executați comenzi, acesta se consumă.

În continuare vom analiza acest mecanism pe exemplul unui reviewer personalizat pentru citirea codului: ce informații primește și cum să creați fișierul rolului său. Aici vorbim despre o lansare nouă obișnuită; modalitățile de a continua munca anterioară sau de a transmite o copie a istoricului nu sunt necesare în acest exemplu.

2. Ce știe reviewer-ul despre proiect

Un context separat nu înseamnă că asistentul nu știe nimic. Are instrucțiuni inițiale și acces la proiect. Iată de unde vin informațiile pentru reviewer-ul personalizat din exemplul nostru:

CLAUDE.md - fișier cu instrucțiuni generale pentru Claude Code: de exemplu, unde se află codul sursă și ce convenții sunt acceptate în proiect. Nu este necesar să-l creați special pentru această verificare.

Istoricul conversației dumneavoastră nu se transferă automat. Dacă agentul principal a citit deja app.js, ce a citit nu va apărea de la sine la reviewer. Dar fișierul nu a dispărut nicăieri: asistentul îl poate deschide din nou.

Aceeași poveste cu deciziile din chat. Să presupunem că ați discutat că două nume identice din listă ar trebui să rămână achiziții separate. Pentru verificarea ștergerii, aceasta este o cerință esențială. Va ajunge la reviewer dacă agentul principal o include în sarcină sau dacă asistentul citește documentul în care este înscrisă.

3. Creăm fișierul rolului

Vom pune rolul în .claude/agents/reviewer.md în interiorul proiectului. În folderul dumneavoastră de utilizator ~/.claude/agents/ puteți, de asemenea, stoca roluri disponibile în diferite proiecte; semnul ~ indică folderul personal (home) al utilizatorului. Deocamdată, varianta proiectului este suficientă.

Puteți crea fișierul prin intermediul unei cereri către Claude Code:

Creează .claude/agents/reviewer.md pentru verificarea codului paginii
fără modificări. Permite doar Read, Grep, Glob.
Reviewer-ul returnează constatări justificate, volumul verificat
și limitările; lipsa constatărilor este acceptabilă.
Arată fișierul creat.

Ca rezultat, ar trebui să apară un fișier text obișnuit. Fără magie. Mai jos este varianta finală: puteți compara răspunsul agentului cu ea sau o puteți salva singur. Dacă aveți deja un rol cu acest nume, mai întâi verificați-i conținutul, ca să nu înlocuiți o instrucțiune de care aveți nevoie.

---
name: reviewer
description: Verifică codul paginii finalizate pentru erori de comportament și returnează un raport justificat. De folosit când se cere review-ul paginii fără corecturi.
tools: Read, Grep, Glob
---
Studiază codul fișierelor indicate conform cerințelor date.
Nu modifica fișierele. Nu promite rularea paginii: ai doar citire și căutare.
Pentru fiecare constatare indică locul, comportamentul așteptat, justificarea concluziei,
condițiile de verificare și impactul. Dacă datele nu ajung, semnalează asta.
Enumeră separat ce ai verificat și ce nu ai verificat.
Dacă nu ai găsit probleme după criteriile date, scrie exact asta.

Blocul dintre două rânduri --- se numește frontmatter: setări la începutul fișierului Markdown. Aici name setează numele rolului, description explică agentului principal când să-l aleagă, iar tools listează instrumentele disponibile. Mai jos urmează instrucțiuni obișnuite, scrise în cuvinte.

Cele trei instrumente din exemplu fac exact ceea ce este necesar pentru a vizualiza codul: Read citește fișierul, Grep caută după conținut, Glob găsește fișiere după nume sau cale. Prin urmare, reviewer-ul va putea găsi funcția de ștergere și s-o citească, dar nu va rula pagina în browser și nu va executa comenzi în terminal.

Linia "nu modifica fișierele" descrie sarcina. Câmpul tools limitează mijloacele prin care aceasta se execută. Dacă lăsați doar cererea în text și nu limitați instrumentele, asistentul poate păstra posibilitatea de a scrie. În exemplul gata făcut, ambele părți sunt deja la locul lor, nu trebuie să adăugați limitarea mai târziu.

Fișierul rolului este similar cu un skill: setări și text de instrucțiuni. Ușor de confundat. Dar aici configurăm o lansare separată pentru verificare. Un skill adaugă de obicei o procedură repetabilă la conversația curentă, deși skill-urile pot fi și lansate într-un context separat. Alegeți după modul în care trebuie executată munca, nu după faptul că cele două fișiere arată la fel.

4. Verificăm și apelăm reviewer-ul

Prezența fișierului pe disc este primul rezultat. Acum să verificăm dacă sesiunea îl vede. Deschideți fișierul și uitați-vă la numele reviewer, la descriere, la linia cu instrumente și la text: să nu existe acolo vreo promisiune de a lansa browserul sau de a corecta imediat erorile.

În câmpul de intrare Claude Code, tastați @ și selectați reviewer cu eticheta agent. Aveți nevoie anume de rol, nu de un element asemănător cu calea către fișier. Selectarea din listă vă permite să indicați în mod explicit asistentul pentru această sarcină.

Dacă rolul nu apare, mai întâi verificați calea: fișierul trebuie să se afle în .claude/agents/ al proiectului deschis. Apoi frontmatter-ul: ambele linii separatoare, numele și descrierea. Puteți cere Claude Code să verifice singur fișierul definiției.

Conform documentației Claude Code, modificările într-un folder deja urmărit sunt preluate în câteva secunde. Dacă folderul agents a apărut pentru prima dată după lansarea sesiunii, este necesar un restart. Finalizați sesiunea curentă, apoi într-un terminal obișnuit, din același folder de proiect, executați:

claude --continue

Aceasta va continua cea mai recentă conversație din directorul curent. După lansare, verificați din nou lista @. Comanda de lansare a lui Claude se tastează în terminal după ieșire, nu în interiorul conversației aflate deja în curs.

Pentru prima sarcină, vom lua o pagină de listă de cumpărături: markup în index.html, logică în app.js, ambele fișiere în rădăcina proiectului. În proiectul dumneavoastră, înlocuiți căile și comportamentul așteptat cu ale dumneavoastră. După selectarea reviewer-ului din listă, adăugați după mențiune următorul text:

Studiază index.html și app.js din rădăcina proiectului.
Verifică adăugarea și ștergerea elementelor: contorul trebuie să coincidă
cu numărul elementelor rămase, ștergerea unei înregistrări nu trebuie
să șteargă alta cu același nume.
Nu modifica fișierele. Returnează concluziile din cod și ce trebuie verificat în browser.

Aici există deja totul pentru o verificare punctuală: unde să caute, ce trebuie să se întâmple și ce rezultat e necesar. De un brief într-un fișier separat nu e nevoie aici. Agentul principal va formula sarcina pentru reviewer-ul ales; alegerea prin @ stabilește executantul, nu transmiterea literală a mesajului dumneavoastră.

5. Cum vine rezultatul

După trimiterea cererii, verificați dacă a apărut lansarea reviewer-ului. Într-o sesiune interactivă obișnuită, o asemenea muncă poate rula în fundal: o vedeți în panou și puteți continua conversația. Comanda /tasks vă ajută să vedeți sarcinile, inclusiv pe cele finalizate recent.

Când verificarea se termină, agentul principal primește rezultatul și vi-l comunică. Dacă repovestirea e prea scurtă, cereți: "Arată raportul final al reviewer-ului în întregime". Așa e mai ușor să păstrați formularea exactă a constatării și limitele verificării.

De exemplu, un raport didactic despre contor ar putea arăta așa:

Am verificat adăugarea și ștergerea în app.js.
În removeItem() lista se redesenează, dar nu am găsit apelul updateCounter()
pe această cale. Contorul ar trebui să arate numărul
înregistrărilor rămase.
Verificare în browser: adaugă un element, șterge-l,
compară contorul cu lista goală.
Nu am verificat separat ștergerea înregistrărilor cu același nume.
Nu am rulat în browser.

Acesta este un exemplu de formă a răspunsului, nu o promisiune că veți găsi exact un asemenea bug pe pagina dumneavoastră. Reviewer-ul nostru poate doar citi codul, deci ultima linie îi descrie cinstit posibilitățile. O concluzie din cod poate fi întemeiată și fără rulare, dar justificarea ei trebuie verificată: de exemplu, dacă nu cumva contorul este actualizat de o altă funcție pe aceeași cale.

Deschideți locul indicat sau repetați acțiunile descrise în browser. Dacă problema se confirmă, puteți cere agentului principal să o corecteze. Dacă nu, comunicați observația dumneavoastră și cereți verificarea concluziei. Un raport frumos formatat încă nu decide ce anume trebuie schimbat.

Răspunsul "conform criteriilor date, nu am găsit probleme" este de asemenea acceptabil, dacă este clar ce a fost verificat. Dar "nu am găsit fișierul cu logica de ștergere" înseamnă un rezultat parțial: mai întâi trebuie clarificată calea. Nu are rost să umpleți raportul cu presupuneri doar de dragul numărului.

Apropo, în listă pot apărea și rolurile încorporate Explore și Plan. Sunt disponibile fără a crea propriile fișiere de rol.

6. Când merită să delegați

După prima verificare cu succes, este ușor să doriți un asistent separat pentru fiecare acțiune. Tentația e de înțeles. Dar o lansare nouă trebuie să aducă ceva: o privire independentă sau o muncă de sine stătătoare, al cărei mers detaliat nu e necesar în conversația principală.

Mai mulți pași dependenți pot forma, de asemenea, o singură sarcină pentru un subagent. Să găsească handlerul, să-i verifice apelurile și să formuleze o concluzie - este o sarcină normală, unitară. Doar că nu merită să dați fiecare pas unui asistent separat, dacă apoi va trebui să le explicați tuturor din nou rezultatele pasului vecin.

Modelul pentru subagent se poate stabili separat, prin câmpul model. acum nu e necesar: mai întâi e mai util să obțineți un rol clar și un rezultat verificabil. O lansare separată nu înseamnă în sine nici un model mai puternic, nici unul mai slab.

Al doilea rol trebuie să verifice altceva

Să presupunem că, pe lângă reviewer, aveți nevoie de un playtester pentru a verifica un scenariu al utilizatorului. O copie a instrucțiunii anterioare cu un nume nou nu va schimba aproape nimic. Mai întâi, delimitați obiectul muncii și rezultatul:

De exemplu, rolul ar putea analiza doar ștergerea uneia din două achiziții cu același nume: după acțiune trebuie să rămână o înregistrare, iar contorul trebuie să afișeze 1. Aceasta este o sarcină măsurabilă. "Evaluează dacă pagina e bună" lasă prea mult loc pentru sfaturi subiective.

Acum puneți sarcina în corespondență cu instrumentele. Având doar citire și căutare, ca reviewer-ul nostru, asistentul nu va executa acțiuni în browser. Poate alcătui un scenariu de verificare sau poate analiza observațiile pe care le-ați notat. Aceasta este pregătirea sau analiza verificării, nu un playtest executat de el însuși.

Pregătește un scenariu de verificare a ștergerii uneia din două achiziții
cu același nume. Pentru fiecare pas indică acțiunea
și rezultatul așteptat. Nu modifica codul, nu declara execuția.
După observațiile mele, compară ce era așteptat cu ce s-a întâmplat
și enumeră ce date lipsesc.

Pentru ca rolul să ruleze singur verificarea, e nevoie de un instrument disponibil pentru lucrul cu browserul și de confirmarea că rularea chiar a avut loc. Doar numele playtester nu ajunge pentru asta. Mai întâi alegeți metoda de verificare, apoi descrieți în rol când să fie apelat și ce rezultat poate returna cinstit.

7. Cum arată asta în sesiunea dumneavoastră

Acum aveți un fișier de rol pe care sesiunea îl vede și o verificare scurtă pe care i-o puteți încredința. Pentru început e suficient. Nu trebuie să adunați din timp o duzină de reviewer-i asemănători.

Mai departe corectați stratul în care a apărut problema. Nu ați transmis o condiție importantă - completați sarcina. Ați primit o concluzie discutabilă - verificați justificarea. Reviewer-ul returnează în mod regulat răspunsuri prea generale - clarificați instrucțiunea rolului. Fișierul rămâne în proiect, iar următoarea verificare o veți începe având deja aceste reguli.

Pentru sarcini repetabile, va fi util un brief pentru reviewer. Când ați obținut deja răspunsul, treceți la verificarea constatărilor și alegerea corecțiilor.