Design: napisz spec.md

Etap designu zamienia zaakceptowany intent.md w commitowany spec.md w jednej sesji agenta. Agent spisuje wymagania, kryteria akceptacji i architekturę, a wersjonowane skille polityk bezpieczeństwa, marki, UX i architektury go ograniczają. Każdy konflikt polityk trafia do sekcji Flagged concerns. Nazwany człowiek akceptuje specyfikację, zanim ruszy jakikolwiek plan implementacji.

Ta strona jest dla dewelopera albo product ownera, który prowadzi tę sesję, i dla tech leada, który odpowiada za bramkę. W poniedziałek product owner akceptuje intencję dotyczącą powiadomień o komentarzach. W czwartek pull request zapisuje adresy e-mail w nowej tabeli, ignoruje politykę retencji i dodaje ekran ustawień, który łamie design system. Każda z tych zasad była gdzieś spisana, ale żadnej nie zastosowano przed review.

Tradycyjnie: analitycy piszą wymagania, architekci i projektanci przekładają je na projekt, a bezpieczeństwo i compliance widzą wynik po kilku tygodniach. Każde przekazanie kosztuje dni i gubi część pierwotnej intencji.

AI-native: jedna sesja czyta intent.md, stosuje polityki organizacji zapisane jako skille już podczas pisania i stawia każdy konflikt przed jego właścicielem, zanim specyfikację zobaczą inżynierowie.

Co daje etap designu ograniczony politykami

• spec.md ze sprawdzalnym kryterium akceptacji dla każdego wymagania, listą skilli, które go ukształtowały, i sekcją Flagged concerns z właścicielem każdego zastrzeżenia.
• Skill polityki do skopiowania oraz katalogi, z których Claude Code, Codex i Cursor go ładują.
• Trzy prompty do skopiowania: napisz specyfikację, zaatakuj ją świeżą sesją i zamień zastrzeżenie w decyzję.
• Skrypt powłoki, który oblewa specyfikację bez wymaganej sekcji albo z wymaganiem bez kryterium, więc nikt nie musi ręcznie sprawdzać struktury.
• Sposób wyjścia z każdej typowej awarii tego etapu.

Zanim napiszesz specyfikację

• intent.md zaakceptowany przez product ownera. Powstaje w Plan: zapisz intent.md.
• Co najmniej jedna polityka zapisana jako skill agenta. Zacznij od tej, przez którą najczęściej wracają pull requesty, zwykle bezpieczeństwa albo design systemu.
• Szablon spec.md z łańcucha artefaktów. Ta strona używa jego sekcji i ścieżek: intent/FEATURE/intent.md i intent/FEATURE/spec.md.
• Nazwany właściciel każdej polityki. Zastrzeżenie, którego nikt nie może rozstrzygnąć, blokuje zmianę.

Do prowadzenia sesji nie trzeba umiejętności programistycznych. Może ją poprowadzić product owner, o ile przy zmianach wyższego ryzyka sekcję architektury akceptuje inżynier albo tech lead.

Jak wygląda skill polityki do pisania specyfikacji?

Skill polityki to katalog z plikiem SKILL.md. Jego description mówi agentowi, kiedy go załadować, więc opisz w nim zadanie („pisanie albo przegląd specyfikacji”), a nie temat. Format Agent Skills ogranicza name do 64 znaków, a description do 1024 (specyfikacja agentskills.io, sprawdzone 2026-09-26).

---
name: security-policy
description: Apply when writing or reviewing a spec, plan, or change that touches authentication, personal data, payments, file uploads, or input from outside the service.
---

# Security policy for specs

When you write a spec, check each requirement against these rules and name
the rule you applied in "Skills and policies applied".

1. Personal data (email, name, IP address) is stored only in tables listed
   in docs/data-inventory.md. A new table holding personal data is a
   flagged concern for the data protection owner.
