Planowanie funkcji w Claude Code: od jednozdaniowej prośby do zweryfikowanego planu

Planowanie funkcji w Claude Code zamienia mglistą prośbę w plan, który można zweryfikować, zanim zmieni się choćby jedna linia kodu. Plan mode pozwala Claude czytać bazę kodu, a edycje pozostają zablokowane. Claude przeprowadza wywiad o wymagania, spisuje kryteria akceptacji i pisze etapowy plan. Świeża sesja audytuje następnie ten plan względem kodu, zanim ktokolwiek go zatwierdzi.

Product manager wrzuca na Slacka jedno zdanie: „Admini workspace’u mają móc zapraszać współpracowników mailem”. Nie ma specyfikacji. Nikt nie powiedział, co się dzieje, gdy zaproszona osoba ma już konto, gdy w workspace’ie skończyły się miejsca (seats) albo gdy ktoś prześle link z zaproszeniem dalej. Ta strona jest dla dewelopera, który odpowiada za tę funkcję, i dla tech leada, który zatwierdza plan, zanim agent zacznie go realizować.

Co zyskasz dzięki temu przewodnikowi

• Konfigurację sesji w plan mode z poziomem wysiłku (effort) i modelem wybranymi świadomie, a nie z przyzwyczajenia.
• Sześć promptów do skopiowania: eksploracja kodu, wywiad o wymagania, kryteria akceptacji, etapowy plan, audyt planu w świeżej sesji i badanie zakresu subagentami.
• Tabelę zatwierdzeń, która mówi, jaka kontrola dowodzi której części planu i kto ją podpisuje, więc nikt nie musi czytać całego planu linijka po linijce.
• Sposoby wyjścia z typowych problemów: zbyt ogólne plany, wymyślone ścieżki plików, zapętlone wywiady i kończący się kontekst.

Jak zacząć sesję planowania funkcji w Claude Code?

Plan mode to tryb uprawnień plan. Claude może czytać pliki i uruchamiać zatwierdzone dla niego polecenia, ale nie może edytować plików projektu, dopóki nie zatwierdzisz planu. Właśnie tego chcesz, dopóki wymagania są jeszcze błędne.

1. Uruchom nazwaną sesję w plan mode. W terminalu wpisz:

   claude --permission-mode plan -n invites-planning

   -n (--name) ustawia nazwę wyświetlaną w oknie wyboru sesji /resume, więc za tydzień łatwo znajdziesz tę sesję. W działającej już sesji naciskaj Shift+Tab, aż wskaźnik trybu pokaże plan mode, albo wpisz /plan razem z prośbą. Od v2.1.283 (kanał latest) sesje interaktywne na obsługiwanych modelach startują w auto mode, więc Shift+Tab przechodzi przez więcej trybów niż wcześniej.

2. Zostaw domyślny model i najpierw dostrój poziom effort. Claude Opus 5.5 jest domyślnym modelem Claude Code na każdym płatnym planie od v2.1.280 (kanał wydań latest) i domyślnie działa z poziomem effort medium. Przy funkcji z prawdziwą niejasnością, jak zaproszenia dotykające uwierzytelniania, rozliczeń i maili, podnieś poziom effort poleceniem /effort high, zanim pomyślisz o zmianie modelu. Na Claude Fable 5.1 (/model fable) przełączaj się dopiero wtedy, gdy twoje własne porównanie pokaże, że Opus na wyższym poziomie effort nie wystarcza. Alias opusplan używa Opusa w plan mode i Sonneta przy wykonaniu, jeśli chcesz tańszej fazy budowania. Wersje i ceny są w hubie modeli, a głębokie rozumowanie i poziomy effort wyjaśnia ten kompromis.

3. Zdecyduj, gdzie zapisywać plany. Domyślnie Claude Code zapisuje pliki planów w ~/.claude/plans/, poza repozytorium. Żeby trzymać plany obok kodu, gdzie można je przejrzeć w pull requeście, ustaw plansDirectory w .claude/settings.json:

   {
     "plansDirectory": "docs/plans"
   }

   Ścieżka jest względna wobec katalogu głównego projektu i musi w nim pozostać (sprawdzone w schemacie ustawień v2.1.283).

4. Wciągnij zgłoszenie, jeśli żyje w trackerze. Serwer MCP oszczędza ręcznego wklejania wymagań. Dla Jiry i Confluence zdalny serwer Atlassiana dodajesz z terminala:

   claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp

   Potem uruchom w sesji /mcp, żeby się zalogować. Inne trackery i kompromisy bezpieczeństwa opisuje konfiguracja MCP w Claude Code.

Notatka

