Jak napisać plan, który agent AI zrealizuje bez zgadywania

Skąd się bierze zgadywanie

Agent kodujący czyta kod, uruchamia polecenia i zmienia pliki. Nie wie jednak, co zespół ustalił na spotkaniu, czego klient nie chce i którą z dwóch rozsądnych dróg wolisz. Gdy agent zbuduje coś innego, niż oczekujesz, zwykle brakuje mu właśnie takiej informacji. Agent może też odczytać prośbę zachowawczo i zbudować najskromniejszą wersję, która ją spełnia, bo nie wie, na ile liczysz.

Druga luka dotyczy końca pracy. Agent zwykle kończy, gdy wynik wygląda na gotowy. Jeśli nie ma czego uruchomić, żeby sprawdzić, czy naprawdę jest gotowy, błąd zostaje w kodzie, dopóki go nie zauważysz.

Weźmy zadanie „Dodaj eksport faktur do CSV”. Brzmi jasno, dopóki agent nie zacznie pracy:

• Wszystkie faktury czy tylko z wybranego miesiąca?
• Z fakturami korygującymi czy bez nich?
• Jaki separator pól i jaki zapis kwot?
• Czy przy okazji poprawić istniejący eksport do PDF?

Każde z tych pytań agent rozstrzygnie po swojemu albo zada Ci je w trakcie pracy. Dobry plan rozstrzyga je, zanim praca się zacznie.

Cztery części planu

Plan dla agenta nie musi być długi. Ma odpowiedzieć na cztery pytania: po co, co dokładnie, po czym poznać dobry wynik i kiedy praca jest skończona. Gdy ważne jest, co po czym, dopisz jeszcze kroki.

Spec-driven development po polsku to praca od specyfikacji: najpierw dokument, potem realizacja przez agenta, na końcu porównanie wyniku z tym samym dokumentem. Plan z czterema częściami opisanymi niżej jest właśnie taką specyfikacją. Więcej o tym podejściu znajdziesz w haśle spec-driven development.

Cel

Po co ta praca, w jednym albo dwóch zdaniach. Gdy agent trafi na decyzję, której plan nie przewidział, cel podpowie mu, który wariant wybrać. Zdanie „Księgowość co miesiąc ręcznie przepisuje faktury do swojego programu” mówi agentowi więcej niż „eksport CSV”.

Zakres

Co należy do pracy, a co jest z niej wyraźnie wyłączone. Wyłączenia są tak samo ważne jak to, co do pracy należy. Zdanie „Eksport do PDF zostaje bez zmian” chroni przed zmianami wprowadzanymi przy okazji, a zdanie „Faktury korygujące też trafiają do pliku” przed wersją, która robi za mało.

Kryteria akceptacji

Sprawdzalne stwierdzenia, które muszą być prawdziwe, gdy praca jest skończona. Każde ocenisz jednym słowem: tak albo nie. To z nimi porównasz wynik przy odbiorze, więc pisz je jak listę do odhaczenia.

Definicja ukończenia

Po czym wykonawca pozna, że praca jest skończona i nie zostało nic do dokończenia. Kryteria akceptacji dotyczą tej jednej pracy, a definicja ukończenia jest zwykle wspólna dla wielu prac, na przykład: testy przechodzą, nowe zachowanie ma własny test, dokumentacja jest aktualna.

Wpisz tu polecenie, które agent może uruchomić sam i które kończy się sukcesem albo błędem: testy, budowanie projektu albo linter, na przykład npm test. Agent może wtedy sam wprowadzić zmianę, uruchomić sprawdzenie, a gdy coś się zepsuje, poprawić błąd i sprawdzić jeszcze raz.

Przykład: plan eksportu faktur

Ten sam eksport, opisany tak, żeby agent mógł go zrealizować bez dopytywania:

# Eksport faktur do CSV

## Cel
Księgowość co miesiąc ręcznie przepisuje faktury do swojego
programu. Plik CSV ma to zastąpić.

## Zakres
- Przycisk eksportu na liście faktur, dla wybranego miesiąca.
- Poza zakresem: eksport do PDF i wysyłka pliku e-mailem.

## Kryteria akceptacji
- Plik zaczyna się wierszem z nazwami kolumn.
- Plik obejmuje wszystkie faktury z miesiąca, także korygujące.
- Pola rozdziela średnik, a kwoty mają przecinek dziesiętny.
- Gdy w miesiącu nie ma faktur, użytkownik widzi komunikat
  zamiast pustego pliku.

## Definicja ukończenia
- npm test przechodzi, a eksport ma własne testy.
- Nic z zakresu nie zostało odłożone na później.

