Claude Code Subagent Model Ataması ve Orkestrasyon Maliyeti

Claude Code'da bir subagent'ı tetiklediğinde hangi modelin çalışacağını dört yerden biri belirler ve bu dördünün hangisinin kazanacağı 2026 yazında değişti. Yanlış varsayımla kurulan bir orkestrasyon akışı, basit bir dosya-tarama görevini bile en pahalı modelde koşturabilir — fark edilmesi zor, faturaya yansıması hızlı bir sızıntı. Bu rehber, Claude Code subagent model ayarının güncel çözüm zincirini, inherit davranışının neden sessizce pahalıya patladığını ve görev tipine göre doğru model eşleştirmesini adım adım anlatıyor.

💡 Pro Tip: Bir subagent çağrısında model parametresini açıkça vermediğin ve agent frontmatter'ı ile CLAUDE_CODE_SUBAGENT_MODEL de boş olduğu her durumda, o çağrı ana konuşmanın modelini miras alır — bunu unutmak, en sık rastlanan gizli maliyet kaynağıdır.

İçindekiler

• Model çözüm zinciri: çağrı parametresi > agent frontmatter > env varsayılanı > parent
• Neden bu sıralama önemli
• 'inherit' ne demek ve neden sessizce pahalıya patlar
• Pratik kontrol listesi
• Görev-model eşleştirme tablosu (keşif/mekanik · spesifikasyonlu kod · zor verify)
• general-purpose subagent'ın varsayılan davranışı
• Karar verirken sorulacak üç soru
• [Sessiz tuzak: [1m] etiketi yok sayılınca 200K context'e düşen ajan](#sessiz-tuzak-1m-etiketi-yok-saylnca-200k-contexte-den-ajan)
• Neden bu özellikle subagent'larda tehlikeli
• Prompt cache'i ıskalatan davranışlar ve /cost'un yeni 'neden ıskaladı' satırı
• /cost ve status line'daki yeni sinyal
• Uzun subagent prompt'unu dosyadan vermek (--append-subagent-system-prompt-file)
• Agent teams'in token yükü ve ne zaman buna değer
• Basit karar kuralı
• Doğrulama: hangi modelin gerçekten koştuğunu /tasks ve modelUsage ile kanıtlamak
• SSS
• Claude Code'da subagent hangi modeli kullanır, nasıl zorlanır?
• Model belirtmeden subagent çağırırsam ne kadar pahalıya mal olur?
• Prompt cache neden ıskalanır ve nedenini nasıl görürüm?
• Agent teams mi tek subagent mı daha ucuz?
• [[1m] etiketi neden yok sayılabiliyor?](#1m-etiketi-neden-yok-saylabiliyor)
• Hangi görevi hangi model sınıfına vermeliyim?
• Sonuç
• Kaynaklar

Model çözüm zinciri: çağrı parametresi > agent frontmatter > env varsayılanı > parent

Claude Code, bir subagent'ın hangi modelle çalışacağına dört noktayı sırayla kontrol ederek karar verir. Resmi dokümantasyona göre sıra şöyledir: önce Agent çağrısındaki per-invocation model parametresi, sonra subagent tanımının YAML frontmatter'ındaki model alanı, ardından CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni, en son da hiçbiri set edilmemişse ana konuşmanın (parent) modeli devreye girer.

Bu sıralama her zaman böyle değildi. v2.1.251'den önce CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni zincirin başındaydı — yani hem per-invocation model parametresini hem de frontmatter'daki model: inherit ayarını eziyordu. Bir ekip env değişkenini "varsayılan" sanıp set ettiğinde, aslında her çağrıyı zorla o modele bağlıyordu; explicit olarak farklı bir model istese bile fark etmiyordu. v2.1.251 bu davranışı tersine çevirdi ve env değişkenini gerçek bir "varsayılan"a indirgedi: yalnızca üstünde hiçbir explicit ayar yokken devreye giren bir taban.

Neden bu sıralama önemli

Pratikte bu, üç farklı katmanda model seçebileceğin anlamına gelir:

• Çağrı anında (Agent tool veya workflow agent() içinde model parametresi) — en spesifik, zorlama bayrağı kapalıyken her zaman kazanır.
• Agent tanımında (.claude/agents/*.md frontmatter'ında model: alanı) — o agent'ı her çağırdığında geçerli olan sabit tercih.
• Ortam değişkeninde (CLAUDE_CODE_SUBAGENT_MODEL) — hiçbir explicit ayar yoksa devreye giren son çare varsayılanı.

Üçü de boşsa subagent, ana konuşmanın modelini miras alır — built-in Explore ve Plan ajanları da dahil bu davranışı gösterir. Explore için bir kayıt daha var: Claude API üzerinde miras alınan model Opus ile sınırlanır.

'inherit' ne demek ve neden sessizce pahalıya patlar

Bir agent tanımında model: inherit yazdığında, o subagent ana konuşmanın modelini kullanır. Bu, hızlı bir varsayılan gibi görünür ama pratikte iki farklı şekilde sürpriz yaratabilir.

Birincisi basit: env değişkeni set edilmemişse (veya frontmatter zaten inherit diyorsa) ve ana konuşma pahalı bir modelde çalışıyorsa, "sadece dosyaları tara" diye çağırdığın subagent de aynı pahalı modelde koşar. Keşif ve mekanik işler için bu, gereksiz yere yüksek maliyetli tur anlamına gelir.

İkincisi daha az bilinen bir tuzak: CLAUDE_CODE_SUBAGENT_MODEL tek başına Explore ve Plan gibi built-in ajanları etkilemez. Bu ajanları da env değişkenine bağlamak istiyorsan ayrıca CLAUDE_CODE_SUBAGENT_MODEL_FORCE değerini 1 yapman gerekir. Bayrağın semantiği dört maddede toplanır: (a) ikisi de set edilmişse subagent'lar CLAUDE_CODE_SUBAGENT_MODEL içindeki modelde koşar — bayrak açıkken her subagent tanımının model alanı, built-in Explore ve Plan dahil, yok sayılır ve çağrı anında model parametresi de geçilemez; (b) yalnızca CLAUDE_CODE_SUBAGENT_MODEL_FORCE set edilmişse subagent'lar ana konuşmanın modelinde koşar, Explore ise kendi model tavanını korur; (c) ikisi de set olsa bile iki tür subagent ana konuşmanın modelinde kalmaya devam eder: bir fork ve model: inherit ile subagent'ta koşan bir skill; (d) bayrak Claude Code v2.1.257 veya sonrasını ister.

Pratik kontrol listesi

• model: inherit yazan her agent tanımını gözden geçir — bu, ana modelin ne kadar pahalı olduğuna bağlı bir maliyet kararı.
• Explore/Plan gibi built-in ajanları yönlendirmek istiyorsan CLAUDE_CODE_SUBAGENT_MODEL tek başına yetmez; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 gerekir (v2.1.257+) ve bayrak açıkken fork ile model: inherit skill'inin ana modelde kaldığını hesaba kat.
• Env değişkenini "her şeyi ezen" bir kural sanma — v2.1.251 sonrası o yalnızca son çare varsayılanı.

Görev-model eşleştirme tablosu (keşif/mekanik · spesifikasyonlu kod · zor verify)

Resmi maliyet rehberi, basit subagent görevleri için subagent yapılandırmasında ucuz bir model belirtmeyi öneriyor. Bundled claude-api skill'i de bunu netleştirdi: ucuz worker/subagent modelleri seçerken bile bunların "current-generation" (güncel nesil) olması gerekiyor. Kayıt bundan fazlasını söylemiyor: ucuzluk tek başına yeterli ölçüt değil, model güncel nesilden de olmalı.

general-purpose subagent'ın varsayılan davranışı

general-purpose gibi genel amaçlı bir subagent, üzerinde açık bir model ayarı yoksa ve env değişkeni de boşsa, doğrudan ana konuşmanın modeline düşer. Bu yüzden "genel amaçlı" bir subagent'ı sık çağıran bir akışta, o subagent'a hangi modelin gideceğini varsayımla değil açıkça kontrol ederek belirlemek gerekir — özellikle ana model pahalıysa.

Bu davranış, çok-adımlı bir orkestrasyon script'inde özellikle görünür hale gelir. Bir workflow onlarca kez general-purpose subagent çağırıyorsa ve hiçbirinde model parametresi geçmiyorsa, o workflow'un toplam maliyeti tek bir değişkene — ana konuşmanın hangi modelde açıldığına — bağlı kalır. Aynı workflow script'i bir gün pahalı bir ana modelle, ertesi gün ucuz bir modelle çalıştırıldığında, kod hiç değişmediği hâlde toplam maliyet kayda değer ölçüde farklılaşabilir. Bu yüzden bir workflow script'i yazarken, her agent() çağrısına görev tipine uygun bir model değeri eklemek, workflow'un maliyetini kod seviyesinde öngörülebilir kılan tek pratik adımdır.

Karar verirken sorulacak üç soru

Bir subagent çağrısı için model seçerken üç soruyu sırayla sormak, yukarıdaki tabloyu pratiğe döker:

1. Bu görev ne kadar akıl yürütme gerektiriyor? Mekanik bir dosya taraması ile bir güvenlik akışının doğrulanması aynı model sınıfını hak etmez.
2. Yanlış sonucun maliyeti ne kadar yüksek? Bir keşif ajanının kaçırdığı bir dosya genellikle bir sonraki adımda fark edilir; bir verify ajanının kaçırdığı bir güvenlik açığı çok daha pahalıya patlar.
3. Bu çağrı ne sıklıkta tekrarlanacak? Yüksek hacimli, sık tekrarlanan bir görev, model sınıfındaki küçük bir fiyat farkının bile toplamda büyük bir etkiye dönüşmesine yol açar.

Sessiz tuzak: `[1m]` etiketi yok sayılınca 200K context'e düşen ajan

Bir uzun-context pinini (ANTHROPIC_DEFAULT_FABLE_MODEL üzerinde [1m] etiketi ile) kullanan bir kurulumda, model: fable olarak tanımlanmış ajanlar bir süre bu etiketi yok sayıp sessizce 200K bağlam penceresine düşüyordu. Sorunun sinsi tarafı şuydu: ajan hata vermiyor, sadece daha kısa bir bağlamla çalışıyordu — geniş bir codebase'i taramaya çalışan bir subagent, fark edilmeden yarım bilgiyle sonuç üretebiliyordu.

Bu davranış artık düzeltilmiş durumda; ancak dersin kendisi kalıcı: bir subagent'ın hangi modelde koştuğunu varsaymak yerine doğrulamak gerekiyor. Elindeki kesin sinyal, sonuç mesajındaki modelUsage alanıdır: bu alan gerçek model kimliğini verir — "pin koydum, çalışıyordur" varsayımı yeterli kanıt değil. Şunu ayır: modelUsage hangi model kimliğinin koştuğunu söyler, bağlam penceresini raporlamaz.

Neden bu özellikle subagent'larda tehlikeli

Ana konuşmada bir context daralması fark edilmesi daha kolaydır çünkü konuşmanın kendisini takip edersin. Ama bir subagent arka planda, kendi izole penceresinde çalışırken sessizce daralmış bir context'le döndüğünde, sonucun eksik olduğunu ancak sonradan — belki bir sonraki adımda tutarsızlık fark ettiğinde — anlarsın. Uzun-context gerektiren bir subagent görevinde (örneğin tüm bir codebase'i tarayan bir keşif ajanı), hangi model kimliğinin koştuğunu bir kere doğrulamak, sonradan hata ayıklamaktan çok daha ucuza gelir.

Prompt cache'i ıskalatan davranışlar ve /cost'un yeni 'neden ıskaladı' satırı

Prompt cache, aynı sistem promptu ve tool tanımlarıyla art arda gelen isteklerde önceki context'i yeniden işlemekten kaçınarak maliyeti düşürür. Ama bu mekanizma kırılgandır: istek önekindeki (prefix) küçük bir değişiklik bile cache'i ıskalatabilir. Aşağıdaki maddelerin ilk dördü resmi changelog'da belgelenen somut davranışlar; sonuncusu ise bu genel cache mekaniğinin doğrudan bir sonucu:

• Tool tanımları veya sistem promptu değişmesi — bir subagent çağrısı arasında farklı tool setleri veya farklı bir sistem promptu kullanmak, isteğin önekini değiştirir ve cache'i geçersiz kılar.
• TTL süresinin dolması — cache belirli bir süre (TTL) sonra düşer; bu süre boyunca boşta kalan bir oturum, bir sonraki istekte cache'i ıskalar.
• Agent-teams'te ilk-tur duyurularının tekrar gönderilmesi — in-process takım arkadaşları, ikinci turda birinci-tur tool ve skill duyurularını yeniden gönderiyordu; bu da istek önekini değiştirip cache'i ıskalatıyordu. Bu davranış artık düzeltildi.
• Fable 5.1'de tool-sonrası context'in cache'lenmemesi — Fable 5.1 oturumlarında tool sonucu sonrası eklenen bağlam, önceden cache kapsamının dışında kalıp her tool-çağrısı turunda cache'siz girdi olarak yeniden gönderiliyordu. Bu da düzeltilen davranışlardan biri.
• Aynı prefix'i bozan küçük prompt varyasyonları — her çağrıda biraz farklı ifade edilen bir sistem promptu, teknik olarak "aynı iş" olsa bile cache açısından farklı bir istek sayılır.

/cost ve status line'daki yeni sinyal

Artık /cost çıktısı ve status line'ın prompt_cache alanı, bir cache-miss yaşandığında olası nedenini de gösteriyor — örneğin "tool tanımları değişti" veya "TTL doldu" gibi. Bu, önceden yalnızca "cache ıskalandı, toplam maliyet şu" diyen bir sinyalin artık "neden ıskalandı" diyen bir teşhis satırına dönüşmesi demek. Bu satırın kapsamını da bilmek gerekiyor: yalnızca ana konuşmayı kapsar, subagent'ları kapsamaz. Maliyet beklenmedik şekilde yükseldiğinde önce bu satıra bakmak, ana konuşmanın hangi tool seti veya sistem promptu değişikliğiyle cache'i kırdığını gösterir.

Uzun subagent prompt'unu dosyadan vermek (--append-subagent-system-prompt-file)

Bir subagent'a uzun, tekrar kullanılabilir bir sistem promptu ekletmenin metin hâli (--append-subagent-system-prompt) bir süredir mevcut; non-interactive (headless) modda geçilir ve iç içe subagent'lar dahil her subagent'ın sistem promptunun sonuna eklenir. Kalıcı bir sınırlaması var: fork edilen bir subagent bu ek promptu almaz, çünkü konuşmanın kendi promptunu yeniden kullanır. --append-subagent-system-prompt-file bu sınırlamayı kaldırmaz; yalnızca metnin komut satırına sığmayacak kadar uzun olduğu durumu çözer — prompt'u bir dosyaya kaydedip yolunu geçersin. Dosya bayrağı Claude Code v2.1.261 veya sonrasını ister.

Bunun pratik faydası iki yönlü:

• Okunabilirlik — komut satırına yüzlerce karakterlik bir string gömmek yerine, prompt'u versiyon kontrolünde tutulan ayrı bir dosyada saklayabilirsin.
• Tekrar kullanılabilirlik — aynı dosyayı farklı subagent çağrılarında referans göstererek, prompt'u tek bir yerden güncelleyebilirsin.

1# Uzun bir subagent sistem promptunu dosyadan ekle
2claude --append-subagent-system-prompt-file ./prompts/security-reviewer.md \
3  -p "Bu PR'daki auth değişikliklerini incele"

Bu bayrak, bir orkestrasyon script'inde (ör. bir Workflow tool script'i) her seferinde aynı uzun talimat setini tekrar tekrar inline yazmak yerine, o talimatı bir dosyada merkezi tutup değiştiğinde tek yerden güncellemek isteyen ekipler için düşünülmüş bir ergonomi iyileştirmesi.

Agent teams'in token yükü ve ne zaman buna değer

Agent teams, birden fazla ajanın aynı anda birlikte çalışmasını sağlayan deneysel bir mod (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ile açılır, varsayılan kapalıdır). Resmi doküman burada dolaysız bir uyarı veriyor: bu mod, tek bir oturuma göre belirgin ölçüde daha fazla token tüketir — her takım arkadaşı kendi bağımsız context penceresini taşıdığı için, aynı işi tek bir subagent'la senkron şekilde yapmaktan yapısal olarak daha pahalıdır.

Bu yüzden agent teams'i varsayılan araç yapmak yerine, yalnızca gerçek eşzamanlı koordinasyon gerektiren işlerde tercih etmek gerekir — yani birden fazla ajanın aynı anda, birbirinin ara çıktısını görerek ilerlemesi gereken durumlar. Sıralı işlerde (bir ajan bitirdikten sonra diğeri başlıyorsa) veya aynı dosya üzerinde çalışan işlerde agent teams önerilmiyor; bu tür işler tek bir Agent tool çağrısıyla (fire-and-return) çok daha ucuza tamamlanır.

Basit karar kuralı

1Görev paralel mi VE ajanlar birbirinin ara sonucuna
2gerçek zamanlı ihtiyaç duyuyor mu?
3  EVET → agent teams (token yükünü kabul ederek)
4  HAYIR → tek subagent / sıralı Agent çağrıları

v2.1.261'deki cache-miss düzeltmesi (ikinci-tur duyuru tekrarının giderilmesi) agent teams'in maliyet dezavantajını bir miktar azaltıyor, ama yapısal token farkını ortadan kaldırmıyor — her takım arkadaşının ayrı context penceresi taşıması gerçeği değişmedi.

Doğrulama: hangi modelin gerçekten koştuğunu /tasks ve modelUsage ile kanıtlamak

Bir konfigürasyonun "doğru göründüğü" ile "gerçekten öyle çalıştığı" farklı şeylerdir. Bir subagent'ın hangi modelde koştuğunu varsayımla değil, iki somut sinyalle doğrulayabilirsin:

• /tasks — koşan veya biten bir subagent'ın hangi modelde çalıştığını gösterir.
• --output-format json çıktısındaki modelUsage alanı — bu, gerçek model kimliğini taşıyan kesin sinyaldir; JSON formatında çalışırken stderr'e yazılan model uyarısı susturulduğu için gerçek modeli buradan okuman gerekir.

Model kontrolü yalnızca env değişkenine veya çağrı parametresine bakmakla bitmez — subagent'ın kendi frontmatter'ındaki model: alanını da kapsamalı, çünkü zincirde frontmatter env'den önce geliyor.

1# Koşan model kimliklerini oku (subagent bazında ayrım için /tasks)
2claude -p "..." --output-format json | jq '.modelUsage'

Bir orkestrasyon akışında model ataması konfigüre ettikten sonra, en az bir kez bu iki sinyalden birini kontrol etmek — özellikle maliyet-kritik bir subagent için — "ayarladım, çalışıyordur" varsayımını "ayarladım, doğruladım" haline getirir. Bu fark, faturanın sonunda görünen tutarla ekrandaki beklenti arasındaki uyuşmazlığı önler.

SSS

Claude Code'da subagent hangi modeli kullanır, nasıl zorlanır?

Model çözüm sırası dört basamaklıdır: önce Agent çağrısındaki per-invocation model parametresi, sonra subagent tanımının YAML frontmatter'ındaki model alanı (inherit ana konuşmanın modelini seçer), sonra CLAUDE_CODE_SUBAGENT_MODEL ortam değişkeni, en son ana konuşmanın modeli. Env değişkeni artık yalnızca hiçbir explicit ayar yokken devreye giren bir varsayılandır; gerçek zorlama için CLAUDE_CODE_SUBAGENT_MODEL_FORCE değerini 1 yapman gerekir (v2.1.257+) — ikisi de set edilmişse her subagent, built-in Explore ve Plan dahil, env değişkenindeki modelde koşar.

Model belirtmeden subagent çağırırsam ne kadar pahalıya mal olur?

Explicit model belirtilmezse subagent, ana konuşmanın modelini miras alır — built-in Explore ve Plan ajanları da böyle davranır. Yani pahalı bir ana modelde çalışan bir oturumda basit bir keşif görevi bile o pahalı modelde koşar. Hangi modelde koştuğunu /tasks veya --output-format json çıktısındaki modelUsage alanı ile doğrulayabilirsin.

Prompt cache neden ıskalanır ve nedenini nasıl görürüm?

/cost ve status line'ın prompt_cache alanı, olası nedeni (tool tanımları veya sistem promptu değişti, TTL süresi geçti gibi) doğrudan gösterir; bu satır ana konuşmayı kapsar, subagent'ları değil. Ayrıca agent-teams'te bir davranış düzeltildi: in-process takım arkadaşları ikinci turda birinci-tur duyurularını tekrar gönderip istek önekini değiştiriyor, bu da cache'i ıskalatıyordu.

Agent teams mi tek subagent mı daha ucuz?

Tek subagent (Agent tool ile senkron çağrı) yapısal olarak daha ucuzdur çünkü tek bir context penceresi taşır. Agent teams, resmi dokümana göre tek bir oturuma kıyasla belirgin ölçüde daha fazla token tüketir — her takım arkadaşı kendi bağımsız penceresini taşıdığı için. Agent teams yalnız gerçek eşzamanlı koordinasyon gerektiğinde tercih edilmeli; sıralı veya aynı-dosya işlerde önerilmiyor.

`[1m]` etiketi neden yok sayılabiliyor?

Bir uzun-context pinindeki [1m] etiketi, model: fable ajanlarında bir süre yok sayılıp ajanın sessizce 200K bağlam penceresine düşmesine yol açan bir davranıştı. Bu artık düzeltildi, ama dersin özü kalıcı: hangi model kimliğinin koştuğunu modelUsage üzerinden doğrulamak, varsaymaktan daha güvenlidir.

Hangi görevi hangi model sınıfına vermeliyim?

Keşif ve mekanik işleri (dosya tarama, envanter, format dönüşümü) ucuz, current-generation bir modele; spesifikasyonu net kod yazımını orta-üst seviye bir modele; güvenlik kritik doğrulama gibi zor verify/adversarial judge işlerini ise en güçlü/en yüksek effort modele yönlendirmek, hem maliyeti hem doğruluğu dengeler.

Sonuç

Claude Code'da subagent model ataması artık öngörülebilir bir zincire dayanıyor: çağrı parametresi, agent frontmatter'ı, env varsayılanı ve en son ana model. Bu sırayı bilmek yetmez — inheritin ne zaman pahalıya patladığını, hangi model kimliğinin gerçekten koştuğunu ve prompt cache'in hangi davranışlarla ıskalandığını modelUsage, /tasks ve /cost üzerinden doğrulamak gerekiyor. Agent teams'i yalnız gerçek eşzamanlı koordinasyon gerektiren işlerde açmak, geri kalan her yerde tek subagent'la ilerlemek de yapısal token farkını en aza indiriyor.

Orkestrasyon kurulumunu derinleştirmek istiyorsan Claude Code'da multi-agent teams ve paralel çalışma rehberine veya plan mode ile mimari planlamaya göz atabilirsin. Prompt cache konusunu API tarafında derinleştirmek için Claude prompt caching ile maliyeti 10x azaltma rehberi tamamlayıcı bir kaynak. Hook tabanlı otomasyon kurmak istiyorsan Claude Code hooks otomasyon rehberi işine yarayabilir, MCP entegrasyonları için de Claude Code MCP rehberi kaynak olabilir.

Kaynaklar

• Claude Code sub-agents dokümantasyonu — model çözüm sırası ve --append-subagent-system-prompt-file bayrağı
• Claude Code model-config dokümantasyonu — model yapılandırma ve ortam değişkenleri
• Claude Code maliyet dokümantasyonu — basit subagent görevleri için ucuz model önerisi ve Prompt cache (main) satırının kapsamı
• Claude Code agent-teams dokümantasyonu — token yükü uyarısı ve kullanım koşulları
• Claude Code prompt caching dokümantasyonu — cache'i geçersiz kılan eylemler ve prefix mekaniği
• Claude Code resmi CHANGELOG (GitHub) — v2.1.251, v2.1.260, v2.1.261 sürüm notları
• Claude Code changelog (docs mirror) — sürüm geçmişi görünümü