Qısa Xülasə: Claude Code hook-ları AI kodlaşdırma sessiyaları zamanı müəyyən həyat dövrü nöqtələrində icra olunan avtomatlaşdırma skriptləridir, developer-lərə xüsusi komandaları işə salmağa, əməliyyatları təsdiqləməyə, kodu formatlamağa, bildirişlər göndərməyə və layihə qaydalarını tətbiq etməyə imkan verir. Bu hook-lar SessionStart, PreToolUse və PostToolUse kimi hadisələr vasitəsilə Claude-un iş axınına inteqrasiya olunur, komanda əsaslı, HTTP əsaslı və prompt əsaslı icra nümunələrini konfiqurasiya edilə bilən vaxtaşırı limitlər və çıxış kodu davranışları ilə dəstəkləyir.
Claude Code-un hook sistemi AI kodlaşdırma köməkçisini faydalı bir alətdən tam avtomatlaşdırılmış bir development mühitinə çevirir. Əksər developer-lər hook-lar vasitəsilə mövcud olan nəzarət səviyyəsini başa düşmürlər.
Budur məsələ — hook-lar təkcə fayl redaktələrindən sonra skriptləri işə salmaqdan ibarət deyil. Onlar Claude-un bütün qərar qəbul etmə prosesi boyunca müdaxilə nöqtələri təmin edirlər. Komandaları icra etməzdən əvvəl. Alət çağırışı uğursuz olduqdan sonra. İcazə lazım olduqda. Hətta istifadəçi prompt-larını emal etməzdən əvvəl.
Bu bələdçi, rəsmi sənədlərin təmin etdiyi hər şeyi, üstəlik, icma müzakirələrinin istehsal mühitlərində həqiqətən işlədiyini ortaya qoyduğu praktiki nümunələri əhatə edir.
Claude Code Hook-ları Əslində Nə Edir
Rəsmi Claude Code sənədlərinə görə, hook-lar Claude Code-un həyat dövrünün müəyyən nöqtələrində icra olunan, istifadəçi tərəfindən təyin edilmiş shell komandaları, HTTP son nöqtələri və ya prompt enjeksiyonlarıdır. Onlar stdin vasitəsilə strukturlaşdırılmış JSON girişi qəbul edir və çıxış kodları və ya HTTP cavabları vasitəsilə iş axınına nəzarət edirlər.
Avtomatlaşdırma əksər bələdçilərin təklif etdiyindən daha dərinə gedir. Hook-lar alət icrasını tamamilə bloklaya, Claude-un reasoninginə əlavə kontekst daxil edə, xarici xidmətləri işə sala və Claude-un hörmət etməli olduğu təsdiqləmə qaydalarını tətbiq edə bilər.
Üç əsas hook növü mövcuddur:
- Komanda hook-ları: stdout, stderr və çıxış kodları vasitəsilə ünsiyyət quran shell skriptləri
- HTTP hook-ları: POST sorğuları qəbul edən və JSON cavabları qaytaran uzaq son nöqtələr
- Prompt hook-ları: Müəyyən hadisələrdə Claude-un kontekstinə daxil edilən dinamik təlimatlar
Hər bir növ müxtəlif avtomatlaşdırma nümunələrinə xidmət edir. Komanda hook-ları yerli təsdiqləmə və formatlama ilə məşğul olur. HTTP hook-ları xarici xidmətlər və verilənlər bazaları ilə inteqrasiya olunur. Prompt hook-ları xarici proseslər olmadan Claude-un davranışını dəyişdirir.
Hook Həyat Dövrü və Hadisə Sistemi
Rəsmi sənədlər Claude Code-un icra axını zamanı yaranan bir çox hook hadisəsini (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification və başqaları) təyin edir. Hər birinin nə vaxt yaranacağını başa düşmək, hansı avtomatlaşdırmanın mümkün olduğunu müəyyən edir.
| Hadisə | Nə Zaman Yaranır | Bloklaya Bilər |
|---|---|---|
| SessionStart | Sessiya başladığında və ya davam etdirildikdə | Xeyr |
| UserPromptSubmit | Siz promptu göndərdikdə, Claude onu emal etməzdən əvvəl | Bəli |
| PreToolUse | Alət çağırışı icra olunmazdan əvvəl | Bəli |
| PermissionRequest | İcazə dialoqu göründükdə | Bəli |
| PostToolUse | Alət çağırışı uğurlu olduqdan sonra | Xeyr |
| PostToolUseFailure | Alət çağırışı uğursuz olduqdan sonra | Xeyr |
| Notification | Claude Code bildiriş göndərdikdə | Xeyr |
| SubmitMessage | Claude istifadəçiyə mesaj göndərdikdə | Xeyr |
| ContextCompaction | Kontekst pəncərəsi limitlərə yaxınlaşdıqda | Xeyr |
Bloklama bacarığı ən əhəmiyyətlisidir. PreToolUse hook-ları təhlükəli əməliyyatları icra etməzdən əvvəl mane ola bilər. Çıxış kodu 1 əməliyyatı bloklayır. Çıxış kodu 0 ona icazə verir. Çıxış kodu 2 Claude-u yenidən düşünməyə təşviq edir.
Amma dayan. PostToolUse hook-ları artıq icra olunduğu üçün əməliyyatları geri qaytara bilməz. Bu məhdudiyyət təsdiqləmə məntiqinin necə qurulduğunu formalaşdırır. Kritik yoxlamalar PreToolUse-da yerləşir. Təmizləmə və formatlama PostToolUse-da yerləşir.
Claude Code Quraşdırarkən AI Alət Perks-lərinə Baxın
Claude Code hook-ları ilə işləyirsinizsə, iş axınınızın ətrafında digər AI alətlərini də seçə bilərsiniz. Get AI Perks AI və bulud alətləri üçün başlanğıc kreditlərini və proqram təminatı endirimlərini bir yerdə toplayır. Platform 200-dən çox təklif daxildir, hər biri üçün perk şərtləri və iddia təlimatları var.
Claude və ya Digər AI Alət Perks-ləri Axtarırsınız?
Get AI Perks-ə baxın:
- Claude və digər AI alət təkliflərinə baxın
- Müraciət etməzdən əvvəl perk şərtlərini müqayisə edin
- Alət yığınlarınızda başlanğıc endirimlərini tapın
👉 Mövcud AI proqram təminatı perk-lərinə baxmaq üçün Get AI Perks-i ziyarət edin.
Konfiqurasiya və Fayl Struktur
Hook-lar layihə daxilindəki .claude/settings.json faylında təyin edilir. Konfiqurasiya şeması qlobal hook-ları və hook-ların nə vaxt icra olunacağını süzən alətə xüsusi uyğunlaşdırıcıları dəstəkləyir.
Əsas komanda hook-unun strukturu:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
`${file}` dəyişəni alət girdisindən olan faktiki fayl yolunu genişləndirir. Rəsmi sənədlərə görə, hook-lar komanda və arqument sahələrində bu dəyişən genişlənmələrini dəstəkləyir.
Hook Yerləşmə iyerarxiyası
Claude Code hook təyinlərini bir sıra yerlərdə yoxlayır, aydın prioritet sırası ilə:
- Layihə səviyyəsi: Mövcud iş sahəsindəki .claude/settings.json
- İstifadəçi səviyyəsi: Bütün sessiyalar üçün ~/.claude/settings.json
- Plugin tərəfindən təmin edilmiş: Quraşdırılmış plugin-lərlə birlikdə gələn hook-lar
Layihə hook-ları eyni hadisə üçün istifadəçi hook-larını üstələyir. Bu, qlobal bildiriş handler-lərini saxlayarkən layihəyə xüsusi formatlaşdırma qaydalarına imkan verir.
Seçici İcra üçün Uyğunlaşdırıcı Nümunələri
Uyğunlaşdırıcı sistemi hook-ları müəyyən alətlərə və ya şərtlərə uyğunlaşdırmaq üçün süzür. Uyğunlaşdırıcılar olmadan, hook-lar onların hadisəsinin hər bir görünüşü üçün yaranır.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
`pathPattern` sahəsi glob sintaksis qəbul edir. `toolName` sahəsi edit_file, execute_command, read_file və create_directory kimi Claude-un daxili alətlərinə uyğun gəlir.
İcma müzakirələri, uyğunlaşdırıcı kombinasiyalarının VƏ məntiqi ilə işlədiyini ortaya qoyur. Hook-un icra olunması üçün bütün təyin edilmiş uyğunlaşdırıcılar uyğun gəlməlidir.
Komanda Hook-ları: Shell Skript İnterqrasiyası
Komanda hook-ları strukturlaşdırılmış JSON girişi ilə shell komandalarını və ya skriptlərini icra edir. Onlar yerli avtomatlaşdırma üçün ən çox yayılmış hook növünü təmsil edir.
Rəsmi sənədlər, komanda hook-larının bu strukturla stdin vasitəsilə JSON qəbul etdiyini göstərir:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Bu girdini qərar vermək üçün skriptlər emal edir. Python təsdiqləmə hook-u belə görünə bilər:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Qorunan faylları redaktə etmək olmaz”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Çıxış kodu 0 əməliyyata icazə verir. Çıxış kodu 1 onu bloklayır və stderr mesajını Claude-a göstərir. Çıxış kodu 2 hadisədən asılı olaraq xüsusi davranışları tetikler.
Çıxış Kodu 2 Davranışı
Rəsmi hook-lar referans sənədlərinə görə, çıxış kodu 2-nin hadisəyə xas mənaları var (PreToolUse: bloklayır və yenidən düşünməyi təklif edir; UserPromptSubmit: bloklamadan kontekst təqdim edir; PermissionRequest: icazəni bloklayır):
- PreToolUse: Aləti bloklayır və stderr mesajını kontekst kimi istifadə edərək Claude-u yenidən düşünməyə təşviq edir
- UserPromptSubmit: stderr çıxışını bloklamadan əlavə kontekst kimi təqdim edir
- PermissionRequest: İcazənin verilməsini bloklayır
Bu, sərt bloklama və icazə vermə arasında bir orta yol yaradır. Claude, əməliyyatın niyə problem yarada biləcəyi barədə rəy alır və öz yanaşmasını tənzimləyə bilər.
Asinxron Komanda Hook-ları
`async: true` bayrağı hook-ları Claude-un iş axınını bloklamadan fon rejimində işlədir. Bu, təyinat bildirişləri və ya metrik toplama kimi yavaş əməliyyatlar üçün əhəmiyyətlidir.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Asinxron hook yaranarkən, Claude Code prosesi başlayır və dərhal davam edir. `timeout` sahəsi saniyə cinsindən maksimum icra vaxtını təyin edir. Təyin edilməzsə, asinxron hook-lar 10 dəqiqəlik standart vaxt aşımı istifadə edir.
Real danışıq: asinxron hook-lar əməliyyatları bloklaya bilməz, çünki Claude davam etdikdən sonra işləyirlər. Onlar günlük kaydı, bildirişlər və təmizləmələr üçün işləyirlər — təsdiqləmə üçün deyil.
HTTP Hook-ları: Xarici Xidmət İnterqrasiyası
HTTP hook-ları uzaq son nöqtələrə JSON fayl yüklərini POST edir və qərar nəzarəti üçün cavabları emal edir. Onlar təsdiqləmə xidmətləri, verilənlər bazaları və üçüncü tərəf alətləri ilə inteqrasiyaya imkan verir.
Əsas HTTP hook konfiqurasiyası:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Fayl yüklənmə strukturu komanda hook girişi ilə uyğun gəlir, lakin HTTP POST gövdəsi kimi gəlir. Cavab Claude-un növbəti addımını müəyyən edir.
HTTP Cavab İşlənməsi
Rəsmi sənədlərə görə, HTTP hook-ları cavabları status kodu və gövdə məzmununa əsasən şərh edir:
| Status Kodu | Təsir | Mesaj Mənbəyi |
|---|---|---|
| 200 | Əməliyyata icazə verin | Cavab gövdəsi (ixtiyari) |
| 400 | Əməliyyatı bloklayın | Claude-a göstərilən cavab gövdəsi |
| 500 | Hook xətası, əməliyyata icazə verin | Qeyd edilib, lakin Claude-a göstərilməyib |
| Digər | Əməliyyata icazə verin | Hook xətası iş axınını bloklamır |
Cavab gövdəsi Claude-un gördüyü bir mesaj sahəsini ehtiva edə bilər. Bu, təsdiqləmə xidmətlərinə bir əməliyyatın niyə bloklandığını izah etməyə imkan verir.
Ətraf Mühit Dəyişən İnterpolasiyası
HTTP hook-ları url, başlıqlar və digər mətn sahələrində ${VAR} sintaksisini dəstəkləyir. Dəyişənlər Claude Code-un işlədiyi mühitdən genişlənir.
Rəsmi MCP sənədlərinə görə, ətraf mühit dəyişəninin genişlənməsi standart ehtiyat sintaksisini ehtiva edir: ${VAR:-default} VAR təyin edilibsə, onu genişləndirir, əks halda standart dəyərdən istifadə edir.
Təhlükəsizlik məhdudiyyəti: GitHub issue #28044-ə görə, HTTP hook-ları yalnız `allowedEnvVars` konfiqurasiya sahəsində açıq şəkildə siyahıya alınmış ətraf mühit dəyişənlərinə daxil ola bilər. Bu, təsadüfi etimadnamənin açıqlanmasını mane olur.
Prompt Hook-ları: Kontekst İnksiyası
Prompt hook-ları müəyyən hadisələrdə Claude-un kontekstinə dinamik təlimatlar daxil edir. Onlar xarici proseslər və ya API çağırışları olmadan davranışı dəyişdirirlər.
| { “event”: “SessionStart”, “prompt”: “Siz TypeScript layihəsi üzərində işləyirsiniz. Həmişə ciddi null yoxlamalarını istifadə edin və promislərə qarşı async/await üstünlük verin.” } |
Daxil edilmiş mətn həmin sessiya üçün Claude-un sistem təlimatlarının bir hissəsi olur. Prompt hook-ları hadisə məlumatlarına əsasən genişlənən şablon dəyişənlərini də istifadə edə bilər.
Dinamik Prompt Yaradılması
Rəsmi sənədlərə görə, prompt hook-ları dinamik prompt-lar yaradan komanda sahələrini dəstəkləyir:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Komanda standart JSON girdisini stdin vasitəsilə qəbul edir və prompt mətnini stdout-a çıxarır. Bu, layihə vəziyyətinə əsaslanan kontekstə uyğun təlimatların yaradılmasına imkan verir.
Agent Əsaslı Hook-lar
Agent hook-ları birbaşa prompt daxil etməsi əvəzinə hadisəni idarə edən bir alt agent təyin edir. Alt agent hadisə haqqında kontekst alır və çoxaddımlı reasoning edə bilər.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Bir alət çağırışı uğursuz oldu. Səhvi təhlil edin və düzəlişlər təklif edin.” } |
Adlandırılmış alt agent layihə konfiqurasiyasında təyin edilməlidir. Agent hook-ları sadə prompt daxil etməsinin təmin edə bilmədiyi mürəkkəb qərar məntiqinə imkan verir.
Praktiki Hook Nümunələri
İcma müzakirələri və rəsmi nümunələr istehsalda etibarlı şəkildə işləyən xüsusi avtomatlaşdırma nümunələrini ortaya qoyur.
Redaktələrdən Sonra Kodu Avtomatik Formatla
Ən çox yayılmış nümunə, Claude faylları redaktə etdikdən sonra kodu avtomatik olaraq formatlayır:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
`${toolInput.path}` dəyişəni redaktə edilmiş fayl yolunu genişləndirir. PostToolUse, uğurlu redaktələrdən sonra formatlamanın olmasını təmin edir, lakin Claude-un iş axınını bloklamır.
Qorunan Fayl Dəyişikliklərini Bloklayın
PreToolUse hook-ları fayl qoruma qaydalarını tətbiq edir:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skript, hədəf yolunu qorunan nümunələrə qarşı təsdiqləyir və qadağan olunmuş redaktələri bloklamaq üçün 1 kodu ilə çıxır.
Claude Girişə Ehtiyac Duyduqda Bildiriş Alın
Rəsmi iş axını bələdçisinə görə, Bildiriş hook-ları masaüstü xəbərdarlıqları tetikləyə bilər və ya xarici xidmətlərə mesaj göndərə bilər:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Bu, istifadəçi girişi gözləyərkən və ya tapşırıq tamamlandıqdan sonra, Claude Code bildiriş göndərdikdə hər dəfə yaranır.
Sıxışmadan Sonra Konteksti Yenidən Daxil Edin
ContextCompaction hook-ları söhbət pəncərəsi dolduqda vacib konteksti bərpa edir:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Komanda çıxışı, sıxışdırma köhnə mesajları sildikdən sonra Claude-un kontekstinə geri daxil edilir. Bu, kritik layihəyə xas təlimatların itkisini mane olur.
Konfiqurasiya Dəyişikliklərini Audit Edin
Claude konfiqurasiya fayllarını nə vaxt dəyişdirdiyini izləyin:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asinxron icra, git əməliyyatları tamamlanarkən Claude-u bloklamağı mane edir. Bu, əl ilə mərhələləşdirmə olmadan konfiqurasiya dəyişikliklərinin audit izini yaradır.
JSON Çıxışı və Qərar Nəzarəti
Komanda hook-ları sadə çıxış kodlarından kənar ətraflı rəy vermək üçün strukturlaşdırılmış JSON çıxara bilər. Rəsmi referansına görə, JSON çıxışı Claude-un qərar vermə üçün şərh etdiyi çox sahəli cavablara imkan verir.
| { “allowed”: false, “message”: “Bu fayl komanda siyasəti tərəfindən qorunur”, “suggestion”: “src/features/ əvəzinə yeni fayl yaradın” } |
`allowed` sahəsi əməliyyatın davam edib-etmədiyini idarə edir. Mesaj kontekst kimi Claude-a görünür. Təklif sahəsi alternativ yanaşmaları təqdim edir.
Hook-ların JSON çıxış etməsi üçün onlar aşağıdakıları etməlidirlər:
- Stdout-a etibarlı JSON yazın
- 0 kodu ilə çıxın (icazəli üçün) və ya 1 (bloklanmış üçün)
- Minimum `allowed` boolean sahəsini ehtiva edin
Claude Code JSON-u emal edir və onu rəy döngüsünü gücləndirmək üçün istifadə edir. Çıxış kodları hələ də əsas qərarı müəyyən edir, lakin JSON daha zəngin kontekst təmin edir.
Hook Giriş Sahələri Referansı
Bütün hook-lar ümumi sahələr və hadisəyə xas məlumatlarla birlikdə stdin vasitəsilə JSON obyekti qəbul edir. Tam şemayı başa düşmək daha mürəkkəb hook məntiqinə imkan verir.
Ümumi Giriş Sahələri
Hər bir hook bu əsas sahələri qəbul edir:
- event: Hook hadisəsinin adı (məsələn, "PreToolUse")
- sessionId: Cari Claude sessiyasının unikal identifikatoru
- turnId: Cari söhbət növbəsinin identifikatoru
- timestamp: Hadisənin yarandığı vaxtın ISO 8601 vaxt damğası
Alət Hadisəsi Sahələri
PreToolUse, PostToolUse və PostToolUseFailure hadisələri aşağıdakıları əhatə edir:
- toolName: Çağırılan alətin adı (edit_file, execute_command, və s.)
- toolInput: Alətin giriş parametrlərini ehtiva edən obyekt
- toolResponse: Alətin çıxış məlumatları (yalnız PostToolUse)
- error: Mesaj və kodu daxil olmaqla səhvlər (yalnız PostToolUseFailure)
Alət girdisinin strukturu alətdən asılı olaraq dəyişir. `edit_file` üçün yol və məzmunu ehtiva edir. `execute_command` üçün komanda və arqumentləri ehtiva edir.
İcazə Hadisəsi Sahələri
PermissionRequest hadisələri aşağıdakıları əhatə edir:
- permissionType: Tələb olunan icazə növü (file_write, command_execute, və s.)
- requestedAction: İcazə tələb edən xüsusi əməliyyat
- resourcePath: Təsirə məruz qalan fayl yolu və ya resurs identifikatoru
MCP Alət Hook-ları
Rəsmi hook-lar referansına görə, hook-lar `mcpTool` matcher sahəsindən istifadə edərək Model Kontekst Protokolu (MCP) alətlərinə uyğunlaşa bilər. Bu, Claude MCP serverləri tərəfindən təmin edilən xarici alətlərdən istifadə etdikdə hook icrasına imkan verir.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
`mcpTool` dəyəri `server-name/tool-name` formatında alətin adına uyğun gəlir. Bu, verilənlər bazası sorğuları, API çağırışları və ya digər xarici əməliyyatlar üçün təsdiqləmə məntiqinə imkan verir.
GitHub xüsusiyyət tələbləri, hook-ların MCP server bildirişlərini yoxlamaq və xarici hadisələrə cavab vermək kimi daha dərin MCP inteqrasiyasına artan marağı göstərir.
Təhlükəsizlik Nəzərə Alınmaları
Hook-lar Claude Code-un özü ilə eyni icazələrlə icra olunur. Bu, çox istifadəçili mühitlər və paylaşılmış konfiqurasiyalar üçün təhlükəsizlik nəticələri yaradır.
Komanda İcrası Sandbox-u
GitHub issue #28044-ə görə, HTTP hook-ları şəbəkə girişini məhdudlaşdıran və ətraf mühit dəyişənlərini süzən bir sandbox proxy-dən keçir. Komanda hook-larının belə məhdudiyyətləri yoxdur — onlar tam shell girişi ilə işləyirlər.
Sənədlər bu təcrübələri tövsiyə edir:
- Hook komandalarında heç vaxt etimadnamələri saxlamayın
- Həssas məlumatlar üçün ətraf mühit dəyişənlərindən istifadə edin
- ${...} genişlənmələrindən gələn bütün girdiləri təsdiqləyin
- Xarici xidmətlər üçün vaxt aşımı limitlərini tətbiq edin
- Xətalar zamanı bloklamanı mane olmaq üçün qeyri-kritik əməliyyatlar üçün asinxron hook-lardan istifadə edin
Hook İcrasının Təcrid Edilməsi
`~/.claude/settings.json`-dakı istifadəçi səviyyəli hook-lar bütün layihələrə tətbiq olunur. Bu, müxtəlif etibarlı sərhədlər arasında işləyərkən risklər yaradır. Layihə səviyyəli hook-lar istifadəçi hook-larını üstələyir, lakin onları tamamilə deaktiv edə bilməz.
Claude Code-dakı `/hooks` menyusu cari sessiya üçün bütün aktiv hook-ları göstərir. Həssas layihələr üzərində işləməzdən əvvəl bu siyahıya baxmaq potensial təhlükəsizlik narahatlıqlarını aşkar etməyə kömək edir.
Debug və Problemlərin Həlli
Hook xətaları həmişə Claude-un söhbətində aydın görünmür. Rəsmi sənədlər bir neçə debug yanaşmasını təmin edir.
Hook İcrası Logları
Claude Code hook icrasını sessiya debug çıxışına yazır. Problemlərin həlli bələdçisinə görə, debug log-lamanı aktivləşdirmək aşağıdakıları ortaya qoyur:
- Hər bir hadisə üçün hansı hook-lar uyğun gəldi
- Hər bir hook-a göndərilən JSON girdisi
- Hook proseslərindən stdout və stderr çıxışı
- Çıxış kodları və icra vaxtı
- HTTP hook-ları üçün HTTP cavab kodları və gövdələri
Claude Code-u işə salmazdan əvvəl mühitdə `CLAUDE_DEBUG=1` təyin edərək debug log-lamanı aktivləşdirin.
Hook-ları Müstəqil Olarak Test Edin
Komanda hook-ları, əl ilə JSON girdisi yaradaraq Claude Code xaricində test edilə bilər:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Bu, actual Claude əməliyyatlarını tetiklemeden hook məntiqini təsdiqləyir. Çıxış kodu və stdout/stderr çıxışı gözlənilən davranışla uyğun gəlməlidir.
Ümumi Hook Xətaları
İcma müzakirələri bu tez-tez rast gəlinən məsələləri müəyyən edir:
- Vaxt aşımı xətaları: Standart 10 dəqiqəlik vaxt aşımı yavaş əməliyyatlar üçün çox qısa — `timeout` sahəsi ilə artırın
- Yol genişlənməsi xətaları: `${file}` kimi dəyişənlər fayl konteksti daxil etməyən hadisələr üçün təyin olunmayıb
- İcazə xətaları: Hook skriptlərində icra icazələri yoxdur — `chmod +x script.sh` işlədin
- JSON parse xətaları: Hook-lardan səhv JSON çıxışı — qayıtmazdan əvvəl `jq` ilə təsdiqləyin
- Ətraf mühit dəyişəninin mövcud olmaması: Hook prosesinə yayılmayan dəyişənlər — Claude Code-un mühitini yoxlayın
Hook Performans Nəticələri
Sinkron hook-lar tamamlanana qədər Claude-un iş axınını bloklayır. Standart 10 dəqiqəlik vaxt aşımı qeyri-müəyyən dayanmaların qarşısını alır, lakin qısa gecikmələr belə bir çox əməliyyat boyunca yığılır.
Praktiklər sadə təsdiqləmə hook-larının əhəmiyyətsiz performans təsirinə malik olduğunu bildirirlər. Fayl formatlaşdırma hook-ları nəzərə çarpan, lakin qəbuledilən performans təsirinə səbəb olur. Xarici API çağırışları iş axını sürtünməsi yarada bilər. Ağır hesablamalar asinxron icradan faydalanır.
Hook Qruplaşdırma
Birdən çox hook eyni hadisəyə uyğun gələ bilər. Referans sənədlərinə görə, hook-lar təyin sırasına uyğun olaraq ardıcıl icra olunur. Hər hansı bir hook əməliyyatı bloklayarsa, qalan hook-lar icra olunmur.
Bu, performans üçün əhəmiyyətlidir. 200ms hər biri olan beş sinkron hook hadisə başına bir saniyə əlavə edir. Müvafiq təsdiqləmələri vahid hook-da birləşdirmək əlavə xərcləri azaldır.
Qabaqcıl Nümunələr
Əsas avtomatlaşdırmadan başqa, hook-lar mürəkkəb iş axını fərdiləşdirməsinə imkan verir.
Stateful Hook Zəncirləri
Hook-lar fayllar və ya verilənlər bazaları istifadə edərək icralar arasında vəziyyəti saxlaya bilər. Bir PostToolUse hook-u daha sonra PreToolUse hook-unun qarşılaşdırdığı uğurlu əməliyyatları qeyd edə bilər:
| #!/bin/bash # Uğurlu redaktələri qeyd edin echo “${toolInput.path}” >> .claude/edit-history.txt |
Bir əlavə PreToolUse hook-u, təkrarlanan əməliyyatları mane olmaq və ya sıra məhdudiyyətlərini tətbiq etmək üçün bu tarixi yoxlaya bilər.
Şərti Hook Aktivasiyası
Ətraf mühit dəyişənləri hook davranışını iş vaxtında idarə edir. `CLAUDE_SKIP_HOOKS=1` təyin etmək fövqəladə vəziyyətlər üçün hook-ları deaktiv edir.
Hook-lar özləri ətraf mühit bayraqlarını yoxlaya bilər:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Sərt təsdiqləmə tətbiq et exit 1 fi exit 0 |
Bu, konfiqurasiya dəyişiklikləri olmadan development rejimi və istehsal rejimi davranışına imkan verir.
Çox Mərhələli Təsdiqləmə
PreToolUse hook-ları, çıxış kodu 2-nin Claude-a xəbərdarlıqlarla davam etməyə imkan verdiyi çox səviyyəli təsdiqləmə tətbiq edə bilər:
- Sərt xətalar (çıxış 1): Təhlükəli əməliyyatları bloklayın
- Yumşaq xəbərdarlıqlar (çıxış 2): Yenidən düşünməyi Claude-a bildirin
- Kontekstlə keçin (çıxış 0 + JSON): Əlavə məlumat təqdim edin
Bu, ikili icazə/rədd etmədən daha incə bir təsdiqləmə spektr yaradır.
CI/CD ilə İnterqrasiya
Rəsmi platform interqrasiyası sənədlərinə görə, Claude Code avtomatik kod baxışı və məsələlərin təsnif edilməsi üçün CI/CD mühitlərində işləyir. Hook-lar bu avtomatlaşdırmanı genişləndirir.
GitHub Actions iş axınları avtomatlaşdırılmış sessiyalar zamanı komanda siyasətlərini tətbiq edən hook-lar təyin edə bilər:
| – name: Sərt hook-larla Claude Code işlədin env: STRICT_MODE: 1 run: | claude “Bu PR-ə baxın və təkmilləşdirmələr təklif edin” |
`STRICT_MODE` bayrağı, hook skriptlərində şərti təsdiqləmə məntiqini aktivləşdirir. Bu, avtomatlaşdırılmış sessiyaların interaktiv development-dən daha sərt qaydalara riayət etməsini təmin edir.
Audit İzi Yaratma
CI mühitlərindəki PostToolUse hook-ları bütün Claude əməliyyatlarının ətraflı audit loglarını yaradır:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Fon günlük kaydı performansa təsir etmir, lakin uyğunluq və debug üçün tam əməliyyat tarixini təmin edir.
The /hooks Menyu
Claude Code, cari sessiya üçün bütün aktiv hook-ları göstərən `/hooks` komandasını təqdim edir. Rəsmi sənədlərə görə, bu menyu aşağıdakıları göstərir:
- Hook hadisə növü
- Uyğunlaşdırıcı nümunələri
- Komanda və ya URL son nöqtəsi
- Hook-un async işləyib-işləmədiyi
- Konfiqurasiya mənbəyi (layihə, istifadəçi və ya plugin)
Hook seçmək onun tam konfiqurasiyasını göstərir və cari sessiya üçün müvəqqəti deaktiv etməyə imkan verir.
Hook-ları Deaktiv Et və ya Sil
Hook-lar konfiqurasiyanı silmədən deaktiv edilə bilər, bunun üçün hook təyinində `"enabled": false` əlavə etmək lazımdır. Bu, konfiqurasiyanı saxlayır, lakin icrasını mane olur.
Hook-u daimi silmək üçün, onu müvafiq settings.json faylından silin. Dəyişikliklər növbəti sessiya yenidən başladığında və ya `/reload` işlədildikdə qüvvəyə minir.
Hook-lar Bacarıqlarda və Agentlərdə
Rəsmi sənədlərə görə, bacarıq və ya alt agent konfiqurasiyaları daxilində təyin edilmiş hook-lar yalnız həmin bacarıq və ya agent icra olunduqda tətbiq olunur. Bu, müəyyən iş axınları üçün xüsusi avtomatlaşdırmaya imkan verir.
Bir debug alt agenti, bütün alət çağırışlarını qeyd edən hook-ları ehtiva edə bilər:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Bu hook-lar yalnız normal Claude Code əməliyyatı zamanı deyil, yalnız debug agent sessiyaları zamanı yaranır.
Skriptlərə Yol ilə İstinad
Hook komandaları həm nisbi, həm də mütləq yolları dəstəkləyir. Nisbi yollar Claude Code-un işlədiyi layihə kökündən həll olunur.
İcma müzakirələrindən ən yaxşı təcrübələr:
- Hook skriptlərini `.claude/hooks/` qovluğunda saxlayın
- Təsviredici adlardan istifadə edin: `validate-typescript.sh` deyil, `hook1.sh`
- Skriptləri icra edilən hala gətirin: `chmod +x .claude/hooks/*.sh`
- Shebang sətrini daxil edin: `#!/usr/bin/env bash` və ya `#!/usr/bin/env python3`
- Bash skriptlərində `set -e` ilə xəta idarə etməsi əlavə edin
Gələcək Hook Qabiliyyətləri
GitHub xüsusiyyət tələbləri planlaşdırılmış və tələb olunan hook təkmilləşdirmələrini ortaya qoyur:
- Inline skript hook-ları: Xarici fayllar olmadan `settings.json`-da birbaşa hook məntiqini təyin edin
- MCP alətlərinə inteqrasiya: Shell komandaları əvəzinə hook-lardan MCP server alətlərini çağırın
- Çox agent əməkdaşlığı: Müxtəlif maşınlardakı Claude instansları arasında əlaqə quran hook-lar
- Təkmilləşdirilmiş tiplər: Hook giriş/çıxış şemaları üçün TypeScript tip təyinləri
GitHub issue #4274-ə görə, inteqrasiya olunmuş hook tipləri (MCP aləti, inline skript, API çağırışı) üçün tələb, konfiqurasiyanı sadələşdirmək və developer təcrübəsini yaxşılaşdırmaq məqsədi daşıyır.
Tez-tez Verilən Suallar
Hook-lar Claude-un təhlükəli komandaları icra etməsinin qarşısını ala bilərmi?
Bəli. PreToolUse hook-ları 1 kodu ilə çıxaraq istənilən alət icrasını bloklaya bilər. Bu, fayl redaktələri, komanda icrası və MCP alət çağırışlarını əhatə edir. Hook tam alət girdisini alır və əməliyyata icazə vermədən əvvəl hər hansı bir meyara qarşı təsdiqləyə bilər.
İşləməyən hook-u necə debug etməli?
Claude Code-u işə salmazdan əvvəl `CLAUDE_DEBUG=1` ilə debug log-lamanı aktivləşdirin. Hook icra detalları üçün sessiya loglarına baxın, hansı hook-ların uyğun gəldiyi, göndərilən JSON girdisi, stdout/stderr çıxışı və çıxış kodları daxil olmaqla. Nümunə JSON-u hook skriptinə yönləndirərək hook-ları müstəqil olaraq test edin.
Hook-lar bütün Claude Code platformaları ilə işləyirmi?
Hook-lar CLI, masaüstü proqramı və VS Code uzantısında işləyir. Rəsmi sənədlərə görə, hook-lar fayl sisteminə çıxışı olan yerlərdə Claude Code işlədiyi yerdə icra olunur. Brauzer əsaslı Claude və mobil tətbiqlər sandbox məhdudiyyətləri səbəbindən hook-ları dəstəkləmir.
Hook-lar Claude-un cavablarını və ya davranışını dəyişdirə bilərmi?
Prompt hook-ları Claude-un davranışına təsir edən təlimatlar daxil edir. Agent hook-ları hadisə emalını xüsusi alt agentlərə verir. Lakin, hook-lar Claude-un yaradılmış mətnini və ya reasoning prosesini birbaşa dəyişdirə bilməz — onlar kontekst təmin etməklə və əməliyyatları bloklamaqla işləyirlər.
Asinxron və sinkron hook-lar arasındakı fərq nədir?
Sinkron hook-lar tamamlanma və ya vaxt aşımı baş verənə qədər Claude-un iş axınını bloklayır. Asinxron hook-lar bloklamadan fon rejimində işləyir. Sinkron hook-lar çıxış kodları vasitəsilə əməliyyatları mane ola bilər. Asinxron hook-lar bloklaya bilməz, çünki Claude hook tamamlanmazdan əvvəl davam edir. Loglama və bildirişlər üçün asinxron, təsdiqləmə üçün sinkron istifadə edin.
Hook-ları komanda arasında necə bölüşdürməli?
`.claude/settings.json` faylını versiya nəzarətinə commit edin. Layihə səviyyəli hook-lar repozitoriyanı klonlayan bütün komanda üzvlərinə tətbiq olunur. Təşkilat səviyyəli siyasətlər üçün komandalar üzvlərin `~/.claude/settings.json`-a köçürdüyü paylaşılan istifadəçi səviyyəli settings faylını saxlaya bilər.
HTTP hook-ları divarların arxasındakı daxili API-lərə zəng edə bilərmi?
Bəli, Claude Code həmin API-lərə şəbəkə çıxışı olan bir mühitdə işləyirsə. HTTP hook-lar Claude Code-u işlədən maşından standart POST sorğuları edir. Korporativ divarlar və VPN-lər normal şəkildə tətbiq olunur. Sənədlərdə qeyd olunan sandbox proxy, şəbəkə marşrutlaşdırmasını deyil, ətraf mühit dəyişənlərinin məruz qalmasını idarə edir.
Hook-lar Claude Code-un token istifadəsini artırırmı?
Prompt hook-ları Claude-un kontekstinə mətn daxil edir, bu da token istifadə edir. Komanda və HTTP hook-ları birbaşa token istifadəsinə təsir etmir, lakin onların çıxışı (səhv mesajları, təkliflər) söhbət kontekstinin bir hissəsi olur. Çıxış kodu 2 izahlı mesajlarla sadə bloklama 1 kodundan daha çox kontekst əlavə edir.
Nəticə
Claude Code hook-ları AI köməkçisini güclü bir alətdən tam avtomatlaşdırılmış bir development platformasına çevirir. Hadisə sistemi, Claude-un iş axını boyunca — sessiya başlanğıcından kontekst sıxışdırmasına qədər — müdaxilə nöqtələri təmin edir.
Komanda hook-ları yerli təsdiqləmə və formatlama ilə məşğul olur. HTTP hook-ları xarici xidmətlər və verilənlər bazaları ilə inteqrasiya olunur. Prompt hook-ları kontekst daxil etmə yolu ilə davranışı dəyişdirir. Birlikdə, bunlar komanda siyasətlərini tətbiq edən, kod keyfiyyətini qoruyan və mövcud development infrastrukturuna inteqrasiya edən avtomatlaşdırma nümunələrinə imkan verir.
Uyğunlaşdırıcı sistemi hook-ları müəyyən alətlərə və fayl nümunələrinə uyğunlaşdırır. Çıxış kodları və JSON çıxışı qərar axınını idarə edir. Asinxron icra yavaş əməliyyatlarda bloklanmanı mane olur. Tam konfiqurasiya şeması sadə avtomatik formatlaşdırmadan mürəkkəb çox mərhələli təsdiqləməyə qədər hər şeyi dəstəkləyir.
Kod formatlama üçün sadə PostToolUse hook-ları ilə başlayın. Siyasətlər ortaya çıxdıqca PreToolUse təsdiqləməsini əlavə edin. Davranış dəyişikliyi üçün prompt hook-ları ilə təcrübə keçirin. Komanda miqyaslı tətbiq üçün HTTP inteqrasiyaları qurun.
Yeni qabiliyyətlər çatdırıldıqca tam hook-lar referansı və yenilənmiş konfiqurasiya şeması üçün rəsmi Claude Code sənədlərinə baxın.
