Mga subagent sa Claude Code: paghihiwalay ng context, orchestrator at reviewer, at kailan hindi kailangan

Ano ang mga subagent sa Claude Code

Ang subagent ay isa pang instance ng agent na pinapatakbo ng pangunahing agent para sa hiwalay na gawain. May sarili itong context window, sariling system prompt, at sariling listahan ng pinapayagang tool. Ibinibigay ng pangunahing agent ang paglalarawan ng gawain, nagtatrabaho nang mag-isa ang subagent (nagbabasa ng file, nagpapatakbo ng mga utos), at ibinabalik lamang ang huling mensahe.

Ang susing salita dito ay paghihiwalay. Lahat ng nabasa ng subagent sa daan (dose-dosenang file, mahabang output ng test, mga hipotesis na napunta sa wala) ay nananatili sa kanyang context at hindi napupunta sa context ng pangunahing session. Maikling resulta lamang ang nakikita ng pangunahing agent: "ang error ay nasa function X, ang sanhi ay ganito, at ito ang tatlong lugar na apektado."

Ang mga subagent sa Claude Code ay isang partikular na kaso ng mas malawak na ideya ng multi-agent na sistema: sa halip na isang siklo ng "mag-isip, gumawa, suriin," nagkakaroon ng graph ng ilang node, bawat isa ay may sariling tungkulin at responsibilidad.

Bakit kailangan ang paghihiwalay ng context

Ang context window ang pangunahing yaman ng agent. Sabay-sabay itong naglalaman ng mga tagubilin mula sa CLAUDE.md, kasaysayan ng usapan, nabasang code, at output ng mga utos. Kapag ilang minuto nang naghahanap ang agent ng sanhi ng bug, napupuno ang context ng mga file na walang kinalaman at log na isang linya lamang ang mahalaga.

Pamilyar ang mga kahihinatnan sa sinumang matagal nang gumagamit ng agent: nahihirapan ang modelo na panatilihin ang mga tuntunin ng proyekto, nalilito sa mga detalye, at kapag awtomatikong pinaikli ang kasaysayan, nawawala ang mahalaga. Istruktural ang lunas ng subagent: ang maruming gawain ay ginagawa sa hiwalay na context na itinatapon pagkatapos ng sagot.

• Paghahanap at pag-iimbestiga. "Hanapin ang lahat ng lugar na tumatawag sa function ng bayad at ilarawan kung paano ito gumagana" — tipikal na gawain para sa subagent.
• Maiingay na pagsusuri. Ipagawa sa subagent ang pagpapatakbo ng test at pagsusuri ng mga pumalyang test, at ibalik ang listahan ng mga sanhi.
• Pagbasa ng malalaking dokumento. Kailangan ang espesipikasyong may daan-daang pahina para sa ilang katotohanan lamang: hayaan ang subagent na kunin ang mga ito.

Paano i-set up ang subagent: folder na .claude/agents

Inilalarawan ang sariling subagent sa pamamagitan ng Markdown file na may YAML header. Nasa .claude/agents/ sa repositoryo ang mga file ng proyekto at naaabot ng buong koponan sa pamamagitan ng git; ang mga personal ay nasa ~/.claude/agents/ at gumagana sa lahat ng proyekto mo. Maaari ding gumawa at mag-edit ng subagent nang interaktibo gamit ang utos na /agents sa Claude Code.

---
name: code-reviewer
description: Sinusuri ang mga pagbabago sa code para sa mga error at paglabag sa tuntunin ng proyekto. Gamitin pagkatapos tapusin ang gawain, bago mag-commit.
tools: Read, Grep, Glob, Bash
---
Ikaw ay reviewer ng code. Hindi mo kailangang ayusin ang anuman.

1. Tingnan ang mga pagbabago: git diff.
2. Suriin ang bawat pagbabago para sa mga error sa lohika, paghawak ng error,
   seguridad (SQL, pag-escape ng output, mga secret).
3. Ihambing sa mga tuntunin sa AGENTS.md.
4. Ibalik ang listahan ng mga puna: file, linya, problema, at kung bakit ito mahalaga.
   Kung walang puna, sabihin mo iyon nang diretso.

Ang kahulugan ng mga field:

Ang katawan ng file ang system prompt ng subagent. Hindi nito nakikita ang kasaysayan ng usapan ninyo, kaya ang lahat ng kailangan niyang malaman tungkol sa tungkulin at format ng sagot ay dapat nasa prompt o nasa gawaing ibinigay ng pangunahing agent.

Paano tawagan ang subagent

