Claude Code Hooks: praktyczny przewodnik po automatyzacji workflowu

Podczas pracy z Claude Code szybko zauważysz typowy problem: pisze dobry kod, ale pomija ważne kroki, jak formatowanie, uruchamianie testów czy przestrzeganie zasad bezpieczeństwa. Kończy się to ciągłym powtarzaniem tych samych przypomnień. Hooki Claude Code pozwalają zautomatyzować te przypomnienia, automatycznie uruchamiając polecenia powłoki w określonych momentach twojego workflowu.

W tym tutorialu pokazuję, jak skonfigurować hooki do formatowania kodu, uruchamiania testów, wysyłania powiadomień i ochrony plików. Zbudujesz system automatyzacji, który egzekwuje twoje standardy deweloperskie bez ręcznej ingerencji.

Jeśli chcesz dowiedzieć się więcej o Claude Code, zajrzyj do naszego poradnika najlepsze praktyki Claude Code oraz tutorialu Claude Skills. Jeśli chcesz nauczyć się konfigurowania instrukcji na poziomie projektu, zobacz poradnik pisania pliku CLAUDE.md.

TL;DR

• Hooki Claude Code to polecenia powłoki uruchamiane automatycznie w określonych punktach cyklu życia Claude Code (przed/po wywołaniach narzędzi, przy starcie sesji, gdy Claude się zatrzymuje)

• Konfiguruj je w .claude/settings.json (projekt) lub ~/.claude/settings.json (globalnie) za pomocą JSON z wydarzeniami, matcherami i poleceniami

• Używaj hooków PreToolUse, by blokować niebezpieczne operacje zanim do nich dojdzie (kod wyjścia 2 = blokada)

• Używaj hooków PostToolUse do zadań porządkowych, jak formatowanie, lintowanie lub uruchamianie testów po tym, jak Claude zapisze kod

• Hooki otrzymują kontekst w formacie JSON na stdin i przekazują wyniki przez kody wyjścia, stdout oraz stderr

Czym są hooki Claude Code?

Hooki Claude Code to polecenia powłoki uruchamiane automatycznie, gdy w twojej sesji kodowania z AI wystąpią określone zdarzenia. Pomyśl o nich jak o automatycznych wyzwalaczach, które odpalają twoje skrypty w precyzyjnych momentach—zanim Claude zapisze plik, po uruchomieniu polecenia albo gdy wyśle ci powiadomienie.

System działa, monitorując działania Claude Code i dopasowując je do reguł zdefiniowanych w pliku konfiguracyjnym. Gdy nastąpi dopasowanie, twoje polecenie uruchamia się z dostępem do kontekstu tego, co właśnie się stało. Daje ci to kontrolę nad zachowaniem Claude'a i pozwala automatyzować powtarzalne zadania, które w innym wypadku wymagałyby ręcznej pracy.

Oto podstawowy hook, który uruchamia formatter kodu za każdym razem, gdy Claude zapisze plik Pythona:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black ."
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Ten hook ma trzy części: 

