Claude Code Hooks: Üretim Örnekleriyle Kapsamlı Geliştirici Rehberi

Claude Code, kod yazmada gerçekten başarılı bir araç — ama yine de olasılıksal bir sistem. Her dosya düzenlemesinin ardından Prettier çalıştırmasını söyleyebilirsiniz, bunu CLAUDE.md'ye yazabilirsiniz ve zaman zaman... unutabilir. Claude Code hooks, Claude'un her eyleminden önce, sırasında ve sonrasında ne olacağı üzerinde deterministik, garantili bir kontrol imkânı sunarak bu sorunu çözer.

Son birkaç aydır onlarca projede hooks yapılandırıyorum ve bunlar sessiz sedasız Claude Code kurulumumun en önemli parçası haline geldi. Bu rehber, temelden bugün herhangi bir projeye doğrudan uygulayabileceğiniz üretime hazır başlangıç kitine kadar her şeyi kapsıyor. Claude Code'u Cursor veya Copilot gibi araçlarla birlikte kullandıysanız, özelleştirmenin değerini zaten biliyorsunuzdur — hooks bunu bir adım öteye taşır.

Claude Code Hooks Nedir ve Neden Önemlidir?

Claude Code hooks, Claude Code'un yaşam döngüsündeki belirli noktalarda otomatik olarak çalışan, kullanıcı tanımlı kabuk komutları, HTTP uç noktaları veya LLM promptlarıdır. Anthropic'in resmi belgelerine göre, Claude'un görmezden gelebileceği prompt talimatlarının aksine, hooks her seferinde deterministik olarak tetiklenir — biçimlendirme, güvenlik, bildirimler ve iş akışı otomasyonu üzerinde garantili kontrol sağlar.

Olasılıksal Sorun

CLAUDE.md talimatlarıyla ilgili şu gerçeği göz önünde bulundurun: bunlar öneri niteliğinde, sözleşme değil. Proje bağlamına "TypeScript dosyalarını düzenledikten sonra her zaman npx prettier --write çalıştır" yazabilirsiniz ve Claude bunu çoğu zaman uygular. Ama bir ekipta kod biçimlendirmesini zorunlu kılarken, prodüksiyona push'ları engellerken ya da güvenlik denetimi için her kabuk komutunu kaydederken "çoğu zaman" yeterli değildir.

Bu, her yapay zeka kodlama aracındaki temel çelişkidir. Claude bir dil modelidir — olasılıklar üzerinde çalışır. Bağlam mühendisliği davranışı yönlendirebilir ama garanti edemez.

Hooks Bu Sorunu Nasıl Çözer

Hooks, LLM'i tamamen devre dışı bırakır. Bunlar, belirli yaşam döngüsü olaylarında tetiklenen kabuk betikleri, HTTP çağrıları veya yapay zeka değerlendirmeleridir: bir araç çalışmadan önce (PreToolUse), tamamlandıktan sonra (PostToolUse), bir bildirim geldiğinde, oturum başladığında ya da Claude durduğunda. Bunları Git hooks gibi düşünebilirsiniz — ama yapay zeka kodlama asistanınız için.

Dört hook türü mevcuttur: command (kabuk betikleri), HTTP (webhook POST istekleri), prompt (tek turlu Claude evet/hayır değerlendirmeleri) ve agent (araç erişimiyle bir alt ajan başlatır). Command hooks, ihtiyaçlarınızın yaklaşık yüzde doksanını karşılar; geri kalanları daha sonra ele alacağız.

Claude Code Hooks Nasıl Çalışır: Yaşam Döngüsü Akışı

Claude Code hooks belirlenmiş bir yaşam döngüsünde çalışır: bir olay tetiklenir (örn. PreToolUse), eşleştirici hook'un uygulanıp uygulanmayacağını kontrol eder, hook betiği çalışır ve stdin üzerinden JSON alır; çıkış kodu ne olacağını belirler. Çıkış kodu 0 devam anlamına gelir, 2 eylemi engeller. Bu akış hangi hook türünü kullandığınızdan bağımsız olarak aynıdır.

Olay -> Eşleştirici -> Hook -> Çıkış Kodu (4 Adımlı Akış)

