Sztuczna Inteligencja

TL;DR

Hook w Claude Code to komenda shell, która odpala się automatycznie przy konkretnym zdarzeniu — zanim AI użyje narzędzia, po edycji pliku, przy starcie sesji albo gdy AI próbuje zakończyć pracę. Dzięki temu pewne rzeczy dzieją się zawsze, deterministycznie, niezależnie od tego, czy model „pamięta” o nich w danym momencie. Prompt to prośba. Hook to gwarancja.

Problem, który hooki rozwiązują

Możesz napisać w CLAUDE.md: „nigdy nie czytaj plików .env„, „zawsze formatuj kod po edycji”, „nie commituj bez konwencji”. I w 95% przypadków AI posłucha. Ale to wciąż instrukcja w prompcie — miękka, podatna na to, że model w długiej sesji o niej zapomni albo ją zinterpretuje po swojemu.

Hook działa inaczej: to twarda bramka na poziomie systemu, nie sugestia dla modelu. Jak git pre-commit hook albo lint-staged — tyle że spina się ze zdarzeniami AI, a nie z gitem.

Analogia dla webdeveloperów: hook w Claude Code to to samo co middleware w aplikacji albo trigger w bazie danych. Przechwytuje zdarzenie, może je zablokować, zmodyfikować albo dorzucić efekt uboczny — zanim „request” przejdzie dalej.

Kiedy odpalają się hooki (eventy)

Claude Code wystawia kilka punktów zaczepienia w cyklu życia sesji:

Najczęściej używane w praktyce: PreToolUse (bramki bezpieczeństwa) i PostToolUse (automatyzacja jakości).

Jak to wygląda w konfiguracji

Hooki definiujesz w settings.json (globalnie w ~/.claude/ albo per-projekt w .claude/). Schemat:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/format-code.sh" }
        ]
      }
    ]
  }
}

• matcher — wzorzec nazwy narzędzia (regex). Edit|Write łapie oba.
• command — Twój skrypt. Dostaje na stdin JSON z danymi zdarzenia (m.in. nazwę narzędzia i jego argumenty).

Jak hook „rozmawia” z AI — kody wyjścia

To jest sedno mechanizmu:

• exit 0 → wszystko OK, operacja przechodzi.
• exit 2 → blokada. To, co skrypt wypisze na stderr, trafia z powrotem do AI jako feedback („nie rób tego, bo X”). Model widzi powód i się dostosowuje.
• inny kod → błąd niezablokujący (logowany, ale nie zatrzymuje).

Dla zaawansowanej kontroli hook może też zwrócić JSON na stdout (np. {"decision": "block", "reason": "..."}) — pełna kontrola nad tym, co się stanie.

3 hooki, które warto mieć od pierwszego dnia

1. Blokada czytania sekretów (.env, klucze)

Najważniejszy z punktu widzenia bezpieczeństwa. AI nie powinno wczytywać plików z hasłami do kontekstu — bo stamtąd mogą wyciec.

#!/usr/bin/env bash
# PreToolUse, matcher: Read|Bash
input=$(cat)
if echo "$input" | grep -qE '.env|credentials|id_rsa|.secrets'; then
  echo "BLOK: próba dostępu do pliku z sekretami. Użyj zmiennych środowiskowych." >&2
  exit 2
fi
exit 0

2. Auto-formatowanie po edycji

Koniec z „AI napisało kod, ale bez formatowania”. Po każdej edycji odpalasz prettier/black/gofmt:

#!/usr/bin/env bash
# PostToolUse, matcher: Edit|Write
file=$(cat | jq -r '.tool_input.file_path')
case "$file" in
  *.ts|*.tsx|*.js) npx prettier --write "$file" ;;
  *.py)            black "$file" ;;
esac
exit 0

3. Blokada destrukcyjnych komend

rm -rf, git reset --hard, DROP TABLE — rzeczy, których nie chcesz, żeby AI odpaliło bez Twojej wiedzy:

#!/usr/bin/env bash
# PreToolUse, matcher: Bash
cmd=$(cat | jq -r '.tool_input.command')
if echo "$cmd" | grep -qE 'rm -rf|git reset --hard|DROP TABLE|--force'; then
  echo "BLOK: operacja destrukcyjna. Wymaga ręcznego potwierdzenia." >&2
  exit 2
fi
exit 0

PRO TIP: plugin /hookify

Nie musisz wymyślać hooków od zera. Anthropic udostępnia plugin /hookify, który analizuje historię Twoich rozmów i proponuje hooki na podstawie tego, co realnie robisz: jeśli wielokrotnie poprawiałeś AI („nie czytaj tego pliku”, „sformatuj po edycji”), /hookify zauważy wzorzec i zaproponuje gotowy hook, który zautomatyzuje tę zasadę na stałe.

To odwrócenie perspektywy: zamiast pisać reguły z głowy, wyciągasz je z własnej praktyki.

Dlaczego to ma znaczenie (szczególnie w agencji)

Gdy AI pracuje na produkcji — Twojej albo klienta — różnica między „prompt prosi” a „hook gwarantuje” to różnica między incydentem a spokojnym snem. Hooki to warstwa governance dla AI: deterministyczne, audytowalne, niezależne od humoru modelu. Wpisujesz zasadę raz, działa zawsze.

W HelpGuru traktujemy to jak każdy inny element pipeline’u jakości: lint, testy, hooki gita — i teraz hooki AI. Bo zasada jest ta sama: błąd, który da się złapać automatycznie, nie ma prawa się powtórzyć.