Hooks ve izin modları

CLAUDE.md'ye "her değişiklikten sonra testleri çalıştır" yazdınız, ajan yine de bazen atlıyor. Bu bir hata değil. Kural dosyası modele bağlam olarak gider ve uyulması garanti değildir (bkz. Prompt ve context engineering). Her seferinde, istisnasız olması gereken bir şey için hook kullanılır.¹

Hook nedir?

Hook, ajanın çalışmasındaki belirli anlarda otomatik çalışan bir shell komutudur.² Ajan bir dosyayı düzenledikten sonra, bir komutu çalıştırmadan önce ya da işi bitirdiğini söylediğinde devreye girer. Model karar vermez, komut her seferinde çalışır.²

Frontend'de en çok işe yarayan üç an:

İki araçta da hook'lar proje klasörüne yazılır ve repoya commit edilebilir: Claude Code'da .claude/settings.json, Cursor'da .cursor/hooks.json.²³ Böylece takımdaki herkesin ajanı aynı kurallarla çalışır.

Her düzenlemeden sonra formatla

Ajanın yazdığı kodu format kurallarınıza uydurmak için PostToolUse kullanın. matcher, hook'un yalnızca dosya düzenleyen araçlardan sonra çalışmasını sağlar:²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Hook çalışırken olayın bilgisi komuta stdin'den JSON olarak gelir. Düzenlenen dosyanın yolu tool_input.file_path alanındadır, jq onu çekip Prettier'a verir.² Aynı yerde npx eslint --fix de çalıştırabilirsiniz.

Tehlikeli işlemi engelle

PreToolUse hook'u araç çalışmadan önce devreye girer ve işlemi durdurabilir. Kural basittir: script çıkış kodu 2 ile biterse işlem engellenir ve stderr'e yazdığınız mesaj ajana geri bildirim olarak gider.² Ajan nedenini okur ve başka bir yol dener.

#!/bin/bash
# .claude/hooks/protect-files.sh
FILE_PATH=$(jq -r '.tool_input.file_path // empty')

for pattern in ".env" "pnpm-lock.yaml" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH is protected" >&2
    exit 2
  fi
done

exit 0

Script'i chmod +x ile çalıştırılabilir yapın ve PreToolUse altında Edit|Write matcher'ıyla kaydedin.² Çıkış kodu 0 işlemi onaylamaz, yalnızca itiraz etmez. Normal izin akışı yine çalışır.²

Testler geçmeden bitirtme

Stop hook'u ajan cevabını bitirdiğinde çalışır. Çıkış kodu 2 burada "henüz bitmedi" demektir: ajan durmaz ve stderr'deki mesajla çalışmaya devam eder.¹² Böylece "testler geçene kadar düzelt" bir rica olmaktan çıkar, kural olur:

#!/bin/bash
# .claude/hooks/require-tests.sh
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

if ! OUTPUT=$(pnpm test --run 2>&1); then
  echo "Tests are failing. Fix them before finishing:" >&2
  echo "$OUTPUT" | tail -n 30 >&2
  exit 2
fi

stop_hook_active kontrolü sonsuz döngüyü önler. Claude Code, bir Stop hook'u arka arkaya sekiz kez engellerse onu yok sayar.²

İzin modları

Hook'lar kuralı zorlar. İzin modları ise ajanın ne kadar sormadan çalışacağını belirler. Claude Code'da Shift+Tab ile modlar arasında geçersiniz:⁴

Sürekli onay vermek yorucudur. Onuncu onaydan sonra okumadan tıklamaya başlarsınız.¹ Bunun yerine güvendiğiniz komutlara önceden izin verin, tehlikeli olanları yasaklayın:⁴⁵

{
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Bash(rm -rf *)", "Read(./.env)"]
  }
}

deny kuralları her modda geçerlidir, bypassPermissions dahil.⁴ Bir PreToolUse hook'unun engellemesi de modu değiştirerek aşılamaz.²

Ne zaman hangisi

Kural dosyanızdaki bir satıra ajan sürekli uymuyorsa ve satır gerçekten şartsa, onu hook'a taşıyın.¹

Kendin dene

• Prettier hook'unu ekleyin ve ajandan tek tırnaklı string içeren bir dosya yazmasını isteyin. Dosya kaydedildiğinde tırnaklar ne oluyor?

• .env koruma hook'unu ekleyip ajana ".env'e bir yorum satırı ekle" deyin. Ajan engellenince ne yapıyor?

• Bir testi kasıtlı olarak bozun ve Stop hook'unu açın. Ajan kaç turda testi düzeltip duruyor?

• Claude Code'da /hooks komutunu çalıştırın. Hangi hook'lar hangi olaya bağlı görünüyor?

Detaylı öğrenmek için

• Resmi doküman: Claude Code "Automate actions with hooks"; tüm olaylar, matcher'lar, prompt tabanlı hook'lar ve sık hatalar.²

• Resmi doküman: Cursor "Hooks"; olay listesi, permission çıktısı ve takım hook'ları.³

• Resmi doküman: Claude Code "Permission modes"; her modun ayrıntısı ve auto modun nasıl karar verdiği.⁴