Her hook çalışmasının nasıl işlediği aşağıda gösterilmiştir:

1. OLAY TETİKLENİR      örn. PreToolUse(Write)
       |
2. EŞLEŞTİRİCİ KONTROL EDER   "Write" hook'un eşleştirici kalıbıyla eşleşiyor mu?
       |
3. HOOK ÇALIŞIR         Kabuk betiği çalışır, stdin üzerinden JSON alır
       |
4. ÇIKIŞ KODU KARAR VERİR  0 = devam et | 2 = engelle | diğer = hata

stdin üzerinden gelen JSON, olay hakkında her şeyi içerir: tool_name, tool_input (dosya yolu, içerik, komut) ve oturum meta verileri. Betiğiniz bu JSON'ı okur, gerekli mantığı işler ve uygun kodla çıkar.

PreToolUse hooks için çıkış kodu 2 güçlü olandır — eylemi tamamen engeller ve stdout mesajınızı geri bildirim olarak Claude'a gönderir. Claude mesajınızı görür ve yaklaşımını ayarlayabilir.

Yapılandırma Kapsamları: Kullanıcı, Proje ve Yerel

Hooks, üç düzeyde settings.json içinde yer alır:

Proje ayarları ekipler için en kullanışlı olanıdır. Hooks'larınızı .claude/settings.json'a ekleyin, commit edin ve ekipteki her geliştirici aynı güvenceleri otomatik olarak alır.

if Alanı: İnce Ayarlı Filtreleme

Claude Code v2.1.85'ten itibaren hooks, yalnızca araç adlarına göre değil, araç argümanlarına göre filtreleme yapmanıza olanak tanıyan bir if alanını destekler. Anthropic hooks referansında belgelendiği üzere, bu sayede yalnızca git push ile eşleşen Bash komutlarında tetiklenen bir hook yazabilirsiniz — her tek Bash çağrısında değil.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

Bu gerçekten oyun değiştirici oldu. if öncesinde ya çok geniş eşleşiyordunuz (her Bash komutu) ya da filtrelemeyi betiğin içinde yapıyordunuz — ki bu da oldukça dağınık bir çözümdü.

Tüm Claude Code Hook Olayları: Hızlı Başvuru Tablosu

Claude Code, resmi hooks referansında ve Claude Code değişiklik günlüğünde belgelendiği üzere, yaşam döngüsü boyunca 20'den fazla hook olayı sunar. En yaygın kullanılanlar PreToolUse, PostToolUse, Notification ve Stop'tur — ancak ConfigChange ve FileChanged gibi yeni olaylar ileri düzey otomasyon kalıpları açar.

İşte tam başvuru tablosu:

İpucu: Hooks'larınızın yüzde sekseninde PreToolUse ve PostToolUse kullanacaksınız. Bir sonraki en kullanışlı olan SessionStart — her oturumun başında Claude'un ihtiyaç duyduğu proje bağlamını eklemek için mükemmel.

4 Claude Code Hook Türü Açıklandı

Claude Code dört hook işleyici türü destekler: command hooks kabuk betikleri çalıştırır, HTTP hooks URL'lere POST gönderir, prompt hooks Claude'a evet/hayır sorusu sorar ve agent hooks araç erişimiyle bir alt ajan başlatır. Deneyimimize göre command hooks kullanım durumlarının yüzde doksanını karşılar. Harici entegrasyonlar için HTTP, nüanslı kararlar için prompt ve agent hooks kullanın.

Command Hooks (İş Atı)

Command hooks bir kabuk komutu çalıştırır ve sonucu belirlemek için çıkış kodunu kullanır. Olayın JSON verisini stdin üzerinden alırlar.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

Biçimlendirme, dosya koruma, bildirimler ve çoğu otomasyon için kullanacağınız şey budur. Hızlı, basit ve öngörülebilir.

HTTP Hooks (Harici Entegrasyonlar)

HTTP hooks, gövde olarak olay JSON'ıyla bir URL'ye POST isteği gönderir. Yanıt durum kodu sonucu belirler (200 = devam, 403 = engelle).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Slack, Discord, PagerDuty veya özel bir panoya olay göndermek için harika. Bunu aynı zamanda bir araç çalışmasına izin vermeden önce harici bir politika motorunu sorgulamak için de kullanabilirsiniz.

