Jak sprawdzić plan coding agenta, zanim napisze kod

Poprosiłem agenta o zapisane wyszukiwania w katalogu urządzeń w aplikacji React. Plan miał osiem porządnych kroków w sensownej kolejności, więc zatwierdziłem go po pobieżnym przejrzeniu. Krok trzeci wprowadzał nowy globalny store dla całego modułu wyszukiwania, choć projekt miał już serwis zapisanych wyszukiwań i lokalny stan widoku, które w zupełności wystarczały. Kiedy to zauważyłem, store miał już slice, selektory, providera w app shellu i kilkanaście poprawionych testów. Kod był dobry. Kierunek nie był mój.

Jak korzystać z plan mode w Claude Code

W Claude Code plan mode pozwala agentowi czytać pliki i uruchamiać komendy, żeby rozpoznać repozytorium, ale nie edytuje kodu, dopóki nie zatwierdzisz planu. Włączasz go przez Shift+Tab, prefiksem /plan przed pojedynczą wiadomością albo startując claude --permission-mode plan. Inne agenty mają podobny krok planowania lub tryb tylko do odczytu. Niezależnie od narzędzia wartość bierze się z tego, co zrobisz z planem przed akceptacją:

1. Opisz sytuację: jak jest teraz, jak ma być i czego nie wolno zmienić.
2. Poproś o plan, nie o kod, razem z założeniami i otwartymi pytaniami.
3. Przeczytaj plan przez cztery pytania audytu opisane niżej.
4. Odeślij poprawki i poproś o nową wersję planu, nadal bez implementacji.
5. Zatwierdź dopiero wtedy, gdy plan zgadza się z zadaniem, granicami i sposobem weryfikacji.

Użytkownik ma móc zapisać do 5 wyszukiwań na liście urządzeń
i później do nich wrócić. Nie zmieniaj API ani współdzielonych komponentów.

Najpierw przejrzyj listę urządzeń i istniejący kod zapisanych wyszukiwań.
Potem zaproponuj plan, w którym będą:
- pliki, które zmienisz, i istniejący wzorzec, którego się trzymasz
- założenia i otwarte pytania
- czego świadomie nie robisz
- jak to zweryfikujemy (testy i kroki ręczne)
Jeszcze nie pisz kodu.

Plan jest najtańszą wersją diffu. Właśnie dlatego warto go poprawiać.

Dlaczego płynny plan wciąż może być zły?

Agent pisze uporządkowany plan z takiego obrazu systemu, jaki akurat ma, a niepełny obraz wcale nie sprawia, że plan brzmi mniej pewnie. Schludna lista kroków wygląda na przemyślaną. To nie to samo. Plan może czytać się świetnie i mimo to:

• dotyczyć złego obszaru, na przykład pierwszego podobnego komponentu, który agent znalazł;
• dokładać funkcje, o które nikt nie prosił;
• bez potrzeby zmieniać kontrakt, współdzielony komponent albo API;
• pomijać edge case: puste dane, odświeżenie strony, limit;
• budować nowy mechanizm obok istniejącego;
• zakładać zachowanie, którego nikt nie potwierdził.

Oto plan zbliżony do tego, który zatwierdziłem za szybko. Zadanie: użytkownik może zapisać do pięciu wyszukiwań na liście urządzeń i później do nich wrócić.

## Plan: zapisane wyszukiwania

1. Rozszerz model SavedSearch o aktywne filtry i sortowanie.
2. Dodaj zapis i odczyt do istniejącego savedSearchService.
3. Wprowadź nowy globalny searchStore dla całego modułu wyszukiwania,
   żeby zapisane wyszukiwania, filtry i wyniki miały jedno źródło prawdy.
4. Dodaj przycisk „Zapisz wyszukiwanie” do toolbara listy urządzeń.
5. Utwórz stronę /saved-searches, na której użytkownik edytuje
   kryteria zapisanego wyszukiwania.
6. Wczytaj zapisane wyszukiwanie w widoku listy i zaktualizuj URL.
7. Przepisz DeviceFilters tak, żeby czytał z searchStore.
8. Dodaj testy jednostkowe dla searchStore i nowej strony.

