Plan-and-Solve Prompting

1. Przegląd koncepcji i problem systemowy

Gdy deweloper powierza sztucznej inteligencji duże zadanie inżynierskie (np. „przepisz moduł autoryzacji z JWT na sesje w bazie danych”), impulsywna reakcja agenta polega na natychmiastowej edycji pierwszego napotkanego pliku.

Tak czysto reaktywne podejście prowadzi do krytycznych awarii:

1. Naruszenie kolejności zależności: Agent modyfikuje komponent interfejsu, zanim zaktualizował schemat bazy danych lub utworzył niezbędne typy TypeScript.
2. Cykliczne poprawki: Model naprawia jeden błąd, psując inny powiązany plik, i wpada w nieskończoną pętlę łatek składniowych bez zrozumienia szerszego kontekstu.
3. Utrata pierwotnego celu: Po 10 krokach debugowania kontekst zostaje zaśmiecony komunikatami kompilatora, a model zapomina o początkowym zadaniu użytkownika.

Wzorzec Plan-and-Solve eliminuje ten problem poprzez klasyczną zasadę inżynieryjną: Rozdzielenie strategicznego projektowania (Planning) od taktycznej realizacji (Execution).

2. Taksonomia architektoniczna i model mentalny

Wzorzec realizowany jest przez trzy uzupełniające się fazy:

• 1. Faza eksploracji i planowania (Discovery & Planner Phase): Agent analizuje zapytanie, wstępnie czyta system plików (Read-Only) i generuje precyzyjnie ustrukturyzowany graf działań: tablicę kroków zawierającą cele, kryteria sukcesu oraz wymagane pliki.
• 2. Faza wykonania kroków (Solver / Execution Phase): Specjalistyczny wykonawca pobiera pierwszy otwarty punkt planu, wywołuje niezbędne narzędzia (edycja plików, uruchomienie builda), weryfikuje wykonanie podzadania i oznacza punkt jako zakończony.
• 3. Faza dynamicznego replanowania (Replanning & Feedback Phase): Jeśli podczas wykonywania kroku wystąpi błąd niemożliwy do rozwiązania prostym ponownym uruchomieniem (np. wykryto brak wymaganego modułu w systemie), replanner przegląda pozostałe punkty planu, dodając krok instalacji zależności.

3. Techniczny pipeline i mechanika wewnętrzna

Cykl życia pracy zgodnej ze wzorcem Plan-and-Solve:

1. Generowanie planu (Plan Generation): Model tworzy walidowany obiekt JSON z tablicą zadań: tasks: [{ id: 1, title: "DB Schema", status: "pending" }, { id: 2, title: "API Route", status: "pending" }].
2. Iniekcja stanu (State Injection): Plan zapisywany jest w stanie agenta. Użytkownik widzi wizualny postęp wykonania w formie interaktywnej listy kontrolnej.
3. Pętla wykonania (Execution Loop): Orkiestrator wybiera kolejne zadanie ze statusem pending. Kontekst jest oczyszczany ze starych szczegółów debugowania, skupiając się wyłącznie na bieżącym zadaniu i finalnym celu.
4. Kontrola niezmienników i zmiana statusu (Invariant Check & Status Transition): Po zakończeniu kroku uruchamiany jest linter lub test jednostkowy. Jeśli sprawdzenie przebiegnie pomyślnie – status zmienia się na completed. W przeciwnym razie wywoływana jest metoda replan(), korygująca niewykonane kroki.

4. Praktyczne scenariusze inżynierskie w środowisku produkcyjnym

01. Złożona migracja bazy kodu

Przejście projektu z Next.js Pages Router na App Router:

• Krok 1: Audyt struktury folderu pages/ i wyodrębnienie wspólnych Layouts.
• Krok 2: Utworzenie głównego pliku app/layout.tsx oraz stylów bazowych.
• Krok 3: Etapowe przenoszenie stron statycznych.
• Krok 4: Przepisanie tras dynamicznych i API Routes w plikach route.ts.
• Krok 5: Pełny build projektu i usunięcie przestarzałych plików.

02. Tworzenie nowych funkcji na podstawie specyfikacji (Spec-Driven Development)

Agent otrzymuje wymaganie biznesowe. Najpierw pisze dokumentację i schematy Zod, uzgadnia je z użytkownikiem, a dopiero po uzyskaniu akceptacji etapowo generuje backend, hooki klienckie oraz komponenty UI.

03. Wdrożenie infrastruktury serwerowej

Etapowe hardening Linux VPS:

• Generowanie planu składającego się z 6 etapów (klucze SSH, firewall UFW, fail2ban, aktualizacja pakietów, utworzenie użytkownika non-root, wyłączenie dostępu hasłem).
• Każdy punkt realizowany jest osobno z obowiązkową weryfikacją statusu portu przed wyłączeniem poprzedniej metody połączenia.

5. Pułapki, typowe błędy i bezpieczeństwo

• Planowanie „w ciemno” (Premature Planning): Tworzenie planu bez wcześniejszej analizy plików repozytorium. Model może zaplanować użycie bibliotek, których nie ma w projekcie. Rozwiązanie: obowiązkowy krok „Eksploracji” (Discovery) przed uruchomieniem planisty.
• Nadmierna sztywność planu (Plan Rigidity): Agent uparcie próbuje wykonać Krok 3, mimo że na Kroku 1 okazało się, iż architektura wymaga fundamentalnie innego podejścia. Należy bezwzględnie wdrażać hooki dynamicznego replanowania.
• Mikrozarządzanie w 30 krokach: Zbyt drobne kroki (np. osobny krok dla importu każdego typu) pochłaniają czas i zasoby finansowe. Utrzymuj poziom abstrakcji na poziomie logicznych bloków funkcjonalnych.