Kurs vibe coding z Claude Code · Moduł 15: Claude Code dla zaawansowanych
Zasady bez wyjątków: hooki
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.mdto 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
denyalboaskto 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 0case 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
Writew matcherze. Typowy błąd agenta to"matcher": "Edit", bo zadanie brzmiało "przed edycją". Nowy plik.env.localalbo nowa migracja idą przezWritei omijają hook. Rozpoznasz to w diffie po samymEdit.- 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. jqna pokładzie.jq --versionmusi działać. BezjqzmiennaFILEjest pusta, skrypt kończy się kodem 0 i przepuszcza wszystko, a tegoonFailurenie złapie.- Próba. JSON podany ręcznie daje 2 dla
.envi migracji oraz 0 dla.env.exampleilib/pins.ts, a/hookspokazuje 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: "block"
</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. 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. 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: