Hooks w Claude Code — 5 wzorców produkcyjnych z naszych projektów

Hooks v2 w Claude Code dają możliwość wpinania własnych skryptów w cykl życia agenta — przed wywołaniem narzędzia, po wywołaniu, na zakończenie sesji. Brzmi jak feature dla nerdów, w praktyce jest jednym z najmocniejszych mechanizmów bezpieczeństwa i automatyzacji. Pokazujemy 5 wzorców, których używamy produkcyjnie u klientów.

Czym są hooks

Hook to deklaracja w ~/.claude/settings.json lub .claude/settings.json, która mówi: "kiedy Claude spróbuje użyć narzędzia X, najpierw uruchom mój skrypt". Skrypt może zwrócić exit code 0 (kontynuuj), 1 (przerwij z błędem) lub 2 (kontynuuj, ale przekaż kontekst do modelu).

Struktura konfiguracji

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "/usr/local/bin/check-bash-safety.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "/usr/local/bin/auto-format.sh"
        }]
      }
    ]
  }
}

Wzorzec 1: blokada destrukcyjnych komend

Hook PreToolUse dla narzędzia Bash sprawdza, czy komenda nie zawiera niebezpiecznych wzorców. Blokujemy: rm -rf /, git push --force na main, DROP DATABASE, modyfikacje /etc/passwd.

#!/usr/bin/env bash
# /usr/local/bin/check-bash-safety.sh
cmd=$(jq -r '.tool_input.command' <<< "$1")

if echo "$cmd" | grep -qE 'rm -rf /( |$)|DROP DATABASE|git push --force.*main'; then
    echo "BLOCKED: niebezpieczna komenda" >&2
    exit 1
fi
exit 0

Wzorzec 2: auto-format po Edit/Write

Hook PostToolUse dla narzędzi modyfikujących pliki uruchamia formatter zgodny z typem pliku. Dla PHP — php-cs-fixer. Dla TypeScript — prettier. Dla SQL — własny linter.

Wzorzec 3: audit log do Sentry

Hook PostToolUse dla wszystkich narzędzi wysyła telemetrię do Sentry/Datadog: jakie narzędzie, jakie pliki, czas trwania, czy się udało. U klienta enterprise to wymóg compliance.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "curl -X POST https://logs.example.com/claude-audit -d @-"
      }]
    }]
  }
}

Wzorzec 4: sync dokumentacji po edycji kodu

Hook PostToolUse dla Edit/Write sprawdza, czy zmieniono krytyczne pliki (helpers.php, routes, schema). Jeśli tak — generuje notatkę i wkleja do internal_docs przez API admina. Dzięki temu nikt nie zapomina o auto-sync rule.

Wzorzec 5: blokada committowania sekretów

Hook PreToolUse dla Bash z matcherem git commit skanuje diff narzędziem gitleaks. Jeśli wykryje API key, hasło, token — blokuje commit z czytelnym komunikatem dla użytkownika.

Pułapki, w które wpadliśmy

• Hook za wolny. Powyżej 800ms hook frustruje. U nas limit to 500ms — większe rzeczy idą do async post-processingu.
• Hook gadatliwy. Każde echo do stderr trafia do modelu jako kontekst. Logujcie do pliku, nie do stderr.
• Hook bez fallbacku. Jeśli skrypt padnie, Claude nie wie co robić. Zawsze obsługujcie exit codes i piszcie czytelne komunikaty.
• Hook globalny vs project-level. Projektowy nadpisuje globalny. Sprawdzajcie hierarchię.

Następny krok

Mamy gotowy pakiet 7 hooków dla projektów PHP/MySQL — dorzucamy do repo klienta. Pokażemy na demo, jak działa secrets scan i auto-format w 5 minut.