2. Every new endpoint states its authentication and authorization rule.
3. Retention: user-generated content and delivery logs are deleted after
   90 days unless the spec names a legal basis for longer.
4. Never resolve a conflict between this policy and another one yourself.
   Record it under "Flagged concerns" with both rules quoted.

Owner: security-team. Changes to this file need their review.

Napisz osobny skill dla każdego właściciela polityki: bezpieczeństwo, marka i UX (tokeny designu, komponenty, poziom dostępności) oraz architektura (konwencje API, który serwis jest właścicielem jakich danych). Jeden właściciel na plik sprawia, że każdą politykę zmienia się przez review jej właściciela, a CODEOWNERS może to wymusić.

Skąd każde narzędzie ładuje skille projektu:

Narzędzie	Katalog skilli projektu	Uwagi
Claude Code	.claude/skills/NAME/SKILL.md	Ładowane także z katalogów nadrzędnych aż do korzenia repozytorium (dokumentacja Claude Code, v2.1.283)
Codex	.agents/skills/NAME/SKILL.md	Przywołaj skill po nazwie ($NAME), żeby mieć pewność, że się załaduje (codex-cli 0.157.1)
Cursor	.agents/skills/NAME/SKILL.md	Katalog, do którego npx skills add zapisuje skille dla Cursora (skills CLI 1.7.0)

Trzymaj jedną kopię źródłową i skopiuj ją do drugiego katalogu albo utwórz tam dowiązanie symboliczne (symlink), żeby wszystkie trzy narzędzia stosowały tę samą wersję polityki. Testowanie i publikowanie skilli opisuje strona Budowanie własnych skilli.

Napisz spec.md w jednej sesji

1. Uruchom sesję tylko do odczytu z dostępnymi skillami polityk.

   Użyj trybu planowania: agent może czytać kod, ale nie może zmieniać kodu aplikacji. Zakładki poniżej podają polecenie dla każdego narzędzia.

2. Uruchom prompt specyfikacji na zaakceptowanej intencji.

   Prompt do skopiowania: napisz spec.md pod skillami polityk

   Read intent/notifications/intent.md. Before you write anything, list the
   skills you have loaded that cover security, brand, UX, or architecture.
   Then study the parts of the codebase this feature touches: existing
   tables, API conventions, and UI components.
   
   Write intent/notifications/spec.md. Use these exact H2 headings, in this
   order: ## Requirements and acceptance criteria, ## Architecture and
   design, ## Out of scope, ## Skills and policies applied, ## Flagged
   concerns. What each section holds:
   - Requirements and acceptance criteria: one line per requirement in the
     form "- R1: REQUIREMENT. Accepted when: CHECKABLE_CRITERION". A criterion
     must be something a test or a person can check in one step.
   - Architecture and design: API contracts, data model changes, and the
     existing code each part extends. Prefer extending an existing table or
     component over adding a new one.
   - Out of scope.
   - Skills and policies applied: each skill by name and the rules from it
     that changed the spec.
   - Flagged concerns: every conflict between two policies, every policy
     this feature cannot meet as written, and every open question from
     intent.md you could not answer. Quote the rule, name the likely owner,
     and give two options. Do not resolve a conflict yourself.
   
   Do not write a plan, tasks, tests, or application code. Do not edit any
   file except spec.md.

   Pierwsza instrukcja to tani test: jeśli agent nie wymieni żadnego skilla polityki, przerwij. Specyfikacja napisana bez nich powstaje z wiedzy ogólnej, a właśnie temu ma zapobiegać ten etap.

