Slash Commands İleri Seviye: Alt Ajanlar ve Araç Orkestrasyonu

İlk iki yazı slash command'ın ne olduğunu (bir Markdown dosyası) ve ! önekiyle shell çıktısını context'e nasıl enjekte edeceğinizi anlatıyordu. Bu yazı daha ileri gidiyor: tek bir command Claude Code'un en güçlü yeteneklerini — dosya referansları, alt ajanlar, MCP araçları — nasıl orkestre eder ve izinleri nasıl kontrol altında tutarsınız.

Bu katmana geldiğinizde command artık yalnızca bir "prompt kısayolu" değil, yeniden kullanılabilir küçük iş akışlarına dönüşür.

`@file` referansı: `!cat`'ten daha uygun statik enjeksiyon

!cat file.md dosya içeriğini context'e tıkabilir ama shell üzerinden gider ve birkaç dezavantajı vardır: her tetiklemede bir alt süreç doğurmak gerekir; dosya yolunda boşluk veya özel karakter varsa ekstra escape şart olur; ve Claude Code bunu "bir dosya" olarak tanımaz, yalnızca bir metin parçası olarak görür.

@ referansı ise native'dir:

---
description: Değişiklikleri proje kurallarına göre incele
---

Aşağıdaki standartlara bak:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

Şimdi git diff'teki değişiklikleri incele ve kurala aykırı olan her yeri işaret et.

!`git diff HEAD`

@path Claude Code'a "bu dosyayı konuşmaya bir ek olarak ilişkilendir" der. Farklar:

Senaryo	`!cat` kullan	`@` kullan
Yol bir argümandan geliyor (`$ARGUMENTS`)	✅ Yalnızca `!cat` olur	❌ `@` değişken genişletmeyi desteklemez
Sabit proje standartları, şablonlar	⚠️ Olur ama ağır	✅ Native, bir shell çağrısı kazanır
Dinamik içerik (diff, log, test sonucu)	✅ `!` şart	❌ Olmaz

Kural: statik dosyalar için @, dinamik çıktı için !, parametreli yollar için !cat $ARGUMENTS.

`allowed-tools`: command'a izin sınırı koymak

Varsayılanda command çalışırken model, session'daki tüm araçları kullanabilir. Bazen bu istediğiniz şey değildir — örneğin /review salt okunur bir inceleme görevidir, "bu arada" tek bir satır kodu bile değiştirmesini istemezsiniz.

Frontmatter'a allowed-tools ekleyin; command etkin olduğu sürece yalnızca listelenen araçlara izin verilir:

---
description: Salt okunur kod incelemesi
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

Mevcut branch ile master arasındaki farkı yalnızca okuyarak incele, değişiklik yapma.

!`git diff master...HEAD`

Birkaç önemli nokta:

Bash(git diff:*) ince taneli yetkilendirmedir — yalnızca git diff ile başlayan bash çağrılarına izin verir, git push engellenir
Read / Grep / Glob açıkça yalnızca salt okunur araçları verir
Edit / Write listelenmediğinden model kodu değiştirmek istese bile çağıramaz

Benzer biçimde, /deploy gibi yüksek yetkili bir command'a ters yönde yetki verilebilir:

---
description: Mevcut branch'i deploy et
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

"Bu command neleri yapabilir" i önceden sabitlemek, her çalıştırmada bash istemlerini elle onaylamaya bel bağlamaktan çok daha güvenilirdir.

Alt ajan çağırmak: context yiyen işleri izole etmek

Bazı görevler ana konuşmanın context'ini patlatır — bir fonksiyonun tüm çağrı noktalarını bulmak için onlarca dosyayı taramak, codebase istatistikleri çıkarmak, analiz için büyük bir log parçası çekmek. Bunu doğrudan ana konuşmada yaparsanız binlerce satır çıktı context'te kalır ve sonraki turlarda konuşma yavaşlar, zekası düşer.

Doğru yaklaşım, bu işi bir subagent'a devretmektir: subagent bağımsız bir context'te koşar ve yalnızca sonucu ana konuşmaya geri getirir. Command içinde açıkça talimat vermek yeterlidir:

---
description: Bir sembolün tüm kullanımlarını derinlemesine araştır
allowed-tools: Task
---

Explore subagent'ını kullanarak aşağıdaki sembolün tüm kullanımlarını derinlemesine araştır: $ARGUMENTS

Subagent'tan şunları kapsamasını iste:
- Tüm çağrı noktaları (test dosyaları dahil)
- Dokunulan iş senaryoları
- Eşdeğer alternatif bir implementasyon var mı

Subagent döndüğünde bana yalnızca ≤300 kelimelik bir özet ver, ham kod parçaları yapıştırma.

/trace SomeClass#some_method'u tetiklediğinizde Claude Code bir Explore subagent'ı başlatır, codebase'i paralel tarar ve ana konuşmaya yalnızca damıtılmış sonuç döner. Grep çıktısı yok, dosya parçaları yok, context tertemiz.

Daha ileri oyun:

---
description: Üç aday çözümü paralel araştır
allowed-tools: Task
---

Aynı anda 3 subagent ayağa kaldır, sırasıyla aşağıdaki üç implementasyon yolunu araştırsınlar:

1. Mevcut ActiveJob + Sidekiq ile
2. Solid Queue ile
3. Hafif bir queue'yu kendi yazarak

Her ajan şu soruları cevaplasın: iş yükü, risk, mevcut koda ne kadar müdahale. Üç sonuç da elime geçtiğinde karşılaştırmayı ben yapacağım.

