Plan mode w Claude Code — kiedy włączać, kiedy szkoda czasu

Plan mode to oddzielny tryb Claude Code w którym agent nie modyfikuje plików, tylko rozmawia, eksploruje kod i pisze plan. Ostatnie tygodnie nauczyły mnie kiedy ma sens, a kiedy szkoda czasu. Konkrety.

Anatomia dobrego planu

Plan mode wymusza pięć faz:

1. Initial understanding, explore agenty zbierają mapę kodu
2. Design, Plan agent (lub użytkownik) projektuje rozwiązanie
3. Review, sprawdzanie spójności z intencją
4. Final plan, zapis do pliku planu (jedyne co agent może edytować)
5. ExitPlanMode, sygnał że plan gotowy do akceptacji

Plan ma ~150-300 linii markdownu. Sekcje: Context, Phases, Critical Files, Risks. Format ten sam za każdym razem, co ułatwia czytanie.

Kiedy WŁĄCZAM plan mode

Trzy rodzaje zadań w których to się zwraca:

1. Zmiana sieciowa — wiele plików, wiele zależności

Refaktor dotykający 10+ plików. Bez planu agent zaczyna od jednego pliku i się rozjeżdża. Z planem ma listę i kolejność.

Przykład z tego tygodnia: dodanie i18n (PL/EN) do bloga. Dotknięte pliki:

• 1 loader (rozszerzenie sygnatur)
• 4 komponenty (dodanie locale prop)
• 3 nowe komponenty (BlogIndex, PostDetail, LocaleSwitch)
• 5 nowych plików routingu pod /en/blog/
• sitemap

Bez planu: agent by zaczął od app/blog/page.tsx, dotknął tylko PL i zostawił EN na później. Z planem: zrobił migrację git mv → typy → loader → komponenty → routes w jednej spójnej fali.

2. Niejasny scope

"Pomóż mi z X" gdy X ma różne interpretacje. Plan mode wymusza zadawanie pytań przed pisaniem kodu. Zysk: nie piszę raz dwóch wersji bo źle zrozumiałem.

3. Coś mocno destrukcyjnego

Migracja danych, zmiana schemy bazy, masowe zmiany w git. Plan mode ma wbudowane gardy (nie może modyfikować plików, nie może odpalać destrukcyjnych komend). To dodatkowa warstwa bezpieczeństwa zanim model coś zrobi.

Kiedy NIE włączam

Cztery sytuacje gdzie plan mode mnie spowalnia:

1. Fix typo / drobna poprawka

Zmiana 1-2 linijek w jednym pliku. Plan mode wymusza ceremonię która kosztuje 5 minut. Zwykła sesja: 30 sekund. Niewspółmierne.

2. Eksploracja "co tu jest"

Gdy chcę po prostu zrozumieć kod. Plan mode chce produkować plan na końcu. Ja chcę dialogu. Robię to bez plan mode i pytam ad-hoc.

3. Iteracje na UI

Kreatywna praca: "zmień kolor przycisku, zobacz, zmień jeszcze raz". Plan mode zabija iterację, każda zmiana to nowy plan. Dla UI używam normalnego trybu z dev serverem.

4. Coś co już robiłem identycznego wczoraj

Powtarzalne zadania. Mam je opisane w skill / hook / skrypcie. Plan mode reinwentuje koło.

Pytania które poprawiają plan

Plan mode pozwala zadawać pytania użytkownikowi. Kluczowa rzecz: pytania o realne rozwidlenia, nie o aprobację. Przykłady:

❌ "Czy plan ci się podoba?", to robi ExitPlanMode

❌ "Czy mam to zrobić w TypeScript?", context sam to mówi (.ts pliki w repo)

✅ "PL+EN dual czy tylko PL?", realne rozwidlenie, zmienia 5 plików

✅ "Caching: in-memory czy Redis?", różne implikacje na deploy

✅ "Mechanizm publikacji: kolejka draftów czy live AI?", różne ryzyka

Pytanie powinno mieć 2-4 opcje, każda mutually exclusive, z opisem konsekwencji. AskUserQuestion z planem to różnica między "gadanie z agentem" a "wspólne projektowanie".

Pułapki plan mode

Trzy które złapałem:

1. Plan agent designuje od zera, nie reuse. Wczesne plany sugerowały tworzenie funkcji które już istniały w lib/. Lekcja: w prompt do Plan agenta wrzucam "actively search for existing utilities to reuse". Pomaga.

2. Explore agenty czytają fragmenty, nie całe pliki. Mogą przeoczyć coś poniżej swojego okna. Lekcja: jeśli plik jest długi i kluczowy, czytam go sam zanim zaakceptuję plan.

3. Plan staje się stary. Gdy implementacja zajmuje > 2 godziny, plan się rozjeżdża z rzeczywistością. Lekcja: przerywam, aktualizuję plik planu, kontynuuję.

ExitPlanMode — co dokładnie robi

Ostatnia komenda. Sygnalizuje "plan gotowy". W tym momencie:

• plan jest pokazany użytkownikowi
• użytkownik akceptuje albo prosi o zmiany
• po akceptacji agent wychodzi z plan mode i może edytować pliki

Jedna subtelność: można w ExitPlanMode zadeklarować allowedPrompts, listę kategorii akcji które agent będzie wykonywał. To uprzedza permission promptów. Zmniejsza tarcie w fazie wykonawczej.

// Przykład deklaracji
{
  allowedPrompts: [
    { tool: "Bash", prompt: "git mv, git add, git commit w tym repo" },
    { tool: "Bash", prompt: "npm run build" },
    { tool: "Bash", prompt: "docker compose up -d --build" }
  ]
}

TL;DR

Włączaj plan mode gdy: zmiana sieciowa, niejasny scope, destruktywna operacja.

Pomijaj plan mode gdy: fix < 5 minut, eksploracja, iteracje UI, powtarzalne zadanie.

Pytania ad hoc o realne rozwidlenia. Plan jako artefakt do czytania, nie jako ceremonia.

Plan mode to nie magia. To wymuszone "myśl zanim piszesz". Wymuszanie warto kosztu tylko gdy zadanie jest na tyle duże, że bez tego wpadlibyśmy w problemy. Reszta to overhead.