Īss kopsavilkums: Claude Code "hooks" ir automatizācijas skripti, kas izpildās noteiktos dzīves cikla punktos AI kodēšanas sesiju laikā, ļaujot izstrādātājiem palaist pielāgotas komandas, validēt darbības, formatēt kodu, nosūtīt paziņojumus un nodrošināt projektu noteikumu ievērošanu. Šie "hooks" integrējas Claude darbplūsmā, izmantojot notikumus, piemēram, SessionStart, PreToolUse un PostToolUse, atbalstot uz komandām balstītus, uz HTTP balstītus un uz "prompt" balstītus izpildes modeļus ar konfigurējamu taimautu un izietes koda uzvedību.
Claude Code "hook" sistēma pārveido AI kodēšanas palīgu no noderīga rīka par pilnībā automatizētu izstrādes vidi. Lielākā daļa izstrādātāju neapzinās kontroli, kas pieejama, izmantojot "hooks".
Tomēr svarīgākais ir tas, ka "hooks" nav tikai skriptu palaišana pēc failu izmaiņām. Tie nodrošina pārtveršanas punktus visā Claude lēmumu pieņemšanas procesā. Pirms komandas izpildes. Pēc rīka izsaukuma kļūmes. Kad nepieciešama atļauja. Pat pirms lietotāja "prompt" apstrādes.
Šī rokasgrāmata aptver visu, ko nodrošina oficiālā dokumentācija, kā arī praktiskus modeļus, ko kopienas diskusijas atklāj kā reāli darbojošus ražošanas vidēs.
Ko patiesībā dara Claude Code "hooks"
Saskaņā ar oficiālo Claude Code dokumentāciju, "hooks" ir lietotāja definētas komandrindas komandas, HTTP beigu punkti vai "prompt" injekcijas, kas izpildās noteiktos Claude Code dzīves cikla punktos. Tie saņem strukturētu JSON ievadi caur stdin un kontrolē darbplūsmu, izmantojot izietes kodus vai HTTP atbildes.
Automatizācija ir dziļāka, nekā lielākā daļa rokasgrāmatu iesaka. "Hooks" var pilnībā bloķēt rīku izpildi, injicēt papildu kontekstu Claude spriešanā, iedarbināt ārējos pakalpojumus un nodrošināt validācijas noteikumus, kuriem Claude ir jāpakļaujas.
Pastāv trīs galvenie "hook" veidi:
- Komandu "hooks": komandrindas skripti, kas sazinās, izmantojot stdout, stderr un izietes kodus
- HTTP "hooks": attālie beigu punkti, kas saņem POST pieprasījumus un atgriež JSON atbildes
- "Prompt" "hooks": dinamiskas instrukcijas, kas injicētas Claude kontekstā noteiktos notikumos
Katrs veids kalpo dažādiem automatizācijas modeļiem. Komandu "hooks" apstrādā vietējo validāciju un formatēšanu. HTTP "hooks" integrējas ar ārējiem pakalpojumiem un datubāzēm. "Prompt" "hooks" maina Claude uzvedību bez ārējiem procesiem.
Hook dzīves cikls un notikumu sistēma
Oficiālā dokumentācija definē vairākus "hook" notikumus (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification un citus), kas izpildās Claude Code izpildes plūsmā. Sapratne par to, kad katrs notikums notiek, nosaka iespējamo automatizāciju.
| Notikums | Kad tas notiek | Var bloķēt |
|---|---|---|
| SessionStart | Kad sesija sākas vai tiek atsākta | Nē |
| UserPromptSubmit | Kad iesniedzat "prompt", pirms Claude to apstrādā | Jā |
| PreToolUse | Pirms rīka izsaukuma izpildes | Jā |
| PermissionRequest | Kad parādās atļaujas dialogs | Jā |
| PostToolUse | Pēc rīka izsaukuma veiksmes | Nē |
| PostToolUseFailure | Pēc rīka izsaukuma kļūmes | Nē |
| Notification | Kad Claude Code nosūta paziņojumu | Nē |
| SubmitMessage | Kad Claude iesniedz ziņojumu lietotājam | Nē |
| ContextCompaction | Kad konteksta logs tuvojas ierobežojumiem | Nē |
Bloķēšanas iespēja ir vissvarīgākā. PreToolUse "hooks" var novērst bīstamas darbības pirms to izpildes. Izietes kods 1 bloķē darbību. Izietes kods 0 ļauj to veikt. Izietes kods 2 liek Claude pārdomāt.
Bet pagaidiet. PostToolUse "hooks" nevar atcelt darbības, jo rīks jau ir izpildīts. Šis ierobežojums nosaka, kā tiek strukturēta validācijas loģika. Kritiski pārbaudījumi pieder pie PreToolUse. Tīrīšana un formatēšana pieder pie PostToolUse.
Apskatiet AI rīku priekšrocības, iestatot Claude Code
Ja strādājat ar Claude Code "hooks", iespējams, izvēlēsieties arī citus AI rīkus savai darbplūsmai. Get AI Perks apkopo starta kredītus un programmatūras atlaides AI un mākoņiem paredzētiem rīkiem vienuviet. Platformā ir vairāk nekā 200 piedāvājumu, katram ar priekšrocību nosacījumiem un pieprasīšanas norādījumiem.
Meklējat Claude vai citas AI rīku priekšrocības?
Pārbaudiet Get AI Perks, lai:
- Apskatītu Claude un citu AI rīku piedāvājumus
- Salīdzinātu priekšrocību nosacījumus pirms pieteikšanās
- Atrastu starta atlaides visam jūsu rīku komplektam
👉 Apmeklējiet Get AI Perks, lai izpētītu pašreizējās AI programmatūras priekšrocības.
Konfigurācija un failu struktūra
Hooks tiek definēti .claude/settings.json failā projektā. Konfigurācijas shēma atbalsta globālos "hooks" un rīku specifiskus atbilstošus modeļus, kas filtrē, kad "hooks" tiek izpildīti.
Pamata komandu "hook" struktūra:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Mainīgais ${file} tiek paplašināts līdz faktiskajai faila atrašanās vietai no rīka ievades. Saskaņā ar oficiālo dokumentāciju, "hooks" atbalsta šādas mainīgo paplašināšanas komandu un argumentu laukos.
Hook atrašanās vietas hierarhija
Claude Code pārbauda vairākas vietas "hook" definīcijām, ar skaidru prioritātes secību:
- Projektu līmenis: .claude/settings.json pašreizējā darba vidē
- Lietotāja līmenis: ~/.claude/settings.json visām sesijām
- Spraudnis nodrošina: "Hooks", kas iepakoti ar instalētajiem spraudņiem
Projektu "hooks" aizstāj lietotāja "hooks" tādam pašam notikumam. Tas ļauj projektam specifiskus formatēšanas noteikumus, vienlaikus uzturot globālus paziņojumu apstrādātājus.
Matcher modeļi selektīvai izpildei
Matcher sistēma filtrē "hooks" uz specifiskiem rīkiem vai nosacījumiem. Bez matcher, "hooks" tiek izpildīti katru reizi, kad notiek viņu notikums.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Lauks pathPattern pieņem glob sintaksi. Lauks toolName saskaņojas ar Claude iebūvētajiem rīkiem, piemēram, edit_file, execute_command, read_file un create_directory.
Kopienas diskusijas atklāj, ka matcher kombinācijas darbojas ar AND loģiku. Visi norādītie matcher ir jāsaskaņo, lai "hook" tiktu izpildīts.
Komandu "Hooks": Komandrindas skriptu integrācija
Komandu "hooks" izpilda komandrindas komandas vai skriptus ar strukturētu JSON ievadi. Tie pārstāv visizplatītāko "hook" veidu vietējai automatizācijai.
Oficiālā dokumentācija norāda, ka komandu "hooks" saņem JSON caur stdin ar šādu struktūru:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripti apstrādā šo ievadi, lai pieņemtu lēmumus. Python validācijas "hook" varētu izskatīties šādi:#!/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(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Izietes kods 0 atļauj darbību. Izietes kods 1 to bloķē un parāda stderr ziņojumu Claude. Izietes kods 2 izraisa īpašu uzvedību atkarībā no notikuma.
Izietes kods 2 uzvedība
Saskaņā ar oficiālo "hooks" atsauces dokumentāciju, izietes kodam 2 ir notikumam specifiska nozīme (PreToolUse: bloķē un mudina uz pārdomām; UserPromptSubmit: sniedz kontekstu bez bloķēšanas; PermissionRequest: bloķē atļauju):
- PreToolUse: Bloķē rīku un mudina Claude pārdomāt, izmantojot stderr ziņojumu kā kontekstu
- UserPromptSubmit: Sniedz stderr izvadi kā papildu kontekstu bez bloķēšanas
- PermissionRequest: Bloķē atļaujas piešķiršanu
Tas rada vidusceļu starp stingru bloķēšanu un atļaušanu. Claude saņem atsauksmes par to, kāpēc darbība varētu būt problemātiska un var pielāgot savu pieeju.
Asinhronie komandu "Hooks"
Privātslēdzis async: true palaiziet "hooks" fonā, nebloķējot Claude darbplūsmu. Tas ir svarīgi lēniem procesiem, piemēram, izvietošanas paziņojumiem vai metrikas savākšanai.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Kad notiek asinhronais "hook", Claude Code sāk procesu un turpina nekavējoties. Taimauta lauks nosaka maksimālo izpildes laiku sekundēs. Ja tas nav norādīts, asinhronie "hooks" izmanto 10 minūšu noklusējuma taimautu.
Patiesa saruna: asinhronie "hooks" nevar bloķēt darbības, jo tie darbojas pēc tam, kad Claude turpina. Tie darbojas žurnālu sagatavošanai, paziņojumiem un tīrīšanai - nevis validācijai.
HTTP "Hooks": Ārējo pakalpojumu integrācija
HTTP "hooks" nosūta JSON "payload" uz attālajiem beigu punktiem un apstrādā atbildes lēmumu kontrolei. Tie nodrošina integrāciju ar validācijas pakalpojumiem, datubāzēm un trešo pušu rīkiem.
Pamata HTTP "hook" konfigurācija:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
"Payload" struktūra atbilst komandu "hook" ievadei, bet tiek saņemta kā HTTP POST pieprasījuma ķermenis. Atbilde nosaka Claude nākamo darbību.
HTTP atbildes apstrāde
Saskaņā ar oficiālo dokumentāciju, HTTP "hooks" interpretē atbildes, pamatojoties uz statusa kodu un ķermeņa saturu:
| Statusa kods | Efekts | Ziņojuma avots |
|---|---|---|
| 200 | Atļaut darbību | Atbildes ķermenis (nav obligāts) |
| 400 | Bloķēt darbību | Atbildes ķermenis, kas redzams Claude |
| 500 | Hook kļūda, atļaut darbību | Reģistrēts, bet nav redzams Claude |
| Cits | Atļaut darbību | Hook kļūme nebloķē darbplūsmu |
Atbildes ķermenis var ietvert ziņojuma lauku, ko Claude redz kā kontekstu. Tas ļauj validācijas pakalpojumiem paskaidrot, kāpēc darbība tika bloķēta.
Vides mainīgo interpolācija
HTTP "hooks" atbalsta ${VAR} sintaksi laukos url, headers un citos virknes laukos. Mainīgie tiek paplašināti no vides, kurā darbojas Claude Code.
Saskaņā ar oficiālo MCP dokumentāciju, vides mainīgo paplašināšana ietver noklusējuma rezerves sintaksi: ${VAR:-default} tiek paplašināts uz VAR, ja tas ir iestatīts, pretējā gadījumā tiek izmantota noklusētā vērtība.
Drošības ierobežojums: Saskaņā ar GitHub problēmu #28044, HTTP "hooks" var piekļūt tikai tām vides mainīgajiem, kas ir skaidri norādīti laukā allowedEnvVars konfigurācijā. Tas novērš nejaušu akreditācijas datu atklāšanu.
"Prompt" "Hooks": Konteksta injekcija
Prompt "hooks" injicē dinamiskas instrukcijas Claude kontekstā noteiktos notikumos. Tie maina uzvedību bez ārējiem procesiem vai API izsaukumiem.
| { “event”: “SessionStart”, “prompt”: “Jūs strādājat pie TypeScript projekta. Vienmēr izmantojiet stingras nulles pārbaudes un dodiet priekšroku async/await pirms "promises".” } |
Injekcionētā teksta kļūst par daļu no Claude sistēmas instrukcijām šai sesijai. "Prompt" "hooks" var izmantot arī veidņu mainīgos, kas tiek paplašināti, pamatojoties uz notikumu datiem.
Dinamiska "Prompt" ģenerēšana
Saskaņā ar oficiālo dokumentāciju, "prompt" "hooks" atbalsta komandu laukus, kas ģenerē dinamiskus "prompt":
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Komanda saņem standarta JSON ievadi caur stdin un izvadē uz stdout nodod "prompt" tekstu. Tas nodrošina kontekstam jutīgu instrukciju ģenerēšanu, pamatojoties uz projekta stāvokli.
Aģentu balstīti "Hooks"
Aģentu "hooks" norāda apakš-aģentu, kas apstrādā notikumu, nevis tiešu "prompt" injekciju. Apakš-aģents saņem kontekstu par notikumu un var veikt daudzpakāpju spriešanu.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Rīka izsaukums neizdevās. Analizējiet kļūdu un piedāvājiet labojumus.” } |
Nosauktais apakš-aģents ir jādefinē projekta konfigurācijā. Aģentu "hooks" nodrošina sarežģītu lēmumu loģiku, ko vienkārša "prompt" injekcija nespēj sniegt.
Praktiski "Hook" modeļi
Kopienas diskusijas un oficiālie piemēri atklāj specifiskus automatizācijas modeļus, kas uzticami darbojas ražošanā.
Automātiska koda formatēšana pēc izmaiņām
Visizplatītākais modelis automātiski formatē kodu pēc tam, kad Claude veic izmaiņas failos:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Mainīgais ${toolInput.path} tiek paplašināts līdz izmainītā faila atrašanās vietai. PostToolUse nodrošina, ka formatēšana notiek pēc veiksmīgām izmaiņām, bet nebloķē Claude darbplūsmu.
Bloķēt aizsargātu failu izmaiņas
PreToolUse "hooks" nodrošina failu aizsardzības noteikumus:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skripts validē mērķa ceļu attiecībā pret aizsargātiem modeļiem un iziet ar kodu 1, lai bloķētu aizliegtās izmaiņas.
Saņemiet paziņojumus, kad Claude nepieciešama ievade
Saskaņā ar oficiālo darbplūsmas rokasgrāmatu, Notification "hooks" var iedarbināt darbvirsmas brīdinājumus vai nosūtīt ziņojumus uz ārējiem pakalpojumiem:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Tas tiek izpildīts ikreiz, kad Claude Code nosūta paziņojumu, tostarp gaidot lietotāja ievadi vai pēc uzdevuma pabeigšanas.
Konteksta atkārtota injekcija pēc saspiešanas
ContextCompaction "hooks" atjauno svarīgu kontekstu, kad sarunu logs piepildās:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Komandas izvade tiek injicēta atpakaļ Claude kontekstā pēc tam, kad saspiešana noņem vecākus ziņojumus. Tas novērš kritisko projektu specifisko instrukciju zudumu.
Konfigurācijas izmaiņu revīzija
Izsekojiet, kad Claude veic izmaiņas konfigurācijas failos:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asinhronā izpilde novērš Claude bloķēšanu, kamēr notiek git operācijas. Tas rada izmaiņu revīzijas taku bez manuālas sagatavošanas.
JSON izvade un lēmumu kontrole
Komandu "hooks" var izvadīt strukturētu JSON, lai sniegtu detalizētu atsauksmi, kas pārsniedz vienkāršus izietes kodus. Saskaņā ar oficiālo atsauci, JSON izvade nodrošina daudzlauku atbildes, ko Claude interpretē lēmumu pieņemšanai.
| { “allowed”: false, “message”: “Šis fails ir aizsargāts ar komandas politiku”, “suggestion”: “Izveidojiet jaunu failu src/features/ vietā” } |
Lauks "allowed" kontrolē, vai darbība turpinās. Ziņojums parādās Claude kā konteksts. Lauks "suggestion" sniedz alternatīvas pieejas.
Lai "hooks" izvadītu JSON, tiem ir jābūt:
- Rakstīt derīgu JSON uz stdout
- Iziet ar kodu 0 (atļauts) vai 1 (bloķēts)
- Iekļaut vismaz "allowed" boolean lauku
Claude Code parsē JSON un izmanto to, lai uzlabotu atsauksmes cilpu. Izietes kods joprojām nosaka primāro lēmumu, bet JSON nodrošina bagātīgāku kontekstu.
Hook ievades lauku atsauce
Visi "hooks" saņem JSON objektu caur stdin ar kopīgiem laukiem un notikumam specifiskiem datiem. Pilnas shēmas sapratne nodrošina sarežģītāku "hook" loģiku.
Kopīgie ievades lauki
Visi "hooks" saņem šādus bāzes laukus:
- event: "Hook" notikuma nosaukums (piem., "PreToolUse")
- sessionId: Pašreizējās Claude sesijas unikālais identifikators
- turnId: Pašreizējās sarunu kārtas identifikators
- timestamp: ISO 8601 laika zīmogs, kad notikums tika izpildīts
Rīku notikumu lauki
Notikumi PreToolUse, PostToolUse un PostToolUseFailure ietver:
- toolName: Izsauktā rīka nosaukums (edit_file, execute_command utt.)
- toolInput: Objekts, kas satur rīka ievades parametrus
- toolResponse: Rīka izvades dati (tikai PostToolUse)
- error: Kļūdu detaļas, ieskaitot ziņojumu un kodu (tikai PostToolUseFailure)
toolInput struktūra atšķiras atkarībā no rīka. Rīkam edit_file tas ietver ceļu un saturu. Rīkam execute_command tas ietver komandu un argumentus.
Atļaujas notikumu lauki
Notikumi PermissionRequest ietver:
- permissionType: Pieprasītā atļaujas veids (file_write, command_execute utt.)
- requestedAction: Konkrēta darbība, kurai nepieciešama atļauja
- resourcePath: Ietekmētā faila ceļš vai resursa identifikators
MCP rīku "Hooks"
Saskaņā ar oficiālo "hooks" atsauces dokumentāciju, "hooks" var saskaņot ar Model Context Protocol (MCP) rīkiem, izmantojot mcpTool matcher lauku. Tas nodrošina "hook" izpildi, kad Claude izmanto ārējos rīkus, ko nodrošina MCP serveri.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
McpTool vērtība saskaņojas ar rīka nosaukumu formātā server-name/tool-name. Tas nodrošina datubāzes vaicājumu, API izsaukumu vai citu ārēju operāciju validācijas loģiku.
GitHub funkciju pieprasījumi norāda pieaugošo interesi par dziļāku MCP integrāciju, ieskaitot "hooks", kas var pārbaudīt MCP servera paziņojumus un reaģēt uz ārējiem notikumiem.
Drošības apsvērumi
Hooks izpildās ar tām pašām atļaujām kā Claude Code. Tas rada drošības sekas vairāklietotāju vidēs un kopīgajām konfigurācijām.
Komandu izpildes smilškaste
Saskaņā ar GitHub problēmu #28044, HTTP "hooks" tiek novirzīti caur smilškastes starpniekserveri, kas ierobežo tīkla piekļuvi un filtrē vides mainīgos. Komandu "hooks" nav šādu ierobežojumu — tie darbojas ar pilnu komandrindas piekļuvi.
Dokumentācija iesaka šādas prakses:
- Nekad neglabājiet akreditācijas datus "hook" komandās
- Izmantojiet vides mainīgos sensitīviem datiem
- Validējiet visu ievadi no ${…} paplašinājumiem
- Ieviesiet taimauta ierobežojumus ārējiem pakalpojumiem
- Izmantojiet asinhronos "hooks" nekritiskām operācijām, lai novērstu bloķēšanu kļūmju gadījumā
Hook izpildes izolācija
Lietotāja līmeņa "hooks" failā ~/.claude/settings.json attiecas uz visiem projektiem. Tas rada riskus, strādājot dažādās uzticamības robežās. Projektu līmeņa "hooks" aizstāj lietotāja "hooks", bet nevar tos pilnībā atspējot.
Claude Code esošā /hooks izvēlne parāda visus aktīvos "hooks" pašreizējai sesijai. Šīs saraksta pārskatīšana pirms darba pie sensitīviem projektiem palīdz identificēt potenciālas drošības problēmas.
Apmeklēšana un problēmu novēršana
Hook kļūmes ne vienmēr skaidri parādās Claude sarunā. Oficiālā dokumentācija sniedz vairākas apmeklēšanas pieejas.
Hook izpildes žurnāli
Claude Code reģistrē "hook" izpildi sesijas apmeklēšanas izvadei. Saskaņā ar problēmu novēršanas rokasgrāmatu, apmeklēšanas žurnālu iespējošana atklāj:
- Kuri "hooks" atbilda katram notikumam
- JSON ievade, kas nosūtīta katram "hook"
- Stdout un stderr izvade no "hook" procesiem
- Izietes kodus un izpildes laiku
- HTTP atbildes kodus un ķermeņus HTTP "hooks" gadījumā
Iespējojiet apmeklēšanas žurnālu, iestatot CLAUDE_DEBUG=1 vidē pirms Claude Code palaišanas.
Neatkarīga "Hook" testēšana
Komandu "hooks" var testēt ārpus Claude Code, manuāli veidojot JSON ievadi:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Tas validē "hook" loģiku, neizraisot faktiskas Claude darbības. Izietes kodam un stdout/stderr izvadei vajadzētu atbilst gaidītajai uzvedībai.
Izplatītas "Hook" kļūmes
Kopienas diskusijas identificē šīs biežās problēmas:
- Taimauta kļūdas: Noklusējuma 10 minūšu taimauts pārāk īss lēniem procesiem — palieliniet ar taimauta lauku
- Ceļu paplašināšanas kļūdas: Mainīgie, piemēram, ${file}, nav definēti notikumiem, kas neietver faila kontekstu
- Atļauju kļūdas: "Hook" skriptiem trūkst izpildes atļauju — palaidiet chmod +x script.sh
- JSON parsēšanas kļūdas: Nepareizi formatēts JSON izvade no "hooks" — validējiet ar jq pirms atgriešanas
- Vides mainīgo nepieejamība: Mainīgie nav pārsūtīti uz "hook" procesu — pārbaudiet Claude Code vidi
Hook veiktspējas sekas
Sinhronie "hooks" bloķē Claude darbplūsmu līdz pabeigšanai. Noklusējuma 10 minūšu taimauts novērš bezgalīgas palikšanas, taču pat īsas aizkavēšanās uzkrājas vairākās operācijās.
Praktizētāji ziņo, ka vienkāršiem validācijas "hooks" ir niecīga ietekme uz veiktspēju. Failu formatēšanas "hooks" rada pamanāmu, bet pieņemamu veiktspējas ietekmi. Ārēji API izsaukumi var radīt darbplūsmas berzi. Smagas aprēķinu operācijas gūst labumu no asinhronās izpildes.
Hook pakešu apvienošana
Vairāki "hooks" var atbilst vienam notikumam. Saskaņā ar atsauces dokumentāciju, "hooks" izpildās secīgi definīcijas secībā. Ja kāds "hook" bloķē darbību, atlikušie "hooks" netiks izpildīti.
Tas ir svarīgi veiktspējas ziņā. Pieci sinhronie "hooks" pa 200ms katrs pievieno vienu sekundi uz notikumu. Saistītu validāciju apvienošana vienā "hook" samazina virs-izdevumus.
Papildu modeļi
Papildus pamata automatizācijai, "hooks" nodrošina sarežģītu darbplūsmas pielāgošanu.
Statišķu "Hook" ķēdes
Hooks var saglabāt stāvokli starp izpildēm, izmantojot failus vai datubāzes. PostToolUse hook var ierakstīt veiksmīgas operācijas, ko vēlāk validē PreToolUse hook:
| #!/bin/bash # Ierakstīt veiksmīgas izmaiņas echo “${toolInput.path}” >> .claude/edit-history.txt |
Pavadošais PreToolUse hook var pārbaudīt šo vēsturi, lai novērstu liekas operācijas vai nodrošinātu secības ierobežojumus.
Nosacīta "Hook" aktivizācija
Vides mainīgie kontrolē "hook" uzvedību izpildes laikā. CLAUDE_SKIP_HOOKS=1 iestatīšana atspējo "hooks" ārkārtas situācijās.
Paši "hooks" var pārbaudīt vides karodziņus:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Lietot stingru validāciju exit 1 fi exit 0 |
Tas nodrošina izstrādes režīma pretstatā ražošanas režīma uzvedību bez konfigurācijas izmaiņām.
Daudzpakāpju validācija
PreToolUse "hooks" var ieviest daudzpakāpju validāciju, kur izietes kods 2 ļauj Claude turpināt ar brīdinājumiem:
- Smagas kļūmes (izietes kods 1): bloķēt bīstamas operācijas
- Vieglas brīdinājumi (izietes kods 2): brīdināt Claude par pārdomām
- Iet cauri ar kontekstu (izietes kods 0 + JSON): sniegt papildu informāciju
Tas rada validācijas spektru, kas ir niansētāks nekā binārs atļaut/liegt.
Integrācija ar CI/CD
Saskaņā ar oficiālo platformas integrācijas dokumentāciju, Claude Code darbojas CI/CD vidēs automatizētai koda pārskatīšanai un problēmu triāžai. "Hooks" paplašina šo automatizāciju.
GitHub Actions darbplūsmas var definēt "hooks", kas nodrošina komandas politiku automatizēto sesiju laikā:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
STRICT_MODE karodziņš aktivizē nosacītu validācijas loģiku "hook" skriptos. Tas nodrošina, ka automatizētās sesijas ievēro stingrākus noteikumus nekā interaktīvā izstrāde.
Revīzijas ceļa ģenerēšana
PostToolUse "hooks" CI vidēs izveido detalizētus visu Claude operāciju revīzijas žurnālus:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Fona žurnālu sagatavošana neietekmē veiktspēju, bet nodrošina pilnu operāciju vēsturi atbilstībai un apmeklēšanai.
Izvēlne /hooks
Claude Code nodrošina /hooks komandu, kas parāda visus aktīvos "hooks" pašreizējai sesijai. Saskaņā ar oficiālo dokumentāciju, šī izvēlne parāda:
- Hook notikuma veids
- Matcher modeļi
- Komanda vai URL beigu punkts
- Vai "hook" darbojas asinhroni
- Konfigurācijas avots (projekts, lietotājs vai spraudnis)
Izvēloties "hook", tiek parādīta tā pilnā konfigurācija un tiek dota iespēja īslaicīgi atspējot to pašreizējai sesijai.
Atspējot vai noņemt "Hooks"
Hooks var atspējot, nenoņemot konfigurāciju, pievienojot "enabled": false pie "hook" definīcijas. Tas saglabā konfigurāciju, neļaujot tai darboties.
Lai neatgriezeniski noņemtu "hook", izdzēsiet tā ierakstu no attiecīgā settings.json faila. Izmaiņas stāsies spēkā nākamajā sesijas restartē vai palaižot /reload.
Hooks prasmēs un aģentos
Saskaņā ar oficiālo dokumentāciju, prasmju vai apakš-aģentu konfigurācijās definētie "hooks" attiecas tikai tad, kad šī prasme vai aģents tiek izpildīts. Tas nodrošina specializētu automatizāciju specifiskām darbplūsmām.
Ap muchturu apakš-aģents var ietvert "hooks", kas reģistrē visus rīku izsaukumus:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Šie "hooks" darbojas tikai "debugger" aģentu sesiju laikā, nevis normālas Claude Code darbības laikā.
Skriptu atsauce pēc ceļa
Hook komandas atbalsta gan relatīvos, gan absolūtos ceļus. Relatīvie ceļi tiek izšķirti no projekta saknes, kur darbojas Claude Code.
Labākās prakses no kopienas diskusijām:
- Saglabājiet "hook" skriptus .claude/hooks/ direktorijā
- Izmantojiet aprakstošus nosaukumus: validate-typescript.sh nevis hook1.sh
- Padariet skriptus izpildāmus: chmod +x .claude/hooks/*.sh
- Iekļaujiet shebang rindu: #!/usr/bin/env bash vai #!/usr/bin/env python3
- Pievienojiet kļūdu apstrādi ar set -e bash skriptos
Nākotnes "Hook" iespējas
GitHub funkciju pieprasījumi atklāj plānotus un pieprasītus "hook" uzlabojumus:
- Iekšējās skriptu "hooks": Definējiet "hook" loģiku tieši settings.json bez ārējiem failiem
- MCP rīku integrācija: Izsaukšanas MCP servera rīki no "hooks", nevis komandrindas komandām
- Daudz-aģentu sadarbība: "Hooks", kas koordinē starp Claude instancēm dažādās mašīnās
- Uzlaboti tipi: TypeScript tipa definīcijas "hook" ievades/izvades shēmām
Saskaņā ar GitHub problēmu #4274, pieprasījums pēc integrētiem "hook" tipiem (MCP rīks, iekšējais skripts, API izsaukums) mērķē uz konfigurācijas vienkāršošanu un izstrādātāja pieredzes uzlabošanu.
Bieži uzdotie jautājumi
Vai "hooks" var novērst Claude bīstamu komandu izpildi?
Jā. PreToolUse "hooks" var bloķēt jebkura rīka izpildi, izņemot ar kodu 1. Tas ietver failu izmaiņas, komandu izpildi un MCP rīku izsaukumus. "Hook" saņem pilnu rīka ievadi un var validēt pret jebkuriem kritērijiem pirms darbības atļaušanas.
Kā es varu apmeklēt "hook", kas nedarbojas?
Iespējojiet apmeklēšanas žurnālu ar CLAUDE_DEBUG=1 pirms Claude Code palaišanas. Pārbaudiet sesijas žurnālus, lai iegūtu "hook" izpildes detaļas, tostarp kuri "hooks" atbilda, nosūtīto JSON ievadi, stdout/stderr izvadi un izietes kodus. Testējiet "hooks" neatkarīgi, pārvirzot parauga JSON uz "hook" skriptu.
Vai "hooks" darbojas ar visām Claude Code platformām?
Hooks darbojas CLI, darbvirsmas lietotnē un VS Code paplašinājumā. Saskaņā ar oficiālo dokumentāciju, "hooks" izpildās visur, kur Claude Code darbojas ar piekļuvi failu sistēmai. Pārlūkprogrammā balstīti Claude un mobilās lietotnes neatbalsta "hooks" smilškastes ierobežojumu dēļ.
Vai "hooks" var mainīt Claude atbildes vai uzvedību?
"Prompt" "hooks" injicē instrukcijas, kas ietekmē Claude uzvedību. Aģentu "hooks" deleģē notikumu apstrādi specializētiem apakš-aģentiem. Tomēr "hooks" nevar tieši mainīt Claude ģenerēto tekstu vai spriešanas procesu — tie darbojas, sniedzot kontekstu un bloķējot darbības.
Kāda ir atšķirība starp asinhroniem un sinhroniem "hooks"?
Sinhronie "hooks" bloķē Claude darbplūsmu līdz pabeigšanai vai taimautam. Asinhronie "hooks" darbojas fonā, nebloķējot. Sinhronie "hooks" var novērst darbības, izmantojot izietes kodus. Asinhronie "hooks" nevar bloķēt, jo Claude turpina pirms "hook" pabeigšanas. Izmantojiet asinhronos žurnālu sagatavošanai un paziņojumiem, sinhronos validācijai.
Kā es varu kopīgot "hooks" visā komandā?
Iekļaujiet .claude/settings.json failu versiju kontrolē. Projektu līmeņa "hooks" attiecas uz visiem komandas locekļiem, kuri noklonē repozitoriju. Organizācijas līmeņa politiku dēļ komandas var uzturēt kopīgu lietotāja līmeņa iestatījumu failu, ko dalībnieki kopē uz ~/.claude/settings.json.
Vai HTTP "hooks" var izsaukt iekšējos API aiz ugunsmūriem?
Jā, ja Claude Code darbojas vidē ar tīkla piekļuvi šiem API. HTTP "hooks" veic standarta POST pieprasījumus no mašīnas, kas vada Claude Code. Korporatīvie ugunsmūri un VPN attiecas parasti. Smilškastes starpniekserveris, kas minēts dokumentācijā, kontrolē vides mainīgo iedarbību, nevis tīkla maršrutēšanu.
Vai "hooks" palielina Claude Code žetonu lietojumu?
"Prompt" "hooks" injicē tekstu Claude kontekstā, kas patērē žetonus. Komandu un HTTP "hooks" tieši neietekmē žetonu lietojumu, taču to izvade (kļūdu ziņojumi, ieteikumi) kļūst par daļu no sarunas konteksta. Izietes kods 2 ar skaidrojošiem ziņojumiem pievieno vairāk konteksta nekā izietes kods 1 ar vienkāršu bloķēšanu.
Secinājums
Claude Code "hooks" pārveido AI palīgu no jaudīga rīka par pilnībā automatizētu izstrādes platformu. Notikumu sistēma nodrošina pārtveršanas punktus visā Claude darbplūsmā — no sesijas inicializācijas līdz konteksta saspiešanai.
Komandu "hooks" apstrādā vietējo validāciju un formatēšanu. HTTP "hooks" integrē ārējos pakalpojumus un datubāzes. "Prompt" "hooks" maina uzvedību, izmantojot konteksta injekciju. Kopā tie nodrošina automatizācijas modeļus, kas nodrošina komandas politiku ievērošanu, uztur kodu kvalitāti un integrējas ar esošo izstrādes infrastruktūru.
Matcher sistēma filtrē "hooks" uz specifiskiem rīkiem un failu modeļiem. Izietes kods un JSON izvade kontrolē lēmumu plūsmu. Asinhronā izpilde novērš bloķēšanu lēnās operācijās. Pilna konfigurācijas shēma atbalsta visu, sākot no vienkāršas automātiskas formatēšanas līdz sarežģītai daudzpakāpju validācijai.
Sāciet ar pamata PostToolUse "hooks" koda formatēšanai. Pievienojiet PreToolUse validāciju, kad parādās politikas. Eksperimentējiet ar "prompt" "hooks" uzvedības modifikācijai. Izveidojiet HTTP integrācijas komandas līmeņa nodrošināšanai.
Pārbaudiet oficiālo Claude Code dokumentāciju, lai iegūtu pilnu "hooks" atsauci un atjauninātu konfigurācijas shēmu, kad tiek piegādātas jaunas iespējas.