• Zdarzenie: PostToolUse (po zakończeniu działania przez Claude'a)

• Matcher: Write (tylko przy zapisie plików)

• Polecenie: python -m black . (sformatuj pliki Pythona w bieżącym katalogu)

Hook otrzymuje szczegółowe informacje o tym, co właśnie zrobił Claude, poprzez dane JSON wysyłane na wejście skryptu, dzięki czemu możesz tworzyć bardziej zaawansowaną automatyzację reagującą na konkretne zmiany plików.

Jeśli chcesz pójść dalej z automatyzacją w Claude Code, nasz tutorial Claude Code Routines pokazuje, jak planować cykliczne uruchamianie hooków i agentów w chmurze.

Zobaczmy teraz, jak stworzyć hooki od zera i zarejestrować je w Claude Code.

Wymagania wstępne

Zanim zaczniesz, potrzebujesz kilku rzeczy:

• Zainstalowany i działający Claude Code: Powinieneś swobodnie korzystać z Claude Code przy podstawowych zadaniach programistycznych

• Obeznanie z wierszem poleceń: Hooki uruchamiają polecenia powłoki, więc musisz znać podstawowe polecenia terminala w swoim systemie operacyjnym

• Dostęp do edytora tekstu: Będziesz edytować pliki konfiguracyjne JSON, aby ustawić hooki

• Katalog projektu: Projekt, w którym możesz bezpiecznie testować hooki, nie ryzykując ważnej pracy

Nie musisz być ekspertem od skryptów powłoki, ale znajomość poleceń takich jak ls, cd oraz podstawowych operacji na plikach ułatwi śledzenie przykładów. Jeśli dopiero zaczynasz z bashem lub terminalem, polecam nasz kurs Introduction to Shell.

Pierwsze kroki z hookami Claude Code

Skoro już wiesz, czym są hooki, skonfigurujmy twoją pierwszą automatyzację. Proces polega na wyborze właściwego zdarzenia, skonfigurowaniu prostej reguły i przetestowaniu jej podstawowym poleceniem.

Zrozumienie zdarzeń hooków

Claude Code udostępnia ponad 25 zdarzeń hooków. Tabela poniżej obejmuje 10, których będziesz używać najczęściej. Pełną listę znajdziesz w oficjalnej dokumentacji hooków.

PreToolUse i PostToolUse to najczęstsze zdarzenia. PreToolUse uruchamia się, zanim Claude wykona akcję, taką jak zapis pliku czy uruchomienie polecenia, dzięki czemu idealnie nadaje się do walidacji lub blokowania niebezpiecznych operacji. PostToolUse działa po zakończeniu akcji i świetnie sprawdza się w zadaniach porządkowych, takich jak formatowanie kodu czy uruchamianie testów.

UserPromptSubmit wyzwala się, gdy wysyłasz prompt do Claude'a, zanim zacznie go przetwarzać. Możesz go użyć do dodawania kontekstu do rozmowy lub walidacji, czy prompty spełniają określone wymagania.

Notification działa, gdy Claude wysyła alerty, np. prosi o zgodę na uruchomienie polecenia lub potrzebuje twojego wkładu. PermissionRequest wyzwala się, gdy Claude Code wyświetla okno zgody, co pozwala automatycznie zatwierdzać lub odrzucać prośby w imieniu użytkownika.

Stop i SubagentStop wyzwalają się, gdy Claude kończy odpowiedź, co jest przydatne do finalnych kontroli lub generowania raportów. Różnica jest taka, że Stop odpala się po zakończeniu ogólnej odpowiedzi Claude'a, a SubagentStop wtedy, gdy pomocnik uruchomiony przez narzędzie („subagent”) zakończy swoją pracę.

Pozostałe zdarzenia, PreCompact, SessionStart i SessionEnd, dotyczą sytuacji specyficznych dla cyklu życia. PreCompact uruchamia się tuż przed skróceniem historii rozmowy. „SessionStart” odpala się na początku nowej sesji, aby ustawić domyślne wartości, a SessionEnd wyzwala się przy zamykaniu sesji, umożliwiając sprzątanie lub końcowe raportowanie.

Zrozumienie matcherów

Matchery to filtry decydujące, które działania Claude Code wyzwolą hook. Technicznie są to łańcuchy interpretowane jako wyrażenia regularne, więc możesz używać dopasowań dokładnych lub bardziej elastycznych wzorców. 

Najbardziej przydatne są proste matchery, jak Write (odpala się przy zapisie pliku) czy Edit (odpala się przy edycji treści), oraz kombinacje typu Edit|Write, by objąć wiele akcji. 

Możesz też używać prefiksów typu Notebook.*, aby dopasować wszystkie narzędzia zaczynające się od „Notebook”. Jeśli chcesz, by hook odpalał się przy każdej akcji, użyj uniwersalnego regexu .*, pustego łańcucha ("") lub pozostaw matcher pusty.

Ponieważ matchery rozróżniają wielkość liter i działają tylko na nazwach akcji, najlepiej utrzymywać je możliwie precyzyjne. Gdy potrzebujesz dokładniejszej kontroli (np. ograniczyć hook do określonych typów plików), możesz odczytać ładunek JSON przekazywany do hooka i zastosować własne regexy lub warunki.

Tworzenie pierwszego hooka w Claude Code

Claude Code oferuje dwa sposoby konfiguracji hooków: przez interaktywne polecenie /hooks lub poprzez bezpośrednią edycję plików konfiguracyjnych. Zacznijmy od podejścia interaktywnego, bo jest bardziej przyjazne na start.

Użycie polecenia /hooks:

1. Otwórz Claude Code i wpisz /hooks w interfejsie czatu

2. Wybierz zdarzenie wyzwalające (dla tego przykładu wybierz PostToolUse)

3. W menu wybierz „Add new hook”

4. Ustaw wzorzec matchera (wpisz Write, aby celować w zapis plików)

5. Wpisz swoje polecenie:

• Mac: say "Task complete"

• Windows: powershell -c [console]::beep()

• Linux: spd-say "Task complete"

6. Zapisz konfigurację i wróć do Claude Code, naciskając Esc trzy razy

Polecenie /hooks automatycznie zaktualizuje twój plik ustawień i przeładuje konfigurację. Możesz też w każdej chwili użyć /hooks, aby podejrzeć istniejące hooki lub wprowadzić zmiany.

Jeśli wolisz edycję plików konfiguracyjnych, hooki znajdują się w ~/.claude/settings.json dla ustawień globalnych, w .claude/settings.json w katalogu projektu (skomituj do repo, aby współdzielić hooki w zespole) lub w .claude/settings.local.json dla prywatnych hooków, które domyślnie są ignorowane przez gita. Dla naszego przykładu wyglądałoby to tak:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Task complete'"
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Po ręcznej edycji pliku zrestartuj Claude Code lub użyj polecenia /hooks, aby przeładować konfigurację. Teraz za każdym razem, gdy Claude zapisze plik, usłyszysz powiadomienie dźwiękowe.

Testowanie hooka

Zanim pójdziesz dalej, sprawdź, czy hook faktycznie działa:

1. Poproś Claude'a o zapis dowolnego pliku Pythona (np. „Utwórz plik hello.py, który wypisuje hello world”)

2. Powinieneś usłyszeć powiadomienie dźwiękowe, gdy Claude zakończy operację zapisu

3. Jeśli nic nie słyszysz, sprawdź transkrypt Claude Code, naciskając Ctrl-O, aby zobaczyć ewentualne komunikaty o błędach

4. Typowe problemy to: nieznalezione polecenie hooka, złe uprawnienia pliku lub błędy składni w pliku konfiguracyjnym

Doprowadzenie do działania tego prostego testu oszczędzi ci czasu na debugowanie przy budowaniu bardziej złożonych hooków. Jeśli właśnie ręcznie edytowałeś plik ustawień, zmieniłeś matcher lub zdarzenie, albo zainstalowałeś nowe narzędzia używane w poleceniu hooka, pomocne może być ponowne otwarcie /hooks lub restart Claude'a, by przeładować konfigurację.

Ten podstawowy schemat (zdarzenie, matcher, polecenie) stanowi fundament całej automatyzacji hooków. Możesz go rozwinąć, dodając wiele poleceń uruchamianych równocześnie przy tym samym zdarzeniu. Na przykład możesz chcieć jednocześnie odtworzyć dźwięk i utworzyć kopię zapasową, gdy Claude zapisze plik. 

Możesz też tworzyć osobne matchery dla różnych narzędzi w tym samym zdarzeniu, tak aby zapis pliku wyzwalał inne akcje niż edycja kodu. Wszystkie hooki pasujące do tego samego wzorca narzędzia uruchamiają się równolegle. Jeśli skonfigurujesz wiele matcherów dla tego samego zdarzenia, każdy hook uruchomi się, gdy dopasuje się jego matcher.

Praca z wejściami hooków

Gdy Claude Code wyzwala hooka, wysyła informacje o tym, co właśnie się stało, przez standardowe wejście (stdin) — strumień danych trafiający bezpośrednio do twojego polecenia w momencie jego uruchomienia. Te dane sprawiają, że hooki są potężne, a nie tylko przypadkowo odpalanymi skryptami. 

Claude Code pakuje te informacje jako JSON i przekazuje je do skonfigurowanego polecenia — czy to prostego polecenia terminalowego, czy własnego skryptu.

Anatomia wejść hooków

Każdy hook otrzymuje obiekt JSON z podstawowymi polami dotyczącymi bieżącej sesji:

{
  "session_id": "abc123",
  "transcript_path": "/Users/you/.claude/projects/my-project/conversation.jsonl", 
  "cwd": "/Users/you/my-project",
  "hook_event_name": "PostToolUse"
}Obsługiwane przez

Przetłumaczmy każdy element:

• session_id: identyfikuje bieżącą rozmowę

• transcript_path: wskazuje historię rozmowy

• cwd: pokazuje katalog roboczy

• hook_event_name: informuje, które zdarzenie się wyzwoliło

Posiadanie tego kontekstu pozwala twoim hookom podejmować inteligentne decyzje: możesz śledzić, która rozmowa wyzwoliła akcję, w razie potrzeby uzyskać dostęp do pełnej historii czatu lub uruchamiać polecenia we właściwym katalogu.

Warianty wejść zależne od zdarzenia

Zdarzenia narzędziowe, takie jak PreToolUse i PostToolUse, zawierają dodatkowe szczegóły o akcji — to tutaj hooki stają się naprawdę użyteczne do automatyzacji. W PreToolUse podany jest tool_input, a w PostToolUse dodatkowo tool_response:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.py",
    "content": "print('Hello world')"
  },
  "tool_response": {
    "filePath": "/path/to/file.py", 
    "success": true
  }
}Obsługiwane przez

