Özel Agent'lar

O kadar spesifik bir prompt yazdınız ki yalnızca tek bir iş akışına uygulanıyor — Dockerfile’ların güvenlik incelemesi. Bunu her claude -p çağrısına yapıştırmak sıkıcı ve hataya açık. İsmiyle çağırabileceğiniz, kendi araç kısıtlamaları ve izinleri yerleşik olan yeniden kullanılabilir bir agent’a ihtiyacınız var.

Özel agent’lar, belirli talimatlar, araçlar ve varsayılanlara sahip önceden yapılandırılmış Claude kişilikleridir. Bunları kayıtlı profiller veya kişilikler olarak düşünün. Her agent, kimliğini, yeteneklerini ve sistem prompt’unu belirten YAML frontmatter’lı bir Markdown dosyası (“agent dosyası”) olarak tanımlanır. Her agent kendi bağlam penceresinde bağımsız izinlerle çalışır. Bunları bir projeye kapsamlandırabilir, tüm çalışmalarınızda paylaşabilir veya tek seferlik kullanım için satır içi tanımlayabilirsiniz.

Dar kapsamlı bir şeyle başlayın — bir kod inceleyici, bir test yazıcısı. 3-4 araçlı odaklanmış agent’lar, her şeye erişimi olan geniş agent’lardan daha iyi performans gösterir, çünkü daha küçük araç seti daha az yanlış adım anlamına gelir.

Agent Dosya Formatı

Bir agent dosyası, YAML frontmatter’ın agent’ın kimliğini ve yeteneklerini tanımladığı ve Markdown gövdesinin agent’ın sistem prompt’u olduğu bir Markdown belgesidir. Proje düzeyinde erişim için .claude/agents/’a veya kullanıcı düzeyinde erişim için ~/.claude/agents/’a kaydedin.

Örnek: bir ‘code-reviewer’ agent’ı — her zaman plan modunu kullanır, araçları Read/Grep/Glob ile kısıtlar ve bir ‘hata bul’ sistem prompt’una sahiptir:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
---

You are a senior code reviewer ensuring high standards of code quality.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- No duplicated code
- Proper error handling
- No exposed secrets
- Input validation implemented

Yerleşik Agent’lar

Claude Code beş yerleşik agent ile birlikte gelir. Bunları düzenleyemezsiniz, ancak aynı isimde bir agent dosyası oluşturarak geçersiz kılabilirsiniz.

Özel Agent Oluşturma

İhtiyacınız olan kapsama bağlı olarak iki dizinden birinde bir Markdown dosyası oluşturun:

• Proje düzeyi: .claude/agents/code-reviewer.md — ekibinizin agent’ı paylaşması için git’e commit edin
• Kullanıcı düzeyi: ~/.claude/agents/code-reviewer.md — makinenizdeki her projede kullanılabilir

Dosya adı (.md uzantısı hariç) agent adı olur, dolayısıyla code-reviewer.md dosyası code-reviewer adında bir agent oluşturur. Frontmatter’daki name alanı eşleşmelidir.

İsimler çakıştığında, çözüm sırası şöyledir:

Satır İçi Agent’lar

Hızlı test veya CI/CD ardışık düzenleri için, dosya oluşturmak yerine --agents bayrağıyla agent’ları satır içi tanımlayın. Bayrak, her anahtarın bir agent adı ve her değerin agent’ın yapılandırmasını tanımladığı bir JSON nesnesi kabul eder:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

JSON alanları YAML frontmatter alanlarını yansıtır, tek bir farkla: sistem prompt’u için Markdown gövdesi yerine prompt kullanın. Satır içi agent’lar oturum kapsamlıdır ve diske kaydedilmez.

Tüm oturumu belirli bir agent olarak çalıştırmak için --agent (tekil) kullanın:

claude -p "Review this code" \
  --agents '{"reviewer": {"description": "Code reviewer", "prompt": "You are a strict code reviewer. Always start with REVIEWER:"}}' \
  --agent reviewer \
  --output-format json

Agent’ın sistem prompt’u varsayılan Claude Code sistem prompt’unu tamamen değiştirir. CLAUDE.md dosyaları normal şekilde yüklenmeye devam eder.