3. Zaatakuj szkic świeżą sesją.

   Nowa sesja nie widziała rozumowania, z którego powstał szkic, więc czyta specyfikację tak, jak przeczyta ją etap budowy. Uruchom ją, zanim ktokolwiek poświęci specyfikacji swój czas.

   Prompt do skopiowania: sprawdź spec.md względem polityk

   Read intent/notifications/intent.md and intent/notifications/spec.md.
   Do not edit any file. Report, as a table with section, finding, and
   severity (blocking or advisory):
   1. Each problem or outcome in intent.md that no requirement covers.
   2. Each requirement whose acceptance criterion a test could not check.
   3. Each rule in the loaded security, brand, UX, or architecture skills
      that the spec breaks and does not list under Flagged concerns.
   4. Each architectural decision in the spec that nobody asked for and
      that has a trade-off, for example a new table or a new dependency.
   5. Anything in the spec that is a plan or a task list rather than
      required behaviour.

   Blokujące uwagi poprawiaj w samym spec.md, nie w czacie. Decyzja, która istnieje tylko w rozmowie, znika razem z sesją.

4. Rozstrzygnij zastrzeżenia z ich właścicielami.

   To punkty, które dawniej eskalowałby analityk. Wyślij każdy do właściciela polityki jako decyzję do podjęcia, a nie akapit do interpretacji.

   Prompt do skopiowania: zamień zastrzeżenie w prośbę o decyzję

   Take the first unresolved item under "Flagged concerns" in
   intent/notifications/spec.md. Write a decision request for its owner,
   under 200 words: the two rules in conflict (quoted, with the skill they
   come from), what the feature needs, two or three options with the cost
   and risk of each, and your recommendation. End with the exact change to
   spec.md for each option. Do not change spec.md.

   Zapisz każdą decyzję w sekcji Flagged concerns z nazwiskiem właściciela i datą. Zastrzeżenie, którego nie da się jeszcze rozstrzygnąć, zostaje jako otwarte pytanie z datą, do której trzeba je rozstrzygnąć.

5. Zacommituj spec.md obok intent.md.

   git add intent/notifications/spec.md
   git commit -m "docs(spec): notifications spec from accepted intent"

   Para plików zapisuje, o co proszono i co postanowiono. Nagłówek specyfikacji wskazuje intencję, z której powstała, i datę akceptacji.

6. Zaakceptuj specyfikację albo odeślij ją do poprawki.

   Product owner akceptuje wymagania. Tech lead albo architekt akceptuje dodatkowo sekcję architektury, gdy zmiana należy do klasy wyższego ryzyka: uwierzytelnianie, pieniądze, dane osobowe, migracje albo współdzielony interfejs. Akceptacja uruchamia etap budowy, który zaczyna się od plan.md w trybie planowania.

Jak poprowadzić sesję designu w Claude Code, Codeksie i Cursorze?

Prompty są takie same we wszystkich trzech narzędziach. Różni się sposób utrzymania sesji w trybie tylko do odczytu i miejsce, w którym leżą skille projektu.

Claude Code

• Wejdź w tryb planowania przez Shift+Tab, /plan albo claude --permission-mode plan. Od v2.1.283 (kanał latest) sesje interaktywne na obsługiwanych modelach startują w trybie auto, więc tryb planowania musisz włączyć świadomie.
• Tryb planowania blokuje każdą edycję, także spec.md. Gdy szkic jest gotowy, wybierz Yes, manually approve edits i zatwierdź tylko zapis spec.md.
• Skille projektu leżą w .claude/skills/. Wbudowany skill /design (research preview) to inna funkcja; ten etap potrzebuje wyłącznie twoich skilli polityk.

Codex

• Wejdź w tryb planowania przez /plan w CLI. Tryb planowania nie edytuje plików, więc szkic istnieje tylko w czacie.
• Gdy szkic jest gotowy, wyjdź z trybu planowania: po zaproponowanym planie Codex 0.157.1 oferuje opcję Switch to Default and start coding. Potem każ Codeksowi zapisać wyłącznie intent/FEATURE/spec.md i sprawdź wynik testem kształtu opisanym niżej.
• Skille projektu leżą w .agents/skills/. Przywołaj skille polityk po nazwie ($security-policy), jeśli chcesz mieć pewność, że się załadują.
• Żeby pominąć sesję interaktywną, uruchom prompt specyfikacji przez codex exec -s workspace-write i sprawdź wynik tym samym testem.

