Claude Code'da Subagent'lar: Context'i Bölmek, Uzmanlaştırmak ve Paralel Çalıştırmak

Sürüm notu: Bu yazı Claude Code 2.1.325'i (13 Kasım 2026) anlatır; subagent dosya formatı, konumlar, frontmatter alanları ve paralel çalışma seçenekleri 15 Kasım 2026'da code.claude.com/docs'taki Create custom subagents, Run agents in parallel, Orchestrate teams of Claude Code sessions, Orchestrate subagents at scale with dynamic workflows ve Manage costs effectively sayfalarından kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. Örnek subagent dosyalarının frontmatter'ı yerelde ayrıştırılıp doğrulanmıştır.

Önce Tahmin Et

Ayşe, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) sipariş listesi endpoint'ini hızlandırırken Claude Code'a önce EF (Entity Framework; .NET'in veritabanı erişim library'si) Core sorgularını incelettirdi, sonra dotnet test'i çalıştırttı. Kırk dakika sonra session yavaşlamıştı: context'in büyük kısmını otuz dosyanın içeriği ve iki tam test log'u kaplıyordu. Ayşe ertesi gün aynı işi üç subagent'la yaptı ve ana konuşmaya yalnız birkaç satırlık raporlar döndü.

Tahminin ne? Subagent, ana konuşmada daha önce okunan dosyaları ve CLAUDE.md'yi görür mü? Ve yalnız okuma tool'larıyla tanımlanmış bir reviewer'a "öğrendiklerini hatırla" diye memory alanı eklersen hâlâ salt okunur mu kalır? Birinci cevap ilk bölümde, ikincisi memory bölümünde.

Subagent Nedir, Ana Konuşmadan Farkı Ne?

Subagent, ana session'ın bir yan işi devrettiği ayrı bir Claude örneği. Kendi context window'unda, kendi system prompt'uyla ve kendi tool kısıtlarıyla çalışıyor; işini bitirince ana konuşmaya yalnız bir özet dönüyor. Belgelerin önerdiği kullanım net: tekrar bakmayacağın arama sonuçları, log'lar ya da dosya içerikleri ana konuşmayı dolduracaksa o işi subagent'a ver.

Tahmindeki ilk sorunun cevabı başlangıç context'inde. Subagent konuşma geçmişini, daha önce yüklenen skill'leri ve ana session'ın okuduğu dosyaları görmüyor; Claude ona işi anlatan bir görev mesajı yazıyor. Buna karşılık CLAUDE.md hiyerarşisinin tamamı, path-scoped kurallar ve başlarken alınan bir git status görüntüsü subagent'a da yükleniyor. Ana session'ın auto memory'si ve output style'ı ise yüklenmiyor. Built-in Explore ve Plan subagent'ları daha hızlı başlamak için CLAUDE.md ve git status'u da atlıyor.

Claude Code'da hazır gelen subagent'lar var: codebase'de salt okunur arama yapan Explore, plan mode'da araştırma yapan Plan, hem okuyup hem değiştirebilen general-purpose. Kendi subagent'ını, aynı türden bir işçiyi aynı talimatlarla tekrar tekrar başlattığını fark ettiğinde yazmalısın.

Dosya Formatı ve Konumlar

Subagent, YAML (girintiyle yazılan bir configuration formatı) frontmatter'lı bir Markdown dosyası. Yalnız name ve description zorunlu; dosyanın gövdesi subagent'ın system prompt'u oluyor ve Claude Code'un kendi system prompt'unun yerine geçiyor. Konumlar öncelik sırasıyla: managed settings, açılışta verilen --agents JSON'u, projedeki .claude/agents/, kişisel ~/.claude/agents/ ve en sonda plugin'ler. Aynı ad iki yerde varsa öncelikli olan kazanıyor.

Eski sürümlerde /agents komutu bir sihirbaz açıyordu. Belgelere göre v2.1.198'den beri yalnız dosyaların yerini hatırlatan bir not yazıyor; subagent'ı Claude'a yazdırıyorsun ya da dosyayı kendin düzenliyorsun. Claude Code iki klasörü izliyor ve değişiklikler birkaç saniye içinde bir sonraki görevlendirmede geçerli oluyor. Tek istisna, session başladığında henüz var olmayan bir agents klasörü; onu ilk kez oluşturduysan session'ı yeniden başlat.

Frontmatter alan adları camelCase ve tablodakiyle birebir aynı olmalı: Claude Code tanımadığı alanı hata vermeden yok sayıyor. maxturns yazdıysan sınır hiç uygulanmıyor. name eksikse ya da YAML ayrıştırılamıyorsa dosya sessizce atlanıyor; sebebi claude --debug log'unda.

Bookstore: ef-query-reviewer