Kroki 1, 2, 4 i 6 służą zadaniu. Krok 3 dodaje abstrakcję, której repozytorium nie potrzebuje, krok 7 istnieje tylko z powodu kroku 3, a krok 5 to funkcja, o którą nikt nie prosił. Krok 8 testuje nowy kod, a nie zachowanie, na którym zależy użytkownikowi. Limitu pięciu wyszukiwań, pustych kryteriów i odświeżenia strony nie ma wcale.

Jakie cztery pytania zadać przed zatwierdzeniem planu?

Każde pytanie wymusza osobną ocenę. Razem zamieniają „wygląda OK” w decyzję, którą potrafisz uzasadnić.

1. Co akceptuję? Wskaż kroki, które służą zadaniu i pasują do repozytorium, żeby agent wiedział, którą część rozumowania zostawić.
2. Co odrzucam? Wytnij kroki, które poszerzają zakres, dokładają abstrakcje, bez potrzeby ruszają współdzielony kod albo dublują istniejący wzorzec. Powód podaj w jednym zdaniu.
3. Czego brakuje? Edge case’ów, non-goals, ryzyk, a przede wszystkim sposobu weryfikacji. Plan bez weryfikacji nie ma określonego końca.
4. Która decyzja jest moja? Znajdź wybór produktowy lub architektoniczny, którego agent nie powinien podejmować sam, i podejmij go przed implementacją.

Plan v1 po audycie

Co powinien zawierać dobry plan coding agenta?

Tyle, żeby było widać, jak agent zrozumiał zadanie, i żebyś mógł się z nim nie zgodzić, zanim cokolwiek powstanie. Elegancja nie ma znaczenia. Znaczenie mają:

• Zrozumienie: problem w jednym, dwóch zdaniach, własnymi słowami agenta.
• Obszar: pliki, które zmieni, i wzorzec, którego się trzyma, np. savedSearchService.ts i DeviceListPage.tsx, a nie „moduł wyszukiwania”.
• Kolejność: kroki na tyle małe, żeby błędny dało się tanio cofnąć.
• Ryzyka: współdzielone komponenty, stan, routing, kontrakty.
• Otwarte pytania: czego nie wie i czego nie powinien zakładać.
• Non-goals: czego świadomie nie rusza.
• Weryfikacja: testy i kroki ręczne, które pokażą, że zadanie jest zrobione.

Które decyzje należą do człowieka, a nie do agenta?

Każda, która zmienia zakres, kontrakt, współdzielony komponent albo zachowanie produktu. Ustal podział, zanim zatwierdzisz plan:

• Agent decyduje sam: lokalne nazwy, kolejność małych kroków, użycie istniejącego i jednoznacznego wzorca, szczegóły techniczne bez wpływu na kontrakt.
• Agent proponuje, Ty zatwierdzasz: nową abstrakcję, zmianę architektury, zmianę współdzielonego komponentu lub kontraktu, każde rozszerzenie zakresu.
• Agent musi zapytać: gdy wymagania są sprzeczne, gdy dwa zachowania produktu są równie uprawnione, gdy odkrycie zmienia pierwotny cel.
• Agent nie robi sam: operacji destrukcyjnych, zmian na produkcji, migracji danych, niczego z sekretami, nieodwracalnych zmian bez checkpointu.

Warunki zatrzymania wpisz wprost do wiadomości z akceptacją, w języku tego zadania:

Zatrzymaj się i zapytaj mnie, zanim:
- ruszysz pliki poza listą urządzeń i savedSearchService
- zmienisz typ SavedSearch, z którego korzystają inne widoki
- rozstrzygniesz zachowanie produktu, którego plan nie opisuje
- zrobisz cokolwiek, czego nie ma w zatwierdzonym planie

Czy każde zadanie potrzebuje planu?

Nie. Mały, lokalny bug z jasnym zakresem, istniejącym wzorcem i łatwą weryfikacją może iść od razu do diagnozy i poprawki. O plan proś, gdy zmiana dotyka kilku modułów, state managementu, API, współdzielonego komponentu, ważnego flow użytkownika, wydajności albo migracji. Zapisane wyszukiwania się kwalifikują: model, serwis, widok listy, URL i trwałość danych. Literówka w etykiecie przycisku już nie.

Co powinno się wydarzyć przed startem implementacji?

Agent rozpoznaje, dopytuje i proponuje. Ty decydujesz. Ułóż kroki we właściwej kolejności.

Kiedy kod już powstanie, audyt przenosi się na dowody: jak robić review kodu z AI w aplikacji React lub Angular.