%20in%20software%20development.%20The%20image%20features%20a%20hierarchical%20structure%20showing%20software%20c.webp)
.%20The%20model%20is%20shown%20in%20four%20levels,%20with%20each%20level%20representi.webp){kind=spacer}
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ą.
