Hook işləmir və ya mane olur

Hook artıq tənzimlənib, /hooks əmri onu göstərir, sonra isə qəribə şeylər başlayır. Sorğu göndərirsiniz, amma requests.log-da yeni sətir görünmür. Ya da iki dəfə görünür. Bəzən daha pisi: hər düzəlişdən sonra avtomatik hərəkət işə düşür və adi işə mane olmağa başlayır.

Belə vəziyyətdə bütün tənzimləməni yenidən yığmaq lazım deyil. Müşahidəni kiçik, yoxlanıla bilən tapşırığa çevirmək daha faydalıdır: hook-u nə çağırmalıdır, hansı iz qalmalıdır və hansı halda o işə düşməməlidir. Sonra Claude Code konkret faylları yoxlaya və minimal düzəliş təklif edə bilər.

Hook nə vaxt işə düşməlidir

Bu məqalədə tənzimləmə fayllarındakı command tipli hook-ları araşdırırıq. Belə hook-da üç hissə vacibdir: hadisə, işə düşmə şərti və işləyici. Hadisə "nə vaxt baxmaq lazımdır" sualına cavab verir, şərt uyğun halları daraldır, işləyici hərəkəti icra edir.

Məsələn, sorğu jurnalı UserPromptSubmit-ə abunədir. Bu hadisə sessiyaya sorğu daxil olanda, hələ model onu emal etməzdən əvvəl baş verir. Çox vaxt bu sizin sorğunuzdur, amma Claude Code onu özünün başlatdığı addımlarda da işə salır: /loop-un növbəti dövrəsi, fon subagentinin hesabatı. Ona görə jurnaldakı yeni sətir çox az şeyi təsdiqləyir - hook sorğunu aldı və yazdı, bundan artıq deyil. Agentin tapşırığı düzgün yerinə yetirib-yetirmədiyini bu sətirdən bilmək olmaz.

UserPromptSubmit-in matcher-i yoxdur. Jurnala yalnız bəzi sorğular lazımdırsa, onları işləyicinin özü seçir. Alət hadisələrində vəziyyət başqadır. Məsələn, Edit|Write matcher-i alətləri seçir, fayl yolu isə çağırış məlumatlarına görə ayrıca yoxlanılır. Alət adı ilə matcher "yalnız src-dəki fayllar" demək deyil.

Düzəlişdən əvvəl iki qısa ssenari yazın:

• lazımi: test sorğusu göndərmək və requests.log-da bir yeni sətir görmək;
• artıq: Claude Code-a yeni sorğu göndərmədən faylı adi redaktorda açmaq və jurnalın dəyişmədiyinə əmin olmaq. Bütün sorğuların jurnalı üçün ikinci göndərilən prompt da qeyd yaratmalıdır; bu, mənfi nəzarət olmayacaq.

Bunlar yoxlama meyarlarıdır. Claude Code-un konkret cavabını əvvəlcədən uydurmaq lazım deyil.

Qeyd görünmədi

Müşahidənin gözləntidən fərqləndiyi yerdən başlayın. Jurnal üçün bu, test sorğusundan sonra yeni sətrin olmamasıdır. Sonra tənzimləmədən hərəkətə doğru gedin:

1. Claude Code-un interaktiv sessiyasında /hooks yazın və lazımi qeydin yüklənib-yüklənmədiyini yoxlayın. Bu menyunu siz özünüz açırsınız; baxış nəticəsini agentə ötürün.
2. Hadisəni tutuşdurun. Sorğu jurnalı UserPromptSubmit-ə reaksiya verməlidir, fayl dəyişdikdən sonrakı hərəkət isə adətən alət hadisəsinə bağlanır.
3. Tənzimləmənin mənbə faylını tapın. Bu, istifadəçi, layihə və ya yerli tənzimləmə ola bilər; yalnız adları deyil, tam əmrləri də müqayisə edin. Bir neçə tənzimləmə faylında birdən rast gəlinən eyni işləyici təkbaşına iki dəfə işə düşmə demək deyil.
4. İşləyicinin əmrini yoxlayın: fayl mövcuddurmu, əmr ƏS-nizə uyğundurmu, boşluqlu yol pozulmayıbmı.
5. Nəticənin yerini yoxlayın. Nisbi yol prosesin işçi qovluğundan asılıdır, ona görə işləyici faylı sizin axtardığınız yerə yazmamış ola bilər.

