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

Agent na wachcie: skrypty do recenzji, dokumentacji, testów i commitów

8 min czytania
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 docs

Wszystko, 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.md

Odpowiedź 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.md

Przy 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
  fi

find 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
  fi

grep -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
done

Gdy 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ź:

  1. Każdy plik testów osobno: npm run test -- --run lib/plural.test.ts. U nas Claude napisał dla lib/plural.ts 34 przypadki i wszystkie przeszły.
  2. Test na czerwono: na chwilę zepsuj funkcję, jak w lekcji 10_4. W lib/plural.ts zamieniliśmy forms.few na forms.many i 11 z 34 testów zmieniło kolor na czerwony. Potem git restore lib/plural.ts. Test, który przechodzi mimo zepsutej funkcji, jest atrapą.
  3. 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."
fi

read 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. 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. 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:

  1. PytanieQuiz: Sam plik, bez wiadomości
  2. PytanieQuiz: Komentarze przy liniach w CI
  3. Ułóż w kolejnościSortowanie: Opis commita do zmiennej
  4. Zadanie z kodemPraktyka: Generator dokumentacji
  5. PytanieQuiz: Strażnik płotków Markdown
  6. Ułóż w kolejnościSortowanie: Zapis przez plik tymczasowy
  7. PytanieQuiz: Nazwa pliku testów
  8. Ułóż w kolejnościSortowanie: Linie skryptu generate-tests.sh
  9. Zadanie z kodemPraktyka: Testy dla plików bez testów
  10. Ułóż w kolejnościSortowanie: Skrypt smart-commit
  11. PytanieQuiz: Flagi dla pracy bez nadzoru
  12. Ułóż w kolejnościSortowanie: Filtr plików bez funkcji
  13. Ułóż w kolejnościSortowanie: Od skryptu do sprawdzonych testów

Przydatne artykuły