Prompt Hooks (Yapay Zeka Destekli Kararlar)

Prompt hooks, olay verisini tek turlu bir evet/hayır değerlendirmesi için Claude'un kendisine iletir. Claude, "decision": "allow" veya "decision": "block" içeren bir JSON yanıtı ve gerekçe döndürür.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

Bunları tutumlu kullanın. Her hook çalışmasında tam bir LLM çağrısı yapıldığından gecikme ve maliyet eklerler. Ama "bu veritabanı geçişi yıkıcı görünüyor mu?" gibi gerçekten öznel güvenlik kontrolleri için zor geçilirler. Claude Code model değiştirmeyi merak ediyorsanız, prompt hooks için kullanılan model mevcut oturum modelinizi takip eder.

Agent Hooks (Araç Destekli Doğrulama)

Agent hooks, Read, Grep ve Glob araçlarına erişimi olan bir alt ajan başlatır. Alt ajan, kararını vermeden önce dosyaları inceleyebilir.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

Bu en güçlü hook türüdür, ama aynı zamanda en yavaşı. İyi bir karar vermek için dosya bağlamına ihtiyaç duyduğunuz yüksek riskli kontroller için ayırın.

7 Üretime Hazır Claude Code Hook Örneği (Kopyalayıp Yapıştırmaya Hazır)

En kullanışlı Claude Code hooks şunları içerir: dosya düzenlemelerinde Prettier veya Black ile otomatik biçimlendirme, korunan dosyalara yazmaları engelleme, görev tamamlandığında masaüstü bildirimleri gönderme, oturum başlangıcında proje bağlamı ekleme, kod değişikliklerinden sonra testleri çalıştırma, dal korumayı zorunlu kılma ve tüm araç kullanımını denetleme. Son üç aydır bu örneklerin çeşitlemelerini her projede çalıştırıyorum.

Aşağıdaki her örnek .claude/settings.json'ınıza doğrudan ekleyebileceğiniz eksiksiz bir settings.json parçacığıdır. awesome-claude-code gibi topluluk koleksiyonlarında daha fazla kalıp bulunuyor.

1. Kaydetme Sırasında Otomatik Biçimlendirme

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

Bu, her Write veya Edit işleminden sonra tetiklenir, stdin JSON'ından dosya yolunu çıkarır ve uygun biçimlendiriciyi çalıştırır. Sondaki exit 0, hook'un asla engellemeyeceğini garantiler — biçimlendirme hataları Claude'u durdurmamalıdır.

İpucu: Farklı dillerde çalışıyorsanız *.go için gofmt ve *.rs için rustfmt ekleyin.

2. Korunan Dosyalara Yazmaları Engelle

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

Çıkış kodu 2 eylemi engeller ve JSON mesajını Claude'a gönderir. Claude geri bildirimi görür ve ayarlama yapar — genellikle dosyayı değiştirmek istediğini söyler ve sizden manuel olarak yapmanızı ister. if alanı, bunun her tek Write'ta tetiklenmesini önler.

3. Tamamlandığında Masaüstü Bildirimi

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

macOS (osascript) ve Linux (notify-send) üzerinde çalışır. Boş eşleştirici, tüm bildirimlerde tetikleneceği anlamına gelir. Uzun bir görev başlatıp başka bir pencereye geçtiğinizde bu gerçekten işe yarar.

4. Oturum Başlangıcında Bağlam Ekleme

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

Mevcut proje adını, Git dalını ve son commit'i her oturuma ekler. Claude bu bağlamı otomatik olarak alır — hangi dalda çalıştığınızı söylemenize gerek kalmaz.

5. Kod Değişikliklerinden Sonra Otomatik Test Çalıştırma

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

Eşleşen bir test dosyası varsa, Claude kaynağı düzenledikten sonra otomatik olarak çalışır. tail -5 çıktıyı özlü tutar ve zaman aşımı kaçak test paketlerini önler. Bu, yapay zeka destekli kod inceleme iş akışıyla iyi uyum sağlar.

6. Dal Koruma Zorunluluğu (Gelişmiş)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

main, master veya production dallarını hedef alan her git push'u engeller. Claude geri bildirimi alır ve bunun yerine bir özellik dalı oluşturmayı önerir.

