Hook Çalışmıyor ya da Engel Oluyor

Hook zaten ayarlı, /hooks komutu onu gösteriyor, ama sonra işler tuhaflaşıyor. Bir istek gönderiyorsunuz, ama requests.log içinde yeni bir satır belirmiyor. Ya da iki kere beliriyor. Bazen daha kötüsü oluyor: her değişiklikten sonra otomatik bir eylem çalışıyor ve olağan işe engel olmaya başlıyor.

Böyle bir durumda tüm ayarı baştan kurmaya gerek yok. Gözlemi küçük, test edilebilir bir göreve dönüştürmek daha işe yarar: hook'u ne tetiklemeli, hangi iz kalmalı ve hangi durumu mutlaka atlamalı. Böylece Claude Code belirli dosyaları kontrol edebilir ve minimal bir düzeltme önerebilir.

Hook Ne Zaman Tetiklenmeli

Bu yazıda ayar dosyalarındaki komut hook'larını ele alıyoruz. Böyle bir hook'ta önemli olan üç parça var: olay, tetikleme koşulu ve işleyici. Olay "ne zaman bakılmalı" sorusunu yanıtlar, koşul uygun durumları daraltır, işleyici de eylemi gerçekleştirir.

Örneğin istek günlüğü UserPromptSubmit olayına bağlıdır. Bu olay, oturuma bir istek geldiğinde, model onu işlemeden önce tetiklenir. Çoğu zaman bu sizin isteğinizdir, ama Claude Code onu kendi başlattığı adımlarda da çalıştırır: /loop'un bir sonraki turu, arka plandaki bir subagent'ın raporu. Bu yüzden günlükteki yeni bir satır çok az şey doğrular - hook isteği aldı ve kaydetti, o kadar. Ajanın görevi doğru yapıp yapmadığını bu satırdan öğrenemezsiniz.

UserPromptSubmit'in matcher'ı yoktur. Günlüğe yalnızca bazı istekler gerekiyorsa, bunları işleyicinin kendisi ayıklar. Araç olaylarında durum farklıdır. Örneğin Edit|Write matcher'ı araçları seçer, dosya yolu ise çağrının kendi verisinden ayrıca kontrol edilir. Bir araç adı taşıyan matcher "yalnızca src içindeki dosyalar" anlamına gelmez.

Düzeltmeye başlamadan önce iki kısa senaryo yazın:

• istenen: bir test isteği gönderip requests.log içinde bir yeni satır görmek;
• gereksiz: normal bir editörde dosyayı açıp Claude Code'a yeni bir istek göndermeden günlüğün değişmediğinden emin olmak. Tüm isteklerin günlüğe yazıldığı bir durumda, gönderilen ikinci prompt da bir kayıt vermelidir; yani o negatif kontrol olarak işe yaramaz.

Bunlar test kriterleridir. Claude Code'un vereceği kesin yanıtı önceden tahmin etmeye gerek yok.

Kayıt Belirmedi

Gözlemin beklentiden ayrıldığı noktadan başlayın. Günlük için bu, test isteğinden sonra yeni satırın olmamasıdır. Oradan ayardan eyleme doğru ilerleyin:

1. Etkileşimli bir Claude Code oturumunda /hooks yazın ve gereken kaydın yüklenip yüklenmediğini kontrol edin. Bu menüyü siz açarsınız; gördüklerinizi ajana aktarın.
2. Olayı karşılaştırın. İstek günlüğü UserPromptSubmit'e tepki vermeli, dosya değişikliğinden sonraki bir eylem ise genellikle bir araç olayına bağlanır.
3. Hook'un kaynaklandığı ayar dosyasını bulun. Bu bir kullanıcı, proje ya da yerel ayar olabilir; yalnızca adları değil, tam komutları da karşılaştırın. Aynı işleyicinin birden fazla ayar dosyasında görünmesi tek başına iki çalıştırma anlamına gelmez.
4. İşleyicinin komutunu kontrol edin: dosya var mı, komut işletim sisteminize uyuyor mu, boşluklu bir yol bozulmuş mu?
5. Sonucun nereye düştüğünü kontrol edin. Göreli bir yol, sürecin çalışma dizinine bağlıdır, dolayısıyla işleyici dosyayı aradığınız yerden başka bir yere yazmış olabilir.

