Planowanie i specyfikacja: kontrakt przed kodem

Planowanie i specyfikowanie pracy z agentami AI polega na przygotowaniu kontraktu, według którego agent buduje: intent.md, spec.md z numerowanymi wymaganiami, kryteriów akceptacji istniejących już jako czerwone testy, decyzji architektonicznych oraz – przy pracy nad UI – zaakceptowanego kontraktu wizualnego. Konkretna, wskazana osoba zatwierdza ten kontrakt, zanim powstanie kod, a recenzenci sprawdzają wynik względem niego, zamiast czytać każdą linię.

Ta sekcja jest dla programistów, którzy zlecają pracę Claude Code, Codeksowi lub Cursorowi, oraz dla tech leadów, którzy tę pracę zatwierdzają. Agent otwiera pull request na 1200 linii, który się kompiluje, przechodzi własne testy i rozwiązuje nieco inny problem niż ten z ticketu. Code review zamienia się w odtwarzanie wymagań z diffa. Strony w tej sekcji przenoszą tę dyskusję przed kod, gdzie jest tania.

Który przewodnik po planowaniu pasuje do twojego problemu?

Twoja sytuacja	Zacznij od
Specyfikacja dezaktualizuje się tydzień po napisaniu	Spec-driven development
O tym, co znaczy „gotowe”, rozstrzyga się w code review, a nie na starcie	Wykonywalne kryteria akceptacji
Agent po cichu łamie warstwy albo dobiera nową bibliotekę	Decyzje architektoniczne, których agenci przestrzegają
Nowy przepływ UI wymaga uzgodnienia stanów i breakpointów przed kodowaniem	Pipeline czterech artefaktów od designu do kodu
Iteracje designu nie zbiegają się	Pętla oceny oparta na dowodach
Product ownerzy już piszą scenariusze w Gherkinie	Behavior-driven development
Agenci mylą pojęcia domenowe między serwisami	Domain-driven design
Przepustowość sprintu ogranicza code review, a nie kodowanie	Praca zwinna z agentami

W jakiej kolejności powstają artefakty planowania?

Dopasuj koszt artefaktu do ryzyka. Dwulinijkowa poprawka błędu potrzebuje czerwonego testu, nie ADR. Nowy przepływ dla klientów potrzebuje wszystkich pięciu kroków.

1. Zapisz intencję. Opisz w intent.md problem, oczekiwany rezultat, dotkniętych użytkowników i ograniczenia. Product owner ją akceptuje. Zobacz zapisywanie intent.md.
2. Napisz specyfikację. Zamień zaakceptowaną intencję w spec.md z numerowanymi wymaganiami i otwartymi pytaniami. Zobacz pisanie spec.md.
3. Zrób kryteria akceptacji wykonywalnymi. Każde wymaganie dostaje scenariusz Given/When/Then i test, który teraz nie przechodzi. Zablokuj te testy przed edycją przez agenta.
4. Zapisz decyzje, które ograniczają kod. Gdy zmiana dotyka architektury, napisz krótki ADR, a tam, gdzie się da, dodaj automatyczną kontrolę. Zobacz decyzje architektoniczne, których agenci przestrzegają.
5. Zaakceptuj kontrakt wizualny. Przy pracy nad UI zatwierdź prototyp albo opisany zrzut ekranu przed implementacją. Zobacz akceptację wizualną przed pracą nad frontendem.

Dopiero wtedy agent przygotowuje plan implementacji i zaczyna budować.

Jak prowadzić sesję planowania w każdym narzędziu?

Każde narzędzie ma tryb planowania, w którym agent czyta i proponuje, zanim cokolwiek zmieni. Używaj go w krokach od 2 do 4, żeby agent przeanalizował kod i przygotował kontrakt, zanim zmieni się jakikolwiek plik. Sprawdzone na Claude Code 2.1.283 i Codex CLI 0.157.1; Cursor według jego dokumentacji z 2026-08-28.

Claude Code

Uruchom sesję w trybie planowania z terminala albo przełącz otwartą sesję poleceniem /plan lub skrótem Shift+Tab:

claude --permission-mode plan

Tryb planowania to jeden z trybów uprawnień. Sesja czyta i proponuje, a niczego nie edytuje, dopóki nie zatwierdzisz planu. Przepływy specyficzne dla narzędzia opisuje planowanie z Claude Code.

Codex

Uruchom codex w repozytorium i wpisz w sesji /plan. Codex przygotowuje plan, zanim napisze kod. Przepływy specyficzne dla narzędzia opisuje planowanie z Codeksem.

