Subagent Claude Code: ce este, cum il creezi, cat consuma

Subagentii Claude Code (in engleza "Claude Code subagents") sunt asistenti specializati carora Claude le da o sarcina separata. Fiecare lucreaza intr-o fereastra de context proprie, cu propriul prompt de sistem, unelte limitate si permisiuni separate, si trimite inapoi in conversatia principala doar un rezumat.

Ii creezi cu un fisier Markdown in folderul .claude/agents/.

Atentie insa: fiecare subagent Claude Code trimite propriile cereri si consuma din aceleasi limite ale abonamentului tau.

In ghidul asta, actualizat la versiunea 2.1.318 din 4 noiembrie 2026, iti arat ce sunt, cum creezi un subagent de la zero, cum il apelezi si cat consuma pe Pro, Max si Ultra. In romana aproape ca nu exista un ghid complet: documentatia oficiala e doar in engleza si se schimba saptamanal.

Ce sunt subagentii Claude Code

Un subagent Claude Code este o sesiune de lucru secundara pe care Claude o porneste cand o sarcina ar umple conversatia principala cu fisiere citite, loguri sau rezultate de cautare de care nu mai ai nevoie.

Subagentul face munca grea in contextul lui si iti aduce doar sinteza.

Fiecare subagent Claude Code are patru elemente:

• Un prompt de sistem propriu: primeste doar acest prompt si cateva detalii de baza, cum ar fi folderul de lucru. Nu primeste promptul de sistem complet al Claude Code.
• O lista de unelte: ii poti da doar citire sau si scriere si comenzi.
• Un model: acelasi ca in conversatia principala sau unul mai ieftin, de exemplu Haiku.
• Permisiuni independente: un mod de permisiuni diferit de cel al sesiunii.

Lucrul care ii surprinde pe cei mai multi: un subagent nu vede conversatia ta.

Porneste doar cu promptul lui, cu mesajul de delegare scris de Claude, cu fisierele CLAUDE.md si cu un snapshot de git status. Daca ai explicat 20 de minute un bug si apoi delegi "rezolva-l", subagentul nu stie nimic din acele 20 de minute.

Subagentii incorporati: Explore, Plan si general-purpose

Claude Code vine cu cativa subagenti gata facuti, pe care Claude ii foloseste singur cand e cazul:

• Explore: agent rapid, doar citire (Write si Edit blocate), facut pentru cautare si intelegerea codului. Claude ii alege nivelul de detaliu: quick, medium sau very thorough. Porneste fara CLAUDE.md si fara git status, ca sa fie rapid si ieftin.
• Plan: lucreaza in plan mode si aduna context inainte sa iti propuna un plan. Tot doar citire.
• General-purpose: are toate uneltele disponibile pentru subagenti si e folosit pentru sarcini care cer si explorare, si modificari.
• Agenti de serviciu: statusline-setup (ruleaza pe Sonnet cand folosesti /statusline) si claude-code-guide (ruleaza pe Haiku cand pui intrebari despre Claude Code).

Un truc util ca sa economisesti: daca iti creezi propriul subagent numit Explore, el il inlocuieste pe cel incorporat si isi pastreaza campul model. Cu model: haiku toate explorarile ruleaza pe un model mai ieftin.

Cum creezi un subagent Claude Code

Un subagent Claude Code este un fisier Markdown cu un antet YAML (frontmatter) urmat de promptul de sistem. Poti sa ii ceri lui Claude sa il scrie sau il creezi de mana. Sfatul meu: lasa-l pe Claude sa scrie prima versiune, apoi citeste-o rand cu rand.

Pasul 1: alege unde il salvezi

• .claude/agents/ in folderul proiectului: e valabil doar pentru acel proiect. E locul potrivit pentru subagenti legati de un anumit cod, pe care ii pui in git ca sa ii foloseasca toata echipa.
• ~/.claude/agents/ in folderul tau personal: e valabil in toate proiectele tale.
• Flagul --agents la pornire: definitie JSON valabila doar pentru acea sesiune, utila pentru teste si scripturi.
• Plugin: subagentii vin instalati odata cu pluginul.

Daca doi subagenti au acelasi nume, castiga cel cu prioritate mai mare: setarile gestionate de organizatie, apoi flagul --agents, apoi proiectul, apoi utilizatorul si la final pluginul.

Pasul 2: scrie fisierul