Cursor

• Użyj Plan Mode, który „creates detailed implementation plans before writing any code” (dokumentacja Cursora, sprawdzone 2026-08-28). Tutaj „planem” jest specyfikacja: wklej prompt specyfikacji, a wynik zapisz w repozytorium jako spec.md.
• Cursor obsługuje Agent Skills. Umieść skille polityk tam, gdzie npx skills add zapisuje je dla Cursora, czyli w .agents/skills/.
• Specyfikację, która istnieje tylko w czacie, traktuj jak niezapisaną. Recenzenci, CI i pozostałe narzędzia czytają commitowany plik.

Przy pracy nad UI specyfikacja potrzebuje też dowodu wizualnego. Przygotuj makietę z intent.md w zatwierdzonym narzędziu do projektowania albo przez serwer Figma MCP, zapisz, kto ją zaakceptował, i podlinkuj ją ze specyfikacji. Czteroetapowy pipeline projektowy opisuje artefakty designu, akceptacja wizualna przed implementacją frontendu opisuje zatwierdzenie makiety, a Figma MCP i design-to-code opisuje połączenie. W planie Starter oraz na miejscach View i Collab Figma ogranicza MCP do kilku wywołań narzędzi miesięcznie (do 6, dossier ekosystemu, 2026-09-26), więc krok z makietą uruchamiaj z miejsca Dev albo Full. Zdalny serwer to https://mcp.figma.com/mcp:

# Claude Code (potem uruchom /mcp w sesji, żeby się zalogować)
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Codex (codex-cli 0.157.1)
codex mcp add figma --url https://mcp.figma.com/mcp
codex mcp login figma

Uruchamiaj przebieg designu automatycznie po akceptacji intencji

Uruchamiaj prompt ręcznie, dopóki jego wynik nie będzie stale dobry. Potem zapisz prompt specyfikacji jako skill (na przykład write-spec) i uczyń merge zaakceptowanego intent.md wyzwalaczem: job w CI uruchamia przebieg bez interakcji i otwiera spec.md jako pull request. Pierwszym udziałem product ownera jest wtedy review.

# Uruchamiane w CI po merge'u intent/$FEATURE/intent.md.
# FEATURE pochodzi z wejścia joba: to katalog zmergowanego intent.md.
FEATURE=notifications

# Claude Code: bez interakcji, edycje akceptowane, bez pytań o zgodę
claude -p "Use the write-spec skill on intent/$FEATURE/intent.md." \
  --permission-mode acceptEdits

# albo Codex: bez interakcji, sandbox ograniczony do workspace
codex exec -s workspace-write "Use the write-spec skill on intent/$FEATURE/intent.md."

# Uruchom test kształtu z następnej sekcji z SPEC_JOB=1, potem otwórz pull request.
git switch -c "spec/$FEATURE"
git add "intent/$FEATURE/spec.md"
git commit -m "docs(spec): $FEATURE spec from accepted intent"
git push -u origin "spec/$FEATURE"
gh pr create --fill

Cursor może wykonać ten sam przebieg z trybu print swojego CLI albo z Automation dla Cloud Agents z wyzwalaczem na zdarzenie w repozytorium. Zanim to oskryptujesz, sprawdź aktualną nazwę polecenia CLI w dokumentacji Cursora.

W GitHub Actions workflow potrzebuje tylko permissions: contents: write i pull-requests: write oraz klucza API agenta z sekretu repozytorium. Przebieg bez interakcji nie może zapytać cię o zgodę, więc to tryb uprawnień albo sandbox ogranicza, czego job może dotknąć. Dowodem, że job zmienił tylko specyfikację, jest skrypt z następnej sekcji.

Jak sprawdzić specyfikację bez czytania każdej linii?