Jeśli nie znasz jeszcze bazy kodu, zacznij od analizy bazy kodu. Jeśli funkcja wymusza decyzję strukturalną, na przykład nową usługę, nowy magazyn danych albo model multi-tenancy, podejmij ją w analizie architektury i zapisz jako ADR. Ta strona planuje funkcję wewnątrz architektury, którą już masz.

Najpierw zbadaj kod, potem planuj

Najczęstszy błąd planowania to plan napisany pod wyobrażoną bazę kodu. Zacznij od tego, żeby Claude pokazał, co istnieje, z dowodami, które sprawdzisz w kilka sekund.

Prompt do skopiowania: eksploracja przed planowaniem

We are going to plan a feature: workspace admins invite teammates by email.
Do not propose a design yet. First report what already exists:

1. How users, workspaces and memberships are modelled (tables, models, relations).
2. How sign-up and login work today, including any magic-link or token flows.
3. Where roles and permissions are checked for workspace-level actions.
4. How transactional email is sent, and whether there is a template system.
5. Whether seats or plan limits are enforced anywhere, and where.
6. The closest existing feature to this one, which we should imitate.

Cite every claim as path:line. If you did not find something, say
"not found" and list where you looked. Do not guess.

Otwórz samodzielnie dwie lub trzy cytowane linie. Jeśli cytat jest błędny, zatrzymaj się i popraw sesję, zanim zaczniesz planować. Każdy kolejny krok odziedziczy ten błąd.

Niech Claude przeprowadzi z tobą wywiad o wymagania

Nie znasz wszystkich pytań, które trzeba zadać, a te pominięte stają się błędami na produkcji. Poproś Claude o wywiad z użyciem narzędzia AskUserQuestion, które pokazuje w terminalu pytania z odpowiedziami do wyboru zamiast ściany tekstu.

Prompt do skopiowania: wywiad o wymagania

Interview me about the team-invitations feature using the AskUserQuestion tool.
Ground every question in what you found in the code, and ask in batches of
at most four questions.

Cover: invitees who already have an account, invitees who belong to another
workspace, seat limits and what happens at the limit, invitation expiry and
revocation, forwarded or reused links, who is allowed to invite, rate limits
and abuse, audit logging, and what happens to pending invitations when the
inviter leaves.

Skip anything the code already answers. After each batch, write down the
decisions so far in one list. Stop when no open question would change the
data model, the API or the permissions, and tell me which questions you
deliberately left open.

Dobry wywiad daje pytania takie jak te, każde powiązane z linią twojego kodu:

• „memberships ma unikalny indeks na (user_id, workspace_id). Zaproszenie istniejącego członka ma być no-opem, błędem czy ponownym wysłaniem?”
• „Miejsca są liczone w billing/seats.ts tylko przy zakupie. Czy oczekujące zaproszenie ma rezerwować miejsce?”
• „Tokeny magic-link w auth/tokens.ts nigdy nie wygasają. Czy tokeny zaproszeń mają używać tego kodu, czy mieć własny czas wygaśnięcia?”

Odpowiadaj w terminalu. Gdy odpowiadasz „nie wiem”, każ Claude zapisać pytanie jako otwarte, zamiast wymyślać odpowiedź.

Zamień odpowiedzi w kryteria akceptacji przed planem

Kryteria akceptacji to ta część planu, którą człowiek zatwierdza zamiast diffa. Spisz je przed planem implementacji. W przeciwnym razie plan po cichu zdecyduje o zachowaniu za ciebie.

Prompt do skopiowania: kryteria akceptacji

From the decisions we just recorded, write acceptance criteria for team
invitations as Given/When/Then scenarios.

Rules:
- One observable behaviour per scenario. No implementation details.
- Include the failure cases we discussed: seat limit reached, expired token,
  revoked invitation, token reused by a different email, non-admin inviter.
- Give each scenario an ID (INV-01, INV-02, ...).
- Mark every scenario that depends on an open question as BLOCKED and name
  the question.

Put them under a heading "Acceptance criteria" at the top of the plan.

Tę listę zatwierdza product owner albo właściciel funkcji. Pełną praktykę, łącznie z zamianą każdego scenariusza w czerwony test, którego agent implementujący nie może edytować, opisuje strona wykonywalne kryteria akceptacji.

Napisz etapowy plan, który można wdrażać częściami

Teraz poproś o sam plan. Prompt wymusza trzy cechy, dzięki którym agent może plan wykonać, a ty sprawdzić: nazwane pliki, niezależne etapy i polecenie weryfikujące dla każdego etapu.

Prompt do skopiowania: etapowy plan implementacji

Write the implementation plan for team invitations below the acceptance
criteria.