Cursor

Przełącz agenta w Plan Mode, który według dokumentacji Cursora tworzy szczegółowy plan implementacji, zanim napisze jakikolwiek kod. Przepływy specyficzne dla narzędzia opisuje planowanie z Cursorem.

Jeśli zamiast ręcznie pisanych plików wolisz gotowy przepływ pracy ze specyfikacją, zobacz OpenSpec na stronie o spec-driven development oraz skille do planowania w frameworkach dla agentów.

Prompt do skopiowania: zaakceptowana intencja jako specyfikacja do przeglądu

Read intent.md and the modules it names. Do not write or change any code.
Draft spec.md with:
- Scope and explicit non-goals.
- Numbered requirements (REQ-1, REQ-2, ...). Each one states observable
  behavior with concrete example values, not implementation.
- For each requirement, one Given/When/Then acceptance scenario.
- Open questions: every place where intent.md is ambiguous or where the
  codebase contradicts it. Do not resolve them yourself.
Finish by listing the files a change would touch and which requirement
each one serves. Stop and wait for my review.

Prompt do skopiowania: zaatakuj specyfikację, zanim ktoś ją zbuduje

You are reviewing spec.md in a fresh session. You did not write it.
For each requirement, answer:
1. Could two competent engineers implement it differently and both claim
   it passes? Quote the ambiguous words.
2. Is the acceptance scenario able to fail? Name an implementation that
   would pass it while missing the intent.
3. What edge case (empty input, permissions, concurrency, time zones,
   partial failure) does it not mention?
Output a table: requirement ID, problem, proposed rewrite. Do not edit files.

Jak sprawdzić plan bez czytania go linijka po linijce?

Strukturę kontraktu sprawdzaj automatycznie, a uwagę ludzi przeznaczaj wyłącznie na decyzje.

• Identyfikowalność wymagań. Każdy identyfikator wymagania występuje w nazwie co najmniej jednego testu, a CI nie przechodzi, gdy któregoś brakuje. Gotową kontrolę znajdziesz na stronie o spec-driven development.
• Testy padają z właściwego powodu. Uruchom testy akceptacyjne przed implementacją. Każdy powinien padać na braku zachowania, a nie na błędzie składni czy brakującym imporcie.
• Niezależna krytyka. Świeża sesja uruchamia drugi prompt z tej strony. Człowiek czyta tylko wiersze, które ten prompt oznaczył.
• Otwarte pytania są zamknięte albo mają właściciela. Specyfikacja z pytaniem bez właściciela nie jest gotowa.
• Imienna akceptacja. Product owner zatwierdza intencję i kryteria akceptacji. Tech lead zatwierdza ADR. Właściciel designu zatwierdza kontrakt wizualny.

Zaakceptowany kontrakt staje się potem częścią pakietu dowodów, który musi spełnić pull request z implementacją.

Co się psuje, gdy agenci planują, i jak z tego wyjść?

Problem	Sygnał	Wyjście
Plan zatwierdzono po pobieżnym przejrzeniu	Code review pull requesta ponownie otwiera zakres	Zatwierdzaj wymagania i scenariusze, a nie prozę planu; najpierw uruchom prompt z krytyką
Agent edytuje testy akceptacyjne, żeby przeszły	Pliki testów zmieniają się w PR z implementacją	Trzymaj testy poza zasięgiem edycji agenta i pilnuj tego w CI: zobacz ochronę wyroczni
Specyfikacja rozjeżdża się z kodem po merge’u	Zachowanie się zmienia, a specyfikacja nie	Wymagaj zmiany specyfikacji w każdym PR, który zmienia zachowanie
Planowanie kosztuje więcej niż sama zmiana	Poprawka jednej linii czeka na przegląd specyfikacji	Skaluj artefakty do ryzyka: przy drobnych poprawkach wystarczy sam czerwony test
UI powstaje przed akceptacją wizualną	Przeróbki po demo dla interesariuszy	Uzależnij implementację od zaakceptowanego prototypu: zobacz akceptację wizualną przed pracą nad frontendem

Dokąd dalej po planowaniu

• Wcześniej: etapy Plan i Design w cyklu życia oraz miejsce każdego narzędzia na mapie narzędzi.
• Dlaczego na wyższych szczeblach drabiny specyfikacja zastępuje czytanie diffów: Poziom 4: piszesz specyfikacje.
• Następny etap: budowanie z agentami według zatwierdzonego kontraktu.