Wejście hooka zawiera file_path z ścieżką pliku zapisywanego lub edytowanego, a content — dokładny tekst, który narzędzie ma zapisać. Po wykonaniu akcja narzędzia zwraca w odpowiedzi końcowy filePath (zwróć uwagę na camelCase), aby potwierdzić, który plik faktycznie został zmieniony, oraz flagę success wskazującą, czy operacja zakończyła się powodzeniem. 

Dzięki tym szczegółom twoje hooki mogą reagować różnie w zależności od tego, co się wydarzyło. Możesz formatować tylko pliki Pythona, tworzyć kopie zapasowe tylko ważnych katalogów czy wysyłać powiadomienia tylko przy modyfikacji określonych typów plików.

Zdarzenia takie jak UserPromptSubmit są prostsze, bo nie obejmują narzędzi:

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit", 
  "prompt": "Write a function to calculate factorial"
}Obsługiwane przez

Zauważ, że hooki UserPromptSubmit nie używają matcherów w konfiguracji. Wyzwalają się dla wszystkich promptów, a nie operacji narzędzi. Nadają się idealnie do logowania rozmów, automatycznego dodawania kontekstu projektowego lub walidowania promptów, zanim Claude je przetworzy.

Praktyczne odczytywanie wejścia hooka

Stwórzmy hooka, który loguje każdy prompt użytkownika. Rozwiązuje to problem gubienia śladu tego, o co prosiłeś Claude'a, zwłaszcza podczas długich sesji kodowania. Najpierw konfiguracja hooka:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/log_prompts.py"
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Następnie utwórz skrypt Pythona w ~/.claude/log_prompts.py o następującej treści:

