Przejdź do treści
← Powrót do strony głównej
PRD i SDD - jak przygotować dokumenty projektowe dla agentów AI
średniozaawansowany ⏱ 20 min ·
· 6 min czytania czytania

PRD i SDD - jak przygotować dokumenty projektowe dla agentów AI

Jak tworzyć pliki PRD (Product Requirements Document) i SDD (System Design Document), żeby agent AI rozumiał kontekst projektu i generował lepszy kod.

PRD i SDD dla agentów AI

Agent AI jest tak dobry, jak kontekst, który mu dasz. Dwa dokumenty, które radykalnie podnoszą jakość generowanego kodu, to PRD (Product Requirements Document) i SDD (System Design Document).

Po co agentowi dokumentacja?

Bez PRD/SDD agent:

  • Zgaduje architekturę
  • Wymyśla nazwy tabel i endpointów
  • Nie zna ograniczeń biznesowych
  • Generuje „generyczny” kod zamiast dopasowanego

Z PRD/SDD agent:

  • Zna cel biznesowy
  • Rozumie bounded context
  • Stosuje ustalone konwencje
  • Generuje kod spójny z resztą systemu

PRD - Product Requirements Document

PRD odpowiada na pytanie: CO budujemy i DLACZEGO.

Struktura PRD dla AI

# PRD: [Nazwa funkcjonalności]


## Problem
Krótki opis problemu, który rozwiązujemy.
[2-3 zdania - agent musi rozumieć "dlaczego"]


## Cel
Co konkretnie ma powstać.
- Cel 1
- Cel 2


## User Stories
- Jako [rola] chcę [akcja] żeby [cel]
- Jako [rola] chcę [akcja] żeby [cel]


## Scope


### In Scope (robimy)
- Feature A
- Feature B


### Out of Scope (NIE robimy)
- Feature X - na później
- Feature Y - out of scope


## Wymagania niefunkcjonalne
- Wydajność: odpowiedź < 200ms
- Dostępność: 99.9%
- Bezpieczeństwo: OAuth 2.0, rate limiting


## Akceptacja
- [ ] Kryterium 1
- [ ] Kryterium 2

Praktyczny przykład PRD

# PRD: System powiadomień email


## Problem
Użytkownicy nie wiedzą o ważnych zmianach w zamówieniach.
Brak powiadomień powoduje 30% wzrost zapytań do supportu.


## Cel
Automatyczne powiadomienia email przy zmianie statusu zamówienia.


## User Stories
- Jako kupujący chcę dostać email, gdy zamówienie zmieni status,
  żeby nie musiałem sprawdzać ręcznie
- Jako admin chcę widzieć log wysłanych emaili,
  żeby diagnozować problemy z dostarczalnością


## Scope


### In Scope
- Powiadomienia: nowe zamówienie, wysłane, dostarczone, anulowane
- Szablony HTML email (Razor templates)
- Retry mechanism (3 próby z exponential backoff)
- Log wysyłek w bazie danych


### Out of Scope
- Push notifications (osobny PRD)
- SMS (faza 2)
- Personalizacja szablonów przez admina


## Wymagania niefunkcjonalne
- Wysyłka w ciągu 30 sekund od zmiany statusu
- Rate limit: max 10 emaili/sekundę
- Monitoring: alert gdy failure rate > 5%


## Akceptacja
- [ ] Email wysyłany przy każdej zmianie statusu
- [ ] Retry przy failure
- [ ] Log w bazie
- [ ] Szablony responsywne (mobile)

Dlaczego „Out of Scope” jest krytyczne: Bez tego agent będzie próbował zaimplementować push notyfikacje, SMS i panel administracyjny - bo „to logiczne rozszerzenie”. Jawny scope powstrzymuje go od over-engineeringu.

SDD - System Design Document

SDD odpowiada na pytanie: JAK to zbudujemy.

Struktura SDD dla AI

# SDD: [Nazwa funkcjonalności]


## Architektura
Opis podejścia architekturalnego i uzasadnienie.


## Stack technologiczny
- Backend: [framework, język, wersja]
- Baza danych: [typ, silnik]
- Infrastruktura: [cloud, hosting]
- Narzędzia: [kolejki, cache, etc.]


## Struktura projektu
Opis katalogów i odpowiedzialności.


## Modele danych


### Entity: [NazwaEntity]
| Pole | Typ | Opis |
|------|-----|------|
| Id | int | PK |
| ... | ... | ... |


## Endpointy API