Agent(type) Aracı

Çalışan bir oturum içinde Claude, Agent aracını kullanarak subagent’lar oluşturabilir. Bu aracı doğrudan çağırmazsınız — Claude’dan işi ismiyle bir agent’a devretmesini istersiniz:

Use the code-reviewer subagent to review the auth module

Veya @-bahsetme ile:

@"code-reviewer (agent)" look at the auth changes

Bir koordinatörün hangi agent’ları oluşturabileceğini tools frontmatter alanındaki Agent(type) sözdizimi ile kısıtlayabilirsiniz:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Bu koordinatörden yalnızca worker ve researcher agent’ları oluşturulabilir. Parantez olmadan Agent kullanmak, mevcut herhangi bir agent’ın oluşturulmasına izin verir.

Subagent’lar için temel kısıtlamalar:

• Subagent’lar başka subagent’lar oluşturamazlar — iç içe geçirme yasaktır
• Subagent’lar kendi sistem prompt’larını alır, tam Claude Code prompt’unu değil
• Ön plan subagent’ları tamamlanana kadar ana konuşmayı engeller; izin istekleri aktarılır
• Arka plan subagent’ları izinler önceden onaylanmış şekilde eşzamanlı çalışır; çalışan bir görevi arka plana almak için Ctrl+B’ye basın

claude agents Komutu

Yapılandırılmış tüm agent’ları (hem yerleşik hem de özel) görmek için claude agents çalıştırın:

Etkileşimli modda, oturumunuzdan ayrılmadan agent oluşturmak, düzenlemek ve silmek için /agents eğik çizgi komutunu kullanın. Bu şekilde oluşturulan yeni agent’lar yeniden başlatma gerektirmeden hemen kullanılabilir.

--brief Bayrağı

--brief bayrağı Claude’un sistem prompt’unu daha kısa yanıtlar üretecek şekilde değiştirir. Belgelerin SendUserMessage aracını etkinleştirdiğini öne sürmesine rağmen, testler bunun oturuma herhangi yeni bir araç eklemediğini doğrulamaktadır.

--brief’in gerçekte yaptığı:

• Sistem prompt’unu değiştirir — farklı cache oluşturma token’larıyla doğrulanmıştır (standart prompt için 0’a karşı 9.245 yeni token)
• SendUserMessage’ı etkinleştirMEZ — stream-json init olayı --brief olsun veya olmasın aynı araç listesini gösterir
• Çıktı formatını değiştirMEZ — JSON ve stream-json çıktı yapısı aynıdır
• Agent’larla uyumludur — --agent ve --agents ile çakışma olmadan çalışır

# --brief ile (farklı sistem prompt'u önbelleğe alınır)
claude -p "Summarize this file" --brief --output-format json
# Çıktı: aynı yapı, aynı alanlar, potansiyel olarak daha kısa sonuç metni

# --brief olmadan (standart sistem prompt'u)
claude -p "Summarize this file" --output-format json
# Çıktı: aynı yapı, sonuç daha ayrıntılı olabilir

--agent ile Agent Seçimi

--agent bayrağı (tekil), tüm oturum için isimli bir agent seçer. Agent’ları öncelik sırasına göre üç kaynaktan keşfeder:

1. CLI satır içi — --agents '{"name": {...}}' (en yüksek öncelik)
2. Proje agent’ları — .claude/agents/name.md
3. Kullanıcı agent’ları — ~/.claude/agents/name.md

# Dosya tabanlı bir agent seçin
claude -p "Review this code" --agent code-reviewer --output-format json

# Satır içi bir agent seçin
claude -p "Review this code" \
  --agents '{"reviewer": {"description": "...", "prompt": "..."}}' \
  --agent reviewer --output-format json

# Keşfedilebilir tüm agent'ları listeleyin
claude agents

claude agents komutu tüm mevcut agent’ları kaynağa göre gruplandırılmış olarak gösterir:

6 active agents

Project agents:
  code-reviewer · sonnet

Built-in agents:
  claude-code-guide · haiku
  Explore · haiku
  general-purpose · inherit
  Plan · inherit
  statusline-setup · sonnet