Rychlé shrnutí: Claude Code háčky jsou automatizační skripty, které se spouštějí ve specifických bodech životního cyklu během relací kódování s AI, což umožňuje vývojářům spouštět vlastní příkazy, ověřovat akce, formátovat kód, odesílat oznámení a vynucovat pravidla projektu. Tyto háčky se integrují s pracovním postupem Claude prostřednictvím událostí jako SessionStart, PreToolUse a PostToolUse, podporují vzory spouštění založené na příkazech, HTTP a výzvách s konfigurovatelnými časovými limity a chováním výstupního kódu.
Systém háčků Claude Code transformuje asistenta kódování s AI z užitečného nástroje na plně automatizované vývojové prostředí. Většina vývojářů si neuvědomuje míru kontroly dostupnou prostřednictvím háčků.
Tohle je ta věc – háčky nejsou jen o spouštění skriptů po úpravách souborů. Poskytují záchytné body v celém procesu rozhodování Claude. Než provede příkaz. Poté, co volání nástroje selže. Když potřebuje povolení. Dokonce i před zpracováním uživatelských výzev.
Tato příručka pokrývá vše, co oficiální dokumentace poskytuje, plus praktické vzory, které diskuse komunity odhalují, že skutečně fungují v produkčních prostředích.
Co háčky Claude Code skutečně dělají
Podle oficiální dokumentace Claude Code jsou háčky uživatelem definované shell příkazy, koncové body HTTP nebo injektáže výzev, které se spouštějí ve specifických bodech životního cyklu Claude Code. Přijímají strukturovaný JSON vstup prostřednictvím stdin a ovládají pracovní postup prostřednictvím výstupních kódů nebo odpovědí HTTP.
Automatizace jde hlouběji, než naznačuje většina průvodců. Háčky mohou zcela zablokovat provádění nástrojů, vkládat další kontext do uvažování Claude, spouštět externí služby a vynucovat validační pravidla, která Claude musí respektovat.
Existují tři hlavní typy háčků:
- Háčky příkazů: Shell skripty, které komunikují prostřednictvím stdout, stderr a výstupních kódů
- Háčky HTTP: Vzdálené koncové body, které přijímají POST požadavky a vracejí JSON odpovědi
- Háčky výzev: Dynamické instrukce vložené do kontextu Claude ve specifických událostech
Každý typ slouží různým vzorům automatizace. Háčky příkazů zpracovávají lokální validaci a formátování. Háčky HTTP se integrují s externími službami a databázemi. Háčky výzev upravují chování Claude bez externích procesů.
Životní cyklus háčků a systém událostí
Oficiální dokumentace definuje více událostí háčků (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification a další), které se spouštějí během prováděcího toku Claude Code. Pochopení, kdy se každá spustí, určuje, jaká automatizace je možná.
| Událost | Kdy se spustí | Může blokovat |
|---|---|---|
| SessionStart | Když relace začne nebo se obnoví | Ne |
| UserPromptSubmit | Když odešlete výzvu, předtím, než ji Claude zpracuje | Ano |
| PreToolUse | Před spuštěním volání nástroje | Ano |
| PermissionRequest | Když se zobrazí dialog povolení | Ano |
| PostToolUse | Poté, co volání nástroje uspěje | Ne |
| PostToolUseFailure | Poté, co volání nástroje selže | Ne |
| Notification | Když Claude Code odešle oznámení | Ne |
| SubmitMessage | Když Claude odešle zprávu uživateli | Ne |
| ContextCompaction | Když se okno kontextu blíží limitům | Ne |
Schopnost blokování je nejdůležitější. Háčky PreToolUse mohou zabránit nebezpečným operacím před jejich provedením. Výstupní kód 1 blokuje akci. Výstupní kód 0 ji umožňuje. Výstupní kód 2 vyzve Claude k přehodnocení.
Ale počkat. Háčky PostToolUse nemohou vrátit zpět akce, protože nástroj již byl proveden. Toto omezení formuje způsob, jakým je validační logika strukturována. Kritické kontroly patří do PreToolUse. Vyčištění a formátování patří do PostToolUse.
Prohlížejte si benefity AI nástrojů při nastavování Claude Code
Pokud pracujete s háčky Claude Code, možná také vybíráte další nástroje AI kolem vašeho pracovního postupu. Get AI Perks shromažďuje počáteční kredity a slevy na software pro AI a cloudové nástroje na jednom místě. Platforma obsahuje přes 200 nabídek s podmínkami benefitů a pokyny k jejich uplatnění pro každou z nich.
Hledáte benefity pro Claude nebo jiné AI nástroje?
Zkontrolujte Get AI Perks a:
- prohlížejte si nabídky Claude a dalších AI nástrojů
- porovnejte podmínky benefitů před podáním žádosti
- najděte slevy pro startupy napříč vaším softwarovým vybavením
👉 Navštivte Get AI Perks a prozkoumejte aktuální benefity softwaru AI.
Struktura konfigurace a souborů
Háčky jsou definovány v souboru .claude/settings.json v rámci projektu. Schéma konfigurace podporuje globální háčky a párovače specifické pro nástroje, které filtrují, kdy se háčky spouštějí.
Základní struktura háčku příkazu:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
${file} proměnná se rozšíří na skutečnou cestu souboru ze vstupu nástroje. Podle oficiální dokumentace háčky podporují tato rozšíření proměnných v polích command a args.
Hierarchie umístění háčků
Claude Code kontroluje více umístění pro definice háčků s jasným pořadím priority:
- Úroveň projektu: .claude/settings.json v aktuálním pracovním prostoru
- Uživatelská úroveň: ~/.claude/settings.json pro všechny relace
- Poskytovatel pluginu: Háčky dodávané s nainstalovanými pluginy
Háčky na úrovni projektu přepisují uživatelské háčky pro stejnou událost. To umožňuje pravidla formátování specifická pro projekt a zároveň zachovává globální obsluhu oznámení.
Vzory párovačů pro selektivní spouštění
Systém párovačů filtruje háčky na konkrétní nástroje nebo podmínky. Bez párovačů se háčky spouštějí při každém výskytu jejich události.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Pole pathPattern přijímá syntaxi glob. Pole toolName se páruje s předdefinovanými nástroji Claude, jako jsou edit_file, execute_command, read_file a create_directory.
Diskuze komunity odhalují, že kombinace párovačů fungují s logikou AND. Všechny zadané párovače musí odpovídat, aby se háček spustil.
Háčky příkazů: Integrace shell skriptů
Háčky příkazů spouštějí shell příkazy nebo skripty se strukturovaným JSON vstupem. Představují nejběžnější typ háčku pro lokální automatizaci.
Oficiální dokumentace uvádí, že háčky příkazů přijímají JSON přes stdin s touto strukturou:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripty analyzují tento vstup, aby mohly činit rozhodnutí. Python validační háček by mohl vypadat takto:#!/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(“Nelze upravovat chráněné soubory”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Výstupní kód 0 umožňuje operaci. Výstupní kód 1 ji blokuje a zobrazuje zprávu stderr pro Claude. Výstupní kód 2 spouští speciální chování v závislosti na události.
Chování výstupního kódu 2
Podle oficiální dokumentace háčků má výstupní kód 2 význam specifický pro událost (PreToolUse: blokuje a vyzývá k přehodnocení; UserPromptSubmit: poskytuje kontext bez blokování; PermissionRequest: blokuje povolení):
- PreToolUse: Blokuje nástroj a vyzývá Claude k přehodnocení s chybovou zprávou stderr jako kontextem
- UserPromptSubmit: Poskytuje výstup stderr jako dodatečný kontext bez blokování
- PermissionRequest: Blokuje udělení povolení
Toto vytváří střední cestu mezi tvrdým blokováním a povolením. Claude dostává zpětnou vazbu o tom, proč může být akce problematická a může upravit svůj přístup.
Asynchronní háčky příkazů
Příznak async: true spouští háčky na pozadí, aniž by blokoval pracovní postup Claude. To je důležité pro pomalé operace, jako jsou oznámení o nasazení nebo sběr metrik.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Když se spustí asynchronní háček, Claude Code spustí proces a okamžitě pokračuje. Pole timeout nastavuje maximální dobu provádění v sekundách. Pokud není zadáno, asynchronní háčky používají výchozí časový limit 10 minut.
Upřímně řečeno: asynchronní háčky nemohou blokovat operace, protože běží poté, co Claude pokračuje. Fungují pro logování, oznámení a vyčištění—ne pro validaci.
Háčky HTTP: Integrace externích služeb
Háčky HTTP posílají JSON payloady na vzdálené koncové body a analyzují odpovědi pro řízení rozhodování. Umožňují integraci s validačními službami, databázemi a nástroji třetích stran.
Základní konfigurace háčku HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktura payloadu odpovídá vstupu háčku příkazu, ale je doručena jako tělo požadavku HTTP POST. Odpověď určuje další akci Claude.
Zpracování odpovědí HTTP
Podle oficiální dokumentace interpretují háčky HTTP odpovědi na základě stavového kódu a obsahu těla:
| Stavový kód | Efekt | Zdroj zprávy |
|---|---|---|
| 200 | Povolit operaci | Tělo odpovědi (volitelné) |
| 400 | Blokovat operaci | Tělo odpovědi zobrazené Claude |
| 500 | Chyba háčku, povolit operaci | Zalogováno, ale nezobrazeno Claude |
| Jiný | Povolit operaci | Selhání háčku neblokuje pracovní postup |
Tělo odpovědi může obsahovat pole zprávy, které Claude vidí jako kontext. To umožňuje validačním službám vysvětlit, proč byla operace zablokována.
Interpolace proměnných prostředí
Háčky HTTP podporují syntaxi ${VAR} v polích url, headers a dalších řetězcových polích. Proměnné se rozšiřují z prostředí, kde běží Claude Code.
Podle oficiální dokumentace MCP zahrnuje rozšíření proměnných prostředí výchozí záložní syntaxi: ${VAR:-default} se rozšíří na VAR, pokud je nastaveno, jinak použije výchozí hodnotu.
Bezpečnostní omezení: Podle problému GitHub #28044 mohou háčky HTTP přistupovat pouze k proměnným prostředí explicitně uvedeným v konfiguračním poli allowedEnvVars. To zabraňuje náhodnému úniku pověření.
Háčky výzev: Vkládání kontextu
Háčky výzev vkládají dynamické instrukce do kontextu Claude při specifických událostech. Upravují chování bez externích procesů nebo volání API.
| { “event”: “SessionStart”, “prompt”: “Pracuješ na projektu TypeScript. Vždy používej striktní kontroly null a preferuj async/await před promises.” } |
Vložený text se stane součástí systémových instrukcí Claude pro danou relaci. Háčky výzev mohou také používat šablonové proměnné, které se rozšiřují na základě dat události.
Dynamické generování výzev
Podle oficiální dokumentace podporují háčky výzev pole příkazů, které generují dynamické výzvy:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Příkaz přijímá standardní JSON vstup prostřednictvím stdin a výstupuje text výzvy do stdout. To umožňuje generování instrukcí závislých na kontextu na základě stavu projektu.
Háčky založené na agentech
Háčky agentů určují podsložku, která zpracovává událost místo přímého vkládání výzev. Podsložka přijímá kontext o události a může provádět víceúrovňové uvažování.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Volání nástroje selhalo. Analyzujte chybu a navrhněte opravy.” } |
Pojmenovaná podsložka musí být definována v konfiguraci projektu. Háčky agentů umožňují složitou logiku rozhodování, kterou jednoduché vkládání výzev neposkytuje.
Praktické vzory háčků
Diskuze komunity a oficiální příklady odhalují specifické vzory automatizace, které spolehlivě fungují v produkci.
Automatické formátování kódu po úpravách
Nejběžnější vzor automaticky formátuje kód po úpravách souborů Claude:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
${toolInput.path} proměnná se rozšíří na cestu upravovaného souboru. PostToolUse zajišťuje, že formátování proběhne po úspěšných úpravách, ale neblokuje pracovní postup Claude.
Blokovat úpravy chráněných souborů
Háčky PreToolUse vynucují pravidla ochrany souborů:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skript ověří cílovou cestu oproti chráněným vzorům a ukončí se s kódem 1, aby zabránil zakázaným úpravám.
Získejte upozornění, když Claude potřebuje vstup
Podle oficiální průvodce pracovním postupem mohou háčky Notification spouštět desktopová upozornění nebo odesílat zprávy externím službám:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Toto se spustí vždy, když Claude Code odešle oznámení, včetně čekání na vstup uživatele nebo po dokončení úkolu.
Znovu vložte kontext po kompresi
Háčky ContextCompaction obnovují důležitý kontext, když se konverzační okno zaplní:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Výstup příkazu se znovu vloží do kontextu Claude po kompresi, která odstraní starší zprávy. To zabraňuje ztrátě kritických instrukcí specifických pro projekt.
Auditování změn konfigurace
Sledujte, kdy Claude upravuje konfigurační soubory:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asynchronní provádění zabraňuje blokování Claude během dokončování operací git. To vytváří auditní stopu změn konfigurace bez manuálního stagingu.
Výstup JSON a řízení rozhodování
Háčky příkazů mohou vytvářet strukturovaný JSON pro poskytnutí podrobných zpětných informací nad rámec jednoduchých výstupních kódů. Podle oficiálního referenčního průvodce umožňuje JSON výstup odpovědi s více poli, které Claude interpretuje pro rozhodování.
| { “allowed”: false, “message”: “Tento soubor je chráněn zásadami týmu”, “suggestion”: “Vytvořte nový soubor v src/features/ místo toho” } |
Pole allowed řídí, zda operace pokračuje. Zpráva se zobrazí Claude jako kontext. Pole suggestion poskytuje alternativní přístupy.
Aby háčky generovaly JSON, musí:
- Zapsat platný JSON do stdout
- Ukončit se s kódem 0 (pro povolené) nebo 1 (pro blokované)
- Zahrnovat minimálně boolean pole allowed
Claude Code analyzuje JSON a používá jej k vylepšení zpětnovazební smyčky. Výstupní kódy stále určují primární rozhodnutí, ale JSON poskytuje bohatší kontext.
Odkaz na pole vstupu háčku
Všechny háčky přijímají objekt JSON prostřednictvím stdin s běžnými poli plus daty specifickými pro událost. Pochopení kompletního schématu umožňuje sofistikovanější logiku háčků.
Běžná vstupní pole
Každý háček obdrží tato základní pole:
- event: Název události háčku (např. “PreToolUse”)
- sessionId: Jedinečný identifikátor aktuální relace Claude
- turnId: Identifikátor aktuálního obratu konverzace
- timestamp: Časové razítko ISO 8601, kdy se událost spustila
Pole události nástroje
Události PreToolUse, PostToolUse a PostToolUseFailure zahrnují:
- toolName: Název volaného nástroje (edit_file, execute_command atd.)
- toolInput: Objekt obsahující vstupní parametry nástroje
- toolResponse: Výstupní data nástroje (pouze PostToolUse)
- error: Podrobnosti o chybě včetně zprávy a kódu (pouze PostToolUseFailure)
Struktura toolInput se liší podle nástroje. Pro edit_file obsahuje cestu a obsah. Pro execute_command obsahuje příkaz a argumenty.
Pole události povolení
Události PermissionRequest zahrnují:
- permissionType: Typ požadovaného povolení (file_write, command_execute atd.)
- requestedAction: Konkrétní akce vyžadující povolení
- resourcePath: Cesta k souboru nebo identifikátor zdroje, na který se akce vztahuje
Háčky nástrojů MCP
Podle oficiální dokumentace háčků se háčky mohou shodovat s nástroji protokolu Model Context Protocol (MCP) pomocí pole párovače mcpTool. To umožňuje spuštění háčku, když Claude používá externí nástroje poskytované servery MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Hodnota mcpTool se shoduje s názvem nástroje ve formátu server-name/tool-name. To umožňuje validační logiku pro databázové dotazy, volání API nebo jiné externí operace.
Požadavky na funkce na GitHubu naznačují rostoucí zájem o hlubší integraci MCP, včetně háčků, které mohou kontrolovat oznámení serveru MCP a reagovat na externí události.
Bezpečnostní aspekty
Háčky se spouštějí se stejnými oprávněními jako samotný Claude Code. To vytváří bezpečnostní důsledky pro víceuživatelská prostředí a sdílené konfigurace.
Sandbox pro provádění příkazů
Podle problému GitHub #28044 jsou háčky HTTP směrovány přes sandbox proxy server, který omezuje přístup k síti a filtruje proměnné prostředí. Háčky příkazů nemají taková omezení—spouštějí se s plným přístupem k shellu.
Dokumentace doporučuje tyto postupy:
- Nikdy neukládejte pověření do příkazů háčků
- Používejte proměnné prostředí pro citlivá data
- Ověřujte všechen vstup z rozšíření ${...}
- Implementujte časové limity pro externí služby
- Používejte asynchronní háčky pro nekritické operace, abyste zabránili blokování při selháních
Izolace provádění háčků
Háčky na uživatelské úrovni v ~/.claude/settings.json se vztahují na všechny projekty. To vytváří rizika při práci napříč různými hranicemi důvěry. Háčky na úrovni projektu přepisují uživatelské háčky, ale nemohou je zcela zakázat.
Nabídka /hooks v Claude Code zobrazuje všechny aktivní háčky pro aktuální relaci. Kontrola tohoto seznamu před prací na citlivých projektech pomáhá identifikovat potenciální bezpečnostní problémy.
Ladění a řešení problémů
Selhání háčků se ne vždy jasně projeví v konverzaci Claude. Oficiální dokumentace poskytuje několik přístupů k ladění.
Protokoly provádění háčků
Claude Code zaznamenává provádění háčků do výstupu ladění relace. Podle průvodce řešením problémů povolení ladicího logování odhalí:
- Které háčky se shodovaly pro každou událost
- JSON vstup odeslaný každému háčku
- Výstup stdout a stderr z procesů háčků
- Výstupní kódy a dobu provádění
- Kódy a těla odpovědí HTTP pro háčky HTTP
Povolte ladicí logování nastavením CLAUDE_DEBUG=1 v prostředí před spuštěním Claude Code.
Nezávislé testování háčků
Háčky příkazů lze testovat mimo Claude Code manuálním konstruováním JSON vstupu:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
To ověřuje logiku háčků, aniž by byly spuštěny skutečné operace Claude. Výstupní kód a výstup stdout/stderr by měly odpovídat očekávanému chování.
Běžná selhání háčků
Diskuze komunity identifikují tyto časté problémy:
- Chyby časového limitu: Výchozí 10minutový časový limit je příliš krátký pro pomalé operace—zvýšit pomocí pole timeout
- Selhání rozšíření cesty: Proměnné jako ${file} nejsou definovány pro události, které neobsahují kontext souboru
- Chyby oprávnění: Skripty háčků nemají oprávnění ke spuštění—spusťte chmod +x script.sh
- Chyby analýzy JSON: Poškozený JSON výstup z háčků—ověřte pomocí jq před vrácením
- Nedostupnost proměnných prostředí: Proměnné nejsou propagovány do procesu háčku—zkontrolujte prostředí Claude Code
Dopady výkonu háčků
Synchronní háčky blokují pracovní postup Claude až do dokončení. Výchozí 10minutový časový limit zabraňuje nekonečnému zamrzání, ale i krátká zpoždění se akumulují napříč více operacemi.
Odborníci hlásí, že jednoduché validační háčky mají zanedbatelný dopad na výkon. Háčky pro formátování souborů způsobují znatelný, ale přijatelný dopad na výkon. Volání externích API mohou vytvářet tření v pracovním postupu. Těžké výpočetní operace těží z asynchronního provádění.
Dávkování háčků
Více háčků se může shodovat se stejnou událostí. Podle referenční dokumentace se háčky spouštějí sekvenčně v pořadí definice. Pokud jakýkoli háček zablokuje operaci, zbývající háčky se nespustí.
To je důležité pro výkon. Pět synchronních háčků po 200 ms každý přidá jednu sekundu na událost. Kombinace souvisejících validací do jednoho háčku snižuje režii.
Pokročilé vzory
Kromě základní automatizace umožňují háčky pokročilé přizpůsobení pracovního postupu.
Stavové řetězení háčků
Háčky mohou udržovat stav mezi spuštěními pomocí souborů nebo databází. Háček PostToolUse může zaznamenávat úspěšné operace, které háček PreToolUse později ověří:
| #!/bin/bash # Zaznamenat úspěšné úpravy echo “${toolInput.path}” >> .claude/edit-history.txt |
Doprovodný háček PreToolUse by mohl kontrolovat tuto historii, aby zabránil redundantním operacím nebo vynucoval omezení pořadí.
Podmíněné aktivace háčků
Proměnné prostředí řídí chování háčků za běhu. Nastavení CLAUDE_SKIP_HOOKS=1 zakáže háčky pro nouzové situace.
Samotné háčky mohou kontrolovat příznaky prostředí:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Použít striktní validaci exit 1 fi exit 0 |
Toto umožňuje chování v režimu vývoje vs. produkčního režimu bez změn konfigurace.
Vícefázové ověření
Háčky PreToolUse mohou implementovat vícefázové ověření, kde výstupní kód 2 umožňuje Claude pokračovat s varováním:
- Tvrdé selhání (výstup 1): Blokování nebezpečných operací
- Měkká varování (výstup 2): Upozornění Claude k přehodnocení
- Provést s kontextem (výstup 0 + JSON): Poskytněte další informace
Toto vytváří validační spektrum, které je nuancovanější než binární povolení/zamítnutí.
Integrace s CI/CD
Podle oficiální dokumentace platformní integrace běží Claude Code v prostředích CI/CD pro automatizovanou kontrolu kódu a třídění problémů. Háčky rozšiřují tuto automatizaci.
Pracovní postupy GitHub Actions mohou definovat háčky, které vynucují týmové zásady během automatizovaných relací:
| – name: Spustit Claude Code se striktními háčky env: STRICT_MODE: 1 run: | claude “Zkontroluj tento PR a navrhni vylepšení” |
Příznak STRICT_MODE aktivuje podmíněnou validační logiku ve skriptech háčků. To zajišťuje, že automatizované relace dodržují přísnější pravidla než interaktivní vývoj.
Generování auditní stopy
Háčky PostToolUse v prostředích CI vytvářejí podrobné auditní záznamy všech operací Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Zpracování na pozadí neovlivňuje výkon, ale poskytuje kompletní historii operací pro účely dodržování předpisů a ladění.
Nabídka /hooks
Claude Code poskytuje příkaz /hooks, který zobrazuje všechny aktivní háčky pro aktuální relaci. Podle oficiální dokumentace tato nabídka zobrazuje:
- Typ události háčku
- Vzory párovačů
- Příkaz nebo koncový bod URL
- Zda se háček spouští asynchronně
- Zdroj konfigurace (projekt, uživatel nebo plugin)
Výběr háčku zobrazí jeho kompletní konfiguraci a umožní dočasné deaktivování pro aktuální relaci.
Zakázat nebo odstranit háčky
Háčky lze zakázat bez odstranění konfigurace přidáním "enabled": false k definici háčku. To zachová konfiguraci a zabrání spuštění.
Chcete-li háček trvale odstranit, odstraňte jeho záznam z příslušného souboru settings.json. Změny se projeví při příštím restartu relace nebo při spuštění /reload.
Háčky v dovednostech a agentech
Podle oficiální dokumentace se háčky definované v konfiguracích dovedností nebo podsložek vztahují pouze tehdy, když se tato dovednost nebo agent spustí. To umožňuje specializovanou automatizaci pro specifické pracovní postupy.
Podsložka pro ladění může obsahovat háčky, které zaznamenávají všechna volání nástrojů:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Tyto háčky se spustí pouze během relací agenta debugger, nikoli během normálního provozu Claude Code.
Odkaz na skripty podle cesty
Příkazy háčků podporují relativní i absolutní cesty. Relativní cesty se řeší z kořenového adresáře projektu, kde běží Claude Code.
Osvědčené postupy z komunitních diskusí:
- Ukládejte skripty háčků do adresáře .claude/hooks/
- Používejte popisné názvy: validate-typescript.sh ne hook1.sh
- Udělejte skripty spustitelné: chmod +x .claude/hooks/*.sh
- Zahrňte řádek shebang: #!/usr/bin/env bash nebo #!/usr/bin/env python3
- Přidejte zpracování chyb pomocí set -e v bash skriptech
Budoucí schopnosti háčků
Požadavky na funkce na GitHubu odhalují plánovaná a požadovaná vylepšení háčků:
- Inline skriptové háčky: Definujte logiku háčků přímo v settings.json bez externích souborů
- Integrace nástrojů MCP: Volání nástrojů serveru MCP z háčků místo shell příkazů
- Spolupráce více agentů: Háčky, které koordinují mezi instancemi Claude na různých strojích
- Rozšířené typování: TypeScript definice typů pro vstupní/výstupní schémata háčků
Podle problému GitHub #4274 si požadavek na integrované typy háčků (nástroj MCP, inline skript, volání API) klade za cíl zjednodušit konfiguraci a zlepšit uživatelský zážitek vývojáře.
Často kladené otázky
Mohou háčky zabránit Claude v provádění nebezpečných příkazů?
Ano. Háčky PreToolUse mohou zablokovat jakékoli spuštění nástroje tím, že ukončí s kódem 1. To zahrnuje úpravy souborů, spouštění příkazů a volání nástrojů MCP. Háček přijímá kompletní vstup nástroje a může ověřit podle jakýchkoli kritérií před povolením operace.
Jak mohu ladit háček, který nefunguje?
Povolte ladicí logování pomocí CLAUDE_DEBUG=1 před spuštěním Claude Code. Zkontrolujte protokoly relace pro podrobnosti o provádění háčků včetně toho, které háčky se shodovaly, JSON vstup, který byl odeslán, výstup stdout/stderr a výstupní kódy. Testujte háčky nezávisle zasláním vzorového JSON do skriptu háčku.
Fungují háčky se všemi platformami Claude Code?
Háčky fungují v CLI, desktopové aplikaci a rozšíření VS Code. Podle oficiální dokumentace se háčky spouštějí všude tam, kde Claude Code běží s přístupem k souborovému systému. Prohlížečové Claude a mobilní aplikace nepodporují háčky kvůli omezením sandboxu.
Mohou háčky upravovat odpovědi nebo chování Claude?
Háčky výzev vkládají instrukce, které ovlivňují chování Claude. Háčky agentů delegují zpracování událostí na specializované podsložky. Háčky však nemohou přímo upravovat generovaný text nebo proces uvažování Claude—pracují poskytováním kontextu a blokováním operací.
Jaký je rozdíl mezi asynchronními a synchronními háčky?
Synchronní háčky blokují pracovní postup Claude až do dokončení nebo časového limitu. Asynchronní háčky běží na pozadí bez blokování. Synchronní háčky mohou zabránit operacím prostřednictvím výstupních kódů. Asynchronní háčky nemohou blokovat, protože Claude pokračuje před dokončením háčku. Pro logování a oznámení používejte asynchronní, pro validaci synchronní.
Jak mohu sdílet háčky napříč týmem?
Soubor .claude/settings.json nahrajte do správy verzí. Háčky na úrovni projektu se vztahují na všechny členy týmu, kteří repozitář klonují. Pro zásady platné v celé organizaci mohou týmy udržovat sdílený soubor nastavení na uživatelské úrovni, který si členové zkopírují do ~/.claude/settings.json.
Mohou háčky HTTP volat interní API za firewally?
Ano, pokud Claude Code běží v prostředí s přístupem k síti k těmto API. Háčky HTTP provádějí standardní požadavky POST ze stroje, na kterém běží Claude Code. Firewally a VPN společnosti platí normálně. Sandbox proxy server zmíněný v dokumentaci řídí expozici proměnných prostředí, nikoli směrování sítě.
Zvyšují háčky využití tokenů Claude Code?
Háčky výzev vkládají text do kontextu Claude, což spotřebovává tokeny. Háčky příkazů a HTTP přímo neovlivňují využití tokenů, ale jejich výstup (chybové zprávy, návrhy) se stává součástí kontextu konverzace. Výstupní kód 2 s vysvětlujícími zprávami přidává více kontextu než výstupní kód 1 s jednoduchým blokováním.
Závěr
Háčky Claude Code transformují asistenta AI z výkonného nástroje na plně automatizovanou vývojovou platformu. Systém událostí poskytuje záchytné body v celém pracovním postupu Claude—od inicializace relace až po kompresi kontextu.
Háčky příkazů zpracovávají lokální validaci a formátování. Háčky HTTP integrují externí služby a databáze. Háčky výzev upravují chování prostřednictvím vkládání kontextu. Dohromady umožňují vzory automatizace, které vynucují týmové zásady, udržují kvalitu kódu a integrují se s existující vývojovou infrastrukturou.
Systém párovačů filtruje háčky na konkrétní nástroje a vzory souborů. Výstupní kódy a JSON výstup řídí tok rozhodování. Asynchronní provádění zabraňuje blokování u pomalých operací. Kompletní schéma konfigurace podporuje vše od jednoduchého automatického formátování až po složité vícefázové ověření.
Začněte s jednoduchými háčky PostToolUse pro formátování kódu. Přidejte validaci PreToolUse, jak se objeví zásady. Experimentujte s háčky výzev pro úpravu chování. Vytvářejte integrace HTTP pro vynucování napříč týmem.
Podívejte se na oficiální dokumentaci Claude Code pro kompletní referenci háčků a aktualizované schéma konfigurace, jakmile budou vydány nové funkce.