For each phase:
- Goal, and the acceptance-criteria IDs it satisfies.
- Files to create or change, as exact paths. Mark new files as NEW.
- Database migration, if any, and how to roll it back.
- Tests to write first, named after the INV-xx IDs they prove.
- The one command that shows the phase is done (for example
  "pnpm test invitations" plus "pnpm typecheck").
- Risks, and what we do if the phase has to be reverted.

Order the phases so each one can merge and deploy on its own behind a
feature flag. Follow the patterns of the closest existing feature you
found earlier; do not introduce a new library or pattern without
flagging it as a decision for me. End with a list of open questions.

Gdy Claude przedstawi plan, możesz go zatwierdzić, planować dalej albo go edytować. Naciśnij Ctrl+G, żeby otworzyć plan w domyślnym edytorze tekstu. Wytnij zakres, który chcesz odłożyć, zmień kolejność etapów, dopisz uwagi, a potem zapisz i zamknij edytor. Claude kontynuuje od twojej poprawionej wersji.

Pliki planów dostają wygenerowaną nazwę. Prompty audytu i wznowienia poniżej czytają docs/plans/team-invitations.md, więc nadaj planowi tę stałą ścieżkę przed zatwierdzeniem, tak jak pokazuje ostrzeżenie poniżej, albo zmień nazwę pliku samodzielnie.

Uwaga

Każda opcja zatwierdzenia kończy plan mode w tej sesji i Claude zaczyna edytować pliki; uwaga dopisana przy zatwierdzeniu nie zatrzyma tego niezawodnie. Jeśli potrzebujesz tylko dokumentu, wybierz zamiast tego opcję dalszego planowania i wpisz: „Write the plan to docs/plans/team-invitations.md and stop. Do not implement.” Jeśli plan jest już zatwierdzony, naciśnij Esc, żeby zatrzymać Claude, zanim zacznie edytować.

Jak zweryfikować plan bez czytania każdej linijki?

Plan to zbiór twierdzeń o twojej bazie kodu: „ten plik istnieje”, „ta funkcja to jedyne miejsce, gdzie liczone są miejsca”, „etap 2 nie zależy od etapu 3”. Każde twierdzenie ma tanią kontrolę. Uruchamiaj kontrole w świeżej sesji, bo sesja, która postawiła tezę, ma skłonność do jej potwierdzania.

Prompt do skopiowania: audyt planu w świeżej sesji

Read docs/plans/team-invitations.md. You did not write it. Audit it
against the codebase and report a table with one row per finding.

Check:
1. Every path marked as existing exists, and every cited function is
   where the plan says.
2. Every acceptance criterion (INV-xx) is covered by at least one phase
   and at least one named test. List any criterion with no test.
3. No phase depends on a later phase. List any hidden dependency.
4. Every migration has a rollback step.
5. Nothing in the plan contradicts the patterns in the closest existing
   feature. Cite path:line for each contradiction.
6. Every place that checks workspace permissions or seats is in scope.
   Use subagents to search the whole repository and list any the plan
   misses.

Mark each row SUPPORTED, WRONG or MISSING. Do not fix the plan.

Uruchom go poleceniem claude --permission-mode plan w nowym terminalu. Wiersze WRONG i MISSING odeślij do sesji planującej i powtarzaj, aż audyt będzie czysty. Potem ta tabela mówi, kto co zatwierdza:

Część planu	Jak jest sprawdzana	Kto zatwierdza
Kryteria akceptacji	Czytane w całości; z założenia są krótkie	Product owner albo właściciel funkcji
Ścieżki plików i cytowany kod	Audyt w świeżej sesji, punkty 1 i 5	Nikt, jeśli audyt jest czysty
Pokrycie kryteriów testami	Punkt 2 audytu, potem czerwone testy napisane przed etapem 1	Deweloper
Kolejność etapów i rollback	Punkty 3 i 4 audytu	Tech lead, przy planach z więcej niż jedną migracją
Kompletność zakresu	Przeszukanie subagentami, punkt 6 audytu	Deweloper sprawdza wyrywkowo dwa wyniki

Ludzka lektura skupia się na kryteriach akceptacji i otwartych pytaniach. Resztę sprawdza narzędzie albo niezależna sesja, a w trakcie implementacji testy i bramki, które nazywa każdy etap. Szerszą praktykę opisuje strona dowody zamiast diffów.

Zbadaj zakres za pomocą subagentów

W dużej bazie kodu sesja planująca szybko zapełnia się wynikami eksploracji. Oddeleguj wyszukiwanie subagentom, które działają we własnym kontekście i zwracają tylko podsumowanie. Explore i Plan to wbudowane subagenty; własne instrukcje i ograniczenia narzędzi opisuje strona własne subagenty.

