Build: plan.md, potem implementacja

Etap build zmienia zaakceptowany spec.md w commitowany plan.md, izolowaną implementację i pierwsze dowody weryfikacji. Plan mode oddziela analizę od mutacji, a instrukcje repo, skille, hooki i worktree utrzymują powtarzalność wykonania bez przyznawania agentowi prawa do merge albo wdrożenia.

Tradycyjnie: Inżynier czyta design i zaczyna pisać kod. Jak zmiana zostanie zrobiona, zostaje w jego głowie. Pierwszą rzeczą, którą widzi reviewer, jest gotowy diff, a wtedy rework jest wolny.

AI-native: Praca zaczyna się od spisanego planu, który agent produkuje w plan mode, gdzie może czytać codebase bez zmian. Inżynier poprawia plan, zanim powstanie kod. Zatwierdzona wersja jest commitowana jako plan.md.

Zanim zaczniesz

• intent.md i spec.md, jeśli istnieją
• Plik instrukcji projektu: CLAUDE.md, .cursor/rules lub AGENTS.md
• Komenda testu lub builda, którą agent może uruchomić lokalnie (zobacz Test)

Zacznij w plan mode

1. Uruchom sesję w plan mode, żeby agent jeszcze nie mógł edytować plików.

2. Daj agentowi intent.md i spec.md i poproś o plan implementacji, który nazywa pliki do zmiany, kolejność pracy i testy, które to udowodnią.

3. Przesłuchaj plan.

   Zapytaj, co zmiana może zepsuć, który krok jest najbardziej ryzykowny i jakie inne opcje agent odrzucił.

4. Iteruj, aż inżynier, który nigdy nie widział rozmowy, mógłby zaimplementować zmianę z samego planu.

5. Commitnij zatwierdzony plan jako plan.md.

   Późniejsze review sprawdza ostateczny diff względem tego pliku.

6. Zaakceptuj plan i pozwól agentowi implementować.

   Przy solidnym planie implementacja często jest jednym przejściem.

7. Gdy implementacja odbiega od planu, zaktualizuj plan.md w tym samym commicie.

Claude Code

Shift+Tab przełącza tryby uprawnień, aż aktywny będzie plan mode, potem:

Read intent/FEATURE.md and spec.md. Produce plan.md that names the
files that change, the order of work, the risks, and the tests that
prove it. Do not edit application code until I accept the plan.

Po zaakceptowaniu planu przełącz się na najmniej uprzywilejowany tryb, który może wykonać zatwierdzony fragment. Równoległą pracę izoluj w osobnych worktree:

claude -w feature-auth

Zweryfikowana opcja -w/--worktree tworzy izolowany checkout Git dla sesji. Repozytoryjny helper jest lepszy, gdy setup wymaga także portów, ignorowanej konfiguracji albo lokalnej bazy.

Cursor

Przełącz się na Plan mode, dołącz spec.md i poproś o plan.md w repo — nie tylko plan pod .cursor/plans/. Kopia w repo to to, co późniejsze review i inne narzędzia mogą czytać.

Do pracy równoległej uruchom Cloud Agent per niezależne zadanie albo użyj lokalnych git worktrees. Cloud Agents ładują command-based hooks z .cursor/hooks.json.

Codex

Użyj /plan lub Shift+Tab. /plan istnieje w CLI Codex, nie tylko w aplikacji web. approval_policy to osobna kontrola (kiedy pytać o akceptację), nie zamiennik planowania.

Przy dłuższej pracy zapisz zaakceptowany plan w repozytorium. Wybierz Worktree w aplikacji Codex albo utwórz go jawnie przez Git; Codex CLI 0.146.0 nie ma flagi --worktree.

Wiedza instytucjonalna

Wiedza, która siedziała w głowach ludzi, staje się plikiem, który agent czyta na starcie każdej sesji.

1. Wygeneruj plik startowy (/init w Claude Code albo poproś agenta o draft AGENTS.md / .cursor/rules z repo).

2. Przytnij go do tego, czego nowy joiner potrzebuje pierwszego dnia: komendy build, test i lint; konwencje, które mają znaczenie; błędy, które agent powtarza.

3. Wrzuć plik do gita w rootcie repo, żeby cały zespół dzielił jedną wersję.

4. Gdy agent popełni błąd dwa razy, wpisz korektę do pliku.

5. Trzymaj go krótko. Przestarzały tekst kosztuje kontekst i nikomu nie pomaga.

