Generowanie specyfikacji — spec.md w jednej sesji z intent.md

Generowanie specyfikacji to proces przekładania zaakceptowanego pliku intent.md na formalny dokument wymagań technicznych i architektury (spec.md). W natywnym dla AI SDLC wymagania i projektowanie techniczne łączą się w pojedynczą sesję z agentem, gdzie AI jest ściśle ograniczona skillem polityk organizacyjnych (bezpieczeństwo, marka, zgodność i UX), aby wykryć sprzeczne wymagania przed napisaniem pierwszej linii kodu.

Pytanie w scorecardzie: W jaki sposób przekształcasz intencję w specyfikację techniczną i wymagania (spec.md)? Maksymalna odpowiedź (3 pkt): Generowanie spec.md w jednej sesji pod kontrolą skilli marki/bezpieczeństwa/UX; zgłoszone zastrzeżenia rozwiązywane przed rozpoczęciem budowania.

Dlaczego to ważne w 2026

W tradycyjnych organizacjach zbieranie wymagań i projektowanie architektury to domena osobnych zespołów przekazujących sobie pracę sekwencyjnie. Analitycy tworzą specyfikacje wymagań przez tygodnie, a architekci lub projektanci spędzają kolejne tygodnie na przekładaniu ich na projekty techniczne. Każde przekazanie wprowadza opóźnienia, gubi pierwotną intencję i odkłada odkrywanie problemów z bezpieczeństwem lub zgodnością na późny etap przeglądu kodu.

W przepływie natywnym dla AI product owner lub tech lead przeprowadza pojedynczą sesję promptowaną, która pobiera intent.md i stosuje polityki instytucjonalne zakodowane jako skille (.claude/skills/, .cursor/skills/, .agents/skills/). Model redaguje spec.md i natychmiast naświetla konflikty z politykami, pozwalając zespołom podjąć decyzje o kompromisach przed rozpoczęciem prac programistycznych.

Jak wygląda maksymalny wynik

Konfiguracja z maksymalnym wynikiem w Q5 wykazuje cztery kluczowe cechy:

1. Bezpośrednie powiązanie: Każdy plik spec.md jednoznacznie wskazuje na zacommitowany plik intent.md.
2. Wymuszanie polityk przez skille: Agent weryfikuje funkcję względem aktywnych skilli bezpieczeństwa, UX i zgodności podczas redagowania specyfikacji.
3. Sekcja zgłoszonych zastrzeżeń (Flagged Concerns): Agent izoluje sprzeczności i nieuwzględnione przypadki brzegowe w dedykowanej sekcji dla właścicieli polityk.
4. Zatwierdzenie przez człowieka: Product owner i lider techniczny zatwierdzają spec.md przed uruchomieniem trybu planowania implementacji i generowaniem kodu.

Wdrożenie krok po kroku

1. Zweryfikuj obecność skilli polityk.

   Upewnij się, że w repozytorium lub globalnym środowisku agenta znajdują się zwersjonowane skille dla kluczowych obszarów:

   • Standardy bezpieczeństwa (uwierzytelnianie, sanityzacja danych, szyfrowanie)
   • Wytyczne UX i marki (tokeny design systemu, zasady responsywności)
   • Standardy architektoniczne (schematy API, reguły dostępu do bazy danych)

2. Wygeneruj spec.md na podstawie intent.md.

   Uruchom sesję agenta z załadowanymi skillami polityk. Wskaż intent.md i poinstruuj model, aby przygotował spec.md:

   Claude Code

   Przełącz się w tryb Plan (Shift+Tab) i uruchom:

   Przeczytaj intent/NAZWA_SLUG.md. Zastosuj nasze skille bezpieczeństwa, marki i UX.
   Wygeneruj spec/NAZWA_SLUG.md dokumentujący wymagania funkcjonalne, kontrakty API,
   modele danych i przypadki brzegowe. Wypisz sprzeczności z politykami w sekcji
   Flagged Concerns. Nie modyfikuj kodu aplikacji.

   Cursor

   Pozostań w trybie Ask lub Plan z aktywnym katalogiem .cursor/skills/:

   Przeanalizuj intent/NAZWA_SLUG.md pod kątem reguł i skilli w naszym repozytorium.
   Utwórz spec/NAZWA_SLUG.md precyzujący endpointy, modele danych i przepływy UI.
   Wskaż wszelkie konflikty architektoniczne i bezpieczeństwa do przeglądu przez zespół.

   Codex

   Uruchom w Codex CLI za pomocą /plan:

   /plan Przeczytaj intent/NAZWA_SLUG.md i wygeneruj kompletną specyfikację techniczną.
   Zastosuj wszystkie polityki z .agents/skills/. Wypisz nierozstrzygnięte kompromisy
   w sekcji Flagged Concerns.

3. Rozwiąż zgłoszone zastrzeżenia.

   Przeanalizuj zastrzeżenia z odpowiednimi interesariuszami (inżynierem bezpieczeństwa lub liderem designu). Zaktualizuj ograniczenia w spec.md na podstawie ich decyzji.

4. Zacommituj gotową specyfikację.

   Zacommituj plik spec/NAZWA_SLUG.md obok powiązanego pliku intent.md:

   git add spec/NAZWA_SLUG.md
   git commit -m "docs(spec): specyfikacja techniczna dla NAZWA_SLUG"

5. Zatwierdź specyfikację przed rozpoczęciem implementacji.

   Uzyskaj formalną akceptację lidera technicznego lub product ownera. Ta akceptacja otwiera bramkę do Etapu 3: Build (plan.md).

Częste pułapki

• Pomijanie skilli polityk: Zezwalanie agentowi na tworzenie specyfikacji w oparciu o wiedzę ogólną zamiast konkretnych reguł bezpieczeństwa i designu danego projektu.
• Ukrywanie kompromisów: Zgoda na to, by agent podejmował ciche decyzje architektoniczne bez jawnego wypisania sprzeczności w dedykowanej sekcji zastrzeżeń.
• Modyfikowanie kodu w fazie specyfikacji: Pisanie testów jednostkowych lub szkieletu kodu przed zaakceptowaniem spec.md, co marnuje czas inżynierów w razie zmiany założeń.

Jak sprawdzić, czy już tam jesteś

• Plik spec.md jest zacommitowany i bezpośrednio odwołuje się do pliku nadrzędnego intent.md.
• Wszelkie zgłoszone zastrzeżenia posiadają pisemne uzasadnienie decyzji przed rozpoczęciem etapu budowania.
• Czas od zacommitowania intent.md do zacommitowania spec.md liczy się w godzinach.
• Inżynierowie wdrażają rozwiązania na podstawie zatwierdzonej specyfikacji bez napotykania brakujących decyzji architektonicznych w trakcie pracy.

Dodatkowe materiały

Etap Design w natywnym dla AI SDLC Poznaj szczegóły łączenia wymagań i projektowania przy użyciu skilli polityk.

Q6 · Skille agenta jako polityki Jak tworzyć i organizować maszynowo czytelne skille.

Łańcuch artefaktów Zrozum przepływ od intent.md przez spec.md po plan.md.