Claude Code Hooks: Claude’a Güvenmek Yerine Kural Dayatmak

CLAUDE.md dosyasına “asla rm -rf çalıştırma” yazmak bir talimat; Claude’un onu bir gün gözden kaçırmayacağının garantisi değil. Hooks, bu farkı kapatıyor: talimat değil, her seferinde deterministik çalışan bir kural.

Bu yazıda hook’ların ne olduğunu, dört tipini, olayların nasıl kademelendiğini ve iki gerçek örnekle nasıl kurulduğunu resmi Claude Code dokümantasyonuyla anlatıyoruz.

Hook Nedir, Prompt Talimatından Farkı Ne?

Resmi dokümantasyona göre hook’lar, Claude Code’un yaşam döngüsünün belirli noktalarında otomatik çalışan kullanıcı tanımlı shell komutları, HTTP uç noktaları ya da LLM prompt’ları. Claude’un göz ardı edebileceği bir talimatın aksine, hook’lar her seferinde ateşleniyor — format kurallarını, güvenlik kontrollerini, bildirimleri Claude’un hafızasına değil, sisteme bağlıyorsun.

Hook Olayları Üç Kademede

Ağustos 2026 itibarıyla dokümantasyon 31 farklı hook olayı listeliyor. Bunlar üç sıklıkta gruplandı: oturum başına bir kez (SessionStart, SessionEnd), tur başına bir kez (UserPromptSubmit, Stop), ve agentic döngü içinde her araç çağrısında (PreToolUse, PostToolUse). Hangi olayı seçtiğin, kuralının ne sıklıkta çalışacağını belirliyor.

Dört Hook Tipi

En sık kullanılanı command — bir shell script çalıştırır. http, bir URL’ye POST atarak uzaktaki bir servise soruyor. prompt, Claude’a tek turluk hızlı bir evet/hayır sorusu sordurur. agent ise araç erişimi olan bir subagent doğurarak daha karmaşık doğrulamalar yapabiliyor.

Pratik Örnek: Tehlikeli Komutu Engellemek

PreToolUse hook’u, bir araç çalışmadan önce devreye giriyor ve çıkış kodu davranışı belirliyor:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-rm.sh dosyası komutu inceleyip tehlikeli bulursa exit 2 ile çıkıyor — bu, aracın çalışmasını durduruyor ve nedeni Claude’a gösteriyor. Zararsızsa exit 0 ile normal izin akışı devam ediyor.

Pratik Örnek: Her Dosya Yazımından Sonra Otomatik Format

PostToolUse ise araç başarıyla tamamlandıktan sonra çalışıyor — her Edit veya Write‘tan sonra otomatik linter/formatter tetiklemek için ideal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/path/to/lint-check.sh" }
        ]
      }
    ]
  }
}

Bu şekilde format kuralı Claude’un “hatırlamasına” bağlı kalmıyor — her dosya değişikliğinden sonra kendiliğinden çalışıyor.

Güvenlik ve Yönetim

Hook’lar beş farklı yerde tanımlanabiliyor: ~/.claude/settings.json (tüm projeler), .claude/settings.json (tek proje, git ile paylaşılır), .claude/settings.local.json (tek proje, paylaşılmaz), kuruluş genelinde yönetilen policy dosyaları, ve plugin’lerin kendi hooks.json‘u. /hooks komutu o oturumda geçerli olan tüm hook’ları listeliyor; kuruluş yöneticileri allowManagedHooksOnly ile sadece kendi tanımladıklarının çalışmasını zorunlu kılabiliyor, HTTP hook’lar için de allowedHttpHookUrls ile hangi uç noktalara istek atılabileceğini sınırlayabiliyor.

Sık Sorulan Sorular

Hook’ları nasıl devre dışı bırakırım?

Ayarlara "disableAllHooks": true ekleyerek tüm hook’ları tek seferde kapatabilirsin.

Hook çalışmazsa nasıl hata ayıklarım?

CLAUDE_DEBUG=1 ortam değişkeniyle Claude Code’u başlatarak hook hatalarının detaylı log’unu görebilirsin.

Hook’ları belirli bir araçla mı sınırlayabilirim?

Evet, matcher alanıyla — ör. sadece Bash aracına ya da mcp__memory__.* gibi belirli bir MCP sunucusunun tüm araçlarına filtre uygulayabilirsin.

Kuruluş yöneticisi hook’larımı geçersiz kılabilir mi?

Evet, managed policy hook’ları devre dışı bırakılamaz ve allowManagedHooksOnly açıksa yalnızca kuruluşun tanımladığı hook’lar çalışır.

Hook’ları subagent’larla birlikte kullanmak istersen Claude Code Subagents yazımıza bakabilirsin — subagent frontmatter’ına tanımlanan hook’lar sadece o subagent aktifken çalışıyor.