İlk subagent, Ayşe'nin sorgu incelemesini ana konuşmanın dışına taşıyor. .claude/agents/ef-query-reviewer.md:

---
name: ef-query-reviewer
description: Reviews EF Core queries in src/Bookstore.Api for N+1 loads, unneeded tracking, missing indexes and unbounded reads. Use after changing queries, endpoints or BookstoreContext. Read-only.
tools: Read, Grep, Glob
model: sonnet
effort: high
---

You review EF Core data access in Bookstore.Api. You never edit files.

Scope: the files named in the task. If the task names none, use the changed
files under src/Bookstore.Api from the git status snapshot in your context.

Check every query in scope for:
1. N+1: a query inside a loop, or navigation properties read after the query
   without `Include` or a `Select` projection.
2. Tracking: read-only queries without `AsNoTracking()` or a projection.
3. Indexes: `Where`, `OrderBy` and join columns with no index in
   `BookstoreContext.OnModelCreating` or in src/Bookstore.Api/Data/Migrations.
4. Unbounded reads: list endpoints without paging or a maximum page size.
5. Cancellation: async EF Core calls without the request's `CancellationToken`.

Report, at most 30 lines:
- One line per finding: `file:line | rule | what to change`
- Then "Index candidates:" with table and column names
- "No findings" when there are none. Never paste whole files.

tools bir allowlist: listede olmayan her tool, MCP (Model Context Protocol; dış araç ve veri kaynaklarına bağlanma protokolü) tool'ları dahil, bu subagent'a kapalı. Alan hiç yazılmasaydı subagent ana konuşmadaki tool'ları devralacaktı. Tersini istediğinde, yani "her şey ama yazma yok" dediğinde disallowedTools: Write, Edit kullanılıyor. Bir incelik var: disallowedTools'a Bash(git push *) gibi kapsamlı bir kural yazarsan bütün Bash tool'u gidiyor; tek bir komutu engellemek için üçüncü yazıdaki deny kurallarını kullan, onlar subagent'lara da uygulanıyor.

Prompt'taki "git status snapshot" cümlesi bilinçli: görev mesajı dosya adı içermiyorsa subagent'ın değişen dosyaları bulabileceği tek kaynak, başlarken aldığı git status görüntüsü. Rapor formatını satır sınırıyla yazmak da subagent'ın asıl faydasını koruyor; ana konuşmaya dönen metin ne kadar kısaysa o kadar az context harcanıyor.

Bookstore: angular-a11y-checker ve test-runner

İkinci subagent Angular template'lerini erişilebilirlik açısından tarıyor. Kuralların arka planı Accessibility (a11y) serisinde; burada önemli olan subagent'ın neyi kaynak koddan anlayabileceğini, neyi anlayamayacağını açıkça yazmak:

---
name: angular-a11y-checker
description: Checks Angular templates in web/bookstore-web for accessibility problems such as missing labels and alt text, click handlers without keyboard access and ARIA misuse. Use after creating or changing a component template. Read-only.
tools: Read, Grep, Glob
model: haiku
---

You check accessibility in the Angular client under web/bookstore-web/src/app.
You never edit files.

For each template (`*.html` or an inline `template`) in the task scope, check:
- Images: every `<img>` has `alt`; decorative images use `alt=""`.
- Forms: every input, select and textarea has a `<label for>`, `aria-label`
  or `aria-labelledby`.
- Interaction: `(click)` on a `div` or `span` without a role, `tabindex="0"`
  and a key handler; suggest a `<button>` instead.
- Headings: one `h1` per page component and no skipped levels.
- ARIA: attributes that repeat native semantics or point to missing ids.
- Status messages: cart and checkout messages use `aria-live`.

Color contrast and screen reader output cannot be judged from source code;
list them under "Check in the browser".

Report: one line per finding as `file:line | rule | fix`, at most 25 lines.

Üçüncüsü gürültülü test çıktısını ana konuşmadan uzak tutuyor. Bu, belgelerin en etkili kullanım olarak saydığı durum: yüzlerce satırlık çıktı subagent'ın context'inde kalıyor, ana konuşmaya yalnız toplamlar ve kırmızı testler dönüyor:

---
name: test-runner
description: Runs the Bookstore test suites and returns only the totals and the failing tests with their first error lines. Use proactively when tests need to run and the full output is not needed.
tools: Bash, PowerShell, Read, Grep
model: haiku
maxTurns: 8
---

Run only the test commands the task asks for, from the repository root:
- API: `dotnet test Bookstore.slnx`
- Client: `npm test` in `web/bookstore-web`

Never edit files, never install packages and never run
`dotnet ef database update`.