Buradakı əsas yol agentdən keçir. Ona müşahidəni, /hooks yoxlamasının nəticəsini və düzəlişin sərhədlərini ötürün:

UserPromptSubmit hook-u /hooks-da görünür, amma test sorğusundan sonra
requests.log-da yeni sətir yoxdur.

Mənbə tənzimləməsini və işləyicini tap. Hadisəni, əmrin yolunu,
işçi qovluğunu və jurnal üçün kataloq yaradılmasını yoxla. Səbəbi göstər
və minimal düzəliş et. Qalan hook-ları və tənzimləmələri saxla.
Düzəlişdən sonra lazımi və mənfi nəzarət ssenarilərini təsvir et.

Məsələn, agent bunu aşkar etdi: işləyici logs/requests.log-a yazır, amma logs/ qovluğu yoxdur və skript onu yaratmır. Minimal düzəliş yazıdan əvvəl bu qovluğun yaradılmasına aiddir. Ondan sonra məhz logs/requests.log-u yoxlayın: bir test sorğusu bir qeyd əlavə etməlidir. Bu, mümkün səbəbin nümunəsidir, hər hansı boş jurnalın diaqnozu deyil.

Tənzimləmə faylda varsa, amma /hooks-da yoxdursa, səbəb JSON sintaksisində, tənzimləmənin əhatə dairəsində və ya hook-ların hazırda ümumiyyətlə işə düşməməsində ola bilər: layihə qovluğu etibarlı kimi qeyd olunmayıb, disableAllHooks aktivdir və ya administrator yalnız idarə olunan siyasətdəki hook-lara icazə verib. Müxtəlif tənzimləmə fayllarındakı hook-lar bir-birini əvəz etmir, toplanır. Qeyd yüklənibsə, amma iz yoxdursa, diqqət əmrə, giriş məlumatlarına və nəticə yoluna keçir.

Bu yol ayrıcının mənası sadədir: Claude Code qeydi yükləməyənə qədər skriptin işini araşdırmaq tezdir. Qeyd görünəndə konfiqurasiya artıq tətbiqə çatıb və işləyicinin işə düşməsini, giriş JSON-unu və nəticənin görünməli olduğu yeri yoxlamaq daha faydalıdır.

İşləyici xəta ilə bitdi

Command tipli hook JSON-u standart giriş vasitəsilə alır. Orada hadisənin ümumi sahələri və konkret hadisənin məlumatları var. UserPromptSubmit üçün sorğu mətni prompt sahəsinə gəlir. Bu mətni məlumat kimi oxumaq lazımdır. Onu shell-əmri ilə birləşdirib icra etmək olmaz: test sorğusu dırnaq işarələri, sətir keçidləri və istənilən adi mətn saxlaya bilər.

Claude Code-dan işləyicinin işə salınmasını uydurma girişdə təkrarlamağı xahiş edin. Sorğuda vacib halları dərhal göstərin:

Hook işləyicisini sessiyadan ayrı, uydurma JSON-da yoxla.
Bu hallar lazımdır: adi və çoxsətirli prompt, boşluqlu layihə yolu,
olmayan jurnal kataloqu və yanlış giriş.

Prompt mətnini kod kimi icra etmə. İşə salma əmrini, çıxış kodunu,
stderr-i və test faylının faktiki dəyişməsini göstər. İşçi jurnalı dəyişmə.

Çıxış kodu işləyicinin özünün necə bitdiyini anlamağa kömək edir, amma mənası hadisədən asılıdır. exit 0 hook əmrinin xətasız bitdiyini bildirir. Bu, bütün tapşırığın nəticəsini təsdiqləmir. exit 2 hərəkətdən əvvəl baş verən hadisələrdə onu bloklaya bilər, alət icra olunduqdan sonra isə artıq onun işini ləğv etmir. Ona görə exit 2 ilə bir resepti hadisələr arasında kor-koranə köçürmək olmaz.