Un exemplu de reviewer doar pentru citire, salvat ca .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Verifica codul modificat si semnaleaza buguri, probleme de securitate si de mentenanta. Foloseste-l dupa fiecare modificare.
tools: Read, Grep, Glob
model: sonnet
---

Esti un reviewer de cod. Cand esti apelat, analizeaza modificarile
si da indicatii concrete despre calitate, securitate si bune practici.
Indica fisierul si linia pentru fiecare problema. Nu modifica fisierele.

Doar name si description sunt obligatorii. Atentie la greseli de scriere: numele campurilor sunt in camelCase, iar Claude Code ignora fara niciun mesaj un camp pe care nu il recunoaste.

Un fisier fara description, cu YAML invalid sau cu primul --- care nu e pe prima linie este sarit fara avertizare in sesiune. Motivul apare in logul de debug (claude --debug).

Pasul 3: testeaza-l

Cere-i lui Claude sa il foloseasca: "Foloseste subagentul code-reviewer ca sa verifici ultimele modificari". In transcriere vei vedea un rand cu numele subagentului si o scurta descriere a sarcinii.

Claude Code detecteaza fisierele noi sau modificate in cateva secunde, fara restart. Singura exceptie: daca folderul agents nu exista cand ai deschis sesiunea, trebuie sa repornesti.

O nota pentru cine urmeaza tutoriale vechi: comanda /agents nu mai deschide asistentul interactiv. Afiseaza doar un mesaj care iti spune sa ii ceri lui Claude sau sa editezi folderele de mana.

Asistentul cu taburile Running si Library a existat pana la versiunea 2.1.197.

Campurile din frontmatter care conteaza cu adevarat

• description: e regula dupa care Claude decide cand sa delege. E cel mai important rand din fisier. Daca scrii "use proactively" sau "foloseste-l mereu dupa...", Claude deleaga mai des.
• tools si disallowedTools: lista de unelte permise sau interzise. Un prompt care spune "nu modifica fisierele" e o rugaminte; sa scoti Edit si Write din unelte e un zid.
• model: sonnet, opus, haiku, fable, un ID complet ca claude-opus-5-5 sau inherit.
• effort: nivelul de rationament al subagentului (low, medium, high, xhigh, max, in functie de model).
• maxTurns: numarul maxim de pasi. La limita, rezultatul revine marcat ca partial, iar Claude il poate relua.
• skills: skill-uri incarcate din start in contextul subagentului, cu tot continutul.
• isolation: worktree: subagentul lucreaza intr-un git worktree temporar, o copie izolata a repository-ului.
• memory: memorie persistenta cu scop user, project sau local.

Cum apelezi un subagent Claude Code

Exista patru moduri, de la cel mai lejer la cel mai strict:

1. Delegare automata: Claude alege singur, dupa cererea ta si dupa description din fiecare subagent.
2. Dupa nume: "foloseste subagentul test-runner ca sa repari testele". De obicei Claude deleaga, dar decizia ii apartine.
3. Cu mentiunea @: scrii @ si alegi subagentul din lista sau scrii @agent-nume. Asa subagentul porneste sigur pentru acea sarcina.
4. Pentru toata sesiunea: claude --agent code-reviewer transforma intreaga sesiune in acel subagent, cu uneltele si modelul lui. Il poti face implicit pentru un proiect cu cheia agent in .claude/settings.json.

Descrierile ocupa context: cand descrierile subagentilor tai depasesc impreuna 15.000 de tokeni, Claude Code afiseaza un avertisment la pornire.

Tine-le scurte si muta detaliile in promptul de sistem, care se incarca doar cand subagentul ruleaza.

Cat consuma subagentii Claude Code din limite

Asta e partea pe care tutorialele o sar. Documentatia e clara: fiecare subagent trimite propriile cereri, iar acestea se scad din aceleasi limite de utilizare ca si conversatia principala.

Cinci subagenti in paralel inseamna cinci contexte care se umplu, iar rezultatele care se intorc ocupa loc si in conversatia principala.

Daca folosesti Claude Code cu abonament, consumul se vede in fereastra de 5 ore si in plafonul saptamanal.

Detaliile despre planuri si preturi in lei le gasesti in ghidul meu despre cat costa Claude Pro, Max si Ultra. Ai trei parghii ca sa tii consumul sub control.

1. Alege modelul potrivit pentru fiecare subagent

