Kurs vibe coding z Claude Code · Moduł 15: Claude Code dla zaawansowanych
Agent na wachcie: skrypty do recenzji, dokumentacji, testów i commitów
W tej lekcji9
Zajrzyj do ładowni Treasure Map. W lib/ leży czternaście plików z kodem, a dziewięć z nich nie ma testów. README.md wciąż opowiada o create-next-app, choć projekt ma bazę, trasy API i wyszukiwanie obrazem. A opisy commitów z ostatniego tygodnia pewnie brzmią "fix", "fix2" i "poprawki". Żadna z tych prac nie jest trudna, każda jest nudna i każdą odkładasz. Takie obowiązki nocnej wachty oddajesz skryptom, a sam zostajesz przy tym, czego skrypt nie zrobi: przy decyzji.
Co już umiesz
W lekcji 14_1 nauczyłeś się potoku, przekierowania >, flag --tools i --model oraz tego, że -p bez zgody niczego nie zapisze. Z lekcji 10_4 wiesz, że test, którego nie widziałeś na czerwono, mógł niczego nie pilnować, a z lekcji 1_5, że pierwsza linia opisu commita mówi "co" w 50 znakach. W lekcji 12_7 Claude trafił do GitHub Actions. Teraz te klocki składasz w trzy skrypty, a piszesz je rękami Claude Code.
Polecenie dla Claude Code: dokumentacja
Zacznij od dokumentacji, bo jej błąd najmniej kosztuje. W sesji Claude Code napisz:
Polecenie dla Claude Code:
Napisz skrypt scripts/generate-docs.sh: trzy wywołania claude -p z --model sonnet
i --max-turns 10. Wyniki: docs/API.md z tras w app/api, docs/COMPONENTS.md
z components/ i README.md całego projektu, każdy zapisany przekierowaniem >.
Gdy wywołanie się nie uda, stary plik ma zostać. Nie uruchamiaj skryptu, pokaż mi go.Ostatnie zdanie jest ważne: skrypt najpierw czytasz, a dopiero potem uruchamiasz.
Co napisał Claude: generate-docs.sh
Otwórz w Cursorze scripts/generate-docs.sh. Na górze stoi zmienna z regułą wspólną dla wszystkich wywołań:
ONLY="Zwróć wyłącznie treść pliku Markdown, bez płotków wokół całości i bez zdań od siebie."
mkdir -p docsWszystko, co Claude wypisze, ląduje w pliku: także zdanie "Oto dokumentacja:" i trzy znaki płotka wokół całości. Ta reguła mówi, że wynik ma być gotowym plikiem, a nie wiadomością o pliku. mkdir -p zakłada folder docs, a gdy już istnieje, nic nie robi. Pierwsze wywołanie:
claude -p "Opisz trasy z app/api: metoda, adres, dane wejściowe, odpowiedzi i kody błędów. $ONLY" \
--model sonnet --max-turns 10 > docs/API.md.tmp && mv docs/API.md.tmp docs/API.mdOdpowiedź trafia najpierw do pliku .tmp, bo > czyści plik, zanim Claude zacznie. && uruchamia mv tylko wtedy, gdy claude skończył się sukcesem, więc przebieg przerwany limitem tur nie nadpisze dobrego docs/API.md komunikatem o błędzie. Dwa kolejne wywołania mają ten sam kształt:
claude -p "Opisz komponenty z components/: rola, props i przykład użycia. $ONLY" \
--model sonnet --max-turns 10 > docs/COMPONENTS.md.tmp && mv docs/COMPONENTS.md.tmp docs/COMPONENTS.md
claude -p "Napisz README projektu: opis, uruchomienie, testy, baza danych, struktura katalogów. $ONLY" \
--model sonnet --max-turns 10 > README.md.tmp && mv README.md.tmp README.mdPrzy README ta kolejność ma drugi zysk: Claude może przeczytać stary plik, bo > czyści tylko README.md.tmp. Żadne wywołanie nie zmienia kodu: w trybie -p bez zgody Claude tylko czyta, a pliki zapisuje Twój terminal.
Jest druga droga: poprosić "zapisz wynik w docs/API.md" i dodać --permission-mode acceptEdits. Wtedy Claude sam tworzy i edytuje pliki w projekcie, ale każde, nie tylko te trzy. Taki skrypt uruchamiaj tylko na czystym drzewie, gdy git status nic nie pokazuje: wtedy diff w Source Control to dokładnie praca skryptu, a git restore cofnie każdą zmianę. Polecam przekierowanie, bo to skrypt decyduje, gdzie trafia wynik.
Polecenie dla Claude Code: testy
Teraz dziewięć plików bez testów. Projekt używa Vitest, więc o niego prosisz:
Napisz scripts/generate-tests.sh: dla każdego pliku .ts w lib/ bez pliku .test.ts
wywołaj claude -p z prośbą o testy Vitest i zapisz wynik obok. Pomiń pliki z testami
i pliki bez eksportowanych funkcji. Nieudany przebieg nie może zostawić pliku testów.
Nie uruchamiaj skryptu, pokaż mi go.Co napisał Claude: generate-tests.sh
Skrypt to pętla, czyli ten sam rozkaz powtarzany dla każdego pliku. Pierwszy fragment wybiera pliki i pomija te z testami:
for FILE in $(find lib -name "*.ts" ! -name "*.test.ts"); do
TEST_FILE="${FILE%.ts}.test.ts"
if [ -f "$TEST_FILE" ]; then
continue
fifind lib -name "*.ts" wyławia pliki TypeScript, a ! -name "*.test.ts" odrzuca same testy. for ... do w każdym obrocie wkłada jedną ścieżkę do zmiennej FILE. ${FILE%.ts} obcina końcówkę .ts, więc z lib/plural.ts powstaje lib/plural.test.ts. [ -f "$TEST_FILE" ] pyta, czy taki plik istnieje, a continue przeskakuje do następnego obrotu. Twoje testy zostają nietknięte, a skrypt możesz puszczać do woli. Drugi filtr odsiewa pliki, w których nie ma czego testować:
if ! grep -q "export .*function" "$FILE"; then
echo "Pomijam $FILE: nie eksportuje funkcji"
continue
figrep -q szuka tekstu po cichu i odpowiada tylko sukcesem albo porażką, a ! odwraca odpowiedź. U nas odpadły lib/types.ts z samymi typami i lib/prisma.ts z klientem bazy: test do nich byłby atrapą. Dalej właściwe wywołanie:
echo "Piszę testy: $TEST_FILE"
claude -p "Napisz testy Vitest dla @$FILE: każda eksportowana funkcja i przypadki brzegowe.
Zwróć sam kod TypeScript, bez płotków Markdown i bez wyjaśnień." \
--model sonnet --max-turns 5 > "$TEST_FILE.tmp" || continue
mv "$TEST_FILE.tmp" "$TEST_FILE"Terminal podstawia ścieżkę za $FILE, zanim Claude zobaczy zdanie, więc @ w każdym obrocie wskazuje inny plik. || continue przechodzi do następnego pliku, gdy claude się nie uda: zostaje wtedy tylko .tmp, a następne uruchomienie spróbuje jeszcze raz. Gdyby wynik szedł prosto do .test.ts, nieudany plik zablokowałby test na zawsze, bo [ -f ] uznałby go za gotowy. Ostatni fragment łapie najczęstszy błąd agenta:
if grep -q '^```' "$TEST_FILE"; then
echo "Płotki Markdown w $TEST_FILE: usuń je przed uruchomieniem testów"
fi
doneGdy Claude owinie kod w płotki Markdown, plik przestaje być TypeScriptem. Na atrapie z płotkami Vitest zgłosił u nas TypeError: "" is not a function i nie uruchomił ani jednego testu. Ten sam skrypt zadziała z Jest: zmień w poleceniu słowo Vitest na Jest, a w projekcie z kodem w src/ także ścieżkę w find.
Przegląd kapitana
Uruchom bash scripts/generate-tests.sh i zanim cokolwiek dodasz do commita, sprawdź:
- Każdy plik testów osobno:
npm run test -- --run lib/plural.test.ts. U nas Claude napisał dlalib/plural.ts34 przypadki i wszystkie przeszły. - Test na czerwono: na chwilę zepsuj funkcję, jak w lekcji 10_4. W
lib/plural.tszamieniliśmyforms.fewnaforms.manyi 11 z 34 testów zmieniło kolor na czerwony. Potemgit restore lib/plural.ts. Test, który przechodzi mimo zepsutej funkcji, jest atrapą. - Esej zamiast kodu: strażnik płotków nie złapie odpowiedzi pisanej prozą, takiej jak w lekcji 14_1, gdy zapis został zablokowany. Złapie ją dopiero uruchomienie testu, więc punkt 1 jest obowiązkowy.
Polecenie dla Claude Code: commit
Trzeci skrypt kończy się Twoim podpisem:
Napisz scripts/smart-commit.sh: z diffu w poczekalni claude -p proponuje opis commita
w formacie Conventional Commits, skrypt go pokazuje i robi commit dopiero, gdy wpiszę y.
Pusta poczekalnia kończy skrypt bez wołania Claude. Nie uruchamiaj skryptu.Conventional Commits to umowa o kształcie opisu: typ(zakres): opis, gdzie typ to na przykład feat dla nowej funkcji, fix dla poprawki albo test i docs.
Co napisał Claude: smart-commit.sh
Najpierw strażnik pustej poczekalni:
DIFF=$(git diff --cached)
if [ -z "$DIFF" ]; then
echo "Poczekalnia jest pusta. Najpierw: git add <pliki>"
exit 1
fi$(...) wykonuje komendę i wkłada jej wyjście do zmiennej. [ -z "$DIFF" ] pyta, czy zmienna jest pusta, a exit 1 kończy skrypt z kodem błędu, zanim zapłacisz za opis niczego. Potem propozycja:
MESSAGE=$(echo "$DIFF" | claude -p "Napisz opis commita w formacie Conventional Commits: typ(zakres): opis, po polsku, pierwsza linia do 50 znaków. Zwróć sam opis." \
--model sonnet --tools "" --max-turns 2)Diff płynie potokiem, a odpowiedź ląduje w MESSAGE. --tools "" wystarcza, bo do opisu Claude potrzebuje tylko diffu. Na koniec zgoda:
echo "Propozycja: $MESSAGE"
read -r -p "Commit z tym opisem? (y/n) " ANSWER
if [ "$ANSWER" = "y" ]; then
git commit -m "$MESSAGE"
else
echo "Anulowane, nic nie zapisano."
firead zatrzymuje skrypt i czeka na Twoją odpowiedź z klawiatury, a git commit -m rusza tylko po y. Każda inna odpowiedź niczego nie zapisuje. To nie ozdoba: opis może pominąć coś, co widzisz tylko Ty, na przykład że zmiana limitu tagów była celowa. Commit podpisuje człowiek, zawsze.
Następny krok: wachta w CI
Workflow z @claude znasz z lekcji 12_7. Nowa jest recenzja, która zostawia uwagi przy konkretnych liniach pull requesta. Dokumentacja pokazuje ją jako krok akcji z oficjalnym pluginem code-review:
plugins: "code-review@claude-plugins-official"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'Wyżej w tym kroku stoi plugin_marketplaces z adresem oficjalnego marketplace'u. --comment każe opublikować recenzję w pull requeście: komentarz przy każdej linii z problemem albo jeden komentarz podsumowania. claude_args musi wymienić narzędzie do komentarzy, bo akcja uruchamia je tylko wtedy, gdy --allowedTools je nazywa. W publicznym repozytorium GitHub nie daje sekretów przebiegom z forków, więc recenzja ruszy tylko dla gałęzi z Twojego repozytorium.
Gdy zostawiasz Claude samego, best practices radzą zestaw trzech flag: --allowedTools zatwierdza dokładnie to, czego zadanie potrzebuje, --permission-mode dontAsk odrzuca resztę, a --max-turns zatrzymuje przebieg. Dorzucają pięć pytań: czy zadanie wie, jak wygląda koniec, czy może się sprawdzić, czego wolno mu dotykać, co je zatrzyma i kto zatwierdza wynik. Przy naszych skryptach odpowiedź na ostatnie brzmi zawsze tak samo: Ty.
W edytorze obok przepuścisz pliki z lib/ przez pętlę generate-tests.sh i zobaczysz, które pominie, gdzie zostawi .tmp i który test zdradzi atrapę.
Zapamiętaj: automat proponuje, marynarz decyduje, a każdy skrypt kończy się na Twoim podpisie.
Kod do tej lekcji: App.tsx
// Symulator pętli generate-tests.sh: co skrypt pominie, co zapisze i który test pilnuje
import { useState } from 'react';
export type Reply = 'code' | 'weak' | 'fenced' | 'essay' | 'error';
export type Status = 'has-test' | 'no-function' | 'written' | 'failed';
export interface LibFile {
path: string;
hasTest: boolean;
exportsFunction: boolean;
}
export interface FileResult {
path: string;
status: Status;
verdict: string;
guarded: boolean;
}
export const FILES: LibFile[] = [
{ path: 'lib/boards.ts', hasTest: true, exportsFunction: true },
{ path: 'lib/columns.ts', hasTest: false, exportsFunction: true },
{ path: 'lib/imageCheck.ts', hasTest: false, exportsFunction: true },
{ path: 'lib/plural.ts', hasTest: false, exportsFunction: true },
{ path: 'lib/price.ts', hasTest: true, exportsFunction: true },
{ path: 'lib/prisma.ts', hasTest: false, exportsFunction: false },
{ path: 'lib/session.ts', hasTest: false, exportsFunction: true },
{ path: 'lib/types.ts', hasTest: false, exportsFunction: false },
];
const REPLY_LABEL: Record<Reply, string> = {
code: 'sam kod z prawdziwymi asercjami',
weak: 'sam kod, ale expect(1).toBe(1)',
fenced: 'kod w płotkach Markdown',
essay: 'opis prozą zamiast kodu',
error: 'błąd: limit tur',
};
export function testPath(path: string): string {
return path.replace(/\.ts$/, '.test.ts');
}
const VERDICT: Record<Reply, string> = {
code: 'Zielony, a po zepsuciu funkcji czerwony: test pilnuje.',
weak: 'Zielony nawet po zepsuciu funkcji: atrapa, odrzuć ją.',
fenced: 'Vitest: TypeError: "" is not a function, żaden test nie ruszył.',
essay: 'Strażnik milczy, bo nie ma płotków. Błąd składni pokaże dopiero uruchomienie testu.',
error: 'Zostaje tylko plik .tmp z komunikatem błędu. Następne uruchomienie spróbuje znowu.',
};
export function runLoop(files: LibFile[], replies: Record<string, Reply>, existing: string[]) {
const log: string[] = [];
const results: FileResult[] = [];
const created: string[] = [];
for (const file of files) {
const test = testPath(file.path);
if (file.hasTest || existing.includes(test)) {
results.push({ path: file.path, status: 'has-test', verdict: 'Ma test: continue.', guarded: false });
continue;
}
if (!file.exportsFunction) {
log.push('Pomijam ' + file.path + ': nie eksportuje funkcji');
results.push({ path: file.path, status: 'no-function', verdict: 'Brak funkcji do testowania.', guarded: false });
continue;
}
log.push('Piszę testy: ' + test);
const reply = replies[file.path] ?? 'code';
if (reply === 'error') {
results.push({ path: file.path, status: 'failed', verdict: VERDICT.error, guarded: false });
continue;
}
created.push(test);
const guarded = reply === 'fenced';
if (guarded) log.push('Płotki Markdown w ' + test + ': usuń je przed uruchomieniem testów');
results.push({ path: file.path, status: 'written', verdict: VERDICT[reply], guarded });
}
return { log, results, created };
}
const START: Record<string, Reply> = {
'lib/columns.ts': 'code',
'lib/imageCheck.ts': 'fenced',
'lib/plural.ts': 'code',
'lib/session.ts': 'weak',
};
const STATUS_CLASS: Record<Status, string> = {
'has-test': 'text-slate-400',
'no-function': 'text-slate-400',
written: 'text-emerald-400',
failed: 'text-amber-400',
};
export default function App() {
const [replies, setReplies] = useState<Record<string, Reply>>(START);
const [runs, setRuns] = useState(0);
const first = runLoop(FILES, replies, []);
const second = runLoop(FILES, replies, first.created);
const shown = runs === 0 ? null : runs === 1 ? first : second;
return (
<div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
<h1 className="text-xl font-bold">Pętla generate-tests.sh na lib/ z Treasure Map</h1>
<p className="text-sm text-slate-300">Wybierz, co odpowie Claude dla plików bez testów, i uruchom skrypt.</p>
<ul className="space-y-1 text-sm">
{FILES.map((file) => (
<li key={file.path} className="flex flex-wrap items-center gap-2">
<code className="w-40 font-mono">{file.path}</code>
{file.hasTest ? (
<span className="text-slate-400">ma już {testPath(file.path)}</span>
) : !file.exportsFunction ? (
<span className="text-slate-400">nie eksportuje funkcji</span>
) : (
<select
className="rounded border border-slate-600 bg-slate-900 p-1"
value={replies[file.path] ?? 'code'}
onChange={(e) => {
setReplies({ ...replies, [file.path]: e.target.value as Reply });
setRuns(0);
}}
>
{(Object.keys(REPLY_LABEL) as Reply[]).map((r) => (
<option key={r} value={r}>{REPLY_LABEL[r]}</option>
))}
</select>
)}
</li>
))}
</ul>
<div className="flex gap-2">
<button type="button" className="rounded bg-emerald-700 px-3 py-1" onClick={() => setRuns(1)}>bash scripts/generate-tests.sh</button>
<button type="button" className="rounded bg-slate-700 px-3 py-1" disabled={runs === 0} onClick={() => setRuns(2)}>Uruchom drugi raz</button>
</div>
{shown && (
<>
<pre className="rounded bg-slate-900 p-2 font-mono text-xs">{shown.log.length ? shown.log.join('\n') : '(skrypt nic nie wypisał: wszystko ma testy)'}</pre>
<ol className="space-y-1 text-sm">
{shown.results.map((r) => (
<li key={r.path} className="rounded border border-slate-800 p-2">
<strong className={STATUS_CLASS[r.status]}>{r.path}</strong> {r.verdict}
</li>
))}
</ol>
<p role="status" className="font-semibold">
{runs === 1
? 'Uruchom każdy nowy test i zepsuj na chwilę jego funkcję: dopiero wtedy wiesz, który pilnuje.'
: 'Drugi przebieg pomija pliki, które już mają testy, i ponawia tylko nieudane.'}
</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. Dlaczego polecenia w generate-docs.sh kończą się regułą "Zwróć wyłącznie treść pliku Markdown, bez płotków wokół całości i bez zdań od siebie"?
2. Co sprawia, że oficjalna recenzja w GitHub Actions zostawia uwagi przy konkretnych liniach pull requesta?
To 2 z 5 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Układanie w poziomie
Ułóż linię ze smart-commit.sh, która zapisuje propozycję opisu commita w zmiennej MESSAGE:
- Edytor kodu
Napisz w commands.sh skrypt generate-docs.sh, który przez claude -p tworzy trzy pliki: docs/API.md, docs/COMPONENTS.md i README.md. Odpowiedź każdego wywołania zapisz do pliku przekierowaniem >.
- Układanie w poziomie
Ułóż wywołanie z generate-docs.sh, które podmienia docs/API.md tylko po udanym przebiegu:
- Układanie w pionie
Uporządkuj linie pętli z generate-tests.sh od góry do dołu:
- Edytor kodu
Napisz w commands.sh skrypt generate-tests.sh: znajdź pliki .ts w src (find), pomiń te, które mają już plik .test.ts ([ -f ... ]), a dla pozostałych wywołaj claude -p z prośbą o testy Jest.
- Układanie w pionie
Uporządkuj kroki działania skryptu smart-commit.sh:
- Układanie w poziomie
Ułóż linię z generate-tests.sh, która wybiera pliki bez eksportowanych funkcji, żeby je pominąć:
- Układanie w pionie
Uporządkuj pracę z generate-tests.sh, od uruchomienia do commita:
Zadania po tej lekcji
- PytanieQuiz: Sam plik, bez wiadomości
- PytanieQuiz: Komentarze przy liniach w CI
- Ułóż w kolejnościSortowanie: Opis commita do zmiennej
- Zadanie z kodemPraktyka: Generator dokumentacji
- PytanieQuiz: Strażnik płotków Markdown
- Ułóż w kolejnościSortowanie: Zapis przez plik tymczasowy
- PytanieQuiz: Nazwa pliku testów
- Ułóż w kolejnościSortowanie: Linie skryptu generate-tests.sh
- Zadanie z kodemPraktyka: Testy dla plików bez testów
- Ułóż w kolejnościSortowanie: Skrypt smart-commit
- PytanieQuiz: Flagi dla pracy bez nadzoru
- Ułóż w kolejnościSortowanie: Filtr plików bez funkcji
- Ułóż w kolejnościSortowanie: Od skryptu do sprawdzonych testów