Claude Code'da alt ajanlar ve hook'lar nasıl çalışır?

İkisi birlikte, pazarlama ve içerik ekiplerine işi bölme ve kuralı zorunlu kılma imkanı verir.

Bu yazı, ilk yazımız olan Claude Code nedir ve pazarlamacı için ne yapar yazısının devamıdır. İki özellik de yazılım ekipleri için belgelenmiştir. Reklam ve içerik işine neyin taşındığını söylediğimiz yerler bizim yorumumuzdur ve öyle işaretliyoruz.

Subagent nedir?

Anthropic belgeleri tek cümleyle anlatır: subagent'lar, belirli iş türlerini ele alan özel yapay zeka yardımcılarıdır. Her biri kendi bağlam penceresinde, kendi sistem istemi, belirli araç erişimi ve bağımsız izinlerle çalışır (subagents). Claude, bir subagent'ın açıklamasına uyan bir görev görünce işi ona devreder; subagent bağımsız çalışır ve sonuçları geri getirir.

Belgeler beş gerekçe sayar: keşif işini ana sohbetinizin dışında tutmak, yardımcının kullanabileceği araçları sınırlamak, aynı kurulumu projeler arasında yeniden kullanmak, yardımcıya odaklı bir sistem istemi vermek ve basit işleri Haiku gibi daha hızlı, ucuz modellere yönlendirmek (subagents). Pratik kural şudur: yan bir iş, ana sohbetinizi bir daha bakmayacağınız arama sonuçları, loglar ya da dosya içerikleriyle dolduracaksa subagent kullanın.

Pazarlama için bizim yorumumuz: uzun bir reklam hesabı dökümü, 200 yorumluk bir klasör ya da bir yığın rakip sayfası düşünün. Hepsinin ana sohbetinizde durmasını istemezsiniz. Subagent okur, ihtiyacınız olan üç bulguyu getirir. Belgelerdeki sahne bir kod araması, ama mekanizma bir klasöre koyabildiğiniz her metin için aynıdır.

Aynı sayfadan bir maliyet notu: subagent kendi isteklerini gönderir ve bunlar ana sohbetinizle aynı kullanım sınırlarına sayılır (subagents). Devretmek bağlamınızı kurtarır, kotanızı değil.

Hazır yardımcılar ve kendinizinkiler

Claude Code hazır subagent'larla gelir. Belgeler şunları sayar: arama ve analiz için hızlı, salt okunur Explore; plan gösterilmeden önce plan modunda araştırma yapan Plan; ve "hem keşif hem eylem gerektiren karmaşık, çok adımlı işler için yetkin bir ajan" olan General-purpose (subagents). Explore ve Plan dosya yazamaz ya da düzenleyemez.

Kendi subagent'ınız, kısa bir başlığı olan bir markdown dosyasıdır. Belgelerdeki biçim şöyle:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback.

Zorunlu alan yalnızca name ve description. Belgelerin saydığı diğer alanlar arasında tools (izin listesi), disallowedTools, model (sonnet, opus, haiku, fable, tam model kimliği ya da inherit), permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort ve isolation var (subagents).

Dosyanın durduğu yer, onu kimin kullanacağını belirler. Projenin .claude/agents/ klasörü sürüm kontrolüne eklenirse ekibinizle paylaşılır; ~/.claude/agents/ tüm projelerinizde geçerlidir; bir kuruluş yönetilen ayarlarla ajan dağıtabilir ve bunlar her şeyin önüne geçer (subagents).

Birini nasıl çağırırsınız?

Belgeler dört yol anlatır (subagents):

1. Otomatik. Claude, göreve ve subagent'ın description alanına bakarak karar verir. Açıklamadaki "use proactively" gibi ifadeler devri teşvik eder.
2. Düz dille adını söyleyerek: "test-runner subagent'ını kullanıp başarısız testleri düzelt."
3. @-mention. Belgelere göre o subagent'ın görev için çalışmasını "garanti eder".
4. Tüm oturumu subagent olarak açmak: claude --agent <ad>.

Bir subagent ön planda çalışabilir, yani sohbetinizi bekletir, ya da arka planda eşzamanlı çalışır. Arka plandaki izin soruları ana oturumunuzda görünür ve Claude'un başlattığı bir subagent varsayılan olarak arka planda başlar (subagents).

Belgelerin yazdığı sınırlar: varsayılan olarak aynı anda 20 subagent çalışabilir ve bir subagent, ana sohbetin altında üç katmana kadar kendi yardımcılarını başlatabilir. İkisi de ortam değişkenleriyle değiştirilebilir.

Bizim yorumumuz: asıl talimat description alanıdır. Onu bir serbest çalışana verdiğiniz brif gibi yazın: iş nedir, ne zaman çağrılır.

Hook nedir?

Hook'lar, "Claude Code'un yaşam döngüsünde belirli noktalarda otomatik çalışan; kullanıcı tanımlı kabuk komutları, HTTP uç noktaları, MCP araç çağrıları, LLM istemleri ya da subagent'lar"dır (hooks). Anthropic'in kendi verdiği kullanımlar, her dosya düzenlemesinden sonra otomatik biçimlendirme ve commit öncesi lint çalıştırmadır (overview).

CLAUDE.md'den asıl fark, zorunlu kılmadır. İlk yazımızda CLAUDE.md'nin zorunlu bir ayar değil, bağlam olduğunu söylemiştik. Hook bunun zorunlu karşılığıdır: hooks kılavuzuna göre, belirli eylemlerin "LLM'in çalıştırmayı seçmesine bırakılmadan her zaman gerçekleşmesini" sağlar (hooks guide).

Yapılandırma üç katmanlıdır: bir hook olayı, bir matcher grubu ve bir ya da daha fazla işleyici. Hook'lar ayar dosyalarına yazılır: tüm projeleriniz için ~/.claude/settings.json, tek proje için .claude/settings.json (commit edilebilir), git'e girmeyen yerel bir dosya, yönetilen politika, eklentiler ve bir skill ya da subagent'ın başlığı (hooks).

En sık karşılaşacağınız olaylar

Başvuru sayfası otuzdan fazla olay sayar. Oturum başına, tur başına ya da araç çağrısı başına tetiklenirler. Aşağıda bir içerik ekibinin en çok karşılaşacağı olaylar var; tüm satırlar hooks başvurusundan.

Bizim yorumumuz: bir dosya düzenlemesinden sonraki PostToolUse, metinlerde yasaklı kelime taraması için doğal yerdir; PreToolUse ise dokunulmaması gereken bir klasöre yazmayı durduracağınız yerdir.

Hook nasıl karar verir?

Hook, olay hakkında JSON alır; komut hook'unda bu stdin üzerinden gelir. Kabuk hook'u cevabını çıkış koduyla verir (hooks):

• Çıkış 0: başarı; stdout isteğe bağlı JSON için okunur.
• Çıkış 2: engelleyen hata. Engelleyebilen olaylarda Claude Code eylemi durdurur ve stderr metni gerekçe olur.
• Başka herhangi bir kod: engellemeyen hata; eylem devam eder.

Belgeler uyarır: 1 çıkış kodu engellemeyen bir hatadır, "hook'unuz bir politikayı zorunlu kılacaksa exit 2 kullanın." Çıkış kodu yerine hook, 0 ile çıkıp JSON da yazdırabilir, mesela permissionDecision değeri deny ve bir gerekçe içeren bir PreToolUse cevabı. Hook başına tek yaklaşım seçin.

Matcher, hook'un ne zaman çalışacağını daraltır. Araç olaylarında araç adıyla eşleşir, mesela Edit|Write; SubagentStart için ajan türüyle eşleşir. UserPromptSubmit ve Stop gibi bazı olaylar matcher almaz, her zaman tetiklenir (hooks).

Beş hook türü vardır: command, http, mcp_tool, prompt ve agent. prompt hook'u olayı tek turluk bir değerlendirme için bir Claude modeline gönderir; agent hook'u ise bir koşulu doğrulamak için dosya okuyabilen bir subagent başlatır. Belgeler agent hook'larını deneysel olarak işaretler (hooks).

Grafik aynı sayfadaki varsayılanları gösterir: command, http ve mcp_tool için 600 saniye, prompt için 30, agent için 60. Bir olayın eşleşen hook'ları paralel çalışır. UserPromptSubmit olayında command, http ve mcp_tool hook'larının varsayılanı 30 saniyeye düşer.

Subagent ve hook nerede buluşur?

Hook'lar subagent'lara belgelenmiş üç yoldan uzanır (hooks):

• SubagentStart ve SubagentStop, bir yardımcı başladığında ve bittiğinde tetiklenir. SubagentStop hook'ları son metin için last_assistant_message alanını okumalıdır.
• Ayarlardaki hook'lar subagent içindeki araç olaylarında da tetiklenir ve girdilerinde agent_id ile agent_type bulunur.
• Bir subagent kendi başlığında kendi hook'larını taşıyabilir; bunlar yalnızca o subagent çalışırken işler.

Pazarlama ya da içerik ekibi bunlarla ne yapar?

Aşağıdakilerin hiçbiri belgelenmiş bir pazarlama iş akışı değil. Yukarıdaki alan ve olaylardan çıkardığımız, bize ait yorumlardır.

• Araştırma subagent'ı: salt okunur araçlarla (tools: Read, Glob, Grep) bir döküm, yorum ya da brif klasörünü özetleyip getirir. Hiçbir şeyi düzenleyemediği için tek kopyanızı gösterebilirsiniz.
• Metin inceleme subagent'ı: sistem isteminde üslubunuz ve bir kontrol listesi bulunur. Bir grup reklam varyasyonunu kabul etmeden önce @-mention ile çağırın.
• Yasaklı kelime hook'u: metin dosyası düzenlemelerinde PostToolUse üzerinde çalışır. Hiç kullanmadığınız bir ifade bulursa 2 koduyla çıkar ve Claude gerekçeyi görür.
• Korumalı klasör hook'u: PreToolUse üzerinde, onaylı ve nihai varlıkların durduğu klasöre yazmayı engeller.
• Rutin işler için ucuz yardımcı: belgelerin maliyet kontrolü için önerdiği gibi, ayıklama ve etiketleme için model: haiku olan bir subagent.

Bir reklamı harcama yapmadan önce denetlemek isterseniz, bunların hiçbirine bağlı olmayan ücretsiz yaratıcı puanı aracını da kullanabilirsiniz.

Sık sorulan sorular

Subagent ile hook arasındaki fark nedir? Subagent, bir işi kendi bağlam penceresinde yapan yardımcıdır. Hook, belirli bir anda çalışan ve bir eylemi onaylayabilen ya da engelleyebilen işleyicidir. Subagent'ı Claude ya da siz seçersiniz; hook, kimse seçmese de çalışır (subagents, hooks).

Bunları kullanmak için kod yazmam gerekir mi? Subagent, düz dille yazılmış ve kısa bir başlığı olan bir markdown dosyasıdır; gerekmez. Hook genellikle JSON okuyup bir kodla çıkan küçük bir betiktir. Betik yazmıyorsanız Claude Code'a taslağı yazdırıp yazdığını okuyun (bizim yorumumuz).

Bir subagent dosya düzenleyebilir mi? Siz sınırlamadıkça evet. tools alanını boş bırakırsanız subagent'ların kullanabildiği tüm araçları devralır; hazır Explore ve Plan ajanları salt okunurdur (subagents).

Hook, CLAUDE.md'deki bir talimattan daha güvenli midir? Her seferinde geçerli olması gereken bir kural için evet, çünkü hook modelin seçimiyle değil tasarım gereği çalışır. Hooks kılavuzu tam olarak bu amacı anlatır (hooks guide).

Bu nerede işe yarar?

Subagent ve hook'lar, aracı kendi elleriyle yönlendiren kişiler içindir. İhtiyacınız bir atölye değil de bitmiş ürün reklamlarıysa, Framepx'te yaptığımız iş budur: ürün feed'lerini reklama çeviren bir yapay zeka sistemi işletiyoruz, nasıl çalıştığını buradan görebilirsiniz. Daha fazla rehber blogda.

Kaynaklar

• Create custom subagents
• Hooks reference
• Hooks guide
• Claude Code overview