{dev} forge - Jak pisać specyfikacje pod AI?

Jednym z największych nieporozumień ery AI-assisted development jest przekonanie, że wystarczy nauczyć się pisać lepsze prompty.

Przez ostatnie dwa lata internet zalały poradniki o prompt engineeringu:

• jak pisać prompty,
• jak używać odpowiednich słów,
• jak budować role,
• jak poprawnie instruować modele.

To wszystko jest przydatne.

Ale w większych projektach problem szybko przestaje dotyczyć promptów.

Problemem staje się jakość specyfikacji.

Bo niezależnie od tego, czy używasz Codex, Claude Code, Cursor, Gemini CLI czy OpenSpec – wszystkie te narzędzia mają jedną wspólną cechę:

Jakość wyjścia jest ograniczona jakością wejścia.

I właśnie dlatego umiejętność pisania specyfikacji pod AI staje się jedną z najważniejszych kompetencji nowoczesnego software engineeringu.

Największy błąd: traktowanie AI jak człowieka

Większość źle napisanych specyfikacji wynika z jednego założenia:

Autor zakłada, że AI rozumie kontekst tak samo jak człowiek.

To nieprawda.

Doświadczony developer potrafi:

• dopytać o szczegóły,
• wyłapać nieścisłości,
• domyślić się intencji biznesowej,
• rozpoznać brakujące wymagania.

AI działa inaczej.

Jeśli czegoś nie opiszesz, model najczęściej:

• założy własną interpretację,
• uzupełni luki statystycznie,
• wygeneruje „najbardziej prawdopodobne” rozwiązanie.

To właśnie dlatego dobra specyfikacja dla AI musi być bardziej precyzyjna niż specyfikacja dla człowieka.

Zasada #1: Zacznij od intencji, nie od rozwiązania

Najczęstszy antywzorzec wygląda tak:

Dodaj tabelę customer_discount
oraz endpoint GET /discounts.

Problem?

Opisujesz rozwiązanie, a nie problem.

Znacznie lepiej napisać:

Intent:
Klienci premium powinni otrzymywać rabaty
zależne od wartości zakupów.

Business Goal:
Zwiększenie retencji klientów premium.

Success Metric:
Wzrost liczby ponownych zakupów o 10%.

W ten sposób AI rozumie nie tylko co ma zrobić, ale również dlaczego.

Zasada #2: Opisuj domenę przed implementacją

Większość projektów nie upada przez błędne API.

Upada przez błędne zrozumienie domeny.

Zanim opiszesz endpointy, opisz:

• encje,
• relacje,
• słownik pojęć,
• reguły biznesowe.

Przykład:

Entities:
- Customer
- LoyaltyAccount
- LoyaltyTransaction

Rules:
- Jeden klient może mieć tylko jedno konto lojalnościowe
- Punkty wygasają po 365 dniach
- Zwrot zamówienia usuwa przyznane punkty

AI dużo lepiej radzi sobie z implementacją, gdy najpierw rozumie model domenowy.

Zasada #3: Używaj przykładów zamiast opisów

To jedna z najważniejszych lekcji wyniesionych z BDD i Specification by Example.

Zamiast pisać:

System powinien poprawnie naliczać punkty.

Napisz:

Scenario:
Customer places order worth 100 PLN

Given:
Customer is Premium

When:
Order is completed

Then:
100 loyalty points are added

Dla AI przykład jest znacznie bardziej jednoznaczny niż ogólny opis.

Zasada #4: Dokumentuj edge case'y

Większość błędów nie pojawia się w głównym scenariuszu.

Pojawia się na obrzeżach systemu.

Dlatego dobra specyfikacja zawsze zawiera sekcję:

Edge Cases

Na przykład:

Edge Cases:

- Refund after points were spent
- Customer account merged
- Loyalty account deleted
- Promotion expired during checkout

Jeśli nie opiszesz edge case'ów, AI je wymyśli.

I nie zawsze będą to właściwe założenia.

Zasada #5: Definiuj kontrakty

AI świetnie generuje kod.

Jeszcze lepiej generuje kod na podstawie kontraktów.

Dlatego specyfikacja powinna zawierać:

• API Contract
• Event Contract
• Data Contract

Przykład:

POST /loyalty/points

Request:
{
  "customerId": "123",
  "orderValue": 100
}

Response:
{
  "pointsAdded": 100,
  "currentBalance": 1200
}

To eliminuje ogromną część niejednoznaczności.

Zasada #6: Opisuj ograniczenia architektoniczne

AI nie zna architektury Twojej organizacji.

Dlatego trzeba ją opisać.

Na przykład:

Constraints:

- Java 21
- Spring Boot 3
- PostgreSQL
- Event-driven architecture
- Kafka only
- No synchronous communication

Dzięki temu AI nie zaproponuje rozwiązania sprzecznego z kierunkiem architektonicznym organizacji.

Zasada #7: Opisuj kryteria walidacji

Jednym z największych błędów jest kończenie specyfikacji na implementacji.

Dobra specyfikacja odpowiada również na pytanie:

Skąd będziemy wiedzieć, że rozwiązanie jest poprawne?

Przykład:

Validation:

- Unit tests coverage > 80%
- Integration tests pass
- API contract tests pass
- Loyalty points calculation verified

To pozwala AI nie tylko wygenerować kod, ale również zrozumieć sposób jego weryfikacji.

Przykład pełnej specyfikacji pod AI

Intent:
Introduce loyalty program.

Business Goal:
Increase customer retention.

Entities:
Customer
LoyaltyAccount
LoyaltyTransaction

Rules:
1 point per 1 PLN.
Points expire after 365 days.

Scenario:
Given Premium Customer
When Order Completed
Then Points Added

API:
POST /loyalty/points

Edge Cases:
Refunds
Expired points

Constraints:
Java 21
Spring Boot 3
Kafka

Validation:
Unit Tests
Contract Tests
Integration Tests

Zauważ, że taka specyfikacja jest:

• krótka,
• jednoznaczna,
• łatwa do wersjonowania,
• czytelna dla człowieka,
• bardzo czytelna dla AI.

Najważniejsza zmiana mentalna

Przez wiele lat specyfikacja była czymś, co prowadziło do kodu.

W erze AI zaczyna być czymś więcej.

Specyfikacja staje się:

• kontraktem,
• źródłem prawdy,
• interfejsem pomiędzy człowiekiem a AI.

I właśnie dlatego coraz częściej słyszymy o Spec-Driven Development.

Nie dlatego, że AI wymaga więcej dokumentacji.

Ale dlatego, że AI wymaga lepszej dokumentacji.

Podsumowanie

Jeśli miałbym sprowadzić cały artykuł do jednego zdania, brzmiałoby ono tak:

Nie pisz specyfikacji tak, jakby czytał ją człowiek. Pisz ją tak, jakby miała zostać wykonana przez maszynę.

Bo właśnie do tego zmierza nowoczesny software engineering.

Coraz częściej nie programujemy bezpośrednio systemów.

Projektujemy specyfikacje, które systemy budują.