Maaaring pumili ng subagent ang pangunahing agent sa sarili kung tugma ang gawain sa kanyang description. Mas maaasahan kung tahasan itong hihilingin: "Gamitin ang subagent na code-reviewer para suriin ang mga pagbabago." Ang mga parirala tulad ng "gamitin nang maagap" sa paglalarawan ay nagpapataas ng tsansang tawagin ito nang walang paalala, pero hindi nito ginagarantiya.

Subagent na tagasiyasat

Ang pangalawang file na sulit gawin sa halos anumang proyekto ay isang tagasiyasat na read-only. Sumasagot ito sa mga tanong tungkol sa code at walang binabago.

---
name: explorer
description: Naghahanap sa codebase ng mga sagot kung nasaan at paano gumagana ang isang bagay. Gamitin kapag kailangang basahin ang maraming file para sa maikling sagot.
tools: Read, Grep, Glob
---
Sinisiyasat mo ang code at wala kang binabago.
Ibalik: maikling sagot sa tanong, listahan ng mga file na may linya
na pinagbatayan nito, at ang hindi mo nakumpirma.

Lalo na kapaki-pakinabang ang ganitong subagent sa simula ng gawain: nakukuha ng pangunahing agent ang mapa ng mga kailangang lugar nang hindi nauubos ang context sa pagbabasa ng lahat, at tuloy-tuloy na nagtatrabaho sa mga partikular na file.

Ang iskemang "orchestrator at mga worker"

Ang pinakakaraniwang multi-agent na iskema: isang orchestrator ang nagpapanatili ng plano at kabuuang larawan, at ipinamamahagi ang mga partikular na hakbang sa mga worker. Hindi binabasa ng orchestrator ang buong code; bumubuo ito ng mga gawain, tumatanggap ng resulta, at nagpapasya kung ano ang susunod na gagawin.

1. Hinahati ng orchestrator ang gawain sa mga independent na bahagi at para sa bawat isa ay sumusulat ng kumpletong tagubilin: layunin, saan hahanapin, ano ang ituturing na tapos na, at sa anong anyo ibabalik ang sagot.
2. Isinasagawa ng mga worker ang mga tagubilin sa sarili nilang context.
3. Pinagsasama ng orchestrator ang mga sagot, sinisiguradong nagtutugma ang mga bahagi, at nagpapatuloy sa susunod na hakbang o bumabalik sa nakaraan.

Mahinang bahagi ng iskemang ito ang paglilipat ng gawain. Ang subagent ay alam lamang ang isinulat sa kanya. Ang tagubiling "ayusin ang bug na pinag-usapan natin" ay walang laman para sa kanya: wala siyang nakitang usapan. Ang mahusay na tagubilin ay parang gawain para sa bagong kasamahan na unang beses pa lang nagbubukas ng repositoryo.

Ano ang dapat ibalik ng worker

Ituro nang maaga ang format ng sagot: listahan ng mga file, output, natuklasang sanhi, at kung ano ang hindi nasubukan. Nakatitipid ng context ng orchestrator ang maikli at estrukturadong sagot, at pinoprotektahan ka ng bahaging "hindi nasubukan" laban sa maling kumpiyansa: ang worker, tulad ng anumang agent, ay madaling mag-ulat ng tagumpay.

Hiwalay na reviewer: bakit paghiwalayin ang hukom at ang gumagawa

Kapag ang iisang agent ang sumusulat ng code at siya rin ang sumusuri nito, iisang ulo ang hukom at ang akusado. Naaalala ng agent ang gusto niyang gawin at nakikita sa code ang sarili niyang layunin, hindi ang aktuwal na nakasulat. Dagdag pa, interesado siyang matapos ang gawain, kaya nagiging pormalidad ang pagsusuri.

Walang ganitong problema ang reviewer sa hiwalay na context. Wala siyang alam sa kasaysayan ng mga desisyon, nakikita lamang niya ang diff at ang mga tuntunin ng proyekto, at sinusuri niya ang resulta nang may sariwang mata. Ito ang parehong prinsipyo ng totoong koponan: hindi tinatanggap ng awtor ang sarili niyang pull request.

• Bigyan ang reviewer ng mga tool sa pagbasa at pagpapatakbo ng pagsusuri lamang, walang karapatang mag-edit ng file. Sa ganoon, hindi siya magsisimulang "tahimik na ayusin" sa halip na iulat ang problema.
• Ilarawan nang tahasan ang pamantayan ng pagsusuri: ano ang ituturing na error, anong tuntunin ng proyekto ang sapilitan.
• Iwan sa orchestrator o sa tao ang pagpapasya kung ano ang gagawin sa mga puna. Natutuklasan ng reviewer, inaayos ng worker.

