Subagent-lərlə işləmək

Birinci fəsildə subagent-ləri context izolyasiyası aləti kimi tanıdıq: araşdırma ayrı pəncərədə gedir, əsas agent yalnız nəticəni görür. Bu fəsil mexanizmi açır: subagent necə təyin olunur, əsas agent onu nə vaxt seçir, hansı tool-lara çıxışı olur və bir neçə subagent-dən ibarət sistemi necə dizayn etmək lazımdır.

Subagent nədir

Subagent Claude Code-un eyni harness-də, amma ayrı context window və ayrı system prompt ilə işə saldığı ikinci agent-dir. Əsas agent ona tapşırığı mətn kimi verir, subagent öz loop-unu işlədir, yəni faylları oxuyur, command işlədir, düşünür, və sonda bir hesabat qaytarır. Əsas agent-in context-inə yalnız bu hesabat düşür. Subagent-in oxuduğu on fayl, işlətdiyi iyirmi grep, uğursuz cəhdləri, hamısı onun öz pəncərəsində qalır və session bitəndə yox olur.

Claude Code bir neçə built-in subagent ilə gəlir: geniş axtarış üçün yalnız oxuyan agent, plan hazırlayan agent, ümumi məqsədli agent. Siz öz subagent-lərinizi əlavə edirsiniz və əsas fərq məhz oradadır: subagent-in system prompt-u onun ixtisasını, tool siyahısı isə sərhədlərini müəyyən edir.

Subagent-i təyin etmək

Subagent-lər Markdown fayllarıdır. Layihə səviyyəsində .claude/agents/, istifadəçi səviyyəsində ~/.claude/agents/ qovluğunda yaşayır; layihə faylı eyni adlı istifadəçi faylını üstələyir. Faylın frontmatter-i metadata, gövdəsi isə system prompt-dur:

---
name: code-reviewer
description: Dəyişdirilmiş kodu review edir. Kod yazıldıqdan və ya dəyişdirildikdən sonra, commit-dən əvvəl istifadə et. Yeni kod yazmaq üçün istifadə etmə.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Sən təcrübəli code reviewer-san. Vəzifən dəyişdirilmiş kodu oxuyub problemləri tapmaqdır, düzəltmək deyil.

İş qaydası:
1. `git diff` ilə dəyişiklikləri al.
2. Hər dəyişikliyi üç meyarla yoxla: düzgünlük, layihə konvensiyalarına uyğunluq, test coverage.
3. Yalnız real problemləri yaz; üslub iradlarını yalnız CLAUDE.md-də qayda varsa qeyd et.

Hesabat formatı: hər problem üçün fayl və sətir, problemin bir cümləlik təsviri, təklif olunan düzəliş. Problem yoxdursa, bunu bir cümlə ilə de.

Frontmatter-in sahələri:

Faylı əl ilə yazmaq əvəzinə session-da /agents command-ı ilə interaktiv yaratmaq və redaktə etmək də olar; command mövcud subagent-ləri siyahılayır, yenisini Claude-un köməyi ilə yazdırır və tool siyahısını seçdirir.

Routing: əsas agent subagent-i necə seçir

Subagent-in ən vacib sahəsi description-dır, çünki əsas agent subagent-i tapşırığa uyğun seçəndə bu mətnə baxır. Əsas agent sizin prompt-unuzu oxuyur, mövcud subagent-lərin təsvirlərini görür və uyğun gələni seçir; siz subagent-i adı ilə birbaşa da çağıra bilərsiniz: "code-reviewer subagent-i ilə review et".

Buna görə təsvir "kod review edir" kimi ümumi olmamalıdır. Yaxşı təsvir üç şeyi deyir: subagent nə edir, nə vaxt istifadə olunmalıdır, nə vaxt istifadə olunmamalıdır. "Commit-dən əvvəl", "kod yazıldıqdan sonra", "yalnız test faylları üçün" kimi ifadələr routing-i dəqiqləşdirir. İki subagent-in təsviri üst-üstə düşürsə, əsas agent təsadüfi seçir və nəticə qeyri-sabit olur. Təsvirlər bir-birini tamamlamalı, kəsişməməlidir.

