Tek bir yapay zeka kodlama oturumunda bir tavana çarparsınız: bağlam penceresi. Bir sohbeti devasa bir yeniden düzenleme, üç tur test çıktısı ve bir kod incelemesiyle doldurun, ajan konuyu kaybetmeye başlar. Claude Code alt ajanları çözümdür. Her şeyi tek bir bağlamda idare eden tek bir ajan yerine, her biri kendi bağlam penceresine, kendi talimatlarına ve kendi araç izinlerine sahip odaklanmış çalışanlar oluşturursunuz. Tek bir iş yaparlar, bir sonuç döndürürler ve ana iş parçacığını temiz tutarlar. Bu, uygulamalı bir oluşturma kılavuzudur. Özel bir alt ajanı bir yapılandırma dosyası olarak nasıl oluşturacağınız, her bir ön bilgi alanının ne işe yaradığı, Claude'un ona nasıl delege etmeye karar verdiği ve bir ajanın kodu incelerken diğerinin paralel olarak testler yazdığı pratik bir kurulumu nasıl bağlayacağınız anlatılmaktadır. Önce kavramsal genel bakışı istiyorsanız, Claude Code alt ajanlarının ne olduğu ve neden önemli oldukları hakkındaki yazımız temel zemini kapsar. Burada onları inşa etmeye ve bir test alt ajanını güvenebileceğiniz bir doğrulama adımına dönüştüren API test açısına odaklanıyoruz.
ÖZET
Claude Code alt ajanı, `.claude/agents/` içine YAML ön bilgisi içeren bir Markdown dosyası yazarak oluşturulur: bir `name`, Claude'a ne zaman delege edeceğini söyleyen bir `description`, isteğe bağlı bir `tools` izin listesi ve isteğe bağlı bir `model`. Dosyanın gövdesi alt ajanın sistem istemi haline gelir. Her alt ajan, kendi araçlarıyla kendi bağlam penceresinde çalışır, böylece bağlam izolasyonu, paralellik ve uzmanlık elde edersiniz. Claude, açıklamaya göre otomatik olarak delege eder veya bir alt ajanı adıyla çağırırsınız. Resmi referans Claude Code alt ajanları belgeleridir.
60 saniyede Alt Ajanlar
Bir alt ajan, ana Claude Code ajanının bir görevi devrettiği ayrı bir ajan örneğidir. Ana ajan baş mühendistir; alt ajanlar ise içeri çektiği uzmanlardır. Uzman, kendi konuşmasında, kendi bağlam penceresi ve sistem istemiyle çalışır, sonra sadece sonucu döndürür. Üç özelliği onları yapılandırmaya değer kılar:
- Kendi bağlam penceresi. Bir alt ajan, yalnızca kendisine verilen görevle sıfırdan başlar, böylece ana iş parçacığı asla ara çalışmalarıyla dolmaz.
- Özel bir sistem istemi. Nasıl davranacağını şekillendirirsiniz: güvenlik açıklarını avlayan bir denetçi, kurallarınıza uyan bir test yazarı.
- Yapılandırılabilir araçlar. Her alt ajana yalnızca ihtiyaç duyduğu araçları verirsiniz, böylece bir denetçi yazamaz ve bir test çalıştırıcısı sadece yeterli kabuk erişimi alır.
Bu kavramsal zemindir; kavramsal genel bakış nedenine daha derinlemesine iner. Bu kılavuzun geri kalanı, bireysel görevler düzeyinde uygulanan Claude Code ajan donanımı arkasındaki aynı prensip olan onları inşa etmekle ilgilidir.
Neden Alt Ajanlar Kullanılmalı
Üç neden var ve bunlar birleşiyor. Bağlam izolasyonu. Bağlam penceresi dolduğunda uzun bir oturum kalitesini kaybeder. Okunan her dosya, çalıştırılan her test, her sapma bütçeyi tüketir ve odaklanmayı azaltır. Büyük bir görevi bir alt ajana devretmek, tüm bu işi alt ajanın bağlamında tutar, ana bağlamda değil. Ana ajan, 50.000 tokenlik ara gürültü yerine temiz bir özet alır. Bu izolasyon aynı zamanda bir maliyet kaldıraçıdır, çünkü her seferinde şişkin bir bağlamı sürüklemiyorsunuz. Ajan token maliyetlerini düşürme hakkındaki notlarımız ekonomiye girer. Paralellik. Bağımsız görevlerin art arda çalışmasına gerek yoktur. Bir ana ajan aynı anda birkaç alt ajanı gönderebilir: bu modülü incelerken diğerini test et, üçüncüsünü belgele. Toplam yerine en yavaş tek görevin süresi düşer. Claude Code'un dinamik iş akışları bunu sınırına kadar zorlar, tek bir oturumdan yüzlerce paralel alt ajanı yayar. Uzmanlık. Genel bir ajan her şeyde iyidir ama hiçbir şeyde harika değildir. Sıkı bir sistem istemi ve doğru araçlara sahip bir alt ajan tek bir şeyde harikadır. Düşmanca davranması istenen bir denetçi, farka göz atan bir genel uzmandan daha fazla hata bulur. Onay stilinizi bilen bir test yazarı, gerçekten saklayacağınız testler üretir. Aşırı yüklenmiş tek bir genel uzman yerine küçük bir uzman ekibi oluşturursunuz.
Özel bir alt ajan nasıl oluşturulur
Alt ajanlar düz Markdown dosyalarıdır. Proje düzeyindeki dosyaları `.claude/agents/` içine, kişisel olanları ise `~/.claude/agents/` içine koyun. Her dosya YAML ön bilgisine ve alt ajanın sistem istemi haline gelen bir gövdeye sahiptir. İşte bir kod denetçisi: ``` --- name: code-reviewer description: Reviews code changes for bugs, security issues, and convention violations. Use after writing or editing code. tools: Read, Grep, Glob model: sonnet --- You are a senior code reviewer. When given a diff or a set of files: 1. Look for correctness bugs, security holes, and missed edge cases. 2. Check that the code matches the project's existing conventions. 3. Report only high-confidence issues, ranked by severity. Be specific. Cite file and line. Do not rubber-stamp. ``` Ön bilgi alanları:
name— onu çağırmak için kullandığınız tanımlayıcı.description— bu önemli olan. Claude, otomatik olarak ne zaman delege edeceğine karar vermek için bunu okur. Belirsiz bir etiket yerine net bir tetikleyici ("Kod yazdıktan sonra kullanın") olarak yazın.tools— izin listesi. Ana ajanın araçlarını devralmak için boş bırakın veya kısıtlamak için belirli olanları listeleyin. Kod yazamayan bir denetçi, onu yanlışlıkla değiştiremez.model— isteğe bağlı olarak bir model sabitleyin. Mekanik alt ajanlar için daha ucuz, daha hızlı bir model ve zorlu muhakeme için daha güçlü bir model kullanın.
Gövde, sistem istemidir. Uzmanlaşmanın yaşadığı yer burasıdır, bu yüzden yeni bir çalışanı bilgilendirdiğiniz gibi yazın: ne yapmalı, neye öncelik vermeli, neden kaçınmalı. Bunu bir proje design.md veya AGENTS.md ile eşleştirmek, alt ajana her dosyada tekrarlamadan kurallarınızı verir.
Alt ajanlar nasıl çağrılır
Bir alt ajanın iki şekilde çalıştırılması vardır. Otomatik delegasyon. Claude, mevcut her alt ajanın `description` alanını okur ve bir görev eşleştiğinde otomatik olarak delege eder. Bir dosyayı düzenlemeyi bitirdiğinizde ve ana ajan, `code-reviewer`ınıza farkı söylemeden verebilir, çünkü açıklama "kod yazdıktan sonra kullanın" der. İyi açıklamalar, iyi delegasyonu sağlar. Açıkça çağırma. Doğrudan adlandırabilirsiniz: "sipariş modülündeki değişiklikler üzerinde kod denetçisi alt ajanını kullanın." Delegasyonu şansa bırakmak istemediğinizde belirli bir uzmanı bu şekilde zorlarsınız. Her iki durumda da, alt ajan kendi bağlamında çalışır, işi yapar ve ana iş parçacığına bir sonuç döndürür. Devrin gerçekleştiğini görürsünüz ve ne kadar ayrıntının yüzeye çıkacağını yapılandırabilirsiniz. Alt ajanları belirlenimci, tekrarlanabilir dizilere bağlamak için, slash komutları ve SDK, spontane istemlerden daha fazla kontrol sağlar; Claude Code genel bakış yapılandırma yüzeyini kapsar.
Alt ajanlar ve Ajan SDK'sı ve Dinamik İş Akışları Arasındaki Fark
Bunlar örtüşüyor, işte her birinin ne zaman uygun olduğu.
| Araç | Kontrol modeli | En iyisi |
|---|---|---|
| Alt Ajanlar | Model ne zaman delege edeceğine karar verir (veya siz birini adlandırırsınız) | Oturum içi uzmanlaşma ve hafif paralellik |
| Dinamik iş akışları | Model, tek bir oturumda büyük yayılımı düzenler | Yüzlerce paralel görev, geniş taramalar |
| Ajan SDK'sı | Kontrol akışını kodda siz yazarsınız | Belirlenimci döngüler, zamanlanmış veya katılımsız çalıştırmalar |
Alt ajanlar, oturum içi, konuşmaya dayalı seçenektir: Claude Code'da çalışıyorsunuz ve bir veya iki uzman istiyorsunuz. İnsan olmadan zamanlanmış olarak çalışan programatik bir döngüye ihtiyacınız olduğunda, Claude Agent SDK'ya geçersiniz ve orkestrasyonu kendiniz yazarsınız. Kendi çözümünüzü geliştirme ile barındırılan bir seçenek arasında kararsızsanız, yönetilen ajanlar ve Agent SDK karşılaştırmamız takasları açıklar. Üçü birbirinin rakibi olmaktan çok, etkileşimliden tam otomatikye doğru bir merdivenin basamakları gibidir.
Pratik bir örnek: paralel inceleme ve test yazımı
Hadi birleştirelim. Diyelim ki ana ajan yeni bir sipariş uç noktasını uyguladı. Bunun incelenmesini ve test edilmesini istiyorsunuz ve bunların sırayla yapılması için hiçbir neden yok. İki alt ajan tanımlayın. Yukarıdaki `code-reviewer` ve bir test yazarı: ``` --- name: api-test-writer description: Writes API test cases for new or changed endpoints. Use after an endpoint is implemented. tools: Read, Grep, Write, Bash model: sonnet --- You write API tests against the project's OpenAPI spec. 1. Read the spec and the endpoint implementation. 2. Write tests covering success, validation errors, and auth. 3. Assert status codes and validate response bodies against the schema. 4. Run the suite and report pass/fail with reasons. ``` Şimdi ana ajan ikisini birden görevlendirir: denetçi farkı okurken, test yazarı spesifikasyonu okur ve kapsama yazar. İki uzman, iki izole bağlam, paralel olarak çalışıyor. Ana iş parçacığı temiz kalır ve iki özet alır: bir inceleme raporu ve bir test sonucu. Bu test sonucu, bunu güvenilir kılan kısımdır. API süitenizi çalıştıran bir alt ajan, bir doğrulama geçididir; uç noktanın bittiği gibi görünüp görünmediğinden ziyade, gerçekten çalışıp çalışmadığını söyleyen belirleyici bir kontrol. Bu, kodlama ajanı döngülerinin temel fikridir: ajanın kendi güveni sayılmaz, geçidin kararı sayılır. Test alt ajanını gerçek bir API test platformuna bağlayın ve geri bildirim daha keskin hale gelir. Apidog kullanan ekipler, alt ajanı bir Apidog test senaryosuna yönlendirir, böylece her yanıt şema ile doğrulanır ve ajanın canlı uç nokta çağrılarını Apidog AI ajan hata ayıklayıcısı aracılığıyla yönlendirir, böylece insan bir testçinin yapacağı gibi istekleri inceler. Aynı kurulumu alın, bir döngü içine sarın ve sizsiz çalışan otonom Claude iş akışları'nda oluşturduğumuz katılımsız iş akışına sahip olursunuz. Test geçidinin kutudan çıkar çıkmaz şema farkında olmasını istiyorsanız Apidog'u indirin.
En iyi uygulamalar
Birkaç alışkanlık, alt ajanları kaotik yerine kullanışlı tutar.
- Her alt ajan için bir sorumluluk. Bir denetçi inceler. Bir testçi test eder. Her şeyi yapan bir alt ajan oluşturmayın; bu sadece ekstra adımları olan ana ajandır.
- Delege etmek için açıklamalar yazın. `description` alanı, Claude'un alt ajanınızı ne zaman çağıracağına karar verdiği yerdir. Bir başlık değil, net bir tetikleyici yapın. "Hata denetimi için kodu düzenledikten sonra kullanın" cümlesi "Kod denetçisi"nden daha iyidir.
- En az ayrıcalık verin. Her alt ajanın sadece ihtiyaç duyduğu araçları listeleyin. Yazma erişimi olmayan bir denetçi, incelediği şeyi değiştiremez. Bu, çalıştırmalar katılımsız olduğunda daha önemlidir.
- İş başına doğru modeli sabitleyin. Mekanik alt ajanlar daha hızlı, daha ucuz bir modelde çalışabilir. En güçlü modeli, zorlu muhakeme yapan alt ajanlar için saklayın. Bu hem hızı hem de maliyeti kontrol eder.
- Yapılandırılmış sonuçlar döndürün. Alt ajanlardan tutarlı bir biçimde (bir karar, bir sorun listesi, bir geçti/kaldı) rapor vermesini isteyin. Yapılandırılmış çıktı, ana ajanın ve sizin hareket etmesi için daha kolaydır.
- Aşırı iç içe geçmeyin. Alt ajanların alt ajanları çağırması, takip etmesi zorlaşır ve maliyetli olur. Hiyerarşiyi sığ tutun.
Bunlar, ajanik iş akışı araç bağlantı kalıpları'nda ele aldığımız bağlantı kalıplarını yansıtır ve ister iki alt ajanınız olsun ister yirmi, geçerlidirler.
Alt ajanlara ne zaman başvurmalı (ve ne zaman başvurmamalı)
Alt ajanlar bir araçtır, varsayılan değil. Onları ne zaman atlayacağınızı bilmek, kurulumunuzu hızlı ve ucuz tutar. Bir görev sınırlı, bağımsız ve gürültülü olduğunda bir alt ajana başvurun. Bir kod incelemesi sınırlıdır (açık bir sonu vardır), bağımsızdır (ana iş parçacığının çalışma durumuna ihtiyacı yoktur) ve gürültülüdür (ana bağlamı tıkamasını istemediğiniz çok fazla ara okuma üretir). Bir test paketi yazmak, bir hatayı yeniden üretmek veya bir modülü güvenlik sorunları için denetlemek de aynıdır. Bunlar mükemmel delegasyonlardır: işi izole edin, bir karar alın. Görev küçük, sıkıca bağlı veya ana işle ardışık olduğunda alt ajanı atlayın. Bir değişkeni yeniden adlandırmak, tek satırlık bir hatayı düzeltmek veya ana ajanın halihazırda gereken bağlamı görüş alanında olduğu herhangi bir şey, bir devirden fayda sağlamaz. Orada bir alt ajan başlatmak sadece gecikme ve bağlam gidiş-dönüş ekler, hiçbir kazanç sağlamaz. Eğer ana ajanın, alt ajanı bilgilendirmek için konuşmanın yarısını açıklaması gerekseydi, onu ana iş parçacığında tutun. Genel kural: bir paragrafta açıklanabilecek kadar bağımsız ve paralel çalıştırılmaya değer işleri delege edin. İncelenecek ve test edilecek yeni bir uç nokta buna uyar. Bir yazım hatası düzeltmesi uymaz. Birçok eşzamanlı alt ajana ölçeklendiğinizde, dinamik iş akışlarındaki orkestrasyon kalıpları devreye girer, ancak aynı yargı geçerlidir: bağımsız olanı paralelleştirin, bağlı işleri bir arada tutun.
Yaygın hatalar
- Belirsiz açıklamalar. Eğer `description` bir etiketse, otomatik delegasyon beklediğinizde tetiklenmez. Bunu bir kullanım tetikleyicisi olarak yazın.
- Tek şişmiş alt ajan. Her işi tek bir alt ajana tıkmak, uzmanlaşmanın faydasını öldürür. Sorumluluğa göre ayırın.
- Varsayılan olarak tüm araçları devralmak. `tools` ayarlanmadan bırakmak, bir alt ajana ana ajanın sahip olduğu her şeyi verir. Güvenilir işler için iyi, otomatikleştirilmiş her şey için riskli. Bilinçli olarak izin listesi kullanın.
- Doğrulama alt ajanı yok. Test geçidi olmayan bir inceleme ve derleme kurulumu, doğru görünen ve kenarlarda bozulacak kod gönderir. Her zaman testleri gerçekten çalıştıran bir alt ajan dahil edin.
- Alt ajanları SDK gibi ele almak. Alt ajanlar model tarafından gönderilir ve oturum içindedir. Eğer belirleyici, zamanlanmış kontrol akışına ihtiyacınız varsa, bu Agent SDK'nın işidir, bir alt ajan yığınının değil.
Bunları doğru yapın ve iyi kapsamlı birkaç alt ajan, Claude Code'u tek bir meşgul asistandan küçük, odaklanmış bir ekibe dönüştürür. Anthropic'in etkili ajanlar inşa etme makalesi daha geniş durumu ortaya koyuyor: modele göre yapılandırma, daha büyük bir istemden daha iyidir.
Sıkça sorulan sorular
Claude Code alt ajanı nedir? Ana Claude Code ajanının görevlendirdiği ayrı bir ajan örneğidir. Her alt ajanın kendi bağlam penceresi, özel bir sistem istemi ve yapılandırılabilir bir araç seti vardır. Odaklanmış bir görev yapar ve sonucu döndürür, ana konuşmayı temiz tutar ve uzmanları paralel çalıştırmanıza olanak tanır. Claude Code alt ajanı nasıl oluşturulur? `.claude/agents/` (proje) veya `~/.claude/agents/` (kişisel) içinde bir Markdown dosyası oluşturun. `name`, `description`, isteğe bağlı `tools` ve isteğe bağlı `model` içeren YAML ön bilgisini ekleyin, ardından sistem istemini gövdeye yazın. Açıklama, Claude'a ona ne zaman otomatik olarak delege edeceğini söyler. Claude hangi alt ajanı kullanacağına nasıl karar verir? Mevcut her alt ajanın `description` alanını okur ve bir görev eşleştiğinde otomatik olarak delege eder. Ayrıca, "kod denetçisi alt ajanını kullan" gibi adıyla açıkça çağırabilirsiniz. Açık, tetikleyici tarzı açıklamalar otomatik delegasyonu güvenilir kılar. Alt ajanlar ve Claude Agent SDK arasındaki fark nedir? Alt ajanlar oturum içi ve model tarafından gönderilir: Claude Code'da çalışıyorsunuz ve uzmanları içeri çekiyorsunuz. Agent SDK programatiktir, burada belirleyici veya katılımsız çalıştırmalar için kontrol akışını kodda siz yazarsınız. Etkileşimli uzmanlaşma için alt ajanları, zamanlanmış döngüler için SDK'yı kullanın. Alt ajanlar paralel çalışabilir mi? Evet. Ana ajan, bağımsız görevler için aynı anda birden fazla alt ajanı gönderebilir, böylece inceleme, test ve dokümantasyon sırayla değil, birlikte gerçekleşir. Büyük ölçekli yayılım için Claude Code'un dinamik iş akışları bunu tek bir oturumda birçok paralel alt ajana genişletir. Alt ajanlar API testine nasıl yardımcı olur? OpenAPI spesifikasyonuna karşı API testlerinizi yazan ve çalıştıran bir alt ajan tanımlayın. Bu, bir uç noktanın sadece bittiği gibi görünüp görünmediğinden ziyade, gerçekten çalışıp çalışmadığını kontrol eden bir doğrulama geçidi haline gelir. Bunu Apidog gibi bir platforma yönlendirmek, geri bildirimi şema farkında yapar, böylece her yanıt sözleşmeye göre doğrulanır.
Sonuç
Claude Code alt ajanları, tek bir bağlam penceresinin her şeyi tutamama sorununu çözer. Her göreve kendi bağlamını, talimatlarını ve araçlarını vererek, tek bir aşırı yüklenmiş ajanı, paralel çalışan ve temiz rapor veren küçük bir uzman ekibiyle değiştirirsiniz. Kurulum sadece bir Markdown dosyasıdır ve getirisi odaklanma, hız ve doğru işe doğru modeli koyma yeteneğidir. İki tane ile başlayın: bir denetçi ve bir testçi. Claude'un kendi başına delege etmesi için sıkı açıklamalar yazın, her birine sadece ihtiyaç duyduğu araçları verin ve testçiyi API süitenize yönlendirerek gerçek bir doğrulama geçidi haline getirin. Uç noktalarla ilgili her şey için, Apidog o geçide kontrol edeceği bir şema verir; indirin ve bir test alt ajanının, farkı okumadan önce kodunuzun çalıştığını kanıtlamasına izin verin.