#!/usr/bin/env python3
import json
import sys
from datetime import datetime

# Read JSON data from stdin
input_data = json.load(sys.stdin)

# Extract information
session_id = input_data.get("session_id", "unknown")
prompt = input_data.get("prompt", "")
timestamp = datetime.now().isoformat()

# Log the prompt
log_entry = f"{timestamp} | Session: {session_id[:8]} | {prompt}\n"
with open("prompt_history.txt", "a") as f:
    f.write(log_entry)Obsługiwane przez

Skrypt odczytuje dane JSON wysyłane przez Claude Code i loguje prompt wraz z kontekstem sesji. Tworzy to przeszukiwalną historię interakcji, co jest nieocenione, gdy po tygodniach chcesz przypomnieć sobie, jak rozwiązałeś dany problem.

Praca z wyjściami hooków

Po uruchomieniu twojego polecenia hook musi przekazać Claude Code informację, co się stało i czy kontynuować normalnie. Ten mechanizm kontroli zamienia hooki z prostych narzędzi do logowania w potężną automatyzację workflowu, która może sterować zachowaniem Claude'a. Dzieje się to przez trzy kanały: standardowe wyjście (stdout), standardowe wyjście błędów (stderr) i kody wyjścia.

Kanały wyjścia i kody wyjścia

Standardowe wyjście (stdout) to zwykłe wyjście. Na przykład, jeśli coś wypiszesz, trafi to do stdout. W większości hooków to, co pojawia się w transkrypcie Claude Code po naciśnięciu Ctrl-O, dając ci zapis tego, co zrobiła automatyzacja, bez zaśmiecania głównej rozmowy.

Standardowe wyjście błędów (stderr) służy do komunikatów o błędach. Możesz pisać na stderr używając 

• Python: print("message", file=sys.stderr) lub

• Wiersz poleceń: echo "message" >&2

Kluczowa różnica polega na tym, że stderr może być wysłane bezpośrednio do Claude'a do automatycznego przetworzenia, co pozwala mu reagować na problemy wykryte przez twoje hooki.

Kody wyjścia mówią Claude Code, co robić dalej:

• Kod wyjścia 0: Sukces (pokazuje użytkownikowi stdout)