Birinci fəslin ROI prinsipi burada da işləyir: hər subagent-in adı və təsviri əsas agent-in context-ində dayanır. Beş-on yaxşı təsvir edilmiş subagent sağlamdır; əlli subagent həm context-i doldurur, həm də routing-i qarışdırır.

Tool sərhədləri və model seçimi

tools sahəsi subagent-in nə edə biləcəyini müəyyən edir və bu, həm təhlükəsizlik, həm də keyfiyyət məsələsidir. Reviewer-ə Edit verməmək onu "düzəltmək" həvəsindən saxlayır və hesabatı təmiz edir. Araşdırma agent-inə Bash verməmək onun təsadüfən test işlədib context-i log ilə doldurmasının qarşısını alır. MCP tool-ları da buraya daxildir: sənədləşmə server-inin tool-unu yalnız ona ehtiyacı olan subagent-ə vermək context-i və xərci azaldır.

Model seçimi iş növünə görədir. Geniş axtarış, fayl siyahısı, sadə xülasə kimi işlər kiçik və sürətli model ilə ucuz və yetərli olur. Mürəkkəb mühakimə tələb edən review və ya dizayn üçün böyük model lazımdır. inherit seçimi subagent-in əsas session-ın modelini götürməsini təmin edir; əsas session-da model dəyişəndə subagent-lər də dəyişir.

Nümunə: iki fərqli xarakterli subagent

Fərqi görmək üçün iki subagent müqayisə edək.

Diagram generator. Kod strukturunu oxuyub Mermaid diaqramı qaytaran agent. Tool-ları: Read, Glob, Grep, və diaqramı fayla yazmaq üçün Write. Təsviri: "Kod bazasının və ya modulun strukturunu diaqram kimi göstərmək istənəndə istifadə et; kod dəyişikliyi üçün istifadə etmə." System prompt-u çıxış formatını sərt müəyyən edir: yalnız diaqram, izah yox. Bu agent "yalnız nəticə" tipidir; hesabatı kiçikdir və əsas context-ə demək olar ki, xərc yazmır.

Test author. Dəyişdirilmiş funksiyalar üçün test yazan agent. Tool-ları: oxuma tool-ları, Write, Edit, və test işlətmək üçün Bash. Təsviri: "Yeni və ya dəyişdirilmiş funksiya üçün test lazım olanda istifadə et; mövcud test-ləri refactor etmək üçün istifadə etmə." System prompt-u layihənin test konvensiyalarını və "test keçməyincə bitirmə" qaydasını yazır. Bu agent iş görür və hesabatı daha böyükdür: yazılan fayllar, keçən və keçməyən test-lər.

İkisinin ortaq cəhəti standartlaşdırılmış çıxışdır. Subagent-in hesabatı əsas agent-in context-inə yazıldığı üçün "nə etdim, nə tapdım, nə qaldı" formatı hər subagent-in system prompt-unda olmalıdır. Sərbəst formatlı, uzun hesabat izolyasiyanın faydasını yeyir.

Nə vaxt subagent, nə vaxt yox

Subagent pulsuz deyil və hər işə uyğun deyil. Üç xərci var. Birincisi, gecikmə: subagent öz context-ini sıfırdan qurur, yəni system prompt-u və memory fayllarını yenidən yükləyir, sonra araşdırmaya başlayır; kiçik iş üçün bu, əsas agent-in iki grep-indən yavaşdır. İkincisi, detalın itməsi: əsas agent subagent-in nə gördüyünü yox, nə dediyini bilir; hesabatda olmayan müşahidə itir. Üçüncüsü, paylaşılan yaddaşın olmaması: iki subagent bir-birinin nəticəsini görmür və eyni faylı iki dəfə oxuya bilər.

