Jak powstala strona /auth: Spec-Driven Development w praktyce

Najpierw zdefiniowalem historie uzytkownikow dla strony logowania i rejestracji, a dopiero potem - z pomoca Perplexity - przelozylem je na wymagania. Ten porzadek (stories -> requirements -> specification) pozwolil utrzymac spojny przeplyw od potrzeb uzytkownika, przez decyzje produktowe, az po implementacje.

1. Historie uzytkownikow jako punkt startowy

W specs/userstories.md opisalem kluczowe sytuacje dla /auth:

• M1. Rejestracja i weryfikacja email - rejestracja tworzy konto w stanie pending, a link weryfikacyjny aktywuje konto.
• M2. Logowanie i utrzymanie sesji - ciasteczko pt1_session z bezpiecznymi flagami i poprawne wylogowanie.
• V9. Dostepnosc i responsywnosc - obsluga klawiatury, widoczne focusy, poprawne dzialanie na mobile.

Z tych historii wynikal cel strony: bezpieczne logowanie i rejestracja bez tarcia, z jasna informacja o bledach i stabilnym przekierowaniem.

2. Z historii do wymagan z pomoca Perplexity

Nastepny krok to zamiana historii na konkretne wymagania (specs/req.md). Uzywalem Perplexity, aby wydobyc brakujace detale i doprecyzowac wymagania bez wchodzenia w kod.

Przykladowe prompty do ekstrakcji wymagan:

Masz historie uzytkownikow M1 i M2 dla strony /auth.
Wypisz funkcjonalne wymagania dla logowania i rejestracji.
Uwzglednij walidacje, przekierowania i komunikaty o bledach.

Na podstawie historii M1/M2 wypisz wymagania niefunkcjonalne
(bezpieczenstwo, prywatnosc, wydajnosc) dla /auth i /api/login.

Wynikiem byly m.in. wymagania dotyczace bezpiecznych przekierowan, blokady po 3 nieudanych logowaniach oraz polityki cookie.

3. Refinement wymagan: doprecyzowania i ryzyka

Po pierwszej wersji wymagan robilem iteracje, aby usunac niejednoznacznosci i ryzyka. Perplexity pomagal znalezc luki, np. w obsludze linkow weryfikacyjnych, edge-caseach dla redirect, czy w polityce lockoutu.

Przykladowe prompty do doprecyzowania wymagan:

Przejrzyj ponizsze wymagania dla /auth.
Wypisz niejednoznacznosci i zaproponuj doprecyzowania oraz kryteria akceptacji.

Wymaganie: "Bezpieczne przekierowania po logowaniu".
Zaproponuj 5 scenariuszy testowych i ograniczenia walidacji URL.

4. Od wymagan do specyfikacji (Spec-Driven Development)

Kiedy wymagania byly stabilne, przepisalem je do pelnej specyfikacji (specs/spec.md) - z architektura, API, modelem danych i zabezpieczeniami. Tak powstala mapa tego, co musi zrobic frontend i backend.

Przykladowe prompty do przejscia z wymagan do specyfikacji:

Na podstawie wymagan dla /auth rozpisz sekcje "Authentication and Sessions":
endpointy, cookie flags, lockout policy i reset hasla.

Zamien wymagania bezpieczenstwa /auth na konkretne zasady:
same-origin, CSP, przechowywanie tokenow i logowanie bledow.

W efekcie specyfikacja opisuje m.in. POST /api/register, POST /api/login, GET /api/me, polityke sesji oraz wymagania dotyczace weryfikacji emaili.

5. Implementacja strony /auth

Na podstawie specyfikacji zbudowalem strone /auth:

• src/app/auth/page.tsx przygotowuje parametry wejscia i wybiera aktywna zakladke (logowanie lub rejestracja).
• src/app/auth/AuthClient.tsx obsluguje formularze, walidacje, zgody i komunikaty o bledach.
• Zastosowalem bezpieczne przekierowania przez sanitizeRedirect oraz mapowanie kodow bledow na czytelne wiadomosci.

Wizualnie strona trzyma kierunek z specs/ui-style.md: jasne powierzchnie, subtelne cienie, pill buttons i czytelna typografia. Dodatkowo pilnowalem standardow z V9 (focus, mobile).

6. Testy i definition of done

Zgodnie z specs/testplan.md kluczowe scenariusze to logowanie, rejestracja, a takze poprawne stany sesji i bezpieczne przekierowania. Dla mnie done oznacza, ze strona /auth spelnia wymagania z specs/req.md i jest spojna z specs/spec.md.

7. Co daje to podejscie

Spec-Driven Development utrzymal spojnosc na calej osi: stories -> requirements -> spec -> implementacja. Dzieki temu strona /auth ma jasne granice, przewidywalne zachowanie i jest gotowa do testow oraz dalszego rozwoju.