Un subagent Claude Code care ruleaza testele si raporteaza doar ce a picat nu are nevoie de Opus. Claude Code alege modelul unui subagent in aceasta ordine:

1. parametrul model pe care Claude il trimite pentru acel apel;
2. campul model din frontmatter (inherit inseamna modelul principal);
3. variabila de mediu CLAUDE_CODE_SUBAGENT_MODEL;
4. modelul conversatiei principale.

Daca vrei sa impui un singur model tuturor subagentilor, seteaza si CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1.

Ca sa verifici, ruleaza /tasks in timp ce un subagent lucreaza: randul lui arata modelul folosit. Pentru munca de rutina, Claude Haiku 5.5 e prima optiune pe care merita sa o testezi.

2. Scade effort-ul subagentilor

Din versiunea 2.1.316 din 31 octombrie 2026 exista variabila CLAUDE_CODE_SUBAGENT_EFFORT. Ea seteaza nivelul de effort al subagentilor cand nimic altceva nu il indica, in loc sa il mosteneasca pe cel al sesiunii.

Il poti fixa si in campul effort al fiecarui subagent. Pentru un subagent Claude Code care doar cauta in cod, un effort mic e de multe ori suficient.

3. Limiteaza cati pornesc

• Maximum 20 de subagenti care ruleaza simultan intr-o sesiune: peste, apelul esueaza cu Concurrent subagent limit reached. Se schimba cu CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Maximum trei niveluri de imbricare: un subagent poate porni alti subagenti pana la trei niveluri sub conversatia principala. Cu CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 opresti imbricarea.
• Nicio limita totala pentru numarul de subagenti dintr-o sesiune: frana reala sunt limitele abonamentului.

Pentru un control mai larg al consumului de tokeni, comenzile /usage, /context si /compact sunt explicate in ghidul despre optimizarea Claude Code si reducerea tokenilor.

Noutatile de la inceputul lui noiembrie 2026

Ultimele trei versiuni au atins chiar subagentii Claude Code:

• 2.1.316 (31 octombrie): apare CLAUDE_CODE_SUBAGENT_EFFORT.
• 2.1.317 (3 noiembrie): subagentii care ruleaza pe alt model decat cel principal folosesc effort-ul salvat pentru acel model sau valoarea lui implicita, nu effort-ul sesiunii.
• 2.1.318 (4 noiembrie): subagentii din fundal muta in fundal o comanda de shell dupa 3 minute, ca sa nu expire cache-ul promptului cat timp comanda ruleaza. A fost reparat si mesajul "Now using usage credits" care reaparea cam la fiecare 30 de secunde cat timp rula un subagent in fundal.

Sfatul practic: actualizeaza cu claude update si verifica versiunea cu claude --version. Daca nu ai instalat inca instrumentul, porneste de la ghidul de instalare Claude Code pe Windows, Mac si Linux.

Subagenti in paralel, in fundal si fork

Implicit, un subagent Claude Code pornit din conversatia principala ruleaza in fundal: tu continui sa lucrezi, iar rezultatul vine ca notificare.

Daca subagentul cere o permisiune, cererea apare in sesiunea principala cu numele subagentului: aprobi sau apesi Esc ca sa refuzi doar acel apel.

Trei tipare care functioneaza bine:

• Izolarea operatiilor cu output mare: "foloseste un subagent ca sa rulezi testele si raporteaza-mi doar ce a picat, cu eroarea".
• Cercetare in paralel: "analizeaza in paralel modulele de autentificare, baza de date si API cu subagenti separati". Merge bine cand cautarile nu depind una de alta.
• Subagenti in lant: un reviewer gaseste problemele de performanta, apoi un al doilea subagent le repara.

Atentie la scrierea in paralel: doi subagenti care modifica aceleasi fisiere se incurca. In cazul asta foloseste isolation: worktree.

Mai exista si fork-ul: un subagent care mosteneste toata conversatia in loc sa porneasca de la zero. Il pornesti cu /subtask urmat de sarcina.

Pentru ca are acelasi prompt de sistem, aceleasi unelte si acelasi model ca sesiunea principala, refoloseste cache-ul ei si costa mai putin decat un subagent nou cand sarcina cere acelasi context.

Modul fork e activ implicit din versiunea 2.1.302.

Daca vrei ca Claude sa poata astepta un subagent inainte sa continue, il opresti cu CLAUDE_CODE_FORK_SUBAGENT=0 in blocul env din setari.