Hindi pumapalit ang reviewer sa mga mekanikal na pagsusuri. Ang test, linter, at pagsusuri ng uri ay mga deterministikong node, mas maaasahan ang mga ito kaysa sa anumang modelo. Nahuhuli ng reviewer ang hindi nakikita ng mekanika: maling lohika, paglabag sa mga kasunduan, at labis na kumplikasyon.

Sabayang pagpapatakbo ng mga subagent

Kayang magpatakbo ng ilang subagent nang sabay ang Claude Code. Nagpapabilis ito kapag tunay na independent ang mga bahagi ng gawain: pag-aralan ang tatlong module, suriin ang mga pagbabago mula sa tatlong panig (seguridad, performance, test), o mangalap ng impormasyon mula sa ilang pinagmulan.

Mahusay ang sabayang pagpapatakbo sa pagbasa at mahina sa pagsulat. Kapag sabay na nagbabago ang dalawang worker sa parehong mga file, nabubura nila ang pagbabago ng isa't isa, at walang nakakaalam nito. Sa wika ng graph ng mga agent, ito ay shared state na walang panuntunan sa pagsasama. Mga praktikal na tuntunin:

• Sabay ang pagsisiyasat, pagsusuri, at pagrerepaso. Sunod-sunod ang mga pagbabago sa mga file na nagsasalubong.
• Kung sabay pa rin ang pagsusulat ng mga worker, hatiin ang mga sona: bawat isa ay gumagawa lamang sa sarili niyang mga file o sa sarili niyang kopya ng repositoryo (halimbawa sa hiwalay na git worktree).
• Iisang node, ang orchestrator, ang nagsasama ng mga resulta, hindi ang mga worker sa isa't isa.

Kailan hindi kailangan ang mga subagent

May kapalit ang multi-agent na iskema: mas maraming token, mas maraming oras, at mas maraming lugar kung saan nawawala ang impormasyon sa paglilipat. Hindi laging nagbabayad ang mga subagent sa Claude Code.

Bago bumuo ng graph ng mga agent, sagutin muna ang mga simpleng tanong: sino ang may-ari ng pangkalahatang layunin, sino ang may karapatang mag-veto at magbalik ng pagbabago, at anong sukatan ang ituturing na tagumpay. Kung walang sagot, lalo lamang dadami ang gulo ng isang tao sa dami ng mga agent.

Mga karaniwang pagkakamali sa mga subagent

Malabong paglalarawan

Ang paglalarawang "katulong para sa code" ay hindi nakatutulong sa pangunahing agent na pumili kung kailan ito tatawagin. Magsulat ng trigger: "pagkatapos ng pagbabago sa folder na api/, bago mag-commit."

Tagubiling walang konteksto

Tumatanggap ang subagent ng gawain na walang landas, walang pamantayan ng pagkatapos, at walang limitasyon, kaya kalahati ng trabaho ay napupunta sa paghula kung ano ang gusto. Ang lunas ay template ng tagubilin: layunin, input, limitasyon, at format ng sagot.

Sobrang lawak na karapatan

Hindi kailangan ng tagasiyasat at reviewer ang karapatang mag-edit ng file. Ang limitasyon sa tools ay murang paraan para gawing mekanismo ang tungkulin, hindi isang kahilingan sa prompt.

Pagtitiwala sa ulat nang walang pagsusuri

Ang "lahat ng test ay pumasa" sa sagot ng subagent ay pahayag, hindi katotohanan. Dapat umasa ang orchestrator sa mga bagay na nasusuri: output ng utos, return code, at partikular na mga linya.

Sa madaling sabi

Ang mga subagent sa Claude Code ay kasangkapan para sa tatlong gawain: panatilihing malinis ang pangunahing context, ihiwalay ang pagsusuri sa pagpapatupad, at paghiwalayin ang independent na gawain para sabay na gawin. Inilalarawan ang mga ito sa maiikling Markdown file sa .claude/agents/, at ang kalidad ng kanilang trabaho ay halos buo nang nakasalalay sa paglalarawan ng tungkulin, sa hanay ng tool, at sa kung gaano kakumpleto ang pagkakasulat ng tagubilin. Kapag maliit ang gawain o malapit na nakatali sa usapan, mas mabuti pa rin ang isang agent. Ang paglipat mula sa iisang siklo patungo sa sistemang may mga node, gilid, at shared state ay tinatalakay nang praktikal sa kurso.