Krótkie podsumowanie: Haki Claude Code to skrypty automatyzacji, które wykonują się w określonych punktach cyklu życia sesji kodowania AI, umożliwiając programistom uruchamianie niestandardowych poleceń, walidację akcji, formatowanie kodu, wysyłanie powiadomień i egzekwowanie zasad projektu. Haki te integrują się z przepływem pracy Claude za pomocą zdarzeń takich jak SessionStart, PreToolUse i PostToolUse, obsługując wzorce wykonywania oparte na poleceniach, HTTP i promptach, z konfigurowalnymi limitami czasu i zachowaniem kodów wyjścia.
System haków Claude Code przekształca asystenta kodowania AI z pomocnego narzędzia w w pełni zautomatyzowane środowisko programistyczne. Większość programistów nie zdaje sobie sprawy z zakresu kontroli dostępnej dzięki hakom.
Oto jednak najważniejsza sprawa – haki to nie tylko uruchamianie skryptów po edycji plików. Zapewniają punkty przechwytywania w całym procesie decyzyjnym Claude. Zanim wykona polecenie. Po niepowodzeniu wywołania narzędzia. Kiedy potrzebuje pozwolenia. Nawet przed przetworzeniem promptów użytkownika.
Ten przewodnik obejmuje wszystko, co zapewnia oficjalna dokumentacja, a także praktyczne wzorce, które – jak pokazują dyskusje społeczności – faktycznie działają w środowiskach produkcyjnych.
Co właściwie robią haki Claude Code
Zgodnie z oficjalną dokumentacją Claude Code, haki to zdefiniowane przez użytkownika polecenia powłoki, punkty końcowe HTTP lub wstrzyknięcia promptów, które są wykonywane w określonych punktach cyklu życia Claude Code. Odbierają one ustrukturyzowane dane wejściowe JSON za pośrednictwem standardowego wejścia i kontrolują przepływ pracy za pomocą kodów wyjścia lub odpowiedzi HTTP.
Automatyzacja jest głębsza niż sugerują większość przewodników. Haki mogą całkowicie zablokować wykonanie narzędzia, wstrzyknąć dodatkowy kontekst do rozumowania Claude, wywołać zewnętrzne usługi i egzekwować zasady walidacji, których Claude musi przestrzegać.
Istnieją trzy podstawowe typy haków:
- Haki poleceń: Skrypty powłoki komunikujące się za pomocą stdout, stderr i kodów wyjścia
- Haki HTTP: Zdalne punkty końcowe, które odbierają żądania POST i zwracają odpowiedzi JSON
- Haki promptów: Dynamiczne instrukcje wstrzykiwane do kontekstu Claude w określonych zdarzeniach
Każdy typ służy innym wzorcom automatyzacji. Haki poleceń obsługują lokalną walidację i formatowanie. Haki HTTP integrują się z zewnętrznymi usługami i bazami danych. Haki promptów modyfikują zachowanie Claude bez procesów zewnętrznych.
Cykl życia haka i system zdarzeń
Oficjalna dokumentacja definiuje wiele zdarzeń haków (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification i inne), które wyzwalają się w przepływie wykonania Claude Code. Zrozumienie, kiedy każde z nich się wyzwala, określa, jaka automatyzacja staje się możliwa.
| Zdarzenie | Kiedy się wyzwala | Może zablokować |
|---|---|---|
| SessionStart | Gdy sesja się rozpoczyna lub wznawia | Nie |
| UserPromptSubmit | Gdy wysyłasz prompt, zanim Claude go przetworzy | Tak |
| PreToolUse | Zanim wywołanie narzędzia zostanie wykonane | Tak |
| PermissionRequest | Gdy pojawia się okno dialogowe z prośbą o pozwolenie | Tak |
| PostToolUse | Po pomyślnym wywołaniu narzędzia | Nie |
| PostToolUseFailure | Po niepowodzeniu wywołania narzędzia | Nie |
| Notification | Gdy Claude Code wysyła powiadomienie | Nie |
| SubmitMessage | Gdy Claude wysyła komunikat do użytkownika | Nie |
| ContextCompaction | Gdy okno kontekstu zbliża się do limitów | Nie |
Możliwość blokowania ma największe znaczenie. Haki PreToolUse mogą zapobiegać niebezpiecznym operacjom przed ich wykonaniem. Kod wyjścia 1 blokuje akcję. Kod wyjścia 0 ją zezwala. Kod wyjścia 2 prosi Claude o ponowne rozważenie.
Ale czekaj. Haki PostToolUse nie mogą cofnąć akcji, ponieważ narzędzie zostało już wykonane. To ograniczenie kształtuje sposób strukturyzowania logiki walidacji. Krytyczne kontrole należą do PreToolUse. Czyszczenie i formatowanie należą do PostToolUse.
Przeglądaj oferty AI Tool Perks podczas konfigurowania Claude Code
Jeśli pracujesz z hakami Claude Code, możesz również wybierać inne narzędzia AI do swojego przepływu pracy. Get AI Perks gromadzi kredyty startowe i zniżki na oprogramowanie dla narzędzi AI i chmurowych w jednym miejscu. Platforma zawiera ponad 200 ofert, z warunkami ofert i wskazówkami dotyczącymi ich odbierania dla każdej z nich.
Szukasz ofert Claude lub innych narzędzi AI?
Sprawdź Get AI Perks, aby:
- przeglądać oferty Claude i innych narzędzi AI
- porównywać warunki ofert przed złożeniem wniosku
- znajdować zniżki dla startupów na cały stos narzędzi
👉 Odwiedź Get AI Perks, aby zapoznać się z aktualnymi ofertami oprogramowania AI.
Konfiguracja i struktura plików
Haki są definiowane w pliku .claude/settings.json w projekcie. Schemat konfiguracji obsługuje haki globalne i dopasowania specyficzne dla narzędzi, które filtrują, kiedy haki są wykonywane.
Podstawowa struktura haka polecenia:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Zmienna ${file} rozszerza się do faktycznej ścieżki pliku z danych wejściowych narzędzia. Zgodnie z oficjalną dokumentacją, haki obsługują te rozszerzenia zmiennych w polach command i args.
Hierarchia lokalizacji haków
Claude Code sprawdza wiele lokalizacji definicji haków, z wyraźną kolejnością pierwszeństwa:
- Poziom projektu: .claude/settings.json w bieżącym obszarze roboczym
- Poziom użytkownika: ~/.claude/settings.json dla wszystkich sesji
- Dostarczane przez wtyczkę: Haki dołączone do zainstalowanych wtyczek
Haki projektowe nadpisują haki użytkownika dla tego samego zdarzenia. Umożliwia to zasady formatowania specyficzne dla projektu, przy jednoczesnym utrzymaniu globalnych procedur obsługi powiadomień.
Wzorce dopasowania do wybiórczego wykonania
System dopasowania filtruje haki do konkretnych narzędzi lub warunków. Bez dopasowań, haki wyzwalają się przy każdej wystąpieniu ich zdarzenia.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Pole pathPattern akceptuje składnię glob. Pole toolName dopasowuje się do wbudowanych narzędzi Claude, takich jak edit_file, execute_command, read_file i create_directory.
Dyskusje społeczności pokazują, że kombinacje dopasowań działają z logiką AND. Wszystkie określone dopasowania muszą zostać dopasowane, aby hak został wykonany.
Haki poleceń: Integracja skryptów powłoki
Haki poleceń wykonują polecenia lub skrypty powłoki ze ustrukturyzowanymi danymi wejściowymi JSON. Stanowią one najczęstszy typ haka do lokalnej automatyzacji.
Oficjalna dokumentacja określa, że haki poleceń odbierają JSON za pośrednictwem standardowego wejścia o tej strukturze:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skrypty analizują te dane wejściowe, aby podejmować decyzje. Hak walidacyjny w Pythonie może wyglądać tak:#!/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(“Nie można edytować chronionych plików”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Kod wyjścia 0 zezwala na operację. Kod wyjścia 1 blokuje ją i wyświetla komunikat stderr dla Claude. Kod wyjścia 2 wyzwala specjalne zachowanie w zależności od zdarzenia.
Zachowanie kodu wyjścia 2
Zgodnie z oficjalną dokumentacją referencyjną haków, kod wyjścia 2 ma znaczenie zależne od zdarzenia (PreToolUse: blokuje i prosi o ponowne rozważenie; UserPromptSubmit: dostarcza kontekst bez blokowania; PermissionRequest: blokuje pozwolenie):
- PreToolUse: Blokuje narzędzie i prosi Claude o ponowne rozważenie z komunikatem stderr jako kontekstem
- UserPromptSubmit: Dostarcza dane wyjściowe stderr jako dodatkowy kontekst bez blokowania
- PermissionRequest: Blokuje udzielenie pozwolenia
Tworzy to pośrednie rozwiązanie między twardym blokowaniem a zezwalaniem. Claude otrzymuje informacje zwrotne o tym, dlaczego akcja może być problematyczna i może dostosować swoje podejście.
Asynchroniczne haki poleceń
Flaga async: true uruchamia haki w tle bez blokowania przepływu pracy Claude. Ma to znaczenie w przypadku powolnych operacji, takich jak powiadomienia o wdrożeniu lub zbieranie metryk.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Gdy hak asynchroniczny się wyzwoli, Claude Code rozpoczyna proces i kontynuuje natychmiast. Pole timeout określa maksymalny czas wykonania w sekundach. Jeśli nie zostanie określony, haki asynchroniczne używają domyślnego limitu czasu wynoszącego 10 minut.
Szczerze mówiąc: haki asynchroniczne nie mogą blokować operacji, ponieważ działają po przejściu Claude. Działają do logowania, powiadomień i czyszczenia – nie walidacji.
Haki HTTP: Integracja usług zewnętrznych
Haki HTTP wysyłają ładunki JSON do zdalnych punktów końcowych i analizują odpowiedzi w celu kontroli decyzji. Umożliwiają integrację z usługami walidacyjnymi, bazami danych i narzędziami stron trzecich.
Podstawowa konfiguracja haka HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktura ładunku odpowiada danym wejściowym haka poleceń, ale dociera jako treść żądania POST HTTP. Odpowiedź określa następną akcję Claude.
Obsługa odpowiedzi HTTP
Zgodnie z oficjalną dokumentacją, haki HTTP interpretują odpowiedzi na podstawie kodu statusu i treści ciała:
| Kod statusu | Efekt | Źródło komunikatu |
|---|---|---|
| 200 | Zezwól na operację | Ciało odpowiedzi (opcjonalne) |
| 400 | Zablokuj operację | Ciało odpowiedzi widoczne dla Claude |
| 500 | Błąd haka, zezwól na operację | Zalogowano, ale nie pokazano Claude |
| Inny | Zezwól na operację | Błąd haka nie blokuje przepływu pracy |
Ciało odpowiedzi może zawierać pole komunikatu, które Claude widzi jako kontekst. Umożliwia to usługom walidacyjnym wyjaśnienie, dlaczego operacja została zablokowana.
Interpolacja zmiennych środowiskowych
Haki HTTP obsługują składnię ${VAR} w polach url, headers i innych polach tekstowych. Zmienne rozwijają się z środowiska, w którym działa Claude Code.
Zgodnie z oficjalną dokumentacją MCP, rozszerzanie zmiennych środowiskowych obejmuje domyślną składnię zastępczą: ${VAR:-default} rozwija się do VAR, jeśli jest ustawione, w przeciwnym razie używa wartości domyślnej.
Ograniczenie bezpieczeństwa: Zgodnie z problemem na GitHub #28044, haki HTTP mogą uzyskiwać dostęp tylko do zmiennych środowiskowych jawnie wymienionych w polu konfiguracji allowedEnvVars. Zapobiega to przypadkowemu ujawnieniu poświadczeń.
Haki promptów: Wstrzykiwanie kontekstu
Haki promptów wstrzykują dynamiczne instrukcje do kontekstu Claude w określonych zdarzeniach. Modyfikują zachowanie bez procesów zewnętrznych ani wywołań API.
| { “event”: “SessionStart”, “prompt”: “Pracujesz nad projektem TypeScript. Zawsze używaj ścisłych sprawdzania null i preferuj async/await zamiast promises.” } |
Wstrzyknięty tekst staje się częścią instrukcji systemowych Claude dla tej sesji. Haki promptów mogą również używać zmiennych szablonu, które rozwijają się na podstawie danych zdarzenia.
Dynamiczne generowanie promptów
Zgodnie z oficjalną dokumentacją, haki promptów obsługują pola poleceń, które generują dynamiczne prompty:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Polecenie otrzymuje standardowe dane wejściowe JSON przez stdin i wyprowadza tekst promptu na stdout. Umożliwia to generowanie instrukcji zależnych od kontekstu na podstawie stanu projektu.
Haki oparte na agentach
Haki agentów określają podagenta, który obsługuje zdarzenie zamiast bezpośredniego wstrzykiwania promptu. Podagent otrzymuje kontekst dotyczący zdarzenia i może przeprowadzać wieloetapowe rozumowanie.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Wywołanie narzędzia nie powiodło się. Przeanalizuj błąd i zaproponuj poprawki.” } |
Nazwany podagent musi być zdefiniowany w konfiguracji projektu. Haki agentów umożliwiają złożoną logikę decyzyjną, której nie zapewnia proste wstrzykiwanie promptów.
Praktyczne wzorce haków
Dyskusje społeczności i przykłady oficjalne ujawniają konkretne wzorce automatyzacji, które niezawodnie działają w produkcji.
Automatyczne formatowanie kodu po edycji
Najczęstszy wzorzec automatycznie formatuje kod po edycji plików przez Claude:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Zmienna ${toolInput.path} rozwija się do ścieżki edytowanego pliku. PostToolUse zapewnia, że formatowanie odbywa się po pomyślnych edycjach, ale nie blokuje przepływu pracy Claude.
Blokowanie modyfikacji plików chronionych
Haki PreToolUse egzekwują zasady ochrony plików:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skrypt weryfikuje ścieżkę docelową pod kątem wzorców chronionych i kończy działanie z kodem 1, aby zablokować niedozwolone edycje.
Otrzymuj powiadomienia, gdy Claude potrzebuje danych wejściowych
Zgodnie z oficjalnym przewodnikiem po przepływie pracy, haki Notification mogą wywoływać alerty na pulpicie lub wysyłać wiadomości do usług zewnętrznych:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Wyzwala się to za każdym razem, gdy Claude Code wysyła powiadomienie, w tym podczas oczekiwania na dane wejściowe od użytkownika lub po zakończeniu zadania.
Ponowne wstrzyknięcie kontekstu po zagęszczeniu
Haki ContextCompaction przywracają ważny kontekst, gdy okno konwersacji się wypełni:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Wyjście polecenia jest wstrzykiwane z powrotem do kontekstu Claude po zagęszczeniu usunie starsze wiadomości. Zapobiega to utracie krytycznych instrukcji specyficznych dla projektu.
Audyt zmian konfiguracji
Śledź, kiedy Claude modyfikuje pliki konfiguracyjne:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Wykonanie asynchroniczne zapobiega blokowaniu Claude podczas zakończenia operacji git. Tworzy to ścieżkę audytu zmian konfiguracji bez ręcznego zatwierdzania.
Wyjście JSON i kontrola decyzji
Haki poleceń mogą generować ustrukturyzowane dane JSON, aby dostarczyć szczegółowe informacje zwrotne poza prostymi kodami wyjścia. Zgodnie z oficjalnym dokumentem referencyjnym, wyjście JSON umożliwia odpowiedzi z wieloma polami, które Claude interpretuje w celu podejmowania decyzji.
| { “allowed”: false, “message”: “Ten plik jest chroniony polityką zespołu”, “suggestion”: “Utwórz nowy plik w src/features/ zamiast tego” } |
Pole allowed kontroluje, czy operacja jest kontynuowana. Komunikat pojawia się dla Claude jako kontekst. Pole suggestion oferuje alternatywne podejścia.
Aby haki mogły generować dane JSON, muszą:
- Zapisać prawidłowy JSON do stdout
- Zakończyć działanie z kodem 0 (dla dozwolonego) lub 1 (dla zablokowanego)
- Zawierać co najmniej pole boolean allowed
Claude Code analizuje dane JSON i wykorzystuje je do ulepszenia pętli informacji zwrotnej. Kody wyjścia nadal określają główną decyzję, ale JSON dostarcza bogatszy kontekst.
Dokumentacja pól wejściowych haków
Wszystkie haki odbierają obiekt JSON przez stdin z polami wspólnymi plus danymi specyficznymi dla zdarzenia. Zrozumienie pełnego schematu umożliwia bardziej zaawansowaną logikę haków.
Wspólne pola wejściowe
Każdy hak otrzymuje te podstawowe pola:
- event: Nazwa zdarzenia haka (np. "PreToolUse")
- sessionId: Unikalny identyfikator bieżącej sesji Claude
- turnId: Identyfikator bieżącej tury konwersacji
- timestamp: Stempel czasowy w formacie ISO 8601, kiedy zdarzenie zostało wyzwolone
Pola zdarzeń narzędzi
Zdarzenia PreToolUse, PostToolUse i PostToolUseFailure obejmują:
- toolName: Nazwa wywoływanego narzędzia (edit_file, execute_command itp.)
- toolInput: Obiekt zawierający parametry wejściowe narzędzia
- toolResponse: Dane wyjściowe narzędzia (tylko PostToolUse)
- error: Szczegóły błędu, w tym komunikat i kod (tylko PostToolUseFailure)
Struktura toolInput różni się w zależności od narzędzia. W przypadku edit_file zawiera ścieżkę i zawartość. W przypadku execute_command zawiera polecenie i argumenty.
Pola zdarzeń zezwolenia
Zdarzenia PermissionRequest obejmują:
- permissionType: Typ żądanego pozwolenia (file_write, command_execute itp.)
- requestedAction: Konkretna akcja wymagająca pozwolenia
- resourcePath: Ścieżka pliku lub identyfikator zasobu, którego dotyczy problem
Haki narzędzi MCP
Zgodnie z oficjalnym dokumentem referencyjnym haków, haki mogą dopasowywać się do narzędzi Model Context Protocol (MCP) za pomocą pola dopasowania mcpTool. Umożliwia to wykonanie haka, gdy Claude używa narzędzi zewnętrznych dostarczanych przez serwery MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Wartość mcpTool dopasowuje się do nazwy narzędzia w formacie nazwa_serwera/nazwa_narzędzia. Umożliwia to logikę walidacji dla zapytań do baz danych, wywołań API lub innych operacji zewnętrznych.
Żądania funkcji na GitHub wskazują na rosnące zainteresowanie głębszą integracją MCP, w tym hakami, które mogą sprawdzać powiadomienia serwerów MCP i reagować na zdarzenia zewnętrzne.
Uwagi dotyczące bezpieczeństwa
Haki wykonują się z tymi samymi uprawnieniami co sam Claude Code. Tworzy to implikacje bezpieczeństwa dla środowisk wieloużytkownikowych i udostępnianych konfiguracji.
Piaskownica wykonania poleceń
Zgodnie z problemem na GitHub #28044, haki HTTP są kierowane przez proxy piaskownicy, które ogranicza dostęp do sieci i filtruje zmienne środowiskowe. Haki poleceń nie mają takich ograniczeń – działają z pełnym dostępem do powłoki.
Dokumentacja zaleca te praktyki:
- Nigdy nie przechowuj poświadczeń w poleceniach haków
- Używaj zmiennych środowiskowych do danych wrażliwych
- Waliduj wszystkie dane wejściowe z rozszerzeń ${...}
- Implementuj limity czasu dla usług zewnętrznych
- Używaj haków asynchronicznych do operacji niekrytycznych, aby zapobiec blokowaniu w przypadku błędów
Izolacja wykonania haków
Haki na poziomie użytkownika w ~/.claude/settings.json dotyczą wszystkich projektów. Stwarza to ryzyko podczas pracy w różnych granicach zaufania. Haki na poziomie projektu nadpisują haki użytkownika, ale nie mogą ich całkowicie wyłączyć.
Menu /hooks w Claude Code pokazuje wszystkie aktywne haki dla bieżącej sesji. Przeglądanie tej listy przed pracą nad wrażliwymi projektami pomaga zidentyfikować potencjalne obawy dotyczące bezpieczeństwa.
Debugowanie i rozwiązywanie problemów
Błędy haków nie zawsze są wyraźnie widoczne w konwersacji Claude. Oficjalna dokumentacja zawiera kilka metod debugowania.
Logi wykonania haków
Claude Code loguje wykonanie haków do debugowania sesji. Zgodnie z przewodnikiem rozwiązywania problemów, włączanie logowania debugowania pokazuje:
- Które haki pasowały do każdego zdarzenia
- Dane wejściowe JSON wysłane do każdego haka
- Wyjście stdout i stderr z procesów haków
- Kody wyjścia i czas wykonania
- Kody odpowiedzi i ciała odpowiedzi dla haków HTTP
Włącz logowanie debugowania, ustawiając CLAUDE_DEBUG=1 w środowisku przed uruchomieniem Claude Code.
Niezależne testowanie haków
Haki poleceń można testować poza Claude Code, ręcznie tworząc dane wejściowe JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Testuje to logikę haka bez wywoływania faktycznych operacji Claude. Kod wyjścia i dane wyjściowe stdout/stderr powinny odpowiadać oczekiwanemu zachowaniu.
Typowe błędy haków
Dyskusje społeczności identyfikują następujące częste problemy:
- Błędy limitu czasu: Domyślny limit 10 minut za krótki dla powolnych operacji – zwiększ za pomocą pola timeout
- Błędy rozszerzania ścieżki: Zmienne takie jak ${file} niezdefiniowane dla zdarzeń, które nie zawierają kontekstu pliku
- Błędy uprawnień: Skrypty haków nie mają uprawnień do wykonywania – uruchom chmod +x script.sh
- Błędy parsowania JSON: Nieprawidłowe dane wyjściowe JSON z haków – waliduj za pomocą jq przed zwróceniem
- Niedostępność zmiennych środowiskowych: Zmienne nie są propagowane do procesu haka – sprawdź środowisko Claude Code
Wpływ wydajności haków
Synchroniczne haki blokują przepływ pracy Claude do momentu zakończenia. Domyślny 10-minutowy limit czasu zapobiega niekończącemu się zawieszaniu, ale nawet krótkie opóźnienia kumulują się w wielu operacjach.
Praktycy zgłaszają, że proste haki walidacyjne mają znikomy wpływ na wydajność. Haki formatujące pliki powodują zauważalny, ale akceptowalny wpływ na wydajność. Wywołania zewnętrznych API mogą powodować tarcie w przepływie pracy. Ciężkie operacje obliczeniowe korzystają z wykonania asynchronicznego.
Pakietowanie haków
Wiele haków może pasować do tego samego zdarzenia. Zgodnie z dokumentacją referencyjną, haki wykonują się sekwencyjnie w kolejności definicji. Jeśli jakikolwiek hak zablokuje operację, pozostałe haki nie zostaną wykonane.
Ma to znaczenie dla wydajności. Pięć haków synchronicznych po 200 ms każdy dodaje jedną sekundę na zdarzenie. Łączenie powiązanych walidacji w jeden hak zmniejsza narzut.
Zaawansowane wzorce
Poza podstawową automatyzacją, haki umożliwiają zaawansowane dostosowywanie przepływu pracy.
Łańcuchy haków z zachowaniem stanu
Haki mogą utrzymywać stan między wykonaniami, używając plików lub baz danych. Hak PostToolUse może rejestrować pomyślne operacje, które hak PreToolUse później waliduje:
| #!/bin/bash # Rejestruj udane edycje echo “${toolInput.path}” >> .claude/edit-history.txt |
Towarzyszący hak PreToolUse może sprawdzać tę historię, aby zapobiec powtarzalnym operacjom lub wymusić ograniczenia kolejności.
Warunkowa aktywacja haków
Zmienne środowiskowe kontrolują zachowanie haków w czasie rzeczywistym. Ustawienie CLAUDE_SKIP_HOOKS=1 wyłącza haki w sytuacjach awaryjnych.
Same haki mogą sprawdzać flagi środowiskowe:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Zastosuj ścisłą walidację exit 1 fi exit 0 |
Umożliwia to zachowanie trybu deweloperskiego versus produkcyjnego bez zmian konfiguracji.
Wielostopniowa walidacja
Haki PreToolUse mogą implementować wielopoziomową walidację, gdzie kod wyjścia 2 pozwala Claude na kontynuowanie z ostrzeżeniami:
- Twarde awarie (wyjście 1): Blokuj niebezpieczne operacje
- Miękkie ostrzeżenia (wyjście 2): Powiadom Claude o ponownym rozważeniu
- Przejście z kontekstem (wyjście 0 + JSON): Dostarcz dodatkowe informacje
Tworzy to spektrum walidacji bardziej zniuansowane niż binarne zezwalanie/odmawianie.
Integracja z CI/CD
Zgodnie z oficjalną dokumentacją integracji platformy, Claude Code działa w środowiskach CI/CD w celu automatycznego przeglądu kodu i triage błędów. Haki rozszerzają tę automatyzację.
Przepływy pracy GitHub Actions mogą definiować haki, które egzekwują zasady zespołu podczas zautomatyzowanych sesji:
| – name: Uruchom Claude Code ze ścisłymi hakami env: STRICT_MODE: 1 run: | claude “Przejrzyj ten PR i zaproponuj ulepszenia” |
Flaga STRICT_MODE aktywuje warunkową logikę walidacji w skryptach haków. Zapewnia to, że zautomatyzowane sesje przestrzegają bardziej rygorystycznych zasad niż interaktywny rozwój.
Generowanie ścieżki audytu
Haki PostToolUse w środowiskach CI tworzą szczegółowe logi audytu wszystkich operacji Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Logowanie w tle nie wpływa na wydajność, ale zapewnia pełną historię operacji do celów zgodności i debugowania.
Menu /hooks
Claude Code zapewnia polecenie /hooks, które wyświetla wszystkie aktywne haki dla bieżącej sesji. Zgodnie z oficjalną dokumentacją, to menu pokazuje:
- Typ zdarzenia haka
- Wzorce dopasowania
- Polecenie lub punkt końcowy URL
- Czy hak działa asynchronicznie
- Źródło konfiguracji (projekt, użytkownik lub wtyczka)
Wybranie haka pokazuje jego pełną konfigurację i pozwala na tymczasowe wyłączenie dla bieżącej sesji.
Wyłącz lub usuń haki
Haki można wyłączyć bez usuwania konfiguracji, dodając "enabled": false do definicji haka. Zachowuje to konfigurację, jednocześnie zapobiegając wykonaniu.
Aby trwale usunąć hak, usuń jego wpis z odpowiedniego pliku settings.json. Zmiany zaczną obowiązywać przy następnym restarcie sesji lub po uruchomieniu /reload.
Haki w umiejętnościach i agentach
Zgodnie z oficjalną dokumentacją, haki zdefiniowane w konfiguracjach umiejętności lub podagentów dotyczą tylko sytuacji, gdy ta umiejętność lub agent jest wykonywany. Umożliwia to specjalistyczną automatyzację dla określonych przepływów pracy.
Podagent debugowania może zawierać haki, które logują wszystkie wywołania narzędzi:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Te haki wyzwalają się tylko podczas sesji agenta debugera, a nie podczas normalnego działania Claude Code.
Odwoływanie się do skryptów według ścieżki
Polecenia haków obsługują zarówno ścieżki względne, jak i bezwzględne. Ścieżki względne są rozwiązywane od katalogu głównego projektu, w którym działa Claude Code.
Najlepsze praktyki z dyskusji społeczności:
- Przechowuj skrypty haków w katalogu .claude/hooks/
- Używaj opisowych nazw: validate-typescript.sh zamiast hook1.sh
- Uczyń skrypty wykonywalnymi: chmod +x .claude/hooks/*.sh
- Dołącz linię shebang: #!/usr/bin/env bash lub #!/usr/bin/env python3
- Dodaj obsługę błędów za pomocą set -e w skryptach bash
Przyszłe możliwości haków
Żądania funkcji na GitHub ujawniają planowane i wnioskowane ulepszenia haków:
- Haki skryptów wbudowanych: Definiuj logikę haka bezpośrednio w settings.json bez zewnętrznych plików
- Integracja narzędzi MCP: Wywołuj narzędzia serwera MCP z haków zamiast poleceń powłoki
- Współpraca wielu agentów: Haki koordynujące między instancjami Claude na różnych maszynach
- Ulepszone typowanie: Definicje typów TypeScript dla schematów wejściowych/wyjściowych haków
Zgodnie z problemem na GitHub #4274, prośba o zintegrowane typy haków (narzędzia MCP, skrypty wbudowane, wywołania API) ma na celu uproszczenie konfiguracji i poprawę doświadczenia programisty.
Często zadawane pytania
Czy haki mogą uniemożliwić Claude wykonanie niebezpiecznych poleceń?
Tak. Haki PreToolUse mogą blokować dowolne wykonanie narzędzia, kończąc działanie z kodem 1. Obejmuje to edycję plików, wykonanie poleceń i wywołania narzędzi MCP. Hak otrzymuje pełne dane wejściowe narzędzia i może walidować według dowolnych kryteriów przed zezwoleniem na operację.
Jak debugować hak, który nie działa?
Włącz logowanie debugowania za pomocą CLAUDE_DEBUG=1 przed uruchomieniem Claude Code. Sprawdź logi sesji, aby uzyskać szczegółowe informacje o wykonaniu haka, w tym które haki pasowały, wysłane dane wejściowe JSON, wyjście stdout/stderr i kody wyjścia. Testuj haki niezależnie, przekazując próbki JSON do skryptu haka.
Czy haki działają ze wszystkimi platformami Claude Code?
Haki działają w aplikacji CLI, desktopowej i rozszerzeniu VS Code. Zgodnie z oficjalną dokumentacją, haki wykonują się wszędzie tam, gdzie działa Claude Code z dostępem do systemu plików. Claude oparte na przeglądarce i aplikacje mobilne nie obsługują haków ze względu na ograniczenia piaskownicy.
Czy haki mogą modyfikować odpowiedzi lub zachowanie Claude?
Haki promptów wstrzykują instrukcje, które wpływają na zachowanie Claude. Haki agentów delegują obsługę zdarzeń do specjalistycznych podagentów. Jednak haki nie mogą bezpośrednio modyfikować wygenerowanego tekstu ani procesu rozumowania Claude – działają poprzez dostarczanie kontekstu i blokowanie operacji.
Jaka jest różnica między hakami asynchronicznymi a synchronicznymi?
Synchroniczne haki blokują przepływ pracy Claude do momentu zakończenia lub upływu limitu czasu. Asynchroniczne haki działają w tle bez blokowania. Haki synchroniczne mogą zapobiegać operacjom za pomocą kodów wyjścia. Haki asynchroniczne nie mogą blokować, ponieważ Claude kontynuuje przed zakończeniem haka. Używaj asynchronicznych do logowania i powiadomień, synchronicznych do walidacji.
Jak udostępniać haki w zespole?
Umieść plik .claude/settings.json w systemie kontroli wersji. Haki na poziomie projektu dotyczą wszystkich członków zespołu, którzy klonują repozytorium. W przypadku zasad obowiązujących w całej organizacji, zespoły mogą utrzymywać wspólny plik ustawień na poziomie użytkownika, który członkowie kopiują do ~/.claude/settings.json.
Czy haki HTTP mogą wywoływać wewnętrzne API za zaporami sieciowymi?
Tak, jeśli Claude Code działa w środowisku z dostępem do sieci do tych API. Haki HTTP wysyłają standardowe żądania POST z maszyny uruchamiającej Claude Code. Zapory korporacyjne i VPN stosują się normalnie. Proxy piaskownicy wspomniane w dokumentacji kontroluje ujawnianie zmiennych środowiskowych, a nie routing sieciowy.
Czy haki zwiększają zużycie tokenów przez Claude Code?
Haki promptów wstrzykują tekst do kontekstu Claude, co zużywa tokeny. Haki poleceń i HTTP nie wpływają bezpośrednio na zużycie tokenów, ale ich wyjście (komunikaty o błędach, sugestie) staje się częścią kontekstu konwersacji. Kod wyjścia 2 z wyjaśniającymi komunikatami dodaje więcej kontekstu niż kod wyjścia 1 z prostym blokowaniem.
Wnioski
Haki Claude Code przekształcają asystenta AI z potężnego narzędzia w w pełni zautomatyzowaną platformę programistyczną. System zdarzeń zapewnia punkty przechwytywania w całym przepływie pracy Claude – od inicjalizacji sesji po zagęszczenie kontekstu.
Haki poleceń obsługują lokalną walidację i formatowanie. Haki HTTP integrują usługi zewnętrzne i bazy danych. Haki promptów modyfikują zachowanie poprzez wstrzykiwanie kontekstu. Razem umożliwiają one wzorce automatyzacji, które egzekwują zasady zespołu, utrzymują jakość kodu i integrują się z istniejącą infrastrukturą programistyczną.
System dopasowań filtruje haki do konkretnych narzędzi i wzorców plików. Kody wyjścia i dane wyjściowe JSON kontrolują przepływ decyzyjny. Wykonanie asynchroniczne zapobiega blokowaniu w przypadku powolnych operacji. Kompletny schemat konfiguracji obsługuje wszystko, od prostego automatycznego formatowania po złożoną, wielopoziomową walidację.
Zacznij od prostych haków PostToolUse do formatowania kodu. Dodaj walidację PreToolUse w miarę pojawiania się zasad. Eksperymentuj z hakami promptów w celu modyfikacji zachowania. Twórz integracje HTTP w celu egzekwowania zasad w całym zespole.
Sprawdź oficjalną dokumentację Claude Code, aby uzyskać pełny dokument referencyjny haków i zaktualizowany schemat konfiguracji, gdy dostępne będą nowe funkcje.
