Dlaczego "lecenie na żywioł" z AI to zły pomysł

Wyobraź sobie taką sytuację: masz w głowie jasną wizję nowej funkcji. Odpalasz ulubiony asystent kodowania, wpisujesz szybkie polecenie i patrzysz, jak pewnie przepisuje połowę twojego kodu. Godzinę później siedzisz przed PR-em, który rozwiązuje problem, o którym w ogóle nie myślałeś — i to w sposób, który psuje rzeczy, które miały działać.

Brzmi znajomo? Nie jesteś sam. Kiedy asystenci AI ewoluowali z prostych odpowiadających maszyn do prawdziwych edytorów kodu, wielu programistów odkryło, że ten sam swobodny styl komunikacji, który świetnie działa przy czatbotach, kompletnie się nie sprawdza, gdy w grę wchodzi prawdziwy projekt.

Rozwiązanie? Nie są to bardziej szczegółowe polecenia. Chodzi o fundamentalną zmianę myślenia o tym, jakie dokumenty wysyłamy do tych agentów.

Prompt czy specyfikacja — jaka jest różnica

Prompt świetnie nadaje się do jednego: rozpoczęcia pracy. Sprawdza się przy szybkich wyjaśnieniach, skryptach jednorazowych i eksploracyjnych rozmowach. Żyje w sesji czatu, może używać skrótów i często zakłada kontekst, który rozumie tylko autor.

To wystarczy, gdy po prostu zadajesz pytania.

Ale kiedy agent AI ma edytować współdzielony kod, uruchamiać polecenia terminala i tworzyć gałęzie, które koledzy będą recenzować? Twój swobodny prompt staje się zadaniem. A zadania wymagają więcej niż dobrego sformułowania — potrzebują właściwego kontekstu, jasnych granic, konkretnych przykładów i kryteriów weryfikacji.

I tutaj pojawia się specyfikacja.

Specyfikacja to nie ładniejszy prompt. To ustrukturyzowany dokument, który opisuje: jaki problem rozwiązujemy, jakie zachowanie ma się zmienić, co ma zostać bez zmian, i jak rozpoznać, czy praca się udała. W przeciwieństwie do prompta, który znika w momencie rozpoczęcia pracy, specyfikacja towarzyszy całemu procesowi — kieruje agentem, pomaga recenzentom i pozwala przyszłym opiekunom kodu zrozumieć, dlaczego podjęto konkretne decyzje.

Pięć elementów dobrej specyfikacji dla agenta AI

Nie musisz pisać dwudziestostronicowego dokumentu. Potrzebujesz pięciu kluczowych składników:

1. Kontekst: Dlaczego to zadanie w ogóle powstaje? Jaki problem użytkownika lub dług techniczny je motywuje? Jakie ograniczenia w kodzie agent powinien znać?

2. Zachowanie do zmiany: Co konkretnie ma zostać zmodyfikowane, dodane lub usunięte? Bądź precyzyjny — „użytkownicy otrzymują powiadomienia email, gdy X" brzmi lepiej niż „usprawnij system powiadomień".

3. Ograniczenia do zachowania: Co absolutnie nie może się zmienić? Jaka funkcjonalność, kontrakty API czy parametry wydajności muszą pozostać nienaruszone?

4. Przykłady poprawności: Konkretne scenariusze pokazujące, jak wygląda dobry efekt. Format Given/When/Then się sprawdza, ale wystarczą nawet kilka jawnych przypadków testowych.

5. Kryteria walidacji: Jak recenzent pozna, że praca jest kompletna? Co powinien sprawdzić? Jakie pytania powinien sobie zadać?

Ten framework brzmi znajomo, jeśli pracowałeś ze scenariuszami BDD, szablonami issue'ów z kryteriami akceptacji czy dokumentami projektowymi. Konkretny format ma mniejsze znaczenie — liczy się obecność właściwych informacji w formie gotowej do udostępnienia i recenzji.

Gdzie umieścić specyfikację w procesie

Jedna z najlepszych cech specyfikacji to ich elastyczność. Nie muszą być osobnymi dokumentami spowalniającymi pracę. Specyfikacja może żyć wszędzie tam, gdzie ma sens dla twojego zespołu:

• Issue na GitHubie z wyraźnymi kryteriami akceptacji
• Opis PR-a明确 wskazujący zmieniane zachowanie
• Scenariusz BDD w plikach funkcjonalnych
• Lekki note projektowy przed implementacją
• Narzędzia typu OpenSpec czy GitHub Spec Kit formalizujące ten wzorzec

Kluczowe jest jedno: kontekst i kryteria recenzji muszą być widoczne i trwałe. Specyfikacja nie może zniknąć wraz z końcem sesji czatu. Powinna podróżować razem z pracą, dając kolegom z zespołu coś konkretnego do oceny.

Warstwa zadania: oddzielanie intencji od wykonania

Tutaj robi się naprawdę interesująco.

Najlepsze specyfikacje zachowują się jak małe kontrakty behawioralne. Rozdzielają trzy odrębne kwestie:

1. Jakie zachowanie ma się zmienić? (wymaganie)
2. Jakie ograniczenia lub przykłady definiują poprawność? (kryteria akceptacji)
3. Jaka ścieżka implementacji wydaje się teraz odpowiednia? (podejście techniczne)

Te pytania są powiązane, ale nie powinny zlewać się w jeden chaos instrukcji.

Dlaczego to ma znaczenie dla agentów AI? Bo gdy mieszasz intencję z implementacją zbyt wcześnie, agent może optymalizować pod złą rzecz. Może skrupulatnie podążać za sugerowaną szczegółem implementacyjnym, kompletnie missując zachowanie, które było naprawdę potrzebne. Albo wyprodukować kod technicznie interesujący, ale nierozwiązujący postawionego problemu.

Warstwa zadania utrzymuje wymaganie stabilnym, pozwalając implementacji się rozwijać. Gdy agent czyta kod, odkrywa komplikacje i dopracowuje podejście, specyfikacja pozostaje punktem odniesienia: „Czy praca spełniła to?"

To szczególnie cenne przy istniejących projektach. Większość pracy inżynieryjnej to nie zielone pola — zmieniasz zachowanie, które już istnieje. Dobra specyfikacja mówi: oto obecne zachowanie, a oto co ma się zmienić. Recenzenci nie muszą mentalnie rekonstruować twojej intencji z szczegółów implementacji.

Czas na zmianę podejścia

Jeśli przywykłeś traktować agentów AI jak superwyszukiwarki, to może ci się to wydać przesadą. Ale rozważ alternatywę: niekontrolowane zmiany we współdzielonym kodzie, PR-y trudne do recenzji i praca, która nie do końca odpowiada twojej wizji.

Przejście na współpracę z AI opartą na specyfikacjach to nie biurokracja. To dawanie ludziom i maszynom jasności potrzebnej do efektywnej wspólnej pracy.

Zacznij mało. Następnym razem, zanim wyślesz agenta AI do repozytorium, poświęć pięć minut na spisanie kontekstu, planowanej zmiany zachowania i kryteriów sukcesu. Umieść to gdzieś widocznego — nawet jeśli to tylko opis PR-a.

Przyszły ty (i twoi koledzy z zespołu) wam podziękujecie.

Podsumowując: Agenci AI to potężni współpracownicy. Traktuj ich jak współpracowników. Daj im porządny brief, a dostaniesz pracę wartą recenzji.