Kurs vibe coding z Claude Code · Moduł 15: Claude Code dla zaawansowanych

Zasady bez wyjątków: hooki

7 min czytania
W tej lekcji9

Linia w CLAUDE.md Treasure Map mówi: migracji w prisma/migrations/ nie edytujemy, zmiana schematu to nowa migracja. Prosisz Claude o zmianę nazwy kolumny, a on sumiennie poprawia ją w schema.prisma i w zapisanej migracji, bo tam też stoi stara nazwa. Twoja baza tę migrację już wykonała, więc historia migracji przestaje się zgadzać z bazą. Zasada była zapisana, ale zapis to prośba, a prośba to nie zamek.

Co już umiesz

W lekcji 7_1 przybiłeś hook PostToolUse z matcherem Edit|Write, który formatuje edytowany plik, i oglądałeś go w /hooks. W lekcji 7_3 hook Notification w ustawieniach użytkownika dzwonił, gdy Claude czekał na zgodę. Z lekcji 8_4 znasz regułę deny dla .env, a z lekcji 14_3 kolejność deny, ask, allow i komendę /permissions. Teraz hook nie sprząta po edycji, tylko staje przed nią i mówi "nie".

Prośba, reguła, hook

Zasadę możesz zapisać na trzy sposoby, a różnią się tym, kto jej pilnuje:

  • Linia w CLAUDE.md to kontekst dla modelu. Claude ją czyta i zwykle stosuje, ale dokumentacja mówi wprost, że nie ma gwarancji ścisłego posłuszeństwa.
  • Reguła deny albo ask to wzorzec na narzędzie i ścieżkę, którego pilnuje Claude Code w każdym trybie. Odmowa jest ogólna, bez wskazówki, co zrobić zamiast tego.
  • Hook to Twój program uruchamiany w ustalonym momencie pracy. Może sprawdzić cokolwiek i odpowiedzieć własnym komunikatem.

Dokumentacja pamięci radzi: jeśli coś ma się dziać w konkretnym momencie, na przykład przed każdą edycją, napisz hook, a nie linię w CLAUDE.md. Zdarzenia mają swój rytm: SessionStart raz na początku sesji, PreToolUse przed każdym wywołaniem narzędzia, PostToolUse po nim, a Stop, gdy Claude kończy odpowiedź. Zakaz musi zadziałać przed zapisem, więc wybierasz PreToolUse.

Polecenie dla Claude Code

W sesji w folderze treasure-map napisz:

Dodaj do .claude/settings.json hook PreToolUse dla narzędzi Edit i Write. Ma uruchamiać
skrypt .claude/hooks/chron-pliki.sh, który kończy się kodem 2 i komunikatem na stderr
dla plików .env* (poza .env.example) i dla wszystkiego w prisma/migrations/.
Komunikat ma mówić, co zrobić zamiast tego. Istniejących hooków nie ruszaj.
Gotowe, gdy skrypt dostaje JSON ze ścieżką .env i kończy się kodem 2.

Polecenie podaje zdarzenie, narzędzia, kod wyjścia i sprawdzian, więc nie zostawia miejsca na zgadywanie.

Co napisał Claude: skrypt

Otwórz w Cursorze .claude/hooks/chron-pliki.sh. Hook dostaje opis wywołania jako JSON na standardowe wejście: nazwę narzędzia w tool_name i argumenty w tool_input, a przy Edit i Write pełną ścieżkę w file_path. Pierwsza linia skryptu wyciąga ścieżkę:

#!/bin/bash
# chron-pliki.sh: hook PreToolUse, który nie wpuszcza edycji do sekretów i gotowych migracji

FILE=$(jq -r '.tool_input.file_path // empty')

jq czyta JSON z wejścia, a // empty daje pusty tekst, gdy pola nie ma, na przykład przy komendzie Bash. Dalej stoi decyzja:

case "$FILE" in
  */.env.example)
    exit 0
    ;;
  */.env*)
    echo "Zablokowane: $FILE to plik z sekretami. Zmienne w .env ustawia człowiek; dopisz brakującą nazwę do .env.example." >&2
    exit 2
    ;;
  */prisma/migrations/*)
    echo "Zablokowane: $FILE to zapisana migracja. Zmień prisma/schema.prisma i poproś o nową migrację." >&2
    exit 2
    ;;
esac

exit 0

case porównuje ścieżkę ze wzorcami po kolei i bierze pierwszy pasujący, dlatego wyjątek dla .env.example stoi przed */.env*. Kod wyjścia jest odpowiedzią. 2 blokuje wywołanie, a tekst wypisany przez >&2 na stderr Claude dostaje jako powód. 0 to brak sprzeciwu, nie zgoda: dalej decydują zwykłe uprawnienia. Kod 1, choć w Uniksie oznacza błąd, niczego nie blokuje: dokumentacja nazywa go błędem niezatrzymującym i ostrzega, że hook pilnujący zasady ma kończyć się kodem 2. Zamiast kodu 2 skrypt może też skończyć się kodem 0 i wypisać JSON z permissionDecision ustawionym na deny. Wybierz jedną drogę na hook; kod 2 jest prostszy i tego się trzymam.