Nikt nie powinien ręcznie sprawdzać struktury specyfikacji. Podziel weryfikację na trzy części: skrypt sprawdza kształt, świeża sesja agenta sprawdza treść względem polityk, a ludzie decydują tylko o zastrzeżeniach i ostatecznej akceptacji.

Test kształtu. Uruchamiaj go w CI przy każdym pull requeście, który dodaje albo zmienia spec.md, oraz z SPEC_JOB=1 w jobie bez interakcji zaraz po zakończeniu pracy agenta. W jobie FEATURE pochodzi z wejścia joba. W pull requeście drzewo robocze jest czyste, więc skrypt porównuje gałąź z origin/main i sprawdza każdy spec.md, który gałąź zmienia:

# Headless job (SPEC_JOB=1): FEATURE comes from the job input, and the
# agent's changes are still uncommitted (tracked edits plus new files).
# Pull request: check every spec.md the branch changes (fetch origin/main first).
if [ -n "${SPEC_JOB:-}" ]; then
  specs="intent/$FEATURE/spec.md"
  changed=$(git diff --name-only HEAD; git ls-files --others --exclude-standard)
else
  changed=$(git diff --name-only origin/main...HEAD)
  specs=$(printf '%s\n' "$changed" | grep -E '^intent/[^/]+/spec\.md$')
fi
[ -n "$specs" ] || { echo "No spec.md in this change"; exit 1; }

# The design pass may change only specs.
if printf '%s\n' "$changed" | grep -v '^$' | grep -vqxF "$specs"; then
  echo "The change touches files other than spec.md"; exit 1
fi

printf '%s\n' "$specs" | while IFS= read -r SPEC; do
  test -s "$SPEC" || { echo "No $SPEC written"; exit 1; }

  for section in '## Requirements and acceptance criteria' '## Architecture and design' \
    '## Out of scope' '## Skills and policies applied' '## Flagged concerns'; do
    grep -qx "$section" "$SPEC" || { echo "$SPEC: missing section: $section"; exit 1; }
  done

  # At least one requirement, and every requirement has a checkable criterion.
  grep -qE '^- R[0-9]+:' "$SPEC" || { echo "No requirements in $SPEC"; exit 1; }
  if grep -E '^- R[0-9]+:' "$SPEC" | grep -v 'Accepted when:'; then
    echo "$SPEC: requirements above have no acceptance criterion"; exit 1
  fi
done || exit 1

Test treści. Przegląd świeżą sesją z kroku 3 uruchamia się na tym samym pull requeście. Dołącz jego tabelę do pull requesta i pozwól mu blokować przy każdej uwadze oznaczonej jako blokująca.

Bramki ludzkie. Każdy właściciel polityki zatwierdza zastrzeżenia ze swojego obszaru, a product owner akceptuje specyfikację. Przy klasach wyższego ryzyka sekcję architektury akceptuje dodatkowo tech lead. Nikt nie akceptuje specyfikacji, w której sekcja Flagged concerns wciąż zawiera punkt bez właściciela.

Późniejsza kontrola. Skill jest doradczy: agent wciąż może zignorować regułę. Polityka, która musi obowiązywać zawsze, potrzebuje też deterministycznej kontroli później, jako hook na etapie budowy albo bramka przed wdrożeniem. Każde kryterium akceptacji staje się też testem, co opisuje strona Wykonywalne kryteria akceptacji.

Dwa wskaźniki pokazują, czy etap działa. Oba definiuje strona Metryki AI-native SDLC:

• Wiodący: czas od commita intent.md do commita zaakceptowanego spec.md dla tej samej zmiany. Ustal dla niego cel (na przykład ten sam dzień roboczy) i obserwuj trend.
• Opóźniony: poprawki wymagań po starcie budowy, liczone jako commity spec.md z datą późniejszą niż pierwszy commit plan.md dla tej samej zmiany. Tu widać brakujące decyzje architektoniczne, na które inżynierowie trafiają w trakcie budowy.