Report:
1. The command and its exit code.
2. Totals: passed, failed, skipped.
3. For each failing test, at most 5 lines: the test name, the assertion
   message and the first stack frame in Bookstore code.
4. If the build failed, the compiler errors as `file(line): error CODE message`
   instead of test results.
Never paste the full output.

Listede hem Bash hem PowerShell var, çünkü Git for Windows'u olmayan bir makinede Claude Code Bash tool'unu hiç kaydetmiyor ve komutlar PowerShell tool'undan geçiyor. "Never run" satırları bir güvenlik sınırı değil, talimat; asıl sınır üçüncü yazıdaki settings.json: dotnet test allow listesinde, dotnet ef database update ask listesinde. Description'daki "use proactively" ifadesi belgelerin önerdiği kalıp; Claude'un bu subagent'a kendiliğinden iş devretmesini kolaylaştırıyor.

Çağırmak, Arka Plan ve Fork

Claude, isteğine ve subagent'ların description alanlarına bakarak kendisi görev devrediyor. Emin olmak istediğinde üç yol var: subagent'ın adını prompt'ta geçirmek, @ ile seçmek ya da bütün session'ı o subagent olarak başlatmak:

Use the ef-query-reviewer subagent on the order endpoints changed in this branch.
@"test-runner (agent)" run dotnet test and report only the failures
claude --agent ef-query-reviewer

@ ile seçim o subagent'ın çalışmasını garanti ediyor, ama görev mesajını yine Claude yazıyor. --agent ise ana session'ın kendisine subagent'ın tool kısıtlarını, modelini ve system prompt'unu veriyor; ekip için varsayılan yapmak istersen .claude/settings.json'daki agent ayarı var.

Ana konuşmadan başlatılan subagent varsayılan olarak arka planda çalışıyor ve sen yazmaya devam ediyorsun. Arka plandaki subagent onay gerektiren bir tool'a geldiğinde soru senin ana session'ına, subagent'ın adıyla geliyor; "session boyunca izin ver" dersen bu izin ana konuşmayı da kapsıyor. /tasks çalışan ve az önce biten işleri listeliyor ve her subagent'ın hangi modelde koştuğunu gösteriyor. Arka plandaki subagent'ın daha küçük bir built-in tool setiyle çalıştığını da bil: Read, Grep, Glob, Bash, PowerShell, Edit, Write gibi temel tool'lar kalıyor, listende olsa bile diğerleri çıkarılıyor.

Fork, konuşmanın tamamını devralan özel bir subagent. /subtask ile kendin başlatıyorsun ya da fork mode açıkken Claude başlatıyor; fork mode v2.1.302'den beri varsayılan açık. Fork, ana konuşmayla aynı system prompt'u ve tool'ları kullandığı için prompt cache'ini de paylaşıyor ve aynı context'i isteyen işlerde yeni bir subagent'tan ucuza geliyor. Fork mode açıkken terminalde Claude bir subagent'ın bitmesini bekleyemiyor; beklemesini istiyorsan kişisel ayarına CLAUDE_CODE_FORK_SUBAGENT=0 ekle:

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

Model, Memory ve Worktree İzolasyonu

Model seçiminin sırası: Claude'un görevlendirmede verdiği model, subagent dosyasındaki model, CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni ve en sonda ana konuşmanın modeli. test-runner ve angular-a11y-checker'da haiku kullanmamızın sebebi bu işlerin kurala göre tarama ve kısa rapor yazma olması. Subagent'ların istekleri de ana konuşmanla aynı usage limit'lerinden düşüyor; ucuz model burada gerçekten fark yaratıyor.

Tahmindeki ikinci sorunun cevabı memory alanında. memory: project subagent'a .claude/agent-memory/<name>/ altında kalıcı bir klasör veriyor (user ve local kapsamları da var) ve MEMORY.md'nin ilk 200 satırını ya da 25KB'ını system prompt'a ekliyor. Ama belgelere göre memory açıldığında Read, Write ve Edit tool'ları otomatik olarak açılıyor. Belgeler bu yazma yetkisinin memory klasörüyle sınırlı olup olmadığını söylemiyor; bu yüzden ef-query-reviewer'a memory eklemedik. Salt okunur kalması gereken bir subagent'ta bu alanı kullanmak, sözleşmeyi değiştirmek demek.

isolation: worktree ise dosya değiştiren subagent'lar için: subagent'a varsayılan branch'ten açılmış geçici bir git worktree veriyor ve hiçbir değişiklik yapmazsa worktree otomatik siliniyor. Aynı dosyalara paralel dokunan iki subagent'ın birbirinin değişikliğini ezmesini bu önlüyor. Beşinci yazıdaki bundled /batch skill'i de büyük bir değişikliği worktree'lerde çalışan arka plan subagent'larına bölerek aynı mekanizmayı kullanıyor. Worktree'lerin ayrıntısı dokuzuncu yazıda.