Co napisał Claude: wpis w ustawieniach

W .claude/settings.json, obok permissions z lekcji 14_3, doszła sekcja hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/chron-pliki.sh"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

Kształt znasz z lekcji 7_1. matcher z Edit|Write to dokładna lista nazw narzędzi: Edit zmienia fragment istniejącego pliku, a Write zapisuje cały plik, także nowy. ${CLAUDE_PROJECT_DIR} to folder projektu, więc skrypt się znajdzie, nawet gdy Claude zmieni katalog roboczy. Pole args uruchamia bash bez pośrednictwa powłoki, więc ścieżka ze spacją nie rozpadnie się na kawałki, a skrypt nie potrzebuje chmod +x. onFailure: "block" odwraca domyślne zachowanie: bez niego hook, który nie wystartuje, bo ścieżka jest błędna, przepuści każdą edycję.

Próba na żywo

Skrypt sprawdzasz najpierw bez Claude, podając mu JSON ręcznie:

echo '{"tool_input":{"file_path":"/x/treasure-map/.env"}}' | bash .claude/hooks/chron-pliki.sh; echo $?

Terminal wypisze komunikat "Zablokowane: ..." i liczbę 2. Podmień ścieżkę na /x/treasure-map/lib/pins.ts, a zobaczysz samo 0. Potem próba z Claude: w claude -p, z zapisem dozwolonym przez --allowedTools "Write", poprosiliśmy o utworzenie .env.test i nowego pliku w prisma/migrations/. Migracja zatrzymała się na hooku, mimo zgody na Write:

PreToolUse:Write hook error: [bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/chron-pliki.sh]: Zablokowane: .../prisma/migrations/20261115120000_tagi/migration.sql to zapisana migracja. Zmień prisma/schema.prisma i poproś o nową migrację.

Claude przepisał komunikat i nie szukał innej drogi. .env.test zatrzymała wcześniej reguła Read(./.env.*) z lekcji 8_4, z ogólnym "File is covered by a Read deny rule". Dla .env hook jest więc drugą warstwą, a dla migracji jedynym zamkiem. W sesji wpisz jeszcze /hooks: Twój hook stoi pod PreToolUse ze źródłem w ustawieniach projektu, a hook Notification z lekcji 7_3, jeśli go masz, ze źródłem w ustawieniach użytkownika.

Czego hook nie widzi