Pytanie 5 w Developer Scorecard

Developer Scorecard pyta, jak zamieniasz intencję w specyfikację techniczną. Najwyżej punktowana odpowiedź opisuje tę stronę: spec.md wygenerowany w jednej sesji pod skillami marki, bezpieczeństwa i UX, z zastrzeżeniami rozstrzygniętymi przed startem budowy.

Co psuje się, gdy agenci piszą specyfikacje, i jak to naprawić

Specyfikacja powstaje z wiedzy ogólnej. Agent nie wymienił żadnego skilla polityki albo sekcja „Skills and policies applied” jest pusta. Sprawdź, czy skille leżą w katalogu, który czyta twoje narzędzie, i czy każdy description wspomina o pisaniu specyfikacji. Potem uruchom prompt specyfikacji ponownie w nowej sesji.

Agent po cichu rozstrzyga kompromis. Specyfikacja wybiera nową tabelę, nową zależność albo słabszą regułę retencji, a Flagged concerns jest puste. Przegląd świeżą sesją wyłapuje większość takich przypadków (punkt 4). Odrzuć specyfikację i każ agentowi zapisać konflikt zamiast go rozstrzygać.

Na etapie designu pojawia się kod. Agent „pomocnie” tworzy szkielet migracji albo pisze testy. Test kształtu oblewa job. Usuń dodatkowe pliki, powtórz linię „do not edit any file except spec.md” i uruchom sesję w trybie planowania albo w sandboksie tylko do odczytu.

Claude Code nie zapisuje spec.md w trybie planowania. Tryb planowania blokuje wszystkie edycje. Wybierz Yes, manually approve edits, zatwierdź zapis spec.md i odrzuć każdą inną edycję.

Specyfikacja zamienia się w plan. Wymienia pliki do zmiany i zadania w kolejności. Przenieś to gdzie indziej: specyfikacja opisuje wymagane zachowanie, a o sposobie decyduje plan.md na etapie budowy. Specyfikacja narzucająca zadania utrwala wybory, zanim ktokolwiek przeczytał kod.

Kryteriów akceptacji nie da się przetestować. „Powiadomienia działają szybko” przejdzie ludzką lekturę i obleje każdy test. Test kształtu dowodzi tylko, że kryterium istnieje. Przegląd świeżą sesją (punkt 2) wskazuje mgliste kryteria, a każde z nich powinno stać się liczbą albo obserwowalnym zdarzeniem.

Zastrzeżenie nie ma właściciela. Wisi w specyfikacji, zmiana stoi, aż w końcu ktoś je usuwa. Wpisz właściciela w sam skill polityki (linia Owner:), żeby agent mógł skierować zastrzeżenie od razu, gdy je oznacza.

Polityki za każdym razem sobie przeczą. Ten sam konflikt marki z dostępnością pojawia się w każdej specyfikacji. To błąd polityki, a nie specyfikacji. Wyślij go raz do obu właścicieli, zmień jeden ze skilli, a zastrzeżenie przestanie wracać.

Dokąd iść dalej po etapie designu

Build: plan.md, potem implementacja Zamień zaakceptowaną specyfikację w plan w trybie tylko do odczytu, a potem zaimplementuj go w worktree.

Spec-driven development Utrzymuj spec.md jako źródło prawdy, gdy kod się zmienia: delty specyfikacji i kontrola dryfu.

Wykonywalne kryteria akceptacji Zamień każde kryterium ze specyfikacji w oblewający test, zanim agent zacznie kodować.

Porównanie frameworków spec-driven Kiedy Spec Kit, OpenSpec albo BMAD są warte wdrożenia zamiast zwykłego spec.md.

Governance i autonomia Które zmiany wymagają tech leada albo architekta na bramce i kto zatwierdza produkcję.

Mapa narzędzi Każdy etap cyklu życia w Claude Code, Cursorze i Codeksie, obok siebie.