• Kod wyjścia 2: Błąd blokujący (wysyła stderr do Claude'a)

• Inne kody: Błąd nieblokujący (pokazuje stderr użytkownikowi, ale kontynuuje)

Ten system daje ci precyzyjną kontrolę, kiedy Claude ma się zatrzymać, kontynuować lub otrzymać informację zwrotną o tym, co wykryła twoja automatyzacja. Zobaczmy przykłady dla dwóch najważniejszych kodów wyjścia.

Kod wyjścia 0: Normalne działanie

Większość hooków używa kodu 0, aby wskazać, że wszystko poszło dobrze. Oto kompletny hook, który loguje operacje na plikach i powiadamia użytkownika:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import datetime; open('activity.log','a').write('File written: ' + datetime.datetime.now().isoformat() + '\\n'); print('Logged file operation')\""
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Ten hook uruchamia dwie akcje: zapis do pliku logu, a potem wydruk komunikatu do transkryptu. Można to zrobić na wiele sposobów, ale to podejście jest wieloplatformowe i nie zależy od specyfiki wiersza poleceń.

Ponieważ nie ma jawnego kodu wyjścia, domyślnie jest to 0. Wydrukowana wiadomość pojawia się w transkrypcie Claude Code, dając informację zwrotną, że logowanie zadziałało. Ten wzorzec świetnie się sprawdza przy budowie ścieżek audytu lub śledzeniu zmian, jakie Claude wprowadza w twoim projekcie z czasem.

Kod wyjścia 2: Blokowanie z informacją zwrotną

Kod wyjścia 2 wysyła twój komunikat o błędzie bezpośrednio do Claude'a, pozwalając mu automatycznie zareagować. Tu hooki stają się mechanizmem bezpieczeństwa, a nie tylko automatyzacją. Oto hook, który blokuje niebezpieczne operacje na plikach:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/security_check.py"
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Musisz utworzyć skrypt kontroli bezpieczeństwa w ~/.claude/security_check.py:

#!/usr/bin/env python3
import json
import sys

# Read hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Check for dangerous patterns
dangerous_paths = ["/etc/", "/usr/", "production.conf"]
is_dangerous = any(pattern in file_path for pattern in dangerous_paths)

if is_dangerous:
    # Block the operation and tell Claude why
    print(f"Blocked modification of {file_path} - this appears to be a system or production file", file=sys.stderr)
    sys.exit(2)  # Sends stderr message to Claude
else:
    # Allow the operation
    print(f"Approved modification of {file_path}")
    sys.exit(0)  # Shows stdout in transcriptObsługiwane przez

Gdy ten hook wykryje niebezpieczną ścieżkę, wychodzi z kodem 2. Claude Code wysyła komunikat ze stderr do Claude'a, który może wytłumaczyć, dlaczego operacja została zablokowana, i zaproponować alternatywy. To zapobiega przypadkowemu uszkodzeniu plików systemowych, a jednocześnie informuje Claude'a o twoich zasadach bezpieczeństwa.

Budowa inteligentnego hooka powiadomień dla Claude Code

Zbudujmy ulepszony hook powiadomień, który łączy przetwarzanie wejścia z mądrym sterowaniem wyjściem. Rozwiązuje to problem hałasu z naszego pierwotnego hooka, który alertował przy każdej zmianie pliku:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/smart_notify.py"
          }
        ]
      }
    ]
  }
}Obsługiwane przez

Utwórz skrypt powiadomień w ~/.claude/smart_notify.py:

#!/usr/bin/env python3
import json
import sys
import os
import subprocess

# Read the hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Categorize file importance
important_extensions = [".py", ".js", ".ts", ".java", ".cpp"]
config_files = ["Dockerfile", "requirements.txt", "package.json"]

is_code = any(file_path.endswith(ext) for ext in important_extensions)
is_config = any(filename in file_path for filename in config_files)

if is_code:
    # Important: notify and log
    print(f"Code file modified: {os.path.basename(file_path)}")
    subprocess.run(["say", "Code updated"], check=False)  # Mac
    sys.exit(0)  # Show message in transcript
elif is_config:
    # Very important: louder notification
    print(f"Configuration file changed: {os.path.basename(file_path)}")
    subprocess.run(["say", "Configuration updated - review changes"], check=False)
    sys.exit(0)
else:
    # Not important: silent success
    sys.exit(0)Obsługiwane przez

Ten hook odczytuje wejście, aby zrozumieć, który plik zmodyfikowano, podejmuje decyzje o wadze powiadomienia na podstawie typu pliku, używa stdout do logowania ważnych zmian w transkrypcie, wyzwala różne alerty dźwiękowe w zależności od typu pliku i zawsze kończy się kodem 0, ponieważ to działania informacyjne, a nie blokujące.

Połączenie analizy wejścia i kontroli wyjścia tworzy hooka, który zachowuje się inteligentnie w zależności od kontekstu, zapewniając właściwy poziom informacji zarówno tobie, jak i Claude Code. Zamiast irytujących powiadomień dla każdego pliku tymczasowego, słyszysz tylko o zmianach istotnych dla twojego projektu.

Pamiętaj, że w tym przykładzie użyto polecenia say, które jest dostępne w macOS. Na Linuksie możesz użyć notify-send, a w Windows polecenia PowerShell, aby uzyskać podobne powiadomienia.

Częste potknięcia przy hookach Claude Code

Kilka rzeczy potrafi utrudnić życie w pierwszym tygodniu pracy z hookami:

Instrukcje echo w profilach powłoki psują hooki. Hooki działają w nieinteraktywnych powłokach, które źródłują twój ~/.zshrc lub ~/.bashrc. Jeśli profil ma bezwarunkowe echo, dopisują one tekst do stdout hooka i psują parsowanie JSON. Owiń je warunkiem sprawdzającym powłokę interaktywną:

