Claude Code Subagent'ları: Üretimde 18 Tanesini Çalıştırarak Öğrendiklerimiz
Her subagent rehberi aynı code-reviewer oyuncak örneğiyle anlatıyor. Biz üretimde 18 subagent çalıştırıyoruz: gerçek dizin yapısı, 6/11/1 model dağılımı, işin dosyalar üzerinden nasıl devredildiği ve karşılaştığımız arıza türleri.

On this page
Claude Code Subagent'ları: Üretimde 18 Tanesini Çalıştırarak Öğrendiklerimiz
Bu sitedeki her yazıyı, bu yazı dahil, on sekiz Claude Code subagent'ı yayına hazırlıyor. Altısı Opus'ta, on biri Sonnet'te, biri de Haiku'da çalışıyor. researcher subagent'ı tek başına, başladığımızdan beri 74 bellek dosyası biriktirdi. Hiçbiri birbiriyle konuşmuyor. Bizi en çok şaşırtan kısım da buydu: bir subagent sizin konuşmanızı hiç görmez, başka bir subagent'ın konuşmasını da görmez. Yani tüm pipeline, paylaşılan context yerine diskteki dosyalar üzerine kurulu. İşte filo, model dağılımı, bellek kurulumu ve yolda kırılan şeyler.
Kısa özeti:
- Bir subagent, kendi context window'unda kendi sistem promptu, araçları ve izinleriyle çalışır.
- 18 subagent çalıştırıyoruz: 6'sı Opus'ta, 11'i Sonnet'te, 1'i Haiku'da.
- Subagent'lar, paylaşılan bir context üzerinden değil, diskteki dosyalar aracılığıyla işi birbirine devrediyor.
- v2.1.198 itibarıyla
/agentsoluşturma sihirbazı kalktı. Dosyayı kendiniz yazın.
Claude Code Subagent Nedir?
Bir Claude Code subagent'ı, özel bir sistem promptu, belirli araç erişimi ve bağımsız izinlerle kendi context window'unda çalışan uzmanlaşmış bir yardımcıdır. Ana konuşmanızı boğmadan yan bir görevi yapar ve size yalnızca özetini döndürür. Tanımlar, .claude/agents/ altında YAML frontmatter'lı Markdown dosyaları olarak yaşar; bu da Anthropic'in subagent referansında belgelenmiştir.
Claude, bu devri otomatik olarak yapar. Görebildiği her subagent'ın description alanını okur ve bir görev eşleştiğinde işi size hiç sormadan devreder. v2.1.198 itibarıyla bu subagent'lar varsayılan olarak arka planda çalışıyor, yani devir çoğu zaman siz yazmaya devam ederken gerçekleşiyor. Belirli bir işte belirli bir çalışanı istediğinizde onu isimle de çağırabilirsiniz.
Claude Code üç yerleşik subagent'la birlikte gelir: salt okunur kod tabanı araması için Explore, planlama işleri için Plan ve geri kalan her şey için general-purpose.
Eski rehberleri ve eski config dosyalarını yanıltan bir isimlendirme detayı var: bir subagent oluşturan araç Task değil, Agent olarak adlandırılır. v2.1.63'te yeniden adlandırıldı ve dokümanlar mevcut Task(...) referanslarının hâlâ birer alias olarak çalıştığını doğruluyor. Bu yazı boyunca Agent'ı kullanıyoruz.
Bundan sonrası bir referans dokümanı değil. Anthropic'in dokümanları bunu zaten bizden daha iyi yapıyor, v2.1.212'ye kadar inen versiyon notlarıyla birlikte kabaca 8.000 kelime. Devamında, on sekiz tanesinin her gün çalışırken neye benzediği var.
18 Subagent'lık Filomuz: Diskte Gerçek Bir Kurulum Nasıl Görünür
.claude/agents/ dizinimiz 18 subagent tanım dosyası barındırıyor, her biri YAML frontmatter'lı bir Markdown dosyası. Hep birlikte bu sitenin tüm içerik pipeline'ını yürütüyorlar: araştırma, brief hazırlama, yazma, doğrulama, dokuz dile çeviri, görsel üretimi ve yayınlama. Altısı Opus'ta, on biri Sonnet'te, biri Haiku'da çalışıyor.
Google'ın ilk sayfasındaki her subagent rehberi, dokümanlardan kopyalanan aynı code-reviewer örneğiyle anlatıyor. İşte on sekiz tanesi gerçekten iş çıkarırken neye benziyor.
.claude/agents/ ├── abc-link-checker.md ├── brief-creator.md ├── content-gap-finder.md ├── content-refresher.md ├── content-writer.md ├── image-handler.md ├── language-translator.md ├── payload-publisher.md ├── pipeline-manager.md ├── rank-checker.md ├── rescue-diagnoser.md ├── rescue-prioritizer.md ├── researcher.md ├── sanity-publisher.md ├── seo-auditor.md ├── sitemap-checker.md ├── translation-coordinator.md └── validator.md
Dört iş grubuna ayrılıyorlar. İçerik üretimi researcher'dan brief-creator'a, oradan content-writer'a, oradan validator'a akıyor. Dağıtım translation-coordinator, language-translator, image-handler, payload-publisher ve sanity-publisher'ı kapsıyor. Bakım tarafı content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker ve abc-link-checker'dan oluşuyor. Koordinasyon ise pipeline-manager ve content-gap-finder.
Diskten harfiyen kopyalanan bu iki dosya, maliyet argümanının tamamını taşıyor:
# .claude/agents/researcher.md name: researcher tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash model: opus memory: project skills: - seo - competitor-analysis
# .claude/agents/sitemap-checker.md name: sitemap-checker tools: Read, Write, Edit, Glob, Grep, WebFetch model: haiku
Aynı mekanizma, token başına kabaca on kat maliyet farkıyla. Biri, bir yazının ne savunacağına karar veren, web erişimi ve kalıcı belleği olan bir Opus subagent'ı. Diğeri, bir sitemap çeken ve bir JSON dosyası yazan bir Haiku subagent'ı. Subagent formatındaki hiçbir şey ikinci iş için Opus fiyatı ödemenizi zorunlu kılmıyor, ama gördüğümüz çoğu filo varsayılan olarak tam da bunu yapıyor.
researcher üzerindeki skills: alanı, oluşturulma anında bu subagent'ın sistem promptuna iki skill tanımını önceden yüklüyor; SEO kurallarımızı her çalıştırmada yeniden anlatılmadan bilmesinin nedeni de bu. Henüz bir skill yazmadıysanız, Claude skill nasıl yazılır konusunu ayrı bir yazıda ele aldık, burada tekrar etmeyeceğiz.
Kopyalayabileceğiniz göz atılabilir bir tanım kataloğu istiyorsanız, topluluğun awesome-claude-code-subagents koleksiyonu insanların gerçekten aradığı yer. Onu güncellik için değil, şekil/kalıp fikri için okuyun: bazı girdiler Agent yeniden adlandırmasından önceye ait.
Bir Subagent Nasıl Oluşturulur? (/agents Sihirbazı Kalktı)
Bir Claude Code subagent'ı, .claude/agents/ içine kendiniz bir Markdown dosyası yazarak ya da Claude'dan sizin için yazmasını isteyerek oluşturursunuz. v2.1.198 itibarıyla /agents komutu artık etkileşimli oluşturma sihirbazını açmıyor. Çalıştırdığınızda artık yalnızca sizi dizine yönlendiren bir hatırlatma yazdırıyor.
- Dosyayı oluşturun. Versiyon kontrolüyle giden bir proje subagent'ı için
.claude/agents/{name}.md, sizi projeler arasında takip eden biri için~/.claude/agents/{name}.md. namevedescription'ı yazın. Dosyadaki her şeyden daha fazlasınadescriptionkarar verir, çünkü Claude devir kararı verirken eşleştirdiği alan budur. Onu bir iş unvanı gibi değil, bir yönlendirme kuralı gibi yazın.toolsvemodel'i ayarlayın.toolsbir izin listesidir; boş bırakırsanız subagent ana konuşmanın araçlarını devralır.modelise oturum modelinizi geçersiz kılar.- Sistem promptunu yazın, frontmatter'ın altındaki Markdown gövdesi olarak. Subagent'lar yalnızca bu promptu ve temel ortam bilgilerini alır, Claude Code'un tam sistem promptunu almaz.
- Çağırın.
descriptioneşleşsin diye kendiliğinden, ya da ismiyle isteyerek doğrudan.
--- name: changelog-writer description: Writes release notes from merged pull requests. Use when the user asks for a changelog, release notes, or a summary of what shipped. tools: Read, Grep, Glob, Bash model: sonnet --- You write release notes. Read the merged PRs since the last tag with `git log`, group them into Added / Changed / Fixed, and write one line per change in past tense. Never invent a change that is not in the log. Return only the markdown.
Şu anda sıralamada olan birçok rehber, okuyuculara hâlâ yönetim arayüzünü açmak için /agents komutunu çalıştırmalarını söylüyor. Bu talimat artık geçersiz. Dokümanların açıkça belirttiği bir püf noktası daha var: dosya izleyici yalnızca oturum başladığında zaten var olan dizinleri kapsıyor, bu yüzden yepyeni bir agents/ dizinindeki ilk subagent dosyası yüklenmeden önce bir Claude Code yeniden başlatması gerekiyor.
| Versiyon | Ne değişti | Sizin için anlamı |
|---|---|---|
| v2.1.63 | Task aracı Agent olarak yeniden adlandırıldı | Task(...) hâlâ bir alias olarak çalışıyor, yani eski agent dosyaları çalışmaya devam ediyor |
| v2.1.172 | Bir subagent kendi subagent'larını oluşturabiliyor | İç içe geçme çalışıyor, ama yapılandıramayacağınız sabit bir beş derinliğinde |
| v2.1.198 | /agents artık oluşturma sihirbazını açmıyor | Claude'dan dosyayı yazmasını isteyin ya da .claude/agents/'ı kendiniz düzenleyin |
| v2.1.198 | Subagent'lar varsayılan olarak arka planda çalışıyor | Claude, ön planı yalnızca sonuca devam etmek için ihtiyaç duyduğunda kullanıyor |
| v2.1.208 | Çözülemeyen bir tools listesi başlatmayı reddediyor | Sessiz bir boş sonuç yerine hatalı girdileri adlandıran bir hata alıyorsunuz |
| v2.1.212 | Oturum başına 200 subagent sınırı | CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION ile yükseltin; devre dışı bırakılamaz |
Subagent mi, Skill mi, Agent Team mi, Fork mu: Gerçekte Hangisine İhtiyacınız Var?
Yan bir görev ana konuşmanızı boğacaksa ve yalnızca özetine ihtiyacınız varsa subagent seçin. Claude'a mevcut context'iniz içinde çalıştıracağı bir prosedür öğretmek istediğinizde skill seçin. Çalışanların birbiriyle koordine olması gerektiğinde agent team seçin. Yan görev konuşma geçmişinize ihtiyaç duyduğunda fork seçin.
| Subagent | Skill | Agent Team | Fork | |
|---|---|---|---|---|
| Context | Kendi window'u | Ana konuşmanın context'i | Kendi window'u artı paylaşılan bir görev listesi | Konuşmanın tamamını devralır |
| İletişim | Yalnızca ana agent'a rapor verir, başka bir subagent'a asla | Uygulanamaz, sizin oturumunuza yüklenir | Üyeler doğrudan birbirine mesaj atar | Uygulanamaz, oturumunuzu dallandırır |
| Maliyet profili | Her oluşturmada taze context | En ucuzu, yeni context oluşturulmaz | Belirgin şekilde daha fazla token | Üst öğenin prompt cache'ini yeniden kullanır |
| Durum | Kararlı | Kararlı | Deneysel, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 arkasında varsayılan olarak kapalı | Kararlı |
| Ne zaman seçilir | Yan bir görev ana konuşmanızı boğacaksa | Mevcut context içinde tekrarlanabilir bir prosedür istiyorsanız | Birden çok çalışanın yalnızca rapor vermek değil, koordine olması gerekiyorsa | Konuşmayı zaten bilen bir yan göreve ihtiyacınız varsa |
Subagent'lar size rapor verir, birbirlerine asla. Agent Team'ler ise doğrudan birbirine mesaj atar. Hangi primitife ihtiyacınız olduğuna karar veren tek fark bu.
Bizim varsayılanımız subagent ve şimdiye kadar hiç team'e ihtiyacımız olmadı. Pipeline'ımızdaki koordinasyon konuşmalı değil sıralı, bu yüzden paylaşılan bir görev listesi hiçbir şey kazandırmaz, yalnızca token'a mal olur. Team'ler ayrıca hâlâ deneysel ve varsayılan olarak kapalı, bu da gözetimsiz çalıştırdığımız her şey için kesin bir dur işareti. Skill'ler tamamen farklı bir katmanda oturur: zaten çalışmakta olan hangi context'e yüklenirlerse (bir subagent'ınki dahil) o context'in talimatlarıdır; researcher'ın onlara devretmek yerine ikisini deklare etmesinin nedeni de bu.
Model Seçimi: Hangi Subagent Hangi Modelde Çalışmalı
Bir subagent'ın frontmatter'ındaki model'i haiku, sonnet, opus ya da belirli bir model ID'sine ayarlayın, o subagent oturum modelinizi geçersiz kılsın. 18 subagent'a yayılan gerçek dağılımımız, çıktısının ne kadar muhakeme gerektirdiğine göre atanmış altısı Opus'ta, on biri Sonnet'te, biri Haiku'da.
| Katman | Model (sayı) | Subagent'lar | Onları oraya koyan kural |
|---|---|---|---|
| Karar | opus (6) | researcher, brief-creator, content-writer, validator, rescue-diagnoser, abc-link-checker | Çıktı bir karar meselesi ve kötü bir karar tam bir yeniden yazmaya mal oluyor |
| Uygulama | sonnet (11) | content-refresher, content-gap-finder, payload-publisher, image-handler, language-translator, rescue-prioritizer, rank-checker, pipeline-manager, seo-auditor, sanity-publisher, translation-coordinator | Görev iyi tanımlanmış ve doğru cevabın şekli zaten biliniyor |
| Mekanik | haiku (1) | sitemap-checker | Çıktı deterministik ve girdi küçük |
Bir filoyu katmanlandıracak herkese vereceğimiz üç kural var. Çıktısı deterministik ve girdisi küçükse (çekme, ayrıştırma, sayma, yeniden biçimlendirme) bir subagent'ı Haiku'ya koyun. Görev uzun ve iyi tanımlanmışsa ama "doğru"nun neye benzediğine zaten birileri karar vermişse, ki bu dokuz çeviri çalışanı dahil çoğu uygulama işini kapsar, subagent'ı Sonnet'e koyun. Çıktısını hiçbir alt adımın sorgulamayacağı subagent'lar için Opus'u saklı tutun.
Son kural, validator'ın kısa bir rapor üretmesine rağmen neden Opus'ta olduğunu açıklıyor. Denetleyiciyi kimse denetlemiyor.
Hesabı değiştiren bir versiyon notu: v2.1.198'den beri yerleşik Explore subagent'ı artık her zaman Haiku'da çalışmıyor, oturum modelini devralıyor. Explore adında bir kullanıcı ya da proje düzeyi subagent'ı yerleşik olanı geçersiz kılar ve kendi model alanını korur; bu yüzden keşfi ucuz bir modelde tutmak istiyorsanız model: haiku ile bir tane tanımlayın.
Dosya Sözleşmeleri: Subagent'larımız Context Paylaşmadan İşi Nasıl Devreder
Bir subagent ne sizin konuşma geçmişinizi görür, ne de başka bir subagent'ınkini. Bu yüzden subagent'lar arasında bellek içi bir devir yapısal olarak imkânsız. Çözüm, her devri diskte bir çıktıya dönüştürmek; böylece bir sonraki subagent asla sahip olamayacağı bir context'i devralmak yerine bir dosya okur.
techsy.community/posts/claude-code-subagents/ ├── research.md # researcher → SERP analysis, keyword data, gaps ├── brief.md # brief-creator → section-by-section spec ├── en.md # content-writer → the post you are reading ├── de.md # language-translator (one subagent per language) ├── hero.webp # image-handler ├── validation.md # validator └── meta.json # pipeline stage, updated by a PostToolUse hook
Her biri farklı bir subagent tarafından yazılan, bir sonraki tarafından okunan, hepsi bir insan tarafından okunabilir ve git'te takip edilen beş çıktı. Pipeline context sınırlarını aşıyor çünkü hiçbir subagent bir başkasının context'ine hiç ihtiyaç duymuyor. Yalnızca bir önceki subagent'ın dosyasına ihtiyacı var.
En net kazanç çeviride görülüyor. translation-coordinator, en.md'yi okuyup dile başına bir language-translator subagent'ı oluşturuyor, aynı anda dokuz ya da on tanesini birden. Bizim repomuzda eşzamanlılık, tüm oluşturma çağrılarının tek bir mesajda verilmesine bağlı: bu, dokümanların belirttiği bir şey değil, kendi kurulumumuzda gözlemlediğimiz bir davranış, ama bunu kasıtlı olarak yapacak kadar tutarlı çıktı, o yüzden koordinatör bunu bilerek yapacak şekilde yazıldı. Her çevirmen kendi {lang}.md'sini yazıyor ve hiçbiri diğerinin işini göremiyor; bu sorun değil, çünkü sözleşme dosya ve dosya zaten eksiksiz.
Subagent'ların bittiği ve başka bir şeyin başladığı yer de burası. Subagent'lar tek bir oturum içinde çalışır. Kendi geçmişleriyle gerçekten bağımsız çalışma alanları istiyorsanız, bunun yerine birden fazla Claude Code oturumu çalıştırıyorsunuz demektir; ya da bir subagent'a reponun kendi kopyasını vermek için isolation: worktree'ye başvuruyorsunuzdur.
Subagent'lar Oturumlar Arasında Bir Şeyleri Nasıl Hatırlar?
Yalnızca memory alanını ayarlarsanız; üç kapsamı var: user, ~/.claude/agent-memory/<name>/ içine yazar, project, .claude/agent-memory/<name>/ içine yazar, local ise .claude/agent-memory-local/<name>/ içine yazar. Ayarlamazsanız her çağrı boş başlar. On sekiz subagent'ımızdan on ikisi memory: project bildiriyor.
Kabaca kırk yazının ardından bu dizinler oldukça kabarık. researcher 74 bellek dosyası, validator 66, brief-creator ise 65 tutuyor. Bunlar log değil. Birikmiş kararlar: hangi H1 kalıpları düşük performans gösterdi, hangi müşteri iddialarını yapamayız, hangi SERP şekilleri düz metin yerine bir tabloyu ödüllendiriyor.
Hepsini şekillendiren kısıt da bu. Bellek özelliği açık bir subagent'ın sistem promptuna, hangisi önce gelirse MEMORY.md'nin yalnızca ilk 200 satırı ya da 25KB'ı enjekte edilir. Subagent'larımızın her birinin bir günlük yerine bir indeks tutmasının nedeni bu tek sınır.
# Researcher Memory ## Reusable post patterns - [Challenger H1 pattern](feedback_challenger_h1_pattern.md): when a question-shaped H1 earns the click - [Sponsored post research](feedback_sponsored_post_research.md): H1 must be category-shaped, never a review - [Claude Skills tutorial](project_claude_skills_tutorial.md): docs own the top two slots, target the long tail
Her girdi için tek satır, detay ise subagent'ın kendi Read aracıyla talep üzerine okuduğu bağlantılı konu dosyasına itiliyor. MEMORY.md, arkasındaki külliyat sınırsızca büyürken enjeksiyon bütçesine sığan bir indeks olarak kalıyor.
Neredeyse her şey için user yerine project'i kullanıyoruz, çünkü project bellek repoda yaşar ve versiyon kontrolüyle birlikte gider. Bir ekip arkadaşı pull yaptığında, kodla birlikte subagent'ın biriktirdiği kararı da çeker. local ise notları istediğiniz ama commit'i istemediğiniz durumlar için var.
Ne Bozuldu: Arıza Türleri, Yinelenen İsimler ve Kendi Repomuzdaki Eski Bir Alias
Karşılaştığımız hemen hemen her şey dört arıza türüne dayanıyor. Başlamayı reddeden bir subagent, sessizce düzenlediğiniz subagent olmayan bir subagent, Claude'un hiç bulamadığı bir subagent ve kaç tane oluşturabileceğinize dair kesin bir oturum tavanı. Dördünün de kısa ve net çözümleri var.
| Belirti | Neden | Çözüm |
|---|---|---|
| Başlamayı reddediyor, hata araç girdilerinizi adlandırıyor | tools içindeki hiçbir şey çözülmüyor. v2.1.208'den önce araçsız başlıyor ve kafa karıştırıcı boş bir sonuç döndürüyordu | Girdileri düzeltin; hata bunları sizin için adlandırıyor |
| Aynı isimli iki subagent'tan yalnızca biri hiç yükleniyor | Aynı ağaçta yinelenen name, belgelenmiş bir önceliğe göre değil dosya sistemi okuma sırasına göre çözülüyor | name'i ağaç genelinde benzersiz tutun; /doctor v2.1.205'ten beri yinelenenleri raporluyor |
| Yeni subagent hiç bulunamıyor | İzleyici yalnızca oturum başlangıcında var olan dizinleri kapsıyor | Claude Code'u yeniden başlatın |
Agent aracı Subagent spawn limit reached hatasıyla başarısız oluyor | v2.1.212'de eklenen 200 subagent oturum sınırı | CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION'ı yükseltin |
Yinelenen isim sorunu, okunduğundan daha can sıkıcı. Bir dosyayı düzenlersiniz, davranış değişmez, hiçbir yerde hata yoktur; çünkü aynı name'e sahip başka bir dosya okuma sırasını kazanmıştır.
Hook'lar, aslında hiç hata olmayan, yalnızca bir insanın unuttuğu adımlar için beklediğimizden daha çok işe yaradı. Bizimki bilerek basit tutuldu:
"SubagentStop": [
{
"matcher": "content-writer",
"hooks": [
{
"type": "command",
"command": "echo 'Content writer finished. Run /validate to check quality and SEO compliance.'"
}
]
}
]Şimdi de dürüst olanı. Bu yazıyı yazarken kendi filomuzu grep'ledik ve şunun hâlâ translation-coordinator.md'de durduğunu bulduk:
# .claude/agents/translation-coordinator.md name: translation-coordinator tools: Read, Write, Glob, Grep, Task model: sonnet
Agent değil, Task. Bu alan v2.1.63'ten beri güncel değil ve bir kez bile başarısız olmadı, çünkü Anthropic alias'ı korudu. Henüz temizlemedik. Kendi subagent dosyalarınız hâlâ Task diyorsa, bozuk değiller, sadece eskiler; ve şu anda bu alias birçok repo için sessizce işini yapıyor.
Diğer yönde bir düzeltme daha: v2.1.172'den önce yazılan rehberler okuyuculara bir subagent'ın subagent oluşturamayacağını söylüyor. Oluşturabiliyor, o sürümden beri de öyle. Derinlik, ana konuşmanın beş seviye altında sabit ve yapılandırılamıyor; bu yüzden beşinci derinlikteki bir subagent Agent aracını hiç almıyor.
Subagent'ların Maliyeti ve Ne Zaman Kullanılmamalı
Her subagent oluşturma taze bir context window yaratır, yani devir asla bedava değildir. Anthropic'in mühendislik ekibi, subagent'ların sohbet etkileşimlerine göre kabaca 4 kat daha fazla token kullandığını, çoklu-agent sistemlerinin ise kabaca 15 kat daha fazla kullandığını ve tek başına token kullanımının ölçtükleri performans varyansının %80'ini açıkladığını bildiriyor.
Eklemek için kendi token ölçümümüz yok, bu yüzden bu konuda okuduğunuz herhangi bir spesifik çarpanı, diğer blog yazılarında dolaşan 4-7 kat rakamları dahil, bir benchmark değil o yazarın kendi rakamı olarak değerlendirin. Anthropic'in çoklu-agent araştırma sistemi yazısı, arkasında gerçek veri olan tek kaynak; aynı çalışma, Sonnet subagent'larına sahip bir Opus lider agent'ının kendi iç değerlendirmelerinde tek başına bir Opus agent'ını %90,2 farkla geçtiğini bulmuş. Katmanlandırmanın gerekçesi token sayısı değil, bu sonuç.
Çıktı zaten ana konuşmanıza aitse subagent'ı atlayın, çünkü onu geri yapıştırıp iki kez ödemiş olursunuz. Devir gidiş-dönüşünün işi yapmaktan daha pahalıya geldiği küçük düzenlemeler için de atlayın. Ve görev gerçekten konuşma geçmişinize ihtiyaç duyuyorsa atlayın: bunun yerine, konuşmanın tamamını devralan ve üst öğenin prompt cache'ini yeniden kullanan bir fork kullanın; bu da context ağırlıklı yan işler için taze bir subagent'tan daha ucuzdur. Anthropic'in kendi maliyet rehberi ve ne zaman kullanılır çerçevesi de aynı noktaya varıyor.
Oturum başına 200 sınırı, bir fan-out tasarlamadan önce bilinmeye değer. Kontrolden çıkan bir devrin gerçek bir tavanı bu, ve onu yükseltmek varsayılan değil, bilinçli bir eylem.
Yazar hakkında
Mert Batur, Techsy'de çalışıyor; ekip burada B2B müşteriler için AI ajanları, otomasyon sistemleri ve voice/SDR pipeline'ları geliştiriyor. LLM tooling yığını ve Techsy ekibinin üretimde fiilen kullandığı Claude Skills hakkında yazıyor.
Techsy — University of Birmingham · LinkedIn
Sıkça Sorulan Sorular
Claude Code subagent'ları nedir?
Claude Code subagent'ları, her biri kendi context window'unda özel bir sistem promptu, kısıtlı araç erişimi ve bağımsız izinlerle çalışan uzmanlaşmış yardımcılardır. Bir tanesini .claude/agents/ içinde YAML frontmatter'lı bir Markdown dosyası olarak tanımlarsınız. Subagent yan bir görevi yapar ve ana konuşmanıza yalnızca özetini döndürür.
Claude Code subagent'ları otomatik olarak kullanır mı?
Evet. Claude, erişebildiği her subagent'ın description alanını okur ve bir görev eşleştiğinde size sormadan devreder. v2.1.198 itibarıyla subagent'lar varsayılan olarak arka planda çalışır, bu yüzden devredilen iş çoğu zaman siz ana konuşmada yazmaya devam ederken gerçekleşir.
Subagent dosyaları nerede yaşar?
Proje subagent'ları .claude/agents/ içinde, kullanıcı subagent'ları ise ~/.claude/agents/ içinde yaşar. Her iki konum da özyinelemeli olarak taranır, yani alt klasörler sorun değildir. Kimlik yalnızca name frontmatter alanından gelir, asla yoldan değil. Bir yönetici tarafından dağıtılan yönetilen subagent'lar, aynı ismi paylaşan proje ve kullanıcı tanımlarına göre önceliklidir.
Bir subagent'ı açıkça nasıl çağırırım?
Promptunuzda ismiyle isteyin, örneğin "validator subagent'ını bu taslakta kullan". Açık çağırma, otomatik devri yönlendiren description eşleştirmesini atlar; bu da iki subagent'ınızın örtüşen description'ları olduğunda ve Claude sürekli yanlış olana uzandığında işe yarar.
Bir subagent kendi subagent'larını oluşturabilir mi?
Evet, Claude Code v2.1.172'den beri. Bu sürümden önce yazılan rehberler iç içe geçmenin imkânsız olduğunu söyler ve güncelliğini yitirmiştir. Derinlik, ana konuşmanın altındaki seviyeleri sayar ve beşte sabittir: beşinci derinlikteki bir subagent Agent aracını almaz. Sınır yapılandırılamaz.
Subagent'lar oturumlar arasında bir şey hatırlar mı?
Yalnızca memory alanını ayarlarsanız. ~/.claude/agent-memory/<name>/ için user, .claude/agent-memory/<name>/ için project ya da .claude/agent-memory-local/<name>/ için local kabul eder. Ayarlamazsanız her çağrı boş başlar. On sekiz subagent'ımızdan on ikisi, notları versiyon kontrolüyle gitsin diye memory: project kullanıyor.
Bir subagent, benim oturumumdan farklı bir model kullanabilir mi?
Evet. Frontmatter'da model'i haiku, sonnet, opus ya da belirli bir model ID'sine ayarlayın, o subagent için oturum modelinizi geçersiz kılar. Filomuz, her subagent'ın çıktısının gerektirdiği muhakemeye göre atanmış altı Opus, on bir Sonnet ve bir Haiku'ya bölünüyor.
Yeni subagent'ım neden görünmüyor?
Üç olağan neden var. agents dizini oturum başladığında yoktu, bu yüzden izleyici onu hiç fark etmedi: Claude Code'u yeniden başlatın. Ya da iki dosya aynı name'i paylaşıyor ve yalnızca biri yükleniyor. Ya da tools listenizde hiçbir şey çözülmüyor, ki bu v2.1.208'den beri bir adlandırma hatasıyla başlatmayı reddediyor.
Task hâlâ geçerli bir araç adı mı?
Evet, bir alias olarak. Task aracı v2.1.63'te Agent olarak yeniden adlandırıldı ve mevcut Task(...) referansları ayarlarda ve subagent tanımlarında hâlâ çalışıyor. Yeni dosyalarda Agent yazın. Kendi translation-coordinator.md'miz hâlâ Task bildiriyor; bunu bu yazıyı yazarken bulduk ve henüz temizlemedik.
Aklınızda Kalması Gereken Üç Şey
İlk filonuzu kuruyorsanız buradan başlayın. description alanı her şeye karar verir, çünkü Claude bir çalışan seçerken okuduğu şey budur; bu yüzden onu bir iş unvanı gibi değil, bir yönlendirme kuralı gibi yazın. Subagent'ı tasarlamadan önce devri bir dosya olarak tasarlayın, çünkü hiçbir subagent bir başkasının context'ini asla görmeyecek. Ve her subagent'ı, doğru cevabı üretebilecek en ucuz modele koyun, yalnızca yanlış yaptığını yakaladığınızda bir üst modele taşıyın.
Bu pipeline'ın arkasındaki tüm spesifikasyonlar için kütüphanenin tamamını keşfedin.