Jak pisać kryteria, które da się sprawdzić

Kryteria to część planu, którą najłatwiej napisać zbyt ogólnie. Pomagają cztery zasady:

• Jedno stwierdzenie, jedno sprawdzenie. „Eksport działa poprawnie” nie mówi, co sprawdzić. „Plik obejmuje faktury korygujące” mówi.
• Zachowanie, które widać. Opisz, co zobaczy użytkownik albo co zwróci program, a nie to, jak ma wyglądać kod.
• Liczba zamiast przymiotnika. „Szybko” każdy rozumie inaczej. „Eksport miesiąca z tysiącem faktur trwa krócej niż pięć sekund” da się zmierzyć.
• Przypadki brzegowe, na których Ci zależy. Pusty miesiąc, błędne dane, brak uprawnień. Przypadek, którego nie wpiszesz, agent może pominąć albo rozwiązać inaczej, niż oczekujesz.

Otwarte decyzje i rozmiar planu

Przed startem nie wszystko jest jasne i to nic złego, jeśli plan o tym mówi. Gdy zostaje wybór, nazwij go i podaj rekomendację, na przykład: „Kodowanie pliku: UTF-8, chyba że program księgowy wymaga innego”. Agent nie rozstrzyga wtedy po cichu, a Ty wiesz, na co zwrócić uwagę przy odbiorze. Tak samo z dwoma dobrymi rozwiązaniami: jeśli wolisz jedno z nich, napisz to w planie.

Gdy brakuje Ci większości odpowiedzi, odwróć kolejność: poproś agenta, żeby zadawał Ci pytania tak długo, aż z odpowiedzi da się napisać specyfikację. Pracę nad kodem zacznij potem w nowej sesji, od gotowego dokumentu.

Ostatnia sprawa to rozmiar. Plan powinien opisywać pracę, którą jedna sesja agenta zrealizuje w całości. Duże zadanie podziel na kilka planów i zapisz, który na który czeka. Każdy dostaje wtedy własne kryteria i własny odbiór.

Skąd mniej pytań i mniej poprawek

Pytania agenta pojawiają się tam, gdzie plan milczy. Każde rozstrzygnięcie zapisane przed startem to pytanie, które nie przerwie pracy. Poprawki biorą się z oczekiwań, których nikt nie zapisał: wynik spełnia polecenie, ale rozmija się z tym, czego potrzebujesz.

Kryteria akceptacji zamieniają odbiór w porównanie. Sprawdzasz listę punkt po punkcie, a gdy coś się nie zgadza, przy odrzuceniu wskazujesz konkretne kryterium. Agent wie wtedy, co poprawić, i nie musi zgadywać drugi raz.

Jak to działa w featureloom

W featureloom zadanie dla agenta to plan: dokument w markdownie na tablicy kanban, który konsola dostaje w całości. Plan napiszesz sam przyciskiem Nowy plan. Taki plan zaczyna się od pustego dokumentu, więc cel, zakres, kryteria akceptacji i definicję ukończenia wpisujesz pod własnymi nagłówkami, tak jak w przykładzie wyżej.

Plan wygenerowany z materiału albo napisany przez agenta w konsoli powstaje według szablonu planu projektu. Wbudowany szablon prosi między innymi o cel, zakres, kroki, kryteria akceptacji i definicję ukończenia. Prompt Planista każe agentowi pisać plany w sekcjach szablonu, a gdy materiał zostawia wybór, nazwać go w planie i podać rekomendację. Własny szablon zapiszesz na ekranie Ustawienia projektu, w zakładce Szablon planu.

Gotowy plan oddajesz agentowi, wklejając w konsoli polecenie z planu, na przykład featureloom realizator FAK-14. W jednym wywołaniu agent dostaje prompt, cały dokument planu i dokumenty zrealizowanych planów, od których ten plan bezpośrednio zależy. Prompt Realizator każe mu robić tylko to, co jest w planie, a gdy plan czegoś nie rozstrzyga, zadać pytanie zamiast zgadywać. Pytanie i Twoja odpowiedź zostają w dokumencie planu, a agent przeczyta odpowiedź, gdy znowu pobierze plan.

Na koniec Realizator każe agentowi zgłosić realizację z notą: co zostało zrobione, co inaczej niż w planie i dlaczego, a czego nie zrobiono. Ty porównujesz wynik z kryteriami akceptacji i w części Odbiór wybierasz Przyjmuję albo Nie przyjmuję. Werdykt wydaje tylko osoba w aplikacji. Po odrzuceniu agent czyta werdykt z Twoimi powodami i wraca do poprawek.