if [[ $- == *i* ]]; then
  echo "Welcome back"
fiObsługiwane przez

Hooki Stop mogą zapętlać się bez końca. Hook Stop, który wychodzi z kodem 2, zmusza Claude'a do dalszej pracy. Jeśli twój skrypt nie sprawdza stop_hook_active z wejścia JSON i nie kończy się czysto, gdy jest true, będziesz się kręcić aż do timeoutu. Zawsze dodawaj wczesną gardę.

Matchery rozróżniają wielkość liter. bash nie dopasuje Bash. Używaj dokładnej nazwy narzędzia, jak w Claude Code.

Wyjście jest ograniczone do 10 000 znaków. Jeśli hook wygeneruje więcej, zostanie to ucięte przed wstrzyknięciem do kontekstu Claude'a. Trzymaj stdout zwięzłe i przekazuj tylko to, co model potrzebuje, by działać.

Mylenie hooków zespołowych i osobistych. Hooki w .claude/settings.json są współdzielone z zespołem (skomituj je do repo). Dla prywatnych hooków, których nie chcesz udostępniać, użyj .claude/settings.local.json, który jest domyślnie ignorowany przez gita.

Hooki vs. umiejętności: kiedy używać których

Hooki i Claude Skills mają różne cele i najlepiej działają razem. Skill to plik markdown, który uczy Claude'a jak coś robić (procedury, konwencje, szablony). Hook to polecenie powłoki, które egzekwuje regułę w sposób deterministyczny, niezależnie od decyzji Claude'a.

Różnica jest istotna: skill to sugestia, którą model może zignorować pod presją; hook odpala się za każdym razem. Napisz skill, by udokumentować procedurę migracji zespołu. Napisz hook PostToolUse, by uruchamiać linter migracji na każdym pliku .sql, który zapisze Claude. Skill sprawia, że Claude jest kompetentny; hook sprawia, że jest rozliczalny.

Zaawansowane wzorce dla hooków Claude Code

Poza podstawowymi powiadomieniami i logowaniem hooki mogą rozwiązywać realne problemy workflowu deweloperskiego, z którymi zespoły mierzą się na co dzień. Oto kilka pomysłów do adaptacji w twoich projektach.

Najlepsze jest to, że wcale nie musisz budować tych hooków ręcznie. Możesz po prostu podać Claude Code jeden z poniższych pomysłów na prompt wraz z dokumentacją hooków, a wygeneruje on odpowiedni kod i JSON do konfiguracji.

Każdy z tych wzorców można dostosować do twoich narzędzi i workflowu. Zacznij od tych, które rozwiązują twoje największe codzienne bolączki, a potem rozszerzaj automatyzację, gdy poczujesz się pewniej w tworzeniu hooków.

Zaawansowane hooki dla bezpieczeństwa i zgodności

Hooki świetnie wymuszają zasady bezpieczeństwa i standardy zgodności. Oto cztery przypadki użycia.

Skaner kluczy API

• Problem: Przypadkowe commitowanie sekretów do systemu kontroli wersji

• Wyzwalacze: Przed zapisem dowolnego pliku

• Rozwiązanie: Skanowanie treści plików w poszukiwaniu kluczy API, tokenów i haseł za pomocą wzorców regex

„Utwórz skrypt Pythona, który odczytuje wejściowy JSON hooka, wyciąga treść pliku i używa wzorców regex do wykrywania popularnych formatów sekretów, jak api_key=, token: czy password=.  Dla każdego podejrzanego dopasowania wykonaj lokalną weryfikację i nigdy nie wysyłaj surowych sekretów na zewnątrz. 

Wysyłaj do API Anthropic tylko zamaskowane fragmenty (np. zachowaj 4 znaki prefiksu/sufiksu) lub hashe, by analizować podejrzane ciągi i rozstrzygnąć, czy to faktyczne sekrety, czy nazwy zmiennych. Zakończ kodem 2 i przekaż Claude'owi informację o wykrytych sekretach oraz bezpieczniejszych alternatywach.”

Egzekwowanie nagłówków licencyjnych

• Problem: Projekty open source z brakującymi wymaganymi nagłówkami licencji w nowych plikach

• Wyzwalacze: Przed zapisem plików źródłowych

• Rozwiązanie: Walidacja, że nowe pliki .py, .js, .java zawierają właściwy tekst licencji

