Hooks w Claude Code — deterministyczna automatyzacja, której CLAUDE.md nie zapewni

Jest pewna różnica, o której mało kto mówi wprost: CLAUDE.md to zbiór instrukcji, które Claude stara się przestrzegać. Kluczowe słowo: stara. Estymacja z doświadczeń społeczności to ~80% przestrzegania — Claude może zignorować regułę z CLAUDE.md, jeśli kontekst sesji skieruje go gdzie indziej, lub jeśli instrukcja koliduje z czymś innym.

Hooks działają inaczej. Zawsze. 100%. Niezależnie od tego, co Claude myśli o sytuacji.

Czym są hooks w Claude Code

Hooks to skrypty powłoki (shell commands) skonfigurowane w pliku ustawień Claude Code, które uruchamiają się automatycznie w odpowiedzi na zdarzenia w sesji. Zdarzenie może być dowolne: Claude zakończył edycję pliku, sesja się uruchomiła, Claude zatwierdził zmianę.

Kluczowa właściwość: hook to zewnętrzny proces. Claude go nie interpretuje, nie ocenia, nie może go pominąć. Jeśli hook jest skonfigurowany — wykona się.

Jak skonfigurować hooks

Hooki konfiguruje się w pliku .claude/settings.json w katalogu projektu (lub globalnie w ~/.claude/settings.json). Struktura jest prosta:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ]
  }
}

Ten przykład uruchamia linter automatycznie po każdej edycji pliku przez Claude’a. Bez pytania, bez czekania na zatwierdzenie — po prostu się wykonuje.

Dostępne zdarzenia (eventy)

Claude Code obsługuje kilka typów zdarzeń dla hooks:

• PreToolUse — przed użyciem narzędzia (np. przed edycją pliku)
• PostToolUse — po użyciu narzędzia (najczęściej używane)
• Notification — gdy Claude wysyła powiadomienie
• Stop — gdy sesja kończy pracę

PostToolUse z matcherem Edit|Write to najpopularniejsza kombinacja — uruchamia się po każdej zmianie pliku.

Praktyczne przykłady hooks

Automatyczny lint i format po edycji:

"command": "npx eslint --fix && npx prettier --write"

Uruchomienie testów po zmianach w plikach testowych:

{
  "matcher": "Edit",
  "hooks": [{ "type": "command", "command": "npm test -- --watchAll=false" }]
}

Powiadomienie dźwiękowe gdy sesja się kończy (przydatne przy długich zadaniach):

{
  "event": "Stop",
  "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
}

Automatyczny commit po zakończeniu zadania:

{
  "event": "Stop",
  "hooks": [{ "type": "command", "command": "git add -A && git commit -m 'auto: claude session'" }]
}

CLAUDE.md vs hooks — kiedy co

Oba mechanizmy są potrzebne, ale służą różnym celom:

CLAUDE.md — dla zasad kontekstowych i stylowych, które wymagają interpretacji. „Preferuj async/await nad Promise chains.” „Komentarze po polsku.” „Nie modyfikuj plików w src/generated/.” Claude rozumie te instrukcje i stosuje je z rozsądkiem.

Hooks — dla akcji deterministycznych, które muszą się wykonać zawsze. Linting, formatowanie, uruchamianie testów, powiadomienia, automatyczne commity. Żadnego „zazwyczaj” ani „w większości przypadków” — albo hook się wykona, albo sesja nie będzie mogła kontynuować (jeśli tak skonfigurujesz).

Hooks jako siatka bezpieczeństwa

Jedna z najbardziej wartościowych kombinacji: hook uruchamiający testy przed zakończeniem sesji. Nawet jeśli Claude zapomni o testach w trakcie pracy — hook je uruchomi na koniec. Jeśli testy nie przejdą, możesz skonfigurować hook tak, żeby blokował zakończenie sesji.

To jest właśnie deterministyczna automatyzacja: nie polegasz na tym, że Claude pamięta o testach. Wbudujesz to w infrastrukturę sesji.