### POST /api/[resource]
- Request body: [schemat]
- Response: [schemat]
- Status codes: 201, 400, 409


## Przepływ danych
Opis flow od request do response.


## Decyzje techniczne
| Decyzja | Wybrałem | Odrzuciłem | Dlaczego |
|---------|----------|------------|----------|
| ... | ... | ... | ... |

Praktyczny przykład SDD

# SDD: System powiadomień email


## Architektura
Event-driven z użyciem MediatR notifications.
Zmiana statusu zamówienia emituje event →
Background service przetwarza kolejkę → Wysyłka przez SMTP.


## Stack
- Backend: ASP.NET Core 9, C# 13
- Queue: Azure Service Bus (lub in-memory dla dev)
- Email: Azure Communication Services
- Templates: Razor Light
- Monitoring: Application Insights


## Modele danych


### Entity: EmailNotification
| Pole | Typ | Opis |
|------|-----|------|
| Id | Guid | PK |
| OrderId | int | FK do zamówienia |
| Recipient | string | Adres email |
| TemplateName | string | Nazwa szablonu |
| Status | enum | Pending/Sent/Failed |
| Attempts | int | Liczba prób (max 3) |
| SentAt | DateTime? | Kiedy wysłano |
| Error | string? | Ostatni błąd |


### Enum: NotificationStatus
- Pending = 0
- Sent = 1
- Failed = 2


## Endpointy API


### GET /api/notifications?orderId={id}
- Response: EmailNotification[]
- Auth: Admin only


### POST /api/notifications/{id}/retry
- Response: 202 Accepted
- Auth: Admin only


## Przepływ danych


1. OrderService zmienia status zamówienia
2. Emituje OrderStatusChangedEvent via MediatR
3. EmailNotificationHandler odbiera event
4. Tworzy EmailNotification (status: Pending) w bazie
5. Dodaje do kolejki Azure Service Bus
6. EmailSenderService przetwarza z kolejki
7. Renderuje szablon Razor
8. Wysyła przez SMTP
9. Aktualizuje status na Sent lub Failed


## Decyzje techniczne


| Decyzja | Wybrałem | Odrzuciłem | Dlaczego |
|---------|----------|------------|----------|
| Kolejka | Service Bus | Hangfire | Niezależność od app pool |
| Szablony | Razor Light | Scriban | Spójność z ASP.NET |
| SMTP | Azure Comm. | SendGrid | Jeden vendor (Azure) |

Jak używać PRD/SDD z agentem

Podejście 1: Wklej na początku sesji

User: Oto PRD i SDD dla systemu powiadomień email:
      [wklej PRD]
      [wklej SDD]


      Zacznij od implementacji modelu EmailNotification
      i migracji bazy danych.

Podejście 2: Trzymaj w repozytorium

docs/
  prd/
    email-notifications.md
    user-dashboard.md
  sdd/
    email-notifications.md
    user-dashboard.md

Agent z dostępem do filesystem (np. Claude Code, Copilot Agent mode) automatycznie przeczyta te pliki, gdy będą potrzebne.

Podejście 3: Referencja w instrukcjach

.github/copilot-instructions.md
## Architecture
See docs/sdd/ for system design documents.
Follow patterns established in existing code.

Wskazówki

Aktualizuj na bieżąco

Nieaktualny PRD/SDD jest gorszy niż brak. Gdy zmieniasz architekturę - zmień SDD. Gdy scope się zmienia - zmień PRD. Traktuj te dokumenty jak żywy kod.

Nie przesadzaj z detalami

PRD i SDD dla AI nie muszą mieć 30 stron. Agent potrzebuje esencji: cel, scope, modele danych, endpointy, decyzje. Nie potrzebuje diagramów Gantta.

PRD generuj z agentem, SDD pisz sam

PRD (co i dlaczego) możesz szkicować z pomocą AI - to dokument biznesowy. SDD (jak) pisz sam lub weryfikuj bardzo dokładnie - to Twoje decyzje architektoniczne. Agent może zaproponować SDD, ale Ty musisz zweryfikować każdą decyzję.

Podsumowanie

PRD i SDD to mnożnik siły agenta AI. Zamiast powtarzać kontekst w każdym prompcie - napisz go raz w ustrukturyzowanym dokumencie. Agent z PRD+SDD generuje kod spójny z wizją produktu i architekturą systemu.

DokumentOdpowiada naKto piszeKiedy aktualizować
PRDCo i dlaczegoProduct/Dev + AIGdy zmienia się scope
SDDJakDeveloperGdy zmienia się architektura