7. Güvenlik Denetim Kaydı (Gelişmiş)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Claude'un çalıştırdığı her Bash komutunu UTC zaman damgasıyla bir denetim dosyasına kaydeder. Güvenlik incelemeleri ve Claude'un bir oturum sırasında gerçekte ne yaptığını anlamak için son derece değerlidir. .claude/audit.log'u .gitignore'unuza eklemeyi unutmayın.

Hooks ile MCP, Skills ve CLAUDE.md Karşılaştırması: Ne Zaman Hangisini Kullanmalı

Deterministik otomasyon için hooks kullanın — her zaman çalışması gereken şeyler (biçimlendirme, engelleme, bildirimler). Claude'a harici araçlara ve verilere erişim vermek için MCP kullanın. Yeniden kullanılabilir prompt paketleri için Skills kullanın. Davranış rehberliği ve proje bağlamı için CLAUDE.md kullanın. Hooks garantilidir; diğer her şey olasılıksaldır. Bu en önemli ayrımdır ve ekiplere tavsiye verirken sürekli buna dönüyorum.

Karar Matrisi

MCP'ye derinlemesine bakmak için MCP rehberimize göz atın. Cursor'dan geliyorsanız, Cursor'un kurallar sistemi CLAUDE.md'ye kabaca benzerdir — ama Cursor'da hooks gibi bir şey yoktur.

Çakıştıklarında (ve Nasıl Seçilir)

Kullandığım akış şeması şu şekilde:

• "Bunun istisnasız her seferinde gerçekleşmesi mi gerekiyor?" — Hook. Kodu biçimlendir, korunan dosyaları engelle, bildirimler gönder. Sıfır belirsizlik.
• "Claude'un sahip olmadığı yeni bir YETENEK mi gerekiyor?" — MCP sunucusu. Veritabanına eriş, API çağır, harici belgeleri ara.
• "Belirli bir iş akışı için yeniden kullanılabilir TALİMATLAR mı istiyorum?" — Skill (slash komutu). Kod inceleme şablonları, dağıtım kontrol listeleri.
• "Claude'un bu projedeki DAVRANIŞINI şekillendirmek mi istiyorum?" — CLAUDE.md. Kodlama standartları, mimari kararlar, tercih edilen kütüphaneler.

Sınırı netleştiren gerçek örnekler:

• "Prettier ile her zaman biçimlendir" = Hook (her seferinde gerçekleşmeli)
• CLAUDE.md'de "biçimlendirme için Prettier kullan" = Rehber (Claude unutabilir)
• "Şirket belgelerimizi ara" = MCP (yeni yetenek)
• "Kodu incelerken stil rehberimizi takip et" = Skill veya CLAUDE.md

Anthropic'in eklentiler duyurusunda belirtildiği üzere, hooks MCP ve Skills'i de içeren daha geniş bir eklenti ekosisteminin parçasıdır. Birbirleriyle rekabet etmek için değil, tamamlamak için tasarlanmışlardır.

Başlangıç Kiti: Her Proje İçin Hazır Claude Code Hooks Yapılandırması

Claude Code için bir başlangıç hooks yapılandırması şunları içermelidir: dosya düzenlemesinde otomatik biçimlendirme, görev tamamlandığında bildirim, hassas dosyalar için dosya koruma, oturum bağlamı ekleme ve temizlik için stop hook. Bu tam olarak her yeni projeye eklediğim yapılandırma — yığına göre uyarlıyorum ama yapı aynı kalıyor.

Yapılandırma

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

Yığınınıza Göre Nasıl Özelleştirirsiniz

Yığınınıza uygun biçimlendirme ve test komutlarını yukarıdaki yapılandırmada değiştirin. Yapı aynı kalır.

Hooks'larınızın Çalıştığını Doğrulama

Hooks'ların etkin olduğunu doğrulamanın üç yolu:

1. /hooks komutu — Claude Code'da /hooks yazın; tüm kayıtlı hooks'ları, eşleştiricilerini ve durumlarını görün.
2. Transkript incelemesi — Bir hook tetiklendikten sonra oturum transkripsiyonunu kontrol edin. Hook çalışmaları, çıktıları ve çıkış kodlarıyla birlikte görünür.
3. Hızlı geçiş — Yapılandırmayı silmeden tüm hooks'ları geçici olarak devre dışı bırakmak için settings.json'a "disableAllHooks": true ekleyin. Yeniden etkinleştirmek için kaldırın (veya false olarak ayarlayın).

CI/CD Entegrasyonu: Headless Modda Claude Code Hooks

Claude Code hooks, bazı farklılıklarla birlikte headless modda (claude -p) çalışır: Notification hooks hâlâ tetiklenir, ancak masaüstü uyarıları yerine kayıt tutmaya yönlendirmelisiniz. Çıkış kodu 2 olan PreToolUse hooks, headless oturumları insan incelemesi için duraklatabilir. GitHub Actions, anthropics/claude-code-action@v1 kullanır ve hooks'larla otomatik iş akışları oluşturur.

Headless Mod Davranışı

Headless moddaki büyük sürpriz: çıkış kodu 2 ile çıkan PreToolUse hooks'ları sessizce başarısız olmaz. Oturumu duraklatır ve --resume ile devam etmenizi sağlar — bu da belirli eylemlerin manuel onay gerektirdiği CI/CD boru hatları için insan-döngüde bir kalıp sunar.

GitHub Actions Entegrasyonu

Resmi GitHub Actions kılavuzunda belgelendiği üzere, Claude Code ile hooks kullanan minimal bir GitHub Actions iş akışı şöyle görünür:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.claude/settings.json hooks'larınız depoyla birlikte gelir, bu nedenle CI'da yerel ortamla tamamen aynı şekilde çalışırlar. Masaüstüne özgü araçlara (örn. osascript) dayanan hooks'ların geri dönüşleri veya koşulları olduğundan emin olun.

Ekip Hook Yönetimi

Ekipler için iyi çalışan bir kalıp:

• .claude/settings.json (commit'lendi) — Ekip paylaşımlı hooks: dosya koruma, biçimlendiriciler, dal koruma. Herkes bunları alır.
• .claude/settings.local.json (gitignore'da) — Kişisel hooks: bildirim tercihleri, özel kayıt, deneysel hooks.
• ~/.claude/settings.json (kullanıcı-global) — Tüm projeler genelinde varsayılanlarınız: bildirim stili, kişisel biçimlendirme tercihleri.

Bu, .editorconfig (commit'lendi) ve yerel IDE ayarlarının (kişisel) nasıl çalıştığını yansıtır. Angelo Lima'nın CI/CD kılavuzunda belirtildiği üzere, paylaşılan hooks'ları standartlaştıran ekipler Claude Code'da daha az "bende çalışıyor" sorunu yaşar.

Claude Code Hooks Sorunlarını Giderme ve Yaygın Hatalar

Yaygın Claude Code hooks sorunları şunları içerir: hooks'ların tetiklenmemesi (eşleştirici yazımını ve settings.json konumunu kontrol edin), hooks'ların çalışmasına rağmen engellememesi (yanlış çıkış kodu — 1 değil 2 kullanın), sonsuz döngüler (Stop hook'unun kendini tetiklemesi) ve yavaş başlangıç (çok fazla eşzamanlı hook). Gördüğüm en yaygın hata çıkış kodu karışıklığıdır — geliştiriciler exit 2 yerine exit 1 kullanıyor.

Hook Tetiklenmiyor

Belirtiler: Bir hook eklediniz ama olay gerçekleştiğinde hiçbir şey olmuyor.

Çözümler:

• Eşleştirici yazım hatası — Eşleştiriciler büyük/küçük harfe duyarlıdır. "write", Write aracıyla eşleşmez. Tam araç adlarını /hooks ile kontrol edin.
• Yanlış ayar dosyası — ~/.claude/settings.json'daki hooks, proje kapsamı için /hooks çıktısında görünmez. Proje kök dizininde .claude/settings.json deneyin.
• JSON sözdizimi hatası — Fazladan bir virgül veya eksik parantez, tüm hooks yapılandırmasını sessizce devre dışı bırakır. settings.json'ınızı doğrulamak için jq . üzerinden çalıştırın.
• disableAllHooks: true — Birinin (veya önceki bir hata ayıklama oturumunun) bu bayrağı açık bırakıp bırakmadığını kontrol edin.

Hook Çalışıyor Ama Engellemiyor

Belirtiler: PreToolUse hook'unuz çalışıyor, ancak eylem yine de devam ediyor.

Çözümler:

• Yanlış çıkış kodu — Çıkış kodu 1 "hata" anlamına gelir (hook başarısız), "engelle" değil. Bir eylemi engellemek için exit 2 kullanın. Resmi belgede belirtildiği üzere bu neredeyse herkesi yanıltır.
• Eksik stdout JSON — Engelleme hooks'ları için, Claude'un eylemin neden engellendiğini bilmesi amacıyla bir JSON mesajı çıktısı verin: echo '{"message": "Blocked: reason"}'

Sonsuz Döngüler

Belirtiler: Claude aynı eylemi sürekli deniyor veya makineniz şüphe uyandırıcı şekilde ısınıyor.

Çözümler:

• Stop hook eylemlere yol açıyor — Stop hook'unuz bir dosya yazarsa veya Claude'un yanıt vermesine neden olan bir komut çalıştırırsa döngü oluşturdunuz. Stop hooks yalnızca pasif işlemler yapmalıdır: kayıt tut, bildir, temizle.
• PostToolUse hook düzenlemelere neden oluyor — Bir dosyayı değiştiren bir PostToolUse hook'u başka bir PostToolUse olayını tetikler. Buna karşı belirli eşleştiriciler veya if alanıyla önlem alın.

Performans Sorunları

Belirtiler: Claude başlamak veya araçları çalıştırmak için gözle görülür şekilde daha uzun süre alıyor.

Çözümler:

• Çok fazla SessionStart hook'u — Her biri başlangıçta eşzamanlı olarak çalışır. Bunları hafif tutun (her biri 1 saniyenin altında).
• Yüksek frekanslı yollarda ağır betikler — PreToolUse ve PostToolUse hooks'ları sık sık tetiklenir. Betiğiniz ağ istekleri veya ağır hesaplama yapıyorsa, bir timeout alanı ekleyin (milisaniye cinsinden) ve bunun yerine HTTP hook olması gerekip gerekmediğini düşünün.
• Önbellekleme yok — Aynı şeyi tekrar tekrar kontrol ediyorsanız (örn. "bu korumalı bir dal mı?"), her hook çağrısında Git komutları çalıştırmak yerine sonucu geçici bir dosyada önbelleğe alın.

Sıkça Sorulan Sorular

Claude Code hooks nedir ve nasıl çalışır?

Claude Code hooks, bir Claude Code oturumu sırasında belirli yaşam döngüsü olaylarında çalışan kullanıcı tanımlı otomasyon betikleridir. Bunları bir eşleştirici kalıbı ve bir işleyici (kabuk komutu, HTTP uç noktası, prompt veya ajan) ile settings.json'da yapılandırırsınız. Eşleşen olay tetiklendiğinde hook otomatik olarak çalışır ve sonucu kontrol etmek için çıkış kodlarını kullanır.

Claude Code settings.json'da hooks nasıl yapılandırılır?

Üç yapılandırma konumundan herhangi birine bir "hooks" nesnesi ekleyin: ~/.claude/settings.json (kullanıcı-global), .claude/settings.json (proje-paylaşımlı) veya .claude/settings.local.json (proje-kişisel). Her olay türü, matcher, isteğe bağlı if alanı ve type ile command ya da url içeren işleyici nesneleri barındıran bir hooks dizisine sahip hook tanımları dizisiyle eşleşir.

PreToolUse ile PostToolUse hooks arasındaki fark nedir?

PreToolUse bir araç çalışmadan önce tetiklenir ve çıkış kodu 2 ile onu engelleme gücü verir. PostToolUse çalışma tamamlandıktan sonra tetiklenir; biçimlendirme, test veya kayıt tutma için kullanışlıdır. PreToolUse önleme ve geçit denetimi içindir. PostToolUse doğrulama ve temizlik içindir. Her ikisi de stdin üzerinden JSON olarak araç adını ve girdiyi alır.

Claude Code hooks tehlikeli komutları engelleyebilir mi?

Evet. Çıkış kodu 2 ile PreToolUse hooks herhangi bir araç çalışmasını engeller. Hassas dosyaların yazılmasını koruyabilir, rm -rf veya git push main gibi tehlikeli kalıplarla eşleşen kabuk komutlarını engelleyebilir ve prodüksiyon veritabanlarına erişimi önleyebilirsiniz. Engelleme mesajı geri bildirim olarak Claude'a gönderilir; böylece Claude yaklaşımını ayarlayabilir.

Claude Code'da hangi hook olayları mevcuttur?

Claude Code 15'ten fazla olay sunar: araç çalışması için PreToolUse ve PostToolUse, uyarılar için Notification, oturum sonu için Stop, başlatma için SessionStart, girdi filtreleme için UserPromptSubmit, bağlam yönetimi için PreCompact ve PostCompact ve ConfigChange, FileChanged, TaskCreated ile PermissionDenied gibi yeni olaylar. Tam başvuru tablosunu yukarıdaki hook olayları bölümünde görebilirsiniz.

Hooks, MCP araçlarından ve Skills'den nasıl farklıdır?

Hooks deterministiktir — Claude'un ne karar verdiğinden bağımsız olarak eşleşen olaylarda her zaman tetiklenir. MCP araçları Claude'un yeteneklerini genişletir (veritabanı erişimi, API çağrıları) ama Claude ne zaman kullanacağına kendisi karar verir. Skills, slash komutlarıyla çağrılan yeniden kullanılabilir talimat paketleridir. CLAUDE.md davranışsal rehberlik sağlar. Bir şeyin her seferinde gerçekleşmesi gerektiğinde hooks, Claude'un yeni yeteneklere ihtiyaç duyduğunda MCP kullanın.

Claude Code hooks headless modda çalışır mı?

Evet, bazı çekinceleriyle birlikte. Hooks headless modda (claude -p) normal şekilde tetiklenir, ancak macOS bildirimleri gibi masaüstüne özgü hooks'ların geri dönüşlere ihtiyacı vardır. Önemli olarak, çıkış kodu 2 ile çıkan PreToolUse hooks'ları headless oturumları --resume aracılığıyla insan onayı için duraklatabilir. Bu, belirli eylemlerin manuel onay gerektirdiği CI/CD boru hatlarında insan-döngüde bir kalıp sağlar.

Kaç hook çok fazladır? Hooks Claude Code'u yavaşlatır mı?

Katı bir sınır yoktur, ancak her eşzamanlı hook gecikme ekler. SessionStart hooks'ları başlangıçta çalışır, bu nedenle hızlı tutun (her biri 1 saniyenin altında). PreToolUse ve PostToolUse hooks'ları eşleşen her araç çağrısında tetiklenir — ağır betikler burada hızla birikir. Toplam hook sayısını 10-15 altında tutmayı, kapsamı daraltmak için if alanını kullanmayı ve kaçak betikleri önlemek için timeout değerleri eklemeyi öneririm.

Prettier veya Black ile kodu otomatik biçimlendirmek için hooks kullanabilir miyim?

Evet — bu en popüler hook kullanım durumudur. Write|Edit ile eşleşen bir PostToolUse hook'u oluşturun, stdin JSON'ından dosya yolunu çıkarın ve dosya uzantısına göre uygun biçimlendiriciyi çalıştırın. TypeScript, JavaScript ve Python dosyalarını işleyen eksiksiz, kopyalayıp yapıştırmaya hazır bir yapılandırma için yukarıdaki üretim örnekleri bölümündeki birinci örneğe bakın.

Claude Code hooks güvenli midir? Güvenlik riskleri nelerdir?

Hooks tam kullanıcı izinlerinizle çalışır — sandbox yok. Kötü amaçlı bir hook SSH anahtarlarınızı okuyabilir, dosyaları silebilir veya veri sızdırabilir. Yalnızca güvenilen kaynaklardan hooks kullanın, projenize kabul etmeden önce paylaşılan .claude/settings.json'ları gözden geçirin ve paylaşılmaması gereken kişisel hooks için .claude/settings.local.json kullanın. Daha geniş yapay zeka güvenlik kalıpları için LLM guardrails rehberimize bakın.