Rozwój oparty na PRD: jak wykorzystuję ponad 30 PRD do realizacji zadań z agentami AI

Przepływ pracy RalphBlaster od SaasMaker generuje kompletny pull request z jednolinijkowego zgłoszenia w niecałe 45 minut, przy czym programista nie dotyka ani jednej linii kodu podczas implementacji.¹

Wypróbowałem ten wzorzec. Działa. Ale zawodzi również w sposób, którego filmy demonstracyjne nie pokazują.

TL;DR

Napisałem ponad 30 PRD dla zadań agentów AI w ciągu ostatnich sześciu miesięcy. Wzorzec sprawdza się dobrze w przypadku dobrze zdefiniowanych zadań z jasnymi kryteriami akceptacji: endpointy CRUD, dodawanie testów, komponenty UI oparte na ustalonych wzorcach. Zawodzi przy niejednoznacznych wymaganiach, nowatorskich decyzjach architektonicznych i wszystkim, co wymaga iteracyjnej oceny człowieka. Mój szablon PRD ewoluował z prostego formatu user story w ustrukturyzowany dokument z lokalizacjami plików, oczekiwaniami testowymi, ograniczeniami i jawnymi listami „nie modyfikuj”. Ewolucja nastąpiła, ponieważ agenci interpretowali niejasne PRD w zaskakujący sposób.

Przepływ pracy, którego faktycznie używam

Krok 1: Utworzenie zgłoszenia

Definiuję, co ma się wydarzyć, w prostym języku. Precyzja okazała się ważniejsza, niż początkowo sądziłem:

Ogólnikowe (daje nieprzewidywalne rezultaty):

Add user preference saving to the settings page.

Precyzyjne (daje przewidywalne rezultaty):

Add dark mode toggle to /settings. Persist to user_preferences
table (column: dark_mode, type: boolean, default: false).
Use existing SettingsForm component. Add toggle below the
notification section. No new dependencies.

Druga wersja ogranicza agenta na tyle, że wynik odpowiada oczekiwaniom. Pierwsza wersja wygenerowała mi stronę ustawień z nowym komponentem React, trzema nowymi pakietami npm i implementacją opartą na localStorage zamiast oczekiwanej persystencji w bazie danych.

Krok 2: Wygenerowanie lub napisanie PRD

Mój skill /prd przekształca zgłoszenie w ustrukturyzowany PRD z user stories, kryteriami akceptacji, lokalizacjami plików i oczekiwaniami testowymi.² Typowy PRD wygląda następująco:

## Story: Add dark mode toggle
**As a** user
**I want to** toggle dark mode from settings
**So that** I can read comfortably in low light

### Acceptance Criteria
- [ ] Toggle appears in SettingsForm below notifications
- [ ] Persists to user_preferences.dark_mode (boolean)
- [ ] Default: false (light mode)
- [ ] Toggle state reflects current DB value on page load

### Files to Modify
- app/routes/settings.py (add dark_mode to form handler)
- app/templates/settings.html (add toggle component)
- app/models/user.py (add dark_mode column if missing)

### Files NOT to Modify
- app/static/css/styles.css (dark mode CSS already exists)
- app/templates/base.html (already reads dark_mode class)

### Test Expectations
- Test toggle persists to database
- Test default value on new user
- Test toggle reflects current state on reload

Sekcja „Files NOT to Modify” była największą ewolucją szablonu. Bez niej agenci usłużnie „ulepszali” powiązane pliki, wprowadzając zmiany, o które nie prosiłem i których nie chciałem.

Krok 3: Implementacja przez agenta

Agent pracuje w odizolowanym worktree Git, co zapobiega ingerencji w moją bieżącą gałąź:³

# Create isolated worktree for agent task
git worktree add ../worktrees/dark-mode -b feature/dark-mode

# Agent works in ../worktrees/dark-mode/
# I continue working in main workspace

# Review and cleanup after merge
git worktree remove ../worktrees/dark-mode

Moja ochrona przed rekurencją monitoruje zachowanie agenta w zakresie uruchamiania podprocesów. Mój strażnik bezpieczeństwa Git zapobiega force-pushom i commitowaniu poświadczeń przez agenta. Te hooki działają automatycznie. Nie nadzoruje agenta podczas implementacji.

Krok 4: Przegląd kodu

Powiadomienie przychodzi, gdy agent zakończy pracę. Przeglądam diff względem kryteriów akceptacji z PRD. Jeśli wszystkie kryteria są spełnione, merguje. Jeśli nie, naprawiam ręcznie lub restartuję agenta ze zaktualizowanym kontekstem.⁴

Gdzie rozwój oparty na PRD się sprawdza

Endpointy CRUD z jasnym modelem danych. PRD określa model, trasy i format odpowiedzi. Agent generuje szablon kodu zgodny z istniejącymi wzorcami.

Dodawanie testów do istniejącego kodu. „Napisz testy dla app/content.py pokrywające load_post_by_slug z prawidłowym slugiem, nieprawidłowym slugiem i brakującym plikiem” — generuje użyteczne testy, ponieważ funkcja już istnieje, a kryteria akceptacji są obiektywne.

Komponenty UI oparte na ustalonych wzorcach. „Dodaj filtr kategorii na stronie listy bloga, używając tego samego wzorca zakładek co na stronie przewodnika” — działa, ponieważ agent może odwołać się do istniejącego wzorca.

Migracje bazy danych ze zdefiniowanym schematem. PRD określa kolumny, typy, wartości domyślne i ograniczenia. Agent generuje migrację i aktualizuje model.

Gdzie rozwój oparty na PRD zawodzi

Niejednoznaczne wymagania. „Ulepsz blog” to nie jest PRD. Agent wprowadzi zmiany, ale nie będą odpowiadać intencji, ponieważ intencja nie została sprecyzowana.

Nowatorskie decyzje architektoniczne. Gdy musiałem zaprojektować model konsensusu systemu deliberacyjnego, żaden PRD nie był w stanie uchwycić tej decyzji. Musiałem eksplorować opcje, oceniać kompromisy i iterować nad projektem. To wymagało mojego skilla deliberacji, a nie PRD.

Optymalizacja wydajności. „Przyspiesz ładowanie strony” wymaga profilowania, pomiarów i iteracyjnego badania. Agent nie jest w stanie sprofilować wzorców ruchu produkcyjnego na podstawie PRD.

Kod krytyczny pod względem bezpieczeństwa. PRD dla systemów uwierzytelniania generują kod obsługujący ścieżkę pozytywną. Przypadki brzegowe w uwierzytelnianiu (ataki czasowe, utrwalanie sesji, CSRF w niestandardowych przepływach) wymagają ludzkiej ekspertyzy, której PRD nie są w stanie zakodować.

Jak ewoluował mój szablon PRD

Wersja 1 (miesiąc 1): proste user stories

As a user, I want to save preferences so I can customize my experience.

Problem: Zbyt ogólnikowe. Agent przyjmował rozsądne, ale błędne założenia dotyczące mechanizmu przechowywania, umiejscowienia w UI i zakresu.

Wersja 2 (miesiąc 2): dodanie lokalizacji plików

## Story: Save preferences
### Files to Modify
- app/routes/settings.py
- app/templates/settings.html

Problem: Lepiej, ale agenci nadal „ulepszali” sąsiednie pliki bez pozwolenia.

Wersja 3 (miesiąc 4): dodanie ograniczeń

## Story: Save preferences
### Files to Modify (only these)
- app/routes/settings.py
- app/templates/settings.html
### Constraints
- No new dependencies
- Use existing database models
- Do not modify CSS

Problem: Agenci czasami ignorowali ograniczenia, gdy kolidowały z „najlepszymi praktykami” z danych treningowych.

Wersja 4 (obecna): jawne wykluczenia + oczekiwania testowe

Obecny szablon dodaje sekcję „Files NOT to Modify”, jawne oczekiwania testowe i checkboxy kryteriów akceptacji. Ta wersja generuje przewidywalne rezultaty w około 85% przypadków. Pozostałe 15% wymaga drugiego podejścia z doprecyzowanymi instrukcjami.⁵

Biblioteka wzorców z 30 PRD

Po ponad 30 PRD wyłoniły się wzorce:

Skuteczność dla nowatorskich funkcji (50%) wyjaśnia, dlaczego rozwój oparty na PRD uzupełnia mój przepływ pracy, a nie go zastępuje. W połowie przypadków nowatorska praca wymaga iteracji, której PRD nie są w stanie uchwycić z wyprzedzeniem.

Kluczowe wnioski

Dla samodzielnych programistów: - Zacznij od jednego dobrze zdefiniowanego typu PRD (CRUD, testy) i zweryfikuj przepływ pracy, zanim przejdziesz do bardziej złożonych zadań - Dodaj sekcję „Files NOT to Modify” do każdego PRD; agenci usłużnie „ulepszą” kod, o którego modyfikację nie prosiłeś - Używaj worktree Git do izolowania pracy agenta; koszt czyszczenia po nieudanym uruchomieniu agenta powinien wynosić jedno polecenie, a nie sesję archeologii w Git

Dla menedżerów inżynierii: - Jakość PRD determinuje jakość wyników agenta; zainwestuj w szablony PRD i procesy przeglądu, zanim skalujesz autonomiczne użycie agentów - Śledź wskaźnik mergowania bez zmian, aby mierzyć dojrzałość przepływu pracy; wskaźnik powinien się poprawiać w miarę ewolucji szablonów PRD - Nowatorska praca architektoniczna i kod krytyczny pod względem bezpieczeństwa nie powinny być delegowane przez PRD; rezerwuj delegowanie agentom dla dobrze zdefiniowanych, powtarzalnych zadań

Źródła