Buradaki asıl yol ajan üzerinden geçer. Ona gözlemi, /hooks kontrolünün sonucunu ve düzeltmenin sınırlarını verin:

UserPromptSubmit hook'u /hooks içinde görünüyor, ama test isteğinden
sonra requests.log'da yeni bir satır yok.

Kaynak ayarı ve işleyiciyi bul. Olayı, komutun yolunu, çalışma dizinini
ve günlük klasörünün oluşturulup oluşturulmadığını kontrol et. Nedeni
göster ve minimal bir düzeltme yap. Diğer hook'ları ve ayarları olduğu
gibi bırak. Düzeltmeden sonra istenen ve olumsuz kontrol senaryolarını
tarif et.

Örneğin ajan şunu buldu: işleyici logs/requests.log dosyasına yazıyor, ama logs/ klasörü yok ve betik onu oluşturmuyor. Minimal düzeltme, bu klasörü yazmadan önce oluşturmaktan ibaret. Sonrasında tam olarak logs/requests.log'u kontrol edin: bir test isteği bir kayıt eklemeli. Bu, olası bir nedenin örneğidir, her boş günlük için geçerli bir tanı değil.

Ayar dosyada varsa ama /hooks'ta yoksa, neden JSON sözdiziminde, ayarın kapsamında ya da hook'ların şu an hiç çalışmamasında olabilir: proje klasörü güvenilir olarak işaretlenmemiştir, disableAllHooks açıktır ya da yönetici yalnızca yönetilen politikadaki hook'lara izin vermiştir. Farklı ayar dosyalarındaki hook'lar birbirinin yerine geçmez, toplanır. Kayıt yüklendiyse ama iz yoksa, dikkat komuta, girdi verisine ve çıktı yoluna kayar.

Yol ayrımının anlamı basit: Claude Code kaydı yüklemediği sürece betiğin işleyişini incelemek henüz erken. Kayıt göründüğünde konfigürasyon zaten uygulamaya ulaşmıştır ve işleyicinin çalıştırılmasını, girdi JSON'unu ve sonucun beklendiği yeri kontrol etmek daha işe yarar.

İşleyici Hatayla Sonlandı

Bir komut hook'u JSON'u standart girişten alır. İçinde olayın ortak alanları ve o olaya özgü veriler bulunur. UserPromptSubmit için isteğin metni prompt alanında gelir. Bu metin veri olarak okunmalıdır. Onu bir shell komutuna yapıştırıp çalıştırmak olmaz: bir test isteği tırnak işareti, satır sonu ve her türlü sıradan metin içerebilir.

Claude Code'dan işleyicinin çalışmasını uydurma bir girdiyle yeniden üretmesini isteyin. İstekte önemli durumları hemen belirtin:

Hook işleyicisini oturumdan ayrı olarak, uydurma bir JSON ile test et.
Şu durumlar gerekli: normal ve çok satırlı prompt, boşluklu proje yolu,
eksik günlük klasörü ve hatalı girdi.

Prompt metnini kod olarak çalıştırma. Çalıştırma komutunu, çıkış kodunu,
stderr'i ve test dosyasındaki gerçek değişikliği göster. Asıl günlüğe
dokunma.

Çıkış kodu, işleyicinin kendisine ne olduğunu anlamaya yardımcı olur, ama anlamı olaya bağlıdır. exit 0, hook komutunun hatasız tamamlandığını söyler. Bu, görevin tamamının sonucunu doğrulamaz. exit 2, "öncesi" olaylarında eylemi engelleyebilir, ama zaten çalıştırılmış bir araçtan sonra onun işini geri almaz. Bu yüzden exit 2 içeren tek bir reçete olaylar arasında körlemesine taşınamaz.