Üç subagent paralel koşar, ana konuşma tek bir turluk sonuç bekler. Bu command'ın sunduğu en büyük kaldıraçlardan biridir — "sonuca ulaşmak için çok token harcayan" araştırma görevlerini tek dokunuşla tetiklenen iş akışlarına çevirir.

MCP araçlarını çağırmak: command'ı dış sistemlere bağlamak

Session'a bir MCP server bağlıysa (Linear, GitHub, Sentry, kendi yazdığınız veritabanı proxy'si vb.), command doğrudan modele bu araçları çağırmasını söyleyebilir:

---
description: Linear issue'ya göre implementasyon todo'su üret
allowed-tools: mcp__linear__*, Read, Grep
---

Linear issue $ARGUMENTS'ın tam açıklamasını ve yorumlarını oku.

Codebase'in mevcut durumuyla birleştirerek (ilgili dosyaları Grep/Read ile kendin bul), implementasyon için bir todo listesi çıkar:
- Hangi dosyalar değişecek
- Her adım ayrı commit mi, birlikte mi gidecek
- Önce PM ile netleştirilmesi gereken bir belirsizlik var mı

Kod yazmaya başlama, yalnızca planı çıkar.

mcp__linear__* tüm Linear MCP araçlarına izin verir; model issue ayrıntılarını, yorumları ve durumu çekebilir. Tüm command "ticket'tan implementasyon planına" bir iş akışının başlangıç noktasına dönüşür.

Kritik nokta: allowed-tools içinde MCP aracı adını yazarken tam önekiyle yazmalısınız (mcp__<server>__<tool>), aksi halde yetkilendirme işlemez.

Command'ları birleştirmenin tuzağı: slash recursive olarak genişlemez

Çok yaygın bir yanılgı: /review dosyasına /test yazmak ve bunun test command'ını tetikleyeceğini sanmak. Tetiklemez. Slash command yalnızca kullanıcının en üst seviye girdisinde bir kez genişletilir; command'ın içindeki /xxx yalnızca sıradan bir metindir — model onu okur ama Claude Code çalıştırmaya gitmez.

Birden fazla command'ı birleştirmek için birkaç doğru yol vardır:

Yol A: Ortak mantığı bir context dosyasına ayırın, her command @ veya !cat ile referansla çeksin

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

Yol B: Command içinde açıkça "tıpkı /review gibi yap" deyin + kritik talimatları tekrarlayın

Zarif değil ama işe yarar. Prompt yeterince net olduğu sürece model aynı rotayı izler.

Yol C: Bir command Task aracıyla subagent başlatsın, subagent'ın prompt'u aynı context dosyalarını yeniden kullansın

Gerçek iş akışı orkestrasyonu hep bu yoldan geçer. Ana command zamanlama ve özetlemeyle, subagent somut adımları yürütmekle sorumlu olur.

Kaçınılması gereken anti-pattern: command'ı yüzlerce satır uzunluğunda yazıp tek bir talimatla her şeyi yapmaya çalışmak. Granülarite bir kez bozulduğunda bakım maliyeti fırlar ve tek bir çalıştırma tokan bütçesini tek bir command bitirir.

Üçlünün kullanım zamanı

Buraya kadar Claude Code'da command'a "dış yetenek" enjekte etmenin mekanizmaları temelde tamamlandı. Nasıl seçeceğinize dair:

İhtiyaç	Tercih edilen mekanizma
Sabit standartlar, şablonlar, context belgeleri	`@file` referansı
Gerçek zamanlı durum (diff, log, test sonucu, DB sorgusu)	`!shell` enjeksiyonu
Parametreli dosya içeriği	`!cat $ARGUMENTS`
Context yiyen araştırma, dosyalar arası arama	Task üzerinden subagent
Dış sistem (issue tracker, monitoring, production verisi)	MCP araçları + `allowed-tools`
Çok adımlı seri/paralel iş akışı	Ana command'ın subagent zamanlaması

İzin sınırları allowed-tools ile açıkça bildirilir — özellikle takımca paylaşılan command'lar için: neleri yapabileceğini önceden yazmak, her seferinde elle onaya güvenmekten daha sağlamdır.

Üretime yakın bir örnek

Hepsini birleştirip bir "Linear ticket'a göre implementasyon yolu araştır" command'ına bakalım:

---
description: Linear ticket'a dayalı uygulama planı üret
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## Context

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## Mevcut codebase durumu

!`git log --oneline -10`

## Görev

Linear ticket $ARGUMENTS'ın açıklamasını, yorumlarını ve ilişkili ticket'larını çek.

Sonra iki subagent'ı paralel olarak başlat:
1. Birincisi: codebase'de mevcut ilgili tüm implementasyonları, yeniden kullanılabilecek modülleri bulsun
2. İkincisi: riski değerlendirsin — bu değişiklik hangi yüksek trafikli kod yollarına dokunacak, test coverage açığı var mı

İki ajan da döndükten sonra şunları çıkar:
- Uygulama adımları (bağımlılık sırasına göre dizilmiş)
- Risk listesi
- Önerilen commit granülaritesi

Kod yazmaya başlama.

/plan ENG-4213'ü tetiklediğinizde tek bir komutla her şey biter: ticket'ı çek → codebase'i paralel araştır → riski değerlendir → planı topla. Kullanıcının yapması gereken tek şey sonucu okuyup işe koyulup koyulmayacağına karar vermek.

Slash command serisinin ilk üç yazısının eksiksiz yayı böyledir: yeniden kullanılabilir prompt'ları tanımlamak (intro) → context'i dinamik olarak enjekte etmek (context) → araçları ve alt ajanları orkestre etmek (bu yazı). Bu katmana geldiğinizde .claude/commands/ artık bir kısayol değil, ekibinizin küçük iş akışı kütüphanesidir.