Buna görə seçim qaydası belədir. Tapşırıq bir-iki fayla baxmaqla bitirsə, əsas agent özü etsin. Tapşırıq onlarla fayl oxumağı, uzun log-ları və ya bir neçə uğursuz cəhdi tələb edirsə, subagent-ə verin; əsas context yalnız nəticəni görsün. Tapşırıq fərqli rol tələb edirsə, məsələn yazan agent-dən ayrı bir reviewer, subagent-ə verin; təmiz context və ayrı system prompt rolun fərqini qoruyur. Bu üç halın hamısında meyar eynidir: subagent əsas context-i qoruyurmu, yoxsa sadəcə işi uzadır?

Hesabat formatı

Subagent-in əsas agent-ə qaytardığı mətn onun yeganə çıxışıdır və əsas context-ə birbaşa yazılır. Bu mətnin formatı system prompt-da sərt müəyyən olunmalıdır. İşlək bir şablon:

Nəticə: bir cümlə ilə tapıntı və ya görülən iş
Fayllar: toxunulan və ya əhəmiyyətli fayllar, sətir nömrələri ilə
Sübut: işlədilən command və çıxışın əsas sətri
Açıq suallar: qərar tələb edən məqamlar, varsa

Şablonun hər sətri əsas agent-in növbəti qərarı üçündür: nəticə istiqaməti, fayllar hara baxmağı, sübut etibarı, açıq suallar isə insanın nə vaxt lazım olduğunu deyir. "Nə gördüm" sadalaması, yəni oxunan hər faylın təsviri, şablonda yoxdur və olmamalıdır; məhz onu context-dən kənarda saxlamaq üçün subagent işlədilib.

Multi-agent dizayn prinsipləri

Subagent-lərlə sistem qurarkən dörd prinsip işləyir:

1. Tək məsuliyyət. Hər subagent bir iş görür. "Review edən və düzəldən" agent iki agent olmalıdır; əks halda routing qeyri-müəyyən, hesabat qarışıq olur.
2. Minimum tool. İşə lazım olan tool-lar və başqa heç nə. Bu, həm təhlükəsizlik, həm də fokus məsələsidir.
3. Standart çıxış. Hesabatın formatı system prompt-da yazılır; əsas agent onu proqnozlaşdırıla bilən şəkildə emal edir.
4. İşə uyğun model. Ucuz iş ucuz model-ə, mühakimə böyük model-ə.

Bir məhdudiyyəti də bilmək lazımdır: subagent öz subagent-ini işə sala bilmir, ierarxiya iki səviyyəlidir. Daha dərin ierarxiya lazım olanda 6-cı fəsildəki orkestrasiya pattern-ləri və ya 11-ci fəsildəki framework-lər işə düşür.

Subagent-lər paralel

Əsas agent bir-birindən asılı olmayan bir neçə subagent-i eyni anda işə sala bilər: üç modulu üç araşdırma agent-i paralel oxuyur, və ya 2-ci fəsildəki kimi beş variant beş agent-dən eyni vaxtda gəlir. Paralellik vaxt qazandırır, amma nəticələrin hamısı əsas context-ə qayıdır; beş uzun hesabat birdən gələndə context sıçrayışla böyüyür. Qısa, strukturlu hesabat qaydası paralellikdə daha da vacibdir.

Tapşırıqlar

1. Layihəniz üçün code-reviewer subagent-i yaradın: yalnız oxuma tool-ları, sərt hesabat formatı. Onu üç fərqli dəyişiklikdə işlədin və hesabatların formatı sabit qaldımı, yoxlayın. Sabit deyilsə, system prompt-da nə çatışmır?
2. Təsvirləri qəsdən üst-üstə düşən iki subagent yazın, məsələn hər ikisi "kodu yoxlayır" desin. Eyni prompt-u beş dəfə işlədin və əsas agent-in hansını seçdiyini qeyd edin. Sonra təsvirləri "nə vaxt / nə vaxt yox" formatına salıb təkrar edin.
3. Eyni araşdırma tapşırığını bir dəfə subagent-siz, bir dəfə subagent ilə işlədin və hər ikisində /context ilə əsas session-ın doluluğunu ölçün. Fərq nə qədərdir və subagent-in hesabatı nə qədər yer tutdu?