„Przeanalizuj wejście hooka, aby pobrać treść pliku, i sprawdź, czy w pierwszych 10 liniach znajduje się tekst licencji, używając dopasowania łańcuchów. Dla bardziej zaawansowanej walidacji wyślij nagłówek pliku do Claude'a przez API Anthropic, aby potwierdzić obecność właściwych informacji o prawach autorskich i licencji. Zablokuj tworzenie pliku kodem 2, jeśli brakuje nagłówków, i dostarcz Claude'owi właściwy szablon licencji do dodania.”

Strażnik plików produkcyjnych

• Problem: Przypadkowa modyfikacja krytycznych plików konfiguracyjnych systemu

• Wyzwalacze: Przed edycją plików w wrażliwych katalogach

• Rozwiązanie: Blokowanie zmian w /etc/, nginx.conf, database.yml i innych krytycznych konfiguracjach

„Wyciągnij ścieżkę pliku z wejścia JSON hooka i sprawdź, czy pasuje do wzorców, jak /etc/, production.yml czy innych krytycznych nazw. Użyj API Claude'a, aby przeanalizować ścieżkę i stwierdzić, czy to plik konfiguracyjny mogący wpłynąć na systemy produkcyjne. Zakończ kodem 2 i przekaż konkretne wskazówki o bezpieczniejszych praktykach, gdy wykryto niebezpieczne ścieżki.”

Optymalizator obrazów

• Problem: Duże pliki obrazów spowalniające aplikacje i repozytoria

• Wyzwalacze: Po dodaniu nowych plików graficznych

• Rozwiązanie: Kompresja plików PNG/JPEG przy zachowaniu jakości

„Przeanalizuj wejście hooka, aby pobrać ścieżkę pliku, i sprawdź po rozszerzeniu, czy to obraz. Uruchom narzędzia do kompresji, takie jak imageoptim, lub wywołaj API TinyPNG, by skompresować obraz z zachowaniem jakości. Zaloguj wyniki kompresji do stdout, aby zobaczyć oszczędność rozmiaru pliku w transkrypcie Claude'a.”

Zaawansowane hooki dla automatyzacji kontroli wersji

Workflowy Git i dokumentacja to obszary, w których hooki też są bardzo przydatne. Oto kilka pomysłów.

Walidator gałęzi Gita

• Problem: Członkowie zespołu przypadkowo wypychający zmiany na chronione gałęzie

• Wyzwalacze: Przed dowolnym zapisem lub edycją pliku

• Rozwiązanie: Sprawdzanie bieżącej gałęzi Gita i blokowanie operacji na main/master/production

„Użyj prostego polecenia bash git branch --show-current, by pobrać nazwę bieżącej gałęzi i porównać ją z listą chronionych. Jeśli jesteś na chronionej gałęzi, zakończ kodem 2 i wyślij Claude'owi komunikat o zasadach ochrony gałęzi. Dla złożonych reguł nazewnictwa użyj API Claude'a, aby przeanalizować nazwy gałęzi i ocenić dopasowanie do wzorców ochrony.”

Inteligentny auto-commit

• Problem: Zapominanie o commitach lub słabe wiadomości commitów

• Wyzwalacze: Po każdej modyfikacji pliku

• Rozwiązanie: Automatyczne stage'owanie i commitowanie zmian z opisami generowanymi przez AI

„Odczytaj zmodyfikowane ścieżki plików z wejścia hooka, uruchom git diff, aby pobrać zmiany, i wyślij diff do API Claude'a z prośbą o zwięzłą wiadomość commita. Użyj wygenerowanej wiadomości z poleceniami git add i git commit, by automatycznie zatwierdzić zmiany. Uwzględnij nazwy plików i typy zmian w prośbie do API, by wiadomości przestrzegały standardu conventional commits.”

Generator dokumentacji

• Problem: Dokumentacja API wypadająca z synchronizacji ze zmianami w kodzie

• Wyzwalacze: Po modyfikacji plików interfejsów (kontrolery, modele, API)

• Rozwiązanie: Automatyczne uruchamianie narzędzi dokumentacyjnych, takich jak JSDoc, Sphinx czy generatory OpenAPI

„Sprawdź ścieżkę zmodyfikowanego pliku, aby rozpoznać, czy to endpoint API, model lub plik interfejsu, używając dopasowań wzorców. Wyślij treść pliku do API Claude'a z prośbą o wyłuskanie zmian w API i wygenerowanie aktualizacji dokumentacji. Uruchom odpowiednie narzędzie dokumentacyjne (jsdoc, sphinx-build itd.) i automatycznie zatwierdź zaktualizowaną dokumentację.

Zaawansowane hooki dla współpracy i integracji workflowu

Wreszcie, hooki mogą pomóc utrzymać wszystkich członków zespołu na bieżąco.

Integracja ze Slackiem

• Problem: Zespół nie jest świadomy ważnych zmian w współdzielonych bazach kodu

