Wymagania zaczynają się od notatki głosowej

Ta seria opisuje jedną funkcję na mojej stronie, od notatki głosowej aż po produkcję. Większość pracy wykonują w niej agenci AI. Funkcja, którą wybrałem, brzmi prosto. Asystent AI na mojej stronie ma się uczyć z artykułów, które piszę. Ta część opisuje pierwszą godzinę, zanim powstała choćby linijka kodu.

Krok 1: najpierw mówię, potem piszę

Każda funkcja, którą buduję, zaczyna się od notatki głosowej. Dyktuję w Wispr Flow prosto do Claude Code: czego chcę, dla kogo to jest i co mnie niepokoi. Nie ma zgłoszenia w systemie, ale forma jest znajoma, bliska user story. To, czego nauczyliśmy się o pisaniu wymagań dla ludzi, działa prawie bez zmian, gdy czytelnikiem jest maszyna.

Potem czytam transkrypcję i poprawiam to, co dyktowanie przekręciło. Mowa jest szybka, ale robi drobne błędy. Łatwo je wyłapać, a przy okazji przypominają, że pierwszy artefakt procesu to już maszynowa wersja tego, co miałem na myśli.

Ta notatka głosowa to pierwsze wymaganie biznesowe tego projektu. Fragment, z którego powstała funkcja:

Funkcja to zmiana asystenta AI na mojej stronie, tak żeby nauczył się odpowiadać na pytania na podstawie artykułów, które piszę, i rozszerzał swoją wiedzę i umiejętności.

Jedno zdanie i żadnych kryteriów akceptacji. To normalny punkt wyjścia i proces musi sobie z nim poradzić.

Taki pierwszy, luźny opis nie musi pochodzić ode mnie. Może pochodzić z sesji z użytkownikiem biznesowym, z warsztatu albo z nagrania spotkania i może krążyć między nami a użytkownikiem końcowym tyle razy, ile trzeba. Wymagania biznesowe nadal istnieją, tylko przychodzą w innej formie. Nawet pracując sam, nie jestem w stanie trzymać ich w głowie. Wszystko musi zostać zapisane tam, gdzie AI może to przeczytać: do folderu z kopią zapasową, do zgłoszeń na GitHubie, do rejestru decyzji. Zespół potrzebuje więcej: wspólnego miejsca na wymagania, akceptacji i zapisu tego, kto o czym zdecydował.

Uwaga: niepodpisane wymagania. Wymagania często zaczynają się dziś od rozmowy i nikt ich nie podpisuje. Poproś o akceptację; to zajmuje minuty. Zachowaj to, co dostałeś od każdej osoby, w formie, w jakiej przyszło: user stories, kryteria akceptacji, podpisane dokumenty, nagrania, zrzuty ekranu. Bez tego nie sprawdzisz później, czy agent zbudował to, o co proszono, czy tylko to, co zrozumiał.

Uwaga: dokumentacji za mało albo za dużo. Dokumentacja może zawieść na trzy sposoby. Nie ma jej wcale, jest jej za mało albo jest jej tyle, wyprodukowanej przez agentów na autopilocie, że nikt jej nie czyta, łącznie z ludźmi, którzy ją "napisali". Ten trzeci przypadek jest nowy: AI slop, czyli bezwartościowa treść masowo generowana przez AI. Jak zawsze w dostarczaniu, dopasuj dokumenty do tego, co naprawdę budujesz.

Krok 2: agent przepytuje mnie

Następnie uruchamiam skill "grill me". Agent pyta mnie o jedną decyzję naraz. Każde pytanie przychodzi jako małe okno z dwiema do czterech opcji, a rekomendacja agenta jest pierwsza. Klikam jedną albo wpisuję czy dyktuję własną odpowiedź.

Skill pochodzi z otwartej kolekcji Matta Pococka: zobacz grill-me na GitHubie i jego przewodnik po skillach do przepytywania.

W tym przebiegu pytania dotyczyły tego, co budować i jak to dotrze do odwiedzających. Budować sekcję artykułów teraz czy później? Jak pokazać działanie asystenta? Kto zatwierdza to, co trafia na stronę? Gdzie mają trafiać pytania Dispatchera? Najczęściej klikałem rekomendację.

Ważniejsze okazały się moje własne odpowiedzi. Odpowiadając na zamknięte pytanie o wdrożenie, dodałem coś, o co nikt nie pytał: panel administracyjny do wgrywania artykułów, z sekcją ukrytą za flagą w adresie URL, dopóki nie będzie gotowa. Gdy inne pytanie zakładało, że asystent jest wyłączony, poprosiłem agenta, żeby to sprawdził, zanim cokolwiek wybiorę. Tak wyszła na jaw pierwsza porażka opisana niżej.

Zakres więc urósł. Przyszedłem z jedną funkcją, asystentem uczącym się z moich artykułów, a wyszedłem z wywiadu z trzema: sekcją artykułów, panelem administracyjnym do publikowania artykułów i asystentem, który się z nich uczy. Nie było wniosku o zmianę ani oceny wpływu, była tylko rozmowa.

Uwaga: zakres ustalony jednym kliknięciem. Wymagania ustala się dziś w rozmowie, a ten, kto pisze opcje, kształtuje decyzję. Kliknięcie rekomendacji nie zawsze znaczy, że się z nią zgadzasz; czasem po prostu nie było czasu się zastanowić. Zakres może też urosnąć w jednej odpowiedzi i nikt nie widzi kosztu. Zapisuj każde pytanie i odpowiedź, a nowe wymaganie traktuj jako zmianę, nawet gdy przychodzi w jednym zdaniu. AI pomaga i tutaj: po każdej rozmowie niech agent zaktualizuje listę wymagań i zaznaczy, które pozycje doprecyzowują to, co ustalono, a które są nowym zakresem i wymagają wniosku o zmianę.

Porażka 1: agent uwierzył dokumentacji

W połowie wywiadu agent stwierdził, że asystent na stronie jest wyłączony dla odwiedzających, i zapytał, jak pokazać funkcję, której nikt nie widzi. Zamiast wybierać opcję, poprosiłem go o sprawdzenie. Mylił się: asystent działał od jedenastu dni. Instrukcje projektu dla agentów nadal mówiły, że jest wyłączony, a sprawę rozstrzygnęło sprawdzenie na serwerze produkcyjnym.

Nieaktualne dokumenty poprawiła osobna sesja, żeby wywiad mógł iść dalej. Część 3 wyjaśnia, jak działa takie przekazanie pracy i dlaczego ma znaczenie dla zespołu.

Uwaga: agenci wierzą nieaktualnym dokumentom. Agent traktuje dokumentację, którą dostaje, jak prawdę. Nieaktualna dokumentacja to stary problem. Różnica polega na tym, że agent działa na jej podstawie od razu i nie ma rozmowy na korytarzu, która wyłapałaby błąd. Utrzymuj instrukcje dla agentów tak aktualne jak kod.

Gdybym prowadził twój zespół

Zacząłbym od tego, żeby każdą rozmowę o wymaganiach i jej wynik zapisywać w jednym miejscu, z akceptacją osoby, która za nie odpowiada. Kazałbym też agentowi aktualizować listę wymagań po każdej sesji, żeby nowy zakres pojawiał się jako zmiana, a nie jako niespodzianka na demo.

Gdy zakres był ustalony, a fakty sprawdzone, praca trafiła do agenta, który buduje. O tym jest część 2.