Hook z matcherem Edit|Write patrzy tylko na te dwa narzędzia. Gdy Claude dopisze linię komendą echo DEBUG=1 >> .env albo zmieni plik przez sed -i, hook nie ruszy. Dokumentacja radzi dołożyć regułę deny dla Edit, na przykład Edit(./prisma/migrations/**), bo reguły Read i Edit obejmują też rozpoznawane komendy plikowe w Bash (cat, sed, tee) i przekierowania >. Skrypt, który sam otwiera plik, ominie i to; mur na poziomie systemu daje dopiero sandbox, który poznasz w lekcji 14_7.

Pamiętaj też, że hook to komenda, która działa z Twoimi uprawnieniami, także w cudzym repozytorium. Jak mówiła lekcja 14_1, claude -p w sklonowanym projekcie uruchomi hooki z jego .claude/settings.json bez pytania. Zanim puścisz skrypt na obcym kodzie, przeczytaj .claude/settings.json i .claude/hooks/ albo wyłącz hooki na jeden przebieg flagą --settings '{"disableAllHooks": true}'. Hooki mogą też przyjść we frontmatterze skilla i w pluginie, a w lekcji 14_8 hook Stop odeśle Claude do pracy, dopóki typy się nie zgadzają.

Przegląd kapitana

  1. Write w matcherze. Typowy błąd agenta to "matcher": "Edit", bo zadanie brzmiało "przed edycją". Nowy plik .env.local albo nowa migracja idą przez Write i omijają hook. Rozpoznasz to w diffie po samym Edit.
  2. Kod 2 i stderr. Każda blokada kończy się exit 2, a komunikat idzie przez >&2. Bez przekierowania Claude dostanie blokadę bez powodu i będzie zgadywać, co dalej.
  3. jq na pokładzie. jq --version musi działać. Bez jq zmienna FILE jest pusta, skrypt kończy się kodem 0 i przepuszcza wszystko, a tego onFailure nie złapie.
  4. Próba. JSON podany ręcznie daje 2 dla .env i migracji oraz 0 dla .env.example i lib/pins.ts, a /hooks pokazuje wpis.

Następny krok

Domknij lukę w Bash dla najgroźniejszej komendy Prismy:

Rozszerz chron-pliki.sh: gdy tool_input.command zawiera prisma migrate reset, zakończ
kodem 2 z komunikatem. W settings.json dodaj drugą grupę z matcherem Bash.
Sprawdź skrypt JSON-em podanym ręcznie, zanim poprosisz o commit.

Potem poproś o commit, na przykład "Hook chroniący sekrety i migracje". W edytorze obok wybierzesz zdarzenie, matcher, wywołanie i kod wyjścia, a symulator pokaże, czy hook ruszy, co dostanie na wejściu i co stanie się z narzędziem.

Zapamiętaj: co ma się dziać zawsze, nie wpisujesz do dziennika, tylko przybijasz do pokładu.

Kod do tej lekcji: App.tsx
// Symulator hooka: zdarzenie, matcher, wywołanie narzędzia, kod wyjścia i to, co z tego wynika
import { useState } from 'react';

export type Tool = 'Edit' | 'Write' | 'Bash';
export type HookEvent = 'PreToolUse' | 'PostToolUse';
export type ExitChoice = 'script' | '0' | '1' | '2';

export interface Call {
  tool: Tool;
  target: string;
}

export const ROOT = '/x/treasure-map/';

export const CALLS: Call[] = [
  { tool: 'Edit', target: '.env' },
  { tool: 'Write', target: '.env.local' },
  { tool: 'Edit', target: '.env.example' },
  { tool: 'Write', target: 'prisma/migrations/20261115120000_tagi/migration.sql' },
  { tool: 'Edit', target: 'prisma/schema.prisma' },
  { tool: 'Edit', target: 'lib/pins.ts' },
  { tool: 'Bash', target: 'echo DEBUG=1 >> .env' },
];

export function matcherHits(matcher: string, tool: string): boolean {
  const m = matcher.trim();
  if (m === '' || m === '*') return true;
  if (/^[A-Za-z0-9_|, -]+$/.test(m)) {
    return m.split(/[|,]/).map((s) => s.trim()).includes(tool);
  }
  try {
    return new RegExp(m).test(tool);
  } catch {
    return false;
  }
}

function casePattern(pattern: string, value: string): boolean {
  const re = pattern.replace(/[.+?^$()[\]{}|\\]/g, (c) => '\\' + c).replace(/\*/g, '.*');
  return new RegExp('^' + re + '$').test(value);
}

export interface ScriptResult {
  code: number;
  stderr: string;
}

export function runScript(call: Call): ScriptResult {
  const file = call.tool === 'Bash' ? '' : ROOT + call.target;
  if (casePattern('*/.env.example', file)) return { code: 0, stderr: '' };
  if (casePattern('*/.env*', file)) {
    return { code: 2, stderr: 'Zablokowane: ' + file + ' to plik z sekretami. Zmienne w .env ustawia człowiek; dopisz brakującą nazwę do .env.example.' };
  }
  if (casePattern('*/prisma/migrations/*', file)) {
    return { code: 2, stderr: 'Zablokowane: ' + file + ' to zapisana migracja. Zmień prisma/schema.prisma i poproś o nową migrację.' };
  }
  return { code: 0, stderr: '' };
}

export function stdinFor(event: HookEvent, call: Call): string {
  const input = call.tool === 'Bash' ? { command: call.target } : { file_path: ROOT + call.target };
  return JSON.stringify({ hook_event_name: event, tool_name: call.tool, tool_input: input });
}

export interface Outcome {
  fired: boolean;
  code: number | null;
  blocked: boolean;
  text: string;
}