Ayrıca işə salma uğurludursa, sessiyada isə hook hələ də susursa, layihə qovluğundan Claude Code-u claude --debug-file hook-debug.log əmri ilə işə salın və bir test sorğusunu təkrarlayın. Yaranan hook-debug.log faylını açın və hadisəni, uyğun gələn hook-ları və çıxış kodunu tapın. Bu, Claude Code-un öz jurnalıdır, sizin requests.log-unuzdan ayrıdır. Yoxlamadan sonra bu diaqnostika sessiyasını bitirin; adi iş üçün Claude Code-u flaqsız işə salın. Əksər hadisələrin adi stdout-u debug jurnalına gedir və transcript-də mütləq görünmür. İstisnalar hadisədən asılıdır, ona görə stdout-dakı ixtiyari diaqnostika sətirləri rahat jurnal olmaq əvəzinə kontekstə təsir edə bilər.

Hook artıq dəfə işə düşür

Bir sorğudan sonra iki eyni sətir təkrar qeydiyyata işarə edə bilər: oxşar, amma tam eyni olmayan hook-lar, məsələn, istifadəçi və layihə tənzimləmələrində yerləşir. Bu, hərfi mənada eyni əmrdirsə, sadəcə müxtəlif fayllarda təkrarlanıbsa, o, hər halda bir dəfə işə düşəcək. Plugin və ya skill-dən gələn kopiyalar ayrıca nəzərə alınır, ona görə menyudakı mənbə də vacibdir. Əvvəlcə agentə /hooks nəticəsini ötürün və bu hadisənin qeydlərini bütün mövcud tənzimləmə fayllarında sadalamağı xahiş edin. Tənzimləmələrdə hər şey qaydasındadırsa, işləyicinin özünün bir işə salma üçün iki dəfə yazmadığını yoxlayın. Tapılan birinci sətri silmək tezdir.

Başqa tez-tez rast gəlinən səbəb - həddindən artıq geniş şərtdir. Tutaq ki, hook src/-dəki faylları dəyişdikdən sonra diaqnostika işarəsi qoymalıdır, amma hər Edit və Write istifadəsinə reaksiya verir. Burada iki səviyyəli seçim lazımdır:

• matcher Edit və Write alətlərini seçir;
• ayrıca şərt alətin arqumentlərindən yolu yoxlayır və src/-dən kənar hər şeyi nəzərə almır.

Bir yoxlama digərini əvəz etmir. Matcher uyğun olmayan alətləri kənarlaşdırır, sonra arqumentlər üzrə şərt yalnız src/-dən olan yolları saxlayır. Diaqnostika işarəsi yalnız hər iki yoxlama "bəli" cavabı verdikdə görünür.

Tənzimləmə fraqmenti belə görünə bilər:

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

Bu, mövcud settings.json-dakı hooks obyektinin elementidir, tam JSON sənədi deyil. Yol yoxlaması işləyicidə olmalıdır; mark-source-edit.py skripti burada şərtidir, onun mətni məqalədə yoxdur. Əmr python-un mövcud olduğunu və layihənin kökündən işə salınmasını nəzərdə tutur. Agent sizin tənzimləmənizdə interpretatoru, shell-i və yolu tutuşdurmalıdır; nümunəni hazır qoşulma kimi kopyalamaq lazım deyil.

Bu fraqmenti bir cümlə kimi oxumaq rahatdır:

Zəncir yalnız tənzimləmədə göstəriləni əks etdirir. "İşarə qoy və ya faylı keç" qərarını yolun yoxlanmasından sonra artıq işləyici verir. Ona görə matcher-in olması alətin seçimini təsdiqləyir, amma src/-in düzgün süzgəcdən keçirildiyini hələ sübut etmir.

Bu cədvəldə Edit və Write Claude Code alətlərini bildirir. Faylı redaktorda əllə dəyişmək onları çağırmır, ona görə belə matcher-i yoxlamır. Hər hərəkətdən əvvəl diaqnostika faylının sonunu qeyd edin, sonra isə yalnız yeni qeydləri müqayisə edin.

Sərhəd yoxlanana qədər hərəkəti zərərsiz saxlayın: işə düşmə haqqında bir işarə, formatlaşdırma, bloklama və ya kütləvi fayl düzəlişi olmadan. Əvvəlcə lazımi halın düz bir dəfə keçdiyinə, artığın isə keçmədiyinə əmin olun.