Subagent sau skill? Diferente fata de skill-uri, hook-uri si MCP

Se confunda des pentru ca toate extind Claude Code, dar raspund la intrebari diferite:

• Subagent Claude Code: schimba unde face Claude munca. Context separat, se intoarce doar un rezumat. Ideal pentru sarcini zgomotoase si cercetare in paralel.
• Skill: schimba cum face Claude un lucru. Instructiuni refolosibile care ruleaza in conversatia curenta. Detalii in ghidul despre cum creezi un skill Claude de la zero.
• Hook: garanteaza ca ceva se intampla mereu, la un eveniment precis, in afara modelului.
• Server MCP: schimba ce poate atinge Claude, de exemplu baze de date, tichete si API-uri. Vezi ghidul despre ce este MCP si cum functioneaza.

Se pot combina: un subagent poate incarca skill-uri cu campul skills, poate avea propriile hook-uri in frontmatter si propriile servere MCP cu mcpServers.

Regula mea: daca problema e "output-ul asta e prea mare pentru contextul meu", ai nevoie de un subagent. Daca e "explic mereu aceeasi procedura", ai nevoie de un skill. Pentru skill-uri gata facute, vezi cele mai bune skill-uri Claude Code.

Cand nu merita un subagent Claude Code

Subagentii Claude Code nu sunt mereu cea mai buna alegere. Ramai in conversatia principala cand:

• sarcina cere multe schimburi si corecturi repetate;
• mai multe etape impart mult context, cum ar fi planificarea, implementarea si testele;
• ai de facut o modificare rapida si punctuala;
• conteaza viteza: un subagent care nu e fork porneste de la zero si are nevoie de timp sa adune context.

Pentru o intrebare despre ceva care e deja in conversatie exista /btw: nu are acces la unelte, iar raspunsul nu intra in istoric.

Securitate, date personale si GDPR

Cand configurez Claude Code pe un proiect, aici insist cel mai mult. Cateva reguli care se aplica mereu:

• Da doar uneltele necesare: un subagent Claude Code de cercetare cu tools: Read, Grep, Glob nu poate scrie si nu poate rula comenzi.
• Blocheaza comenzi anume din setari: o intrare ca Bash(git push *) in disallowedTools ii ia subagentului tot Bash. Ca sa blochezi doar acea comanda, pune-o in permissions.deny.
• Subagentii din pluginuri au mai putine puteri: din motive de securitate ignora campurile hooks, mcpServers si permissionMode.
• Raportul subagentului e scanat: Claude Code marcheaza texte care imita mesajele lui sau mentioneaza setari ca bypassPermissions. Scanarea nu judeca daca un text e malitios si nu inlocuieste limitarea uneltelor.
• Poti opri subagentii: adaugi un tip in permissions.deny sau refuzi unealta Agent ca sa nu mai existe nicio delegare.

Daca un subagent Claude Code are acces printr-un server MCP la o baza de date cu date personale ale clientilor, de exemplu nume, adrese sau CNP, raspunderea GDPR ramane a firmei tale, iar autoritatea de supraveghere in Romania este ANSPDCP.

In practica: da-i doar uneltele de citire de care are nevoie si nu ii conecta servere MCP pe care nu le-ai verificat.

Pentru un nivel in plus de izolare, poti rula Claude Code intr-o microVM: am scris despre asta in ghidul despre Docker Sandbox pentru Claude Code si Codex.

Citeste si

• Claude Code Projects: cum functioneaza, cat consuma, limite
• Claude Code mods: ce sunt, cum le instalezi si ce riscuri au
• Codex vs Claude Code: limite si pret in Romania
• Claude Cowork vs Claude Code: diferente si ce alegi
• Pi coding agent: ce este, instalare si noutatile din 1.5

Concluzie: incepe cu un singur subagent

Cel mai bun mod de a incepe cu subagentii Claude Code este sa creezi unul singur, pentru cea mai zgomotoasa sarcina pe care o ai: de obicei testele sau cautarea in cod. Da-i unelte doar de citire, un model ieftin si o description clara.

Apoi verifica cu /usage cat consuma din limite inainte sa adaugi altii.

Daca vrei sa aduci astfel de agenti in munca firmei tale, cu permisiuni si costuri sub control, vezi ce fac pe pagina despre agenti AI pentru firme si pe cea despre automatizari AI. Pentru un proiect concret, scrie-mi din pagina de contact.