Subagent'lar varsayılan olarak kendi subagent'larını da başlatabiliyor: ana konuşmanın altında en fazla üç katman ve aynı anda en fazla 20 çalışan subagent. Bir reviewer'ın başka subagent başlatmasını istemiyorsan Agent'ı tools listesine koyma.

Subagent mı, Skill mi, Agent Team mi, Workflow mu?

Run agents in parallel sayfası seçenekleri "işi kim koordine ediyor" sorusuyla ayırıyor. Kendi özetimiz:

Agent team'ler deneysel ve varsayılan kapalı; CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ile açılıyor. Manage costs effectively sayfasına göre teammate'ler plan mode'da çalıştığında standart bir session'dan yaklaşık 7 kat fazla token harcıyorlar. Dynamic workflow'lar ücretli planlarda var; bir çalıştırma 25'ten fazla agent planladığında ya da öngörülen token toplamı 1,5 milyonu geçtiğinde Claude Code bir uyarı gösteriyor. İkisini de Bookstore'un günlük işinde kullanmıyoruz; sıradan bir endpoint değişikliği için tek session ve birkaç subagent yeterli.

Üretimde Dikkat

Description'ları kısa tut. Kendi subagent'larının açıklamaları toplamda 15.000 token'ı geçerse Claude Code açılışta uyarı veriyor; ayrıntı system prompt'a, yani dosyanın gövdesine gider, o yalnız subagent çalışınca yükleniyor.

Hook'lar subagent'ların içinde de çalışıyor. settings.json'daki bir PreToolUse hook'u subagent'ın her tool çağrısından önce de devreye giriyor; yedinci yazıda yazacağımız migration koruması bu yüzden subagent'ları da kapsayacak. Proje subagent'ının frontmatter'ındaki hook'lar ve inline MCP server'ları ise ancak klasör için workspace trust onayı verildikten sonra çalışıyor; claude -p koşusu bu onay sayılmıyor.

Subagent raporunu veri olarak oku. Claude Code her raporu ana konuşmaya vermeden önce talimat görünümlü kalıplar için tarıyor ve işaretliyor, ama belgeler bunun bir güvenlik sınırı olmadığını açıkça söylüyor. Rapordan doğan her tool çağrısı yine permission kontrolünden geçiyor. Konunun derin anlatımı LLM Uygulama Güvenliği serisinde.

Sık Düşülen Tuzaklar

Her şeyi subagent'a bölmek. Sık soru-cevap gerektiren işlerde ve aynı context'i paylaşan aşamalarda ana konuşma daha iyi; fork olmayan bir subagent sıfırdan başladığı için context toplamak zaman alıyor.

Yazma yetkisi verip sonucu review etmemek. Subagent'ın değiştirdiği dosyalar senin diff'ine giriyor; dördüncü yazıda gördüğümüz gibi subagent edit'leri checkpoint ile de çoğunlukla geri alınamıyor.

Aynı dosyalarda paralel edit. İki subagent aynı checkout'ta aynı dosyaya yazıyorsa isolation: worktree kullan ya da işi dosya bazında böl.

Alan adını yanlış yazmak. disallowed-tools skill'lerde geçerli bir alan, subagent'ta ise doğrusu disallowedTools; yanlış yazılan alan hata vermeden yok sayılıyor.

Küçük Bir Deneme

★☆☆ Kendi projende uzun çıktı üreten bir komut seç ve test-runner benzeri bir subagent yaz. Aynı komutu bir kez ana konuşmada, bir kez subagent'la çalıştırıp /context çıktısındaki farkı karşılaştır.

★★☆ ef-query-reviewer'ın açıklamasını belirsiz bir cümleyle değiştir ("Helps with the database") ve beş farklı istekte Claude'un ona görev devredip devretmediğini not et. Sonra açıklamayı geri al ve aynı denemeyi tekrarla.

★★★ Aynı test görevini önce /subtask ile bir fork'a, sonra test-runner'a ver. /tasks'ta modelleri, /usage çıktısında token farkını karşılaştır ve hangi durumda hangisinin ucuz olduğunu yaz.

Subagent'lara "never edit" ya da "never run" dedik, ama bunlar hâlâ talimat; Claude çoğu zaman uyar, her zaman değil. Bookstore'da "mevcut migration dosyalarına dokunma" kuralını kesin hâle getirmenin yolu, Claude Code'un tool çağrısından önce senin script'ini çalıştırması. Yedinci yazıda PreToolUse, PostToolUse ve Stop hook'larıyla bu kuralı, otomatik formatlamayı ve test kontrolünü kuracağız.