• Wyzwalacze: Gdy wysyłane są powiadomienia o istotnych operacjach

• Rozwiązanie: Wysyłanie sformatowanych wiadomości na kanały zespołowe z nazwami plików i podsumowaniami zmian

„Wyciągnij informacje o plikach z wejścia hooka i przefiltruj pod kątem ważnych typów, jak kod źródłowy lub pliki konfiguracyjne. Użyj API Claude'a do wygenerowania zrozumiałego podsumowania zmian na podstawie nazw i typów plików. Wyślij sformatowaną wiadomość do Slacka, używając adresów webhook z wzmiankami o członkach zespołu przy krytycznych zmianach.”

Dyspozytor webhooków

• Problem: Ręczne wyzwalanie potoków CI/CD powodujące opóźnienia wdrożeń

• Wyzwalacze: Gdy zachodzą określone zdarzenia (zmiany konfiguracji, modyfikacje plików wdrożeniowych)

• Rozwiązanie: Wywoływanie zewnętrznych API do uruchamiania buildów, wdrożeń i innych procesów automatycznych

„Porównaj ścieżkę zmodyfikowanego pliku do wzorców typu Dockerfile, package.json lub konfiguracji wdrożeniowych, by zdecydować, czy uruchomić CI/CD. Użyj biblioteki requests w Pythonie, aby wywołać webhooki z nagłówkami autoryzacji i danymi o zmianach. Dołącz ścieżki plików i metadane zmian do ładunku webhooka, by systemy zewnętrzne mogły inteligentnie zdecydować, co budować lub wdrażać.”

Aktualizator strony statusu

• Problem: Klienci nieświadomi prac konserwacyjnych lub wdrożeń

• Wyzwalacze: Gdy modyfikowane są pliki wdrożeniowe lub infrastrukturalne

• Rozwiązanie: Aktualizacje stron statusów usług informujące o pracach konserwacyjnych

„Przeanalizuj wejście hooka pod kątem zmian w plikach infrastruktury, takich jak manifesty Kubernetes czy konfiguracje Terraform, używając wzorców ścieżek. Wygeneruj komunikaty o konserwacji przy pomocy API Claude'a na podstawie typu wykrytych zmian infrastruktury. Wyślij aktualizacje statusu do usług typu StatusPage.io lub PagerDuty przy użyciu ich REST API z odpowiednimi typami incydentów i szacowanym czasem trwania.”

Powiadamiacz statusu zespołu

• Problem: Konflikty, gdy wielu deweloperów nieświadomie pracuje nad tymi samymi funkcjami

• Wyzwalacze: Przy rozpoczęciu nowej sesji Claude Code

• Rozwiązanie: Powiadamianie kanałów zespołowych, że zaczynasz pracę nad konkretnym projektem lub komponentem

„Odczytaj katalog projektu z wejścia hooka i użyj API Claude'a, by przeanalizować ostatnie pliki lub historię gita i zrozumieć, nad jaką pracą trwają działania. Wyślij sformatowaną wiadomość do kanałów komunikacji zespołu z twoim imieniem, nazwą projektu i obszarem prac. Dołącz przewidywany czas pracy i zaproś członków zespołu do koordynacji, jeśli pracują nad powiązanymi funkcjami.”

Na koniec

Hooki Claude Code zamieniają nieprzewidywalnych asystentów AI w zautomatyzowane workflowy, które uruchamiają się dokładnie wtedy, gdy ich potrzebujesz. W tym tutorialu nauczyłeś się konfigurować hooki zarówno przy pomocy interaktywnego polecenia /hooks, jak i ręcznej konfiguracji, rozumieć dane wejściowe JSON napędzające inteligentną automatyzację oraz kontrolować zachowanie Claude'a za pomocą kodów wyjścia i ustrukturyzowanych wyjść. 

Omówione praktyczne wzorce obejmują walidatory bezpieczeństwa blokujące niebezpieczne operacje i inteligentne powiadomienia redukujące hałas. Te przykłady pokazują, jak hooki rozwiązują realne problemy deweloperskie, jednocześnie dając ci pełną kontrolę nad asystentem AI. Skoro znasz już podstawy, możesz budować automatyzację dopasowaną do potrzeb workflowu twojego zespołu. 

Aby dowiedzieć się więcej o pracy z narzędziami AI, sprawdź kurs DataCamp Understanding Prompt Engineering, który omawia strategie promptowania współgrające z rozwojem hooków. Dla szerszych umiejętności w AI codingu wypróbuj nasz Intermediate ChatGPT, aby rozwinąć umiejętności czyniące asystentów AI bardziej niezawodnymi partnerami w twoim workflowie deweloperskim.