export function simulate(event: HookEvent, matcher: string, call: Call, exit: ExitChoice, onFailureBlock: boolean): Outcome {
  if (!matcherHits(matcher, call.tool)) {
    const gap = call.tool === 'Bash' && call.target.includes('.env')
      ? ' Tę dziurę łata reguła deny Edit, która obejmuje też przekierowania w Bash.'
      : '';
    return { fired: false, code: null, blocked: false, text: 'Hook nie ruszył: matcher "' + matcher + '" nie obejmuje narzędzia ' + call.tool + '.' + gap };
  }
  const script = runScript(call);
  const code = exit === 'script' ? script.code : Number(exit);
  const note = call.tool === 'Bash' && exit === 'script'
    ? ' Skrypt czyta tylko file_path, więc komendę Bash przepuszcza; potrzebny osobny warunek na tool_input.command.'
    : '';
  if (event === 'PostToolUse') {
    if (code === 2) return { fired: true, code, blocked: false, text: 'Narzędzie już zadziałało. stderr trafia do Claude, ale zmiany nie cofnie.' };
    return { fired: true, code, blocked: false, text: 'Hook po fakcie niczego nie blokuje; tak działa formatowanie z lekcji 7_1.' + note };
  }
  if (code === 2) {
    const reason = exit === 'script' ? script.stderr : '(Twój komunikat ze stderr)';
    return { fired: true, code, blocked: true, text: 'Zablokowane przed wykonaniem, nawet gdy reguła allow by przepuściła. Claude dostaje: ' + reason };
  }
  if (code === 0) {
    return { fired: true, code, blocked: false, text: 'Brak sprzeciwu, ale to nie zgoda: dalej decydują reguły uprawnień i tryb.' + note };
  }
  return onFailureBlock
    ? { fired: true, code, blocked: true, text: 'Kod inny niż 0 i 2 to błąd hooka, a onFailure: "block" zamienia go w blokadę.' }
    : { fired: true, code, blocked: false, text: 'Kod ' + code + ' to błąd niezatrzymujący: narzędzie działa dalej. Zasadę pilnuje tylko kod 2.' };
}

export default function App() {
  const [event, setEvent] = useState<HookEvent>('PreToolUse');
  const [matcher, setMatcher] = useState('Edit|Write');
  const [index, setIndex] = useState(1);
  const [exit, setExit] = useState<ExitChoice>('script');
  const [onFailureBlock, setOnFailureBlock] = useState(true);
  const call = CALLS[index];
  const result = simulate(event, matcher, call, exit, onFailureBlock);

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">Hook na pokładzie Treasure Map</h1>
      <div className="grid gap-3 text-sm md:grid-cols-2">
        <label className="block">
          Zdarzenie{' '}
          <select className="rounded bg-slate-800 p-1" value={event} onChange={(e) => setEvent(e.target.value as HookEvent)}>
            <option value="PreToolUse">PreToolUse</option>
            <option value="PostToolUse">PostToolUse</option>
          </select>
        </label>
        <label className="block">
          matcher{' '}
          <input className="rounded bg-slate-800 p-1 font-mono" value={matcher} onChange={(e) => setMatcher(e.target.value)} />
        </label>
        <label className="block">
          Wywołanie{' '}
          <select className="rounded bg-slate-800 p-1 font-mono" value={index} onChange={(e) => setIndex(Number(e.target.value))}>
            {CALLS.map((c, i) => (
              <option key={i} value={i}>{c.tool}: {c.target}</option>
            ))}
          </select>
        </label>
        <label className="block">
          Kod wyjścia{' '}
          <select className="rounded bg-slate-800 p-1" value={exit} onChange={(e) => setExit(e.target.value as ExitChoice)}>
            <option value="script">jak w chron-pliki.sh</option>
            <option value="0">0</option>
            <option value="1">1</option>
            <option value="2">2</option>
          </select>
        </label>
      </div>
      <label className="flex items-center gap-2 text-sm">
        <input type="checkbox" checked={onFailureBlock} onChange={(e) => setOnFailureBlock(e.target.checked)} />
        onFailure: &quot;block&quot;
      </label>
      <section>
        <h2 className="font-semibold">Co hook dostaje na wejściu</h2>
        <pre className="overflow-x-auto whitespace-pre-wrap rounded bg-slate-900 p-2 font-mono text-xs">{stdinFor(event, call)}</pre>
      </section>
      <p role="status" className="rounded border border-slate-700 p-2 text-sm">
        <strong className={result.blocked ? 'text-rose-400' : result.fired ? 'text-emerald-400' : 'text-amber-400'}>
          {result.fired ? 'hook ruszył, kod ' + result.code : 'hook nie ruszył'}
        </strong>{' '}
        {result.text}
      </p>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. CLAUDE.md mówi, że migracji nie edytujemy, a Claude i tak poprawił plik w prisma/migrations/. Co zatrzyma go za każdym razem i powie, co zrobić zamiast tego?

  2. 2. Hook PreToolUse bez pola onFailure wypisał powód na stderr i zakończył się kodem 1. Co stanie się z edycją?

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż linię, która podaje skryptowi hooka JSON ze ścieżką .env i wypisuje jego kod wyjścia:

  • Układanie w pionie

    Uporządkuj zdarzenia hooków w kolejności, w jakiej zachodzą podczas używania narzędzia w sesji:

  1. PytanieQuiz: Co egzekwuje zasadę
  2. PytanieQuiz: Kod wyjścia hooka
  3. Ułóż w kolejnościSortowanie: Test hooka bez Claude
  4. Ułóż w kolejnościSortowanie: Zdarzenia cyklu życia hooków

Przydatne artykuły