Prompt do skopiowania: badanie zakresu subagentami

Before we finalise the plan, use subagents in parallel to find:

1. Every query that reads or writes workspace memberships.
   List by file and line.
2. Every API route that lists users or members, which would need to
   show or hide pending invitations.
3. Every background job or webhook that assumes one user per seat.

Each subagent returns at most 20 lines. Then tell me which findings
change the plan, and update the plan's file list.

Planuj w kilku sesjach, nie gubiąc decyzji

Duże funkcje nie mieszczą się w jednym posiedzeniu. Wróć później do nazwanej sesji poleceniem claude --resume invites-planning, które otwiera listę wyboru sesji przefiltrowaną po tym haśle. Nazwę działającej sesji zmienisz poleceniem /rename.

Jeśli sesja jest przeładowana wynikami eksploracji, uruchom /compact Keep the decisions, acceptance criteria and open questions albo zacznij od nowa z zapisanych plików:

Read docs/plans/team-invitations.md. It holds the acceptance criteria,
the phased plan and the open questions from earlier planning sessions.
List the open questions first, then tell me which phase is ready to
start and which failing tests must exist before it does.

Źródłem prawdy jest plik planu, nie rozmowa. Jeśli trzymasz specyfikacje jako długowieczne dokumenty aktualizowane w każdym pull requeście, stosuj spec-driven development. Lżejszy przepływ od PRD do listy zadań opisuje PRD → plan → todo.

Co się psuje przy planowaniu funkcji w Claude Code?

Plan jest zbyt ogólny, żeby go wykonać. Etapy brzmią jak „dodaj logikę zaproszeń”. Wyjście: „For each phase, name the exact files and describe each change in one sentence. If you cannot name the file, say which search you need to run.” Plan, który nie potrafi nazwać plików, powstał przed eksploracją kodu; wróć do promptu eksploracyjnego.

Plan cytuje pliki lub funkcje, które nie istnieją. Claude wypełnił lukę wiarygodnie brzmiącą nazwą. Wyjście: wyłapie to audyt w świeżej sesji. Każdą ścieżkę oznaczoną jako WRONG traktuj jako sygnał, że otaczająca ją sekcja też nie jest zweryfikowana, i powtórz eksplorację dla tego obszaru.

Wywiad się zapętla albo pyta o to, na co odpowiada kod. Wyjście: „You already asked about X. The code answers Y at path:line. Move on to the areas we have not covered: seat limits and token reuse.”

Plan wymyśla nowy wzorzec. Proponuje nową bibliotekę kolejek albo nowy model uprawnień, choć baza kodu już je ma. Wyjście: „Follow how we implemented <closest feature>. List every place your plan departs from it, and justify each one or remove it.”

Poziom effort jest za niski do skali niejasności albo za wysoki do zadania. Na medium plan przekrojowej funkcji może pominąć przypadki brzegowe; na xhigh mała zmiana zjada czas i limit użycia. Wyjście: podnieś poziom effort poleceniem /effort high na czas wywiadu i planu, a przy małych, dobrze rozpoznanych funkcjach wróć do /effort medium. Model zmieniaj dopiero wtedy, gdy twoje własne porównanie tak wskaże.

Sesja zatwierdza plan i zaczyna kodować, zanim jesteś gotowy. Wyjście: naciśnij Esc, żeby przerwać, a potem /rewind (albo dwa razy Esc przy pustym prompcie), żeby wrócić do punktu sprzed edycji. Następnym razem zamiast zatwierdzać wybierz opcję dalszego planowania i poproś Claude, żeby zapisał plan i się zatrzymał.

Kontekst kończy się w połowie planowania. Wyjście: zapisz plik planu, uruchom /compact z instrukcją zachowania decyzji i otwartych pytań albo zacznij świeżą sesję od pliku planu.

Dokąd dalej po zatwierdzeniu planu

Wykonywalne kryteria akceptacji Zamień każdy scenariusz INV-xx w czerwony test, którego agent implementujący nie może edytować.

Implementacja w Claude Code Wykonaj zatwierdzony plan etap po etapie, z testami i bramkami na każdym kroku.

Analiza architektury i projektowanie systemu Podejmij decyzje strukturalne, których plan funkcji nie powinien podejmować sam.

Spec-driven development Utrzymuj specyfikację jako źródło prawdy, gdy funkcja ewoluuje przez kolejne pull requesty.

Pracujesz w innym narzędziu? Etap planowania dla Codexa opisuje planowanie z Codexem, a dla Cursora planowanie z Cursorem. Resztę tego etapu znajdziesz w przeglądzie planowania w Claude Code.