Ayrı çalıştırma başarılıysa ama hook oturumda hâlâ sessizse, Claude Code'u proje klasöründen claude --debug-file hook-debug.log komutuyla başlatın ve bir test isteğini tekrarlayın. Ortaya çıkan hook-debug.log dosyasını açın ve olayı, eşleşen hook'ları ve çıkış kodunu bulun. Bu, Claude Code'un kendi günlüğüdür, sizin requests.log'unuzdan ayrıdır. Kontrolden sonra bu tanı oturumunu kapatın; olağan iş için Claude Code'u bayrak olmadan başlatın. Çoğu olayın sıradan stdout'u debug log'a gider ve transcript'te görünmek zorunda değildir. İstisnalar olaya bağlıdır, bu yüzden stdout'taki keyfi tanı satırları kullanışlı bir log olmak yerine bağlamı etkileyebilir.

Hook Fazladan Tetikleniyor

Tek bir istekten sonra iki özdeş satır, hook'un iki kez tanımlandığına işaret edebilir: benzer ama birebir aynı olmayan hook'lar, örneğin hem kullanıcı hem de proje ayarlarında bulunur. Farklı dosyalarda tekrarlanan komut harfiyen aynıysa, yine de yalnızca bir kez çalışır. Bir plugin ya da skill'den gelen kopyalar ayrı sayılır, bu yüzden menüdeki kaynak da önemlidir. Önce ajana /hooks sonucunu verin ve bu olayın kayıtlarını mevcut tüm ayar dosyalarında listelemesini isteyin. Ayarlarda her şey yolundaysa, işleyicinin kendisinin bir çalıştırmada iki kez yazıp yazmadığını kontrol edin. Bulunan ilk satırı silmek için henüz erken.

Bir başka sık neden de fazla geniş bir koşuldur. Diyelim ki hook, src/ içindeki dosyalar değiştikten sonra bir tanı işareti bırakmalı, ama her Edit ve Write kullanımına tepki veriyor. Burada iki seviyeli bir ayıklama gerekir:

• matcher Edit ve Write araçlarını seçer;
• ayrı bir koşul, aracın argümanlarından yolu kontrol eder ve src/ dışındaki her şeyi atlar.

Bir kontrol diğerinin yerini tutmaz. Matcher uygun olmayan araçları eler, ardından argümanlara dayalı koşul yalnızca src/ içindeki yolları bırakır. Tanı işareti yalnızca her iki kontrol de "evet" yanıtı verdiğinde belirir.

Bir ayar parçası şöyle görünebilir:

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "type": "command", "command": "python .claude/hooks/mark-source-edit.py" }
    ]
  }
]

Bu, mevcut bir settings.json içindeki hooks nesnesinin bir elemanıdır, eksiksiz bir JSON belgesi değil. Yol kontrolü işleyicide olmalıdır; buradaki mark-source-edit.py betiği varsayımsal bir örnektir, gövdesi yazıda yoktur. Komut, python'un kullanılabilir olduğunu ve proje kökünden çalıştırıldığını varsayar. Ajan yorumlayıcıyı, kabuğu ve yolu kendi ayarınızda kontrol etmelidir; örneği hazır bir kurulum gibi kopyalamamak gerekir.

Bu parçayı tek bir cümle gibi okumak rahattır:

Zincir yalnızca ayarda tanımlanan şeyi gösterir. "İşaret bırak ya da dosyayı atla" kararını yolu kontrol ettikten sonra işleyicinin kendisi verir. Bu yüzden bir matcher'ın varlığı aracın seçimini doğrular, ama src/ için doğru filtrelemeyi henüz kanıtlamaz.

Bu tabloda Edit ve Write, Claude Code'un araçlarını ifade eder. Bir dosyayı normal editörde elle değiştirmek onları çağırmaz, bu yüzden böyle bir matcher'ı test etmez. Her eylemden önce tanı dosyasının o anki sonunu not edin, sonrasında yalnızca yeni kayıtları karşılaştırın.

Sınır kontrol edilene kadar eylemi zararsız tutun: tetiklendiğine dair tek bir işaret, biçimlendirme, engelleme ya da toplu dosya düzenlemesi olmadan. Önce istenen durumun tam olarak bir kez geçtiğinden ve gereksiz durumun hiç geçmediğinden emin olun.

Fazladan bir çalıştırma her zaman ek iş demektir. Yine de yalnızca bir dosyaya yazan yerel bir komut, kendi başına modele erişmez. prompt ya da agent tipi bir hook farklı çalışır ve modeli kullanır. Burada maliyet konusuna ayrıntılı girmeye gerek yok, bu iki işleyici türünü birbirine karıştırmamak yeterli.

Tepkiyi Nasıl Kapatırsınız

Hook şu an engel oluyorsa, kaynak kaydını bulun ve yalnızca onu ilgili olayın dizisinden silin. Diğer hook'ları yerinde bırakın. Bu, gelecekteki çalıştırmaları kapatmaktır: zaten çalıştırılmış bir komutu geri almaz, değiştirilmiş dosyaları eski haline getirmez ve günlüğe girmiş satırları silmez.

Geri getirmeyi düşünüyorsanız, silmeden önce seçilen kaydın bir kopyasını saklayın. Değişiklikten sonra /hooks'u yeniden açın ve bu kaydın artık orada olmadığından emin olun. Menü hâlâ eski ayarı gösteriyorsa, oturumu kapatıp aynı projeden yeni bir oturum açın. Ardından bir kontrol eylemi gerçekleştirin ve günlüğün önceki ve sonraki halini karşılaştırın. Kapatılan hook'tan yeni satır gelmemeli.

Tüm hook'ları geçici olarak kapatmak için "disableAllHooks": true ayarı vardır. Ama bu genel bir anahtardır, tek bir kaydı kapatmanın yolu değildir. Bu ayarın kendisinde dosya öncelikleri işler: proje dosyasındaki "disableAllHooks": false, kullanıcı ayarlarınızdaki true değerini geçersiz kılar. Ayrıca, yönetilen bir organizasyon politikasıyla tanımlanan hook'lar, sıradan bir kullanıcı ya da proje ayarıyla kapatılamaz.

Düzeltmeyi Claude Code'a Nasıl Bırakırsınız

İyi bir görev tanımı gözlemi, beklenen olayı, belirli dosyaları ve değişikliğin sınırını içerir. Ajanın tüm otomasyonu yeniden yazmadan ayarı araştırması için bu yeterlidir:

Bu projedeki hook'u incele.

Gözlem: bir test isteğinden sonra requests.log iki satır alıyor.
/loop ve arka plan subagent'ları bu oturumda çalıştırılmadı.
Beklenti: UserPromptSubmit tam olarak bir satır eklemeli.
/hooks sonucunu ekleyeceğim. Mevcut tüm ayar kaynaklarını ve işleyici
komutunu kontrol et.

Önce nedeni ve değiştirilmesi gereken dosyaları söyle. Sonra minimal
bir düzeltme yap, diğer hook'ları koru ve diff'i göster.
İstenen durumu ve olumsuz durumu test et. Ardından yalnızca bu tepkinin
nasıl kapatılacağını göster.

Sonunda elinizde dört net yanıt olmalı:

• hook'u hangi olay tetikliyor;
• hangi koşul gereksiz durumları atlıyor;
• kaynak ayar ve işleyici nerede duruyor;
• diğerlerine dokunmadan tam olarak bu tepki nasıl kapatılıyor.

Ve kontrol rotasının tamamı: istenen eylem beklenen tek bir iz bırakır, gereksiz eylem hiç iz bırakmaz, işleyici hatası hedefli tanıda görünür, kapatıldıktan sonra yeni bir iz belirmez. Hepsi oldukça sade. Böyle bir hook'u sürdürmek tam da bu yüzden "bazen bir şeyler yapan" bir otomasyondan daha kolaydır.

Davranışı belgelerle karşılaştırmak için resmi hooks referansını ve uygulama kılavuzunu kullanın: arayüz Claude Code ile birlikte değişir.

Davranış, 18 Eylül 2026 tarihinde resmi belgelerle karşılaştırılarak kontrol edilmiştir. Örnekler kontrol sürecini gösterir; burada hazır bir işleyici yoktur. Komutu ve yolları kendi işletim sisteminizde ve kabuğunuzda kontrol edin.