Artıq işə düşmə həmişə iş əlavə edir. Bununla belə, sadəcə fayl yazan yerli əmr modelə özü müraciət etmir. prompt və ya agent tipli hook başqa cür qurulub və modeldən istifadə edir. Xərclərin ətraflı təhlili burada lazım deyil, bu iki işləyici növünü qarışdırmamaq kifayətdir.

Reaksiyanı necə söndürmək olar

Hook məhz indi mane olursa, onun mənbə qeydini tapın və yalnız onu lazımi hadisənin massivindən silin. Qalan hook-ları yerində saxlayın. Bu, gələcək işə düşmələrin söndürülməsidir: o, artıq icra olunmuş əmri ləğv etmir, dəyişdirilmiş faylları qaytarmır və artıq jurnala düşmüş sətirləri silmir.

Silməzdən əvvəl, əgər onu qaytarmaq niyyətindəsinizsə, seçilmiş qeydin kopiyasını saxlayın. Dəyişiklikdən sonra yenidən /hooks-u açın və bu qeydin artıq olmadığına əmin olun. Menyu hələ də köhnə tənzimləməni göstərirsə, sessiyanı bitirin və eyni layihədən yenisini açın. Sonra nəzarət hərəkətini icra edin və jurnalı əvvəl və sonra müqayisə edin. Söndürülmüş hook-dan yeni sətir olmamalıdır.

Bütün hook-ları müvəqqəti söndürmək üçün "disableAllHooks": true tənzimləməsi var. Amma bu, ümumi açar-qapayıcıdır, bir qeydi söndürmə üsulu deyil. Bu tənzimləmənin özündə faylların prioritetləri işləyir: layihə faylındakı "disableAllHooks": false sizin istifadəçi tənzimləmələrinizdəki true dəyərini üstələyəcək. Bundan əlavə, təşkilatın idarə olunan siyasəti ilə təyin edilmiş hook-ları adi istifadəçi və ya layihə tənzimləməsi ilə söndürmək olmaz.

Düzəlişi Claude Code-a necə tapşırmaq olar

Yaxşı tapşırıq müşahidəni, gözlənilən hadisəni, konkret faylları və dəyişikliyin sərhədini ehtiva edir. Bu, agentin bütün avtomatlaşdırmanı yenidən yazmadan tənzimləməni araşdırması üçün kifayətdir:

Bu layihədəki hook ilə məşğul ol.

Müşahidə: bir test sorğusundan sonra requests.log iki sətir alır.
/loop və fon subagentləri bu sessiyada işə salınmayıb.
Gözlənti: UserPromptSubmit düz bir sətir əlavə etməlidir.
Mən /hooks nəticəsini əlavə edəcəyəm. Bütün mövcud tənzimləmə mənbələrini
və işləyicinin əmrini yoxla.

Əvvəlcə səbəbi və dəyişdirilməli faylları adlandır. Sonra minimal düzəliş et,
qalan hook-ları saxla və diff-i göstər.
Lazımi halı və mənfi halı yoxla. Bundan sonra yalnız bu reaksiyanı
necə söndürməyi göstər.

Sonda sizdə dörd aydın cavab qalmalıdır:

• hansı hadisə hook-u işə salır;
• hansı şərt artıq halları kənarlaşdırır;
• mənbə tənzimləməsi və işləyici harada yerləşir;
• qalanlarına toxunmadan məhz bu reaksiyanı necə söndürmək olar.

Və nəzarət marşrutu bütövlükdə: lazımi hərəkət bir gözlənilən iz qoyur, artıq iz qoymur, işləyicinin xətası məqsədli diaqnostikada görünür, söndürüldükdən sonra yeni iz daha görünmür. Hamısı olduqca sadədir. Məhz buna görə belə hook-u sadəcə "bəzən nəsə edən" avtomatlaşdırmadan daha asan dəstəkləmək olur.

Davranışı yoxlamaq üçün rəsmi hooks arayışından və praktiki bələdçidən istifadə edin: interfeys Claude Code ilə birlikdə dəyişir.

Davranış rəsmi sənədlərlə 2026-cı il sentyabrın 18-də tutuşdurulub. Nümunələr yoxlama qaydasını göstərir; burada hazır işləyici yoxdur. Əmri və yolları öz ƏS-nizdə və shell-inizdə yoxlayın.