Hook'larda dikkat edilecekler

Hook’lar güçlüdür ama dikkatsiz kullanım sessiz cehennemler üretir. Bu ders pratik tuzakları gösterir.

1. Sonsuz döngü riski

Bir hook bir tool’u tetikleyecek komut çalıştırırsa o tool tekrar hook’u tetikleyebilir. Tipik örnek:

❌ Yanlış:

# PostToolUse: Edit
echo "Edited" >> .audit.log   # bu Write değil ama bazı tool sayılır

Daha kötü:

# PostToolUse: Bash
git add -A && git commit -m "auto"   # commit, dosya değiştirebilir → tekrar PostToolUse

Önlem: hook’larda yan etkilerden kaçın; sadece read + format + report yap. Veya recursion guard ekle:

[[ -n "${CLAUDE_HOOK_DEPTH:-}" ]] && exit 0
export CLAUDE_HOOK_DEPTH=1

2. Yavaş hook’lar

Her edit’ten sonra 3 saniyelik bir lint çalışırsa oturum hissi felç olur. Hedef: PostToolUse hook’ları 500ms altında kalmalı.

Yavaş işler için seçenekler:

• Sadece değişen dosyaya uygula (tüm projeye değil)
• Hook’u arka plana at (& ile fork, ama çıktıyı kaybetme)
• Ağır işi PreCommit veya CI’a bırak, hook’tan çıkar

3. Hook çıktısı: Claude görür mü?

Yere yazılan	Görüldüğü yer
stdout (text)	Sadece sana, terminal’de
stderr (text)	Sana ve Claude’a (özellikle exit 2’de feedback)
stdout (JSON additionalContext)	Claude’ın context’ine enjekte

Bir hatayı Claude’un fark etmesini istiyorsan stderr’e yaz ve gerektiğinde exit 2 ver.

4. Permission ve absolute path

"command": "format.sh"

Bu çalışmaz — Claude’un cwd’sine göre arar. Daima:

"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/format.sh"

Hook script’leri executable olmalı:

chmod +x .claude/scripts/*.sh

Windows’ta chmod gereksiz ama dosya uzantısı PowerShell veya bash’i tetikleyebilmeli.

5. Cross-platform tuzaklar

Sorun	macOS/Linux	Windows
Path separator	/	\ (veya / PowerShell’de)
Shebang	Çalışır	.ps1 veya pwsh -File ile
Env değişkeni	$VAR	$env:VAR (PowerShell)

CLAUDE_PROJECT_DIR her ikisinde de set edilir — kullan.

6. Sessiz fail

Hook script’lerinde:

set -euo pipefail

Yoksa, ortada bir command not found olsa bile script exit 0 dönebilir — hata gizlenir. pipefail cmd | grep ... zincirinde bile gerçek hatayı yakalar.

7. settings.json çakışmaları

Üç seviye (user, project, local) hook’ları birleşir, eşitlemez. Aynı event’e tanımlı tüm hook’lar sırayla çalışır. Çakışma yaşıyorsan:

• .claude/settings.local.json ile geçici override
• Kullanıcı seviyesi hook’larını ~/.claude/settings.json’a koymadan önce proje seviyesinde dene

8. Hook ne için kullanılmamalı?

• “İsteğe bağlı” tavsiyeler → CLAUDE.md’ye yaz
• Konuya özel context → custom command veya @dosya
• Ağır otomasyon (DB migration, deploy) → hook çok dar bir tetik; CI tercih et

Özet

• Recursion’a dikkat: hook → tool → hook
• Hook’u hızlı tut (500ms altı hedef)
• Feedback gerekiyorsa stderr + exit 2
• Daima mutlak path ve chmod +x
• Cross-platform için pwsh -File veya shebang’ı netleştir
• Sessiz fail’i set -euo pipefail ile engelle

Sırada ne var?

Sonraki iki derste gerçek pratik faydalı hook örnekleri vereceğiz — kopyala, yapıştır, adapt et.