Przykładowy CLAUDE.md (ta sama treść należy do AGENTS.md lub reguły Cursor):

# Payments service

## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint

## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.

## Things the agent gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.

Skills versus rules

Napisz skill (SKILL.md) dla wiedzy instytucjonalnej, która musi być stosowana konsekwentnie: standard security, konwencja API, reguła brandu. Umieść go w .claude/skills/NAME/, .cursor/skills/ lub .agents/skills/. Cursor czyta też .claude/skills/ dla kompatybilności.

Nie pisz skilla dla faktów, które należą do CLAUDE.md / AGENTS.md (komendy, lokalne konwencje). Skill jest doradczy. Polityka, która musi zawsze obowiązywać, potrzebuje hooka za sobą.

Hooki build-time

Hook to deterministyczna warstwa za skillem. Podczas implementacji hooki mogą:

• Blokować edycje chronionych ścieżek (wygenerowane klasy, zamrożony pakiet)
• Uruchamiać formatter i linter po edycjach plików
• Trzymać credentials poza diffem

Trzymaj hooki fazy build szybkie i ograniczone do zmienionego pliku. Cięższe checki należą do commit lub PR. Hook, który prosi człowieka o akceptację, należy do Deploy, bo prompt akceptacji podczas builda stawia osobę z powrotem na krytycznej ścieżce każdej równoległej sesji.

Claude Code: .claude/settings.json plus skrypty pod .claude/hooks/. Cursor: .cursor/hooks.json. Codex: sandbox mode plus approval_policy — nie ma runtime hooków identycznego z Claude Code; koduj politykę must-hold jako sandbox denies i CI.

Sesje równoległe i subagenci

Dziel pracę, która dotyka różnych plików. Zadania dzielące pliki uruchamiaj w jednej sesji, jedno po drugim.

Sesja równoległa to kolejny pełny agent we własnym worktree. Subagent działa wewnątrz jednej sesji z własnym kontekstem i limitami narzędzi (verifier, researcher, simplifier). Dwie lub trzy sesje to rozsądny start; sufitem jest to, ile streamów jedna osoba może zrecenzować.

Zamień powtarzalne joby w subagentów wrzuconych do gita (.claude/agents/ lub odpowiednik Cursor/Codex). Przykładowy verifier:

---
name: verifier
description: Runs the app and checks the change works before the session reports done
tools: Bash, Read
---
Start the app with make run. Exercise the changed behavior and the two
nearest neighboring flows. Report what you ran, what you saw, and any
behavior that does not match plan.md. Do not fix anything; report only.

Verifier nie jest pętlą feedbacku. Pętla działa przez całe zadanie; verifier to świeże okno kontekstu na końcu, żeby werdykt nie był zabarwiony założeniami, które wyprodukowały kod. Zobacz Test.

Governance

Design review dzieje się, zanim powstanie jakikolwiek kod — gdy zmiana kursu to nadal edycja dokumentu. Plan mode to egzekwuje: agent nie może edytować plików, dopóki inżynier nie zaakceptuje planu. Rutynowe zmiany zatwierdza inżynier. Praca wyższego ryzyka idzie do tech leada lub architekta.

Więcej sesji oznacza więcej outputu, więc kontrole muszą pochodzić z konfiguracji w repo. Hooki i ustawienia uprawnień tam obowiązują wszystkie sesje. To, co sesja zrobi, jest przypisywane inżynierowi, który ją uruchomił.

Verify

• plan.md jest commitowany, zanim wylądują zmiany w kodzie aplikacji.
• Plik instrukcji wymienia komendy, które agent faktycznie uruchomił.
• Testy lub build przeszły wewnątrz sesji, zanim otworzyłeś PR.

Wskaźnik wiodący: udział zmian mergowanych z pierwszego przejścia implementacji oraz czas od akceptacji planu do zmergowanego PR.

Wskaźnik opóźniony: cykle reworku per zmiana oraz jak często zmergowany diff nadal pasuje do commitowanego plan.md.

Zastosuj praktykę w swoim narzędziu

Adapter Claude Code Użyj Plan mode, claude -w, subagentów i deterministycznych hooków.

Adapter Cursora Użyj Plan mode, worktree w Agents Window lub /worktree i reguł projektu.

Adapter Codex Użyj /plan, worktree aplikacji lub Git, AGENTS.md i jawnego sandboxa.

Przekaż implementację do weryfikacji

Daj sesji sposób na sprawdzenie własnej pracy — Test — potem wyślij diff przez Deploy.