{dev} forge – Struktura dobrej specyfikacji w Spec-Driven Development

W poprzednich artykułach z cyklu {dev} forge – How software is forged with AI ustaliliśmy dwie rzeczy. Po pierwsze – Spec-Driven Development nie jest nową modą, tylko ewolucją podejść takich jak V-Model, BDD i Specification by Example. Po drugie – pojawienie się AI sprawiło, że jakość specyfikacji zaczęła mieć jeszcze większe znaczenie.

Pora więc zejść poziom niżej i odpowiedzieć na bardzo praktyczne pytanie:

Jak powinna wyglądać dobra specyfikacja w Spec-Driven Development?

Nie taka „ładna”. Nie taka „zgodna z template’em”. Tylko taka, która realnie prowadzi implementację – zarówno dla człowieka, jak i dla AI.

Dlaczego struktura specyfikacji ma dziś większe znaczenie niż kiedykolwiek?

W klasycznym developmentcie niedoskonała specyfikacja była problemem, ale często dało się ją „uratować” rozmowami w zespole. Developer dopytał, tester doprecyzował, analityk wyjaśnił kontekst.

W świecie AI sytuacja wygląda inaczej.

AI nie dopytuje. AI zakłada.

Jeśli coś jest nieprecyzyjne, model uzupełni luki na podstawie statystyki, a nie Twojej intencji biznesowej. Dlatego dobra specyfikacja musi być:

• jednoznaczna,
• warstwowa (różne poziomy szczegółowości),
• operacyjna (możliwa do użycia w implementacji i testach),
• spójna (bez sprzecznych założeń).

Struktura nie jest więc formalnością. To mechanizm kontroli jakości myślenia.

Moja referencyjna struktura specyfikacji (Spec-Driven Development)

Nie ma jednego słusznego standardu. Ale po wielu projektach widzę, że dobra specyfikacja najczęściej składa się z kilku powtarzalnych warstw.

Poniżej moja referencyjna struktura, która dobrze działa zarówno dla zespołów, jak i dla AI-assisted development.

1. Kontekst biznesowy (Why)

To najczęściej pomijana sekcja. A jednocześnie najważniejsza.

Tu odpowiadamy na pytania:

• jaki problem rozwiązujemy,
• jakie są pain pointy,
• jakie KPI chcemy poprawić,
• dlaczego ta zmiana ma sens biznesowy.

Bez tej sekcji reszta specyfikacji staje się technicznym opisem czegoś, czego sens może być błędnie zrozumiany.

Anti-pattern: „Dodaj endpoint do zarządzania promocjami” bez kontekstu, po co i dla kogo.

2. Zakres i granice (Scope & Boundaries)

Tu definiujemy, co wchodzi w zakres, a co nie.

• co dokładnie budujemy,
• jakie są wykluczenia,
• jakie systemy są objęte zmianą,
• gdzie kończy się odpowiedzialność tego komponentu.

To sekcja, która chroni przed „feature creep” i nadinterpretacją – szczególnie przez AI.

3. Model domenowy (Domain Model)

To fundament zrozumienia systemu.

Opisujemy:

• kluczowe encje (np. Zamówienie, Promocja, Klient),
• relacje między nimi,
• reguły biznesowe (np. „promocja nie łączy się z inną promocją”),
• słownik pojęć.

To sekcja, która eliminuje różne interpretacje tych samych słów.

Tip: jeśli nazwy w kodzie i w specyfikacji się różnią – masz problem.

4. Scenariusze i zachowania (BDD / Specification by Example)

To serce specyfikacji.

Opisujemy konkretne zachowania systemu:

Given klient premium
And koszyk powyżej 500 zł
When użytkownik przechodzi do płatności
Then system nalicza rabat 10%

Dlaczego to działa?

• jest zrozumiałe dla biznesu,
• jest testowalne,
• jest czytelne dla AI.

Kluczowa zasada: mniej ogólnych wymagań, więcej konkretnych przykładów.

5. Reguły i edge case’y

To sekcja, która oddziela junior-level spec od senior-level spec.

Opisujemy:

• przypadki brzegowe,
• błędy danych,
• konflikty (np. promocje nakładające się),
• fallbacki.

AI bardzo często „gubi się” właśnie tutaj, jeśli nie ma jasno określonych zasad.

6. Kontrakty techniczne (API / Events / Data)

Tu przechodzimy z poziomu domeny do implementacji.

• API (request/response),
• eventy (jeśli system jest event-driven),
• formaty danych,
• walidacje.

To sekcja, która minimalizuje rozjazd między zespołami i komponentami.

7. Ograniczenia architektoniczne

Nie wszystko wolno zrobić „jak się chce”.

Tu definiujemy:

• wymagania niefunkcjonalne (wydajność, SLA),
• zasady integracji,
• security (np. OWASP, auth flows),
• observability (logi, metryki).

To sekcja, która zabezpiecza system przed „technicznie działającym, ale złym” rozwiązaniem.

8. Walidacja (Testability)

Wracamy do DNA V-Modelu.

Każdy element specyfikacji powinien mieć odpowiedź na pytanie:

Jak sprawdzimy, że to działa poprawnie?

• testy automatyczne,
• checklisty,
• kryteria akceptacji,
• metryki sukcesu.

Bez tej sekcji spec jest tylko deklaracją.

9. Traceability (powiązania)

To element często ignorowany, ale kluczowy w większych projektach.

• powiązanie z wymaganiami biznesowymi,
• powiązanie z ticketami,
• powiązanie z testami,
• powiązanie z ADR-ami.

To właśnie tutaj pojawia się realna wartość RTM (Requirements Traceability Matrix).

Jak taka specyfikacja współpracuje z AI?

Dobrze zbudowana specyfikacja działa jak kontrakt wejściowy dla AI.

Zamiast jednego prompta typu:

"Zrób system promocji"

AI dostaje:

• kontekst biznesowy,
• model domenowy,
• scenariusze,
• reguły,
• kontrakty API.

Efekt?

• mniej zgadywania,
• większa spójność,
• lepsza jakość kodu i testów.

Najczęstsze błędy

• brak kontekstu biznesowego,
• zbyt ogólne wymagania,
• brak przykładów,
• pominięcie edge case’ów,
• brak walidacji,
• niespójność nazw.

W świecie AI te błędy są multiplikowane.

Podsumowanie

Dobra specyfikacja w Spec-Driven Development nie jest dokumentem. Jest systemem myślenia.

Łączy:

• kontekst biznesowy,
• zachowania (BDD),
• reguły domenowe,
• kontrakty techniczne,
• walidację.

W świecie AI to właśnie specyfikacja staje się najważniejszym artefaktem w projekcie.

Bo dziś software nie jest już tylko pisany.

Software jest „kuty” – na podstawie specyfikacji.