Spec-driven development: specyfikacja jako źródło prawdy

W spec-driven development wersjonowany plik spec.md jest wiążącym opisem tego, co robi system. Każdy pull request zmieniający zachowanie zawiera deltę specyfikacji, agent implementuje zmianę według niej, a każde wymaganie jest powiązane z testem. Ludzie recenzują wtedy deltę specyfikacji i dowody zamiast diffa, co działa tylko wtedy, gdy rozjazd między specyfikacją a kodem wykrywa się automatycznie.

Trzy miesiące temu twój zespół zaczął pisać spec.md przed każdą funkcją i pierwsze specyfikacje były świetne. Dziś specyfikacja dziennika audytu mówi, że eksport CSV kończy się na 10 000 wierszy, kod strumieniuje bez limitu i nikt nie wie, która wersja jest właściwa. Co gorsza, agent czyta specyfikację, więc w zeszłym tygodniu „naprawił” kod z powrotem do 10 000 wierszy i zepsuł klientowi nocny eksport. Specyfikacja, której nikt nie utrzymuje w zgodzie z rzeczywistością, jest groźniejsza niż jej brak, bo agenci jej wierzą.

Ta strona jest dla programisty, który pisze specyfikacje dla agentów, i dla tech leada, który chce, żeby zespół recenzował specyfikacje zamiast diffów na 2000 linii.

Co daje specyfikacja, która pozostaje prawdziwa

Trzy zasady, dzięki którym specyfikacja jest źródłem prawdy, a nie notatką z planowania wyrzucaną po merge’u.
Szablon spec.md z identyfikatorami wymagań, obserwowalnymi wynikami i celami wyłączonymi z zakresu, gotowy do commita.
Pull request z deltą specyfikacji: kolejność commitów, sekcja szablonu PR i to, kto co zatwierdza.
Dwie kontrole dryfu: 30-liniowy skrypt śledzenia wymagań do CI oraz cykliczny audyt agenta w trybie tylko do odczytu dla Claude Code, Codex i Cursora.
Cztery prompty do skopiowania: szkic delty, implementacja według niej, audyt dryfu i odtworzenie specyfikacji dla istniejącego kodu.
Tabelę decyzyjną: zwykły markdown kontra Spec Kit, OpenSpec, specyfikacje Kiro i BMAD, ze sprawdzonymi poleceniami instalacji.

Co sprawia, że specyfikacja jest źródłem prawdy?

Większość zespołów pisze już coś, zanim wyda polecenie agentowi. Prompt od źródła prawdy odróżnia to, co dzieje się po merge’u. Praktycy inżynierii agentowej powtarzają to od początku 2026 roku: Andrej Karpathy ujął to słowami „You are in charge of the spec and plan” (Sequoia Ascent 2026 summary, 2026-04-30), a programista na poziomie 4 według Dana Shapiro to ten, który ma „write a spec” i sprawdzić, czy testy przechodzą (The Five Levels, 2026-01-23). Żaden z nich nie mówi, jak utrzymać specyfikację w zgodzie z kodem. Robią to te trzy zasady.

Zasada	Co oznacza w repozytorium	Co się psuje bez niej
1. Specyfikacja opisuje bieżące zachowanie	`specs/<capability>/spec.md` mówi, co system robi dziś, a nie co dodała jedna funkcja. Dokumenty funkcji to delty względem niej.	Nikt nie odpowie na pytanie „co robi eksport?” bez czytania dziesięciu folderów funkcji i kodu.
2. Zmiany zachowania przechodzą najpierw przez specyfikację	PR zmieniający obserwowalne zachowanie zawiera deltę specyfikacji, zacommitowaną przed kodem.	Kod się zmienia, a specyfikacja po cichu staje się fikcją.
3. Każde wymaganie da się powiązać z kontrolą	Każde wymaganie ma identyfikator; co najmniej jeden test go wymienia. CI odrzuca identyfikatory bez testu i testy bez wymagania.	Dryfu nie widać, dopóki agent nie „poprawi” kodu z powrotem do nieaktualnej specyfikacji.

Zasadę 1 najłatwiej utracić. Narzędzia do planowania tworzą specyfikację na funkcję, więc po dwudziestu funkcjach bieżące zachowanie jest rozrzucone po dwudziestu folderach. Niezależnie od narzędzia trzymaj jeden scalony spec.md na obszar funkcjonalny, a dokumenty funkcji traktuj jak wnioski o zmianę względem niego.

Warunkiem wstępnym jest napisanie pierwszego spec.md na etapie projektowania. Ta strona dotyczy utrzymania tego pliku w zgodzie z rzeczywistością przez cały cykl życia produktu. Miejsce specyfikacji w pełnym łańcuchu przekazań opisuje łańcuch artefaktów.

Co powinien zawierać wiążący spec.md?

Wiążąca specyfikacja opisuje zachowanie, które test może zaobserwować, i nic, co zmieniłby refaktoring. Stosuj jeden plik na obszar funkcjonalny, stałe identyfikatory wymagań i zdania w formie „when … the system shall …” z konkretnym przykładem pod spodem. Taki kształt zdania to notacja EARS, której według dokumentacji Kiro używają jego pliki wymagań (według źródeł wtórnych, wrzesień 2026; zob. Kiro). Wymagania i prompty zostaw po angielsku: agent i narzędzia czytają je bez tłumaczenia.

# Audit log export

Owner: @team-compliance · Last reviewed: 2026-09-26

## Scope
Team admins export audit-log entries as CSV. Non-goals: scheduled exports, PDF.

## Requirements

### EXPORT-1: Filter by date range and actor
WHEN an admin requests an export with `from`, `to` and optional `actor`
THE SYSTEM SHALL return only entries with `from <= created_at < to`
and, when `actor` is set, only that actor's entries.
Example: from=2026-09-01, to=2026-09-02 excludes an entry at 2026-09-02T00:00:00Z.

### EXPORT-2: Streaming without a row limit
WHEN the result has more than 10,000 rows
THE SYSTEM SHALL stream all rows and SHALL NOT truncate.
(Changed 2026-09-12 in #4812; previously capped at 10,000.)

### EXPORT-3: Authorisation
WHEN a non-admin requests an export
THE SYSTEM SHALL respond 403 and SHALL record the denied attempt in the audit log.

## Open questions
- EXPORT-2: is there a maximum export duration? (owner: @pm-audit)

Cztery elementy tego pliku wykonują całą pracę. Identyfikatory dają testom i PR-om punkt odniesienia. Przykład pod każdym wymaganiem to dane wejściowe, których użyje test. Cele wyłączone z zakresu powstrzymują agenta przed dodaniem eksportów cyklicznych tylko dlatego, że wydawały mu się przydatne. Notatka o zmianie przy EXPORT-2 odpowiada na pytanie z początku strony, zanim ktokolwiek je zada.

Pomiń nazwy klas, ścieżki plików, wybór bibliotek i schematy bazy danych. Ich miejsce jest w plan.md albo w rekordzie decyzji architektonicznej. Jeśli czysty refaktoring wymusza zmianę specyfikacji, specyfikacja opisuje implementację i będzie się rozjeżdżać co tydzień.

Jak pull request niesie deltę specyfikacji?

Delta specyfikacji to ta część PR-a, która zmienia specs/. Trafia do repozytorium pierwsza, w osobnym commicie, żeby recenzent przeczytał zmianę zachowania, zanim powstanie jakikolwiek kod, a agent implementował według zatwierdzonego celu.

Przygotuj szkic delty na podstawie zgłoszenia zmiany. Agent czyta zgłoszenie i bieżący spec.md, a potem edytuje wyłącznie specyfikację: nowe lub zmienione wymagania, notatkę o zmianie i otwarte pytania. Użyj pierwszego promptu poniżej.
Zatwierdź deltę przed kodem. Product owner zatwierdza zachowanie widoczne dla użytkownika; tech lead zatwierdza wymagania niefunkcjonalne, takie jak limity, opóźnienia i bezpieczeństwo. Wypchnij commit ze specyfikacją i poproś o recenzję samego commita albo zatwierdź go w sesji, jeśli zmiana jest mało ryzykowna.
Implementuj według zatwierdzonej specyfikacji. Agent pisze nieprzechodzący test dla każdego zmienionego wymagania, nazwany jego identyfikatorem, a dopiero potem kod. W tej fazie nie wolno mu edytować specs/. Jeśli uzna, że specyfikacja jest błędna, zatrzymuje się i to zgłasza.
Uruchom bramki. Kontrola śledzenia wymagań i kontrola ścieżek zachowania (następna sekcja) działają w CI obok typów, lintera i testów.
Zrecenzuj deltę i dowody. Recenzent czyta diff specyfikacji, sprawdza, czy każdy zmieniony identyfikator ma test, który wcześniej nie przechodził, a teraz przechodzi, i czyta kod tylko w klasach eskalacji: uwierzytelnianie, pieniądze, schemat i migracje.

Dodaj tę sekcję do szablonu pull requesta, żeby każdy PR otwarty przez agenta ją wypełniał:

## Spec delta
- Spec file(s): specs/audit-log/spec.md
- Requirements added/changed/removed: EXPORT-2 (changed)
- Approved by: @pm-audit (behaviour), @lead-platform (non-functional)

## Evidence per requirement
| ID | Test | Failed before | Passes now |
|----|------|---------------|------------|
| EXPORT-2 | tests/export/streaming.test.ts "[EXPORT-2] streams 25,000 rows" | yes | yes |

## No behaviour change?
If this PR changes no observable behaviour, add the label `no-behaviour-change` and say why.

Pełny kontrakt tego, co musi udowodnić PR agenta, opisuje pakiet dowodów; protokół recenzji, który go czyta, to code review PR-a agenta.

Szkic delty specyfikacji w każdym narzędziu

Przepływ jest taki sam we wszystkich trzech narzędziach: zaproponuj deltę bez dotykania kodu, zatwierdź ją, a potem zapisz tylko plik specyfikacji. Różni się mechanizm, który chroni kod przed zmianą.

Zacznij w trybie planowania (/plan albo Shift+Tab, aż dojdziesz do tego trybu). Tryb planowania blokuje edycje do chwili zatwierdzenia, więc agent przedstawia deltę jako swój plan. Zatwierdź go i pozwól zapisać wyłącznie pliki w specs/. Potem uruchom git diff --stat i sprawdź, że nic poza specs/ się nie zmieniło.

Zacznij w trybie planowania (Plan mode, /plan), przejrzyj proponowaną deltę, a potem pozwól agentowi zapisać tylko specs/. Zanim pójdziesz dalej, uruchom w terminalu git diff --stat i sprawdź, że zmieniło się tylko specs/. Jeśli zespół przygotowuje specyfikacje w osobnej sesji planistycznej, uruchom ją z codex --sandbox read-only i nanieś deltę samodzielnie.

Użyj Plan Mode, który tworzy plan, zanim powstanie jakikolwiek kod. Przejrzyj proponowaną deltę w planie, a potem pozwól agentowi zapisać tylko specs/. Przed przejściem do implementacji uruchom git diff --stat i sprawdź, że zmieniło się tylko specs/.

Read specs/audit-log/spec.md and the change request below.
Propose a spec delta, and edit ONLY files under specs/:
- Add or change requirements with stable IDs (never renumber existing IDs).
- Write each requirement as WHEN ... THE SYSTEM SHALL ..., with one concrete example.
- Add a change note to every changed requirement: date, PR or ticket, previous behaviour.
- List non-goals the request implies.
- Put anything you had to assume under "Open questions" with a suggested owner.
Do not touch application code or tests. Finish by listing the IDs you added, changed or removed.

Change request: Admins need exports larger than 10,000 rows; the cap was a performance guard.

The spec delta in specs/audit-log/spec.md is approved (EXPORT-2 changed).
For each added or changed requirement:
1. Write a failing test whose name starts with the requirement ID in brackets, e.g. "[EXPORT-2] ...".
   Use the example in the requirement as the test input.
2. Run it and show that it fails for the right reason.
3. Implement the smallest change that makes it pass, then run the full test suite.
Do not edit anything under specs/. If the spec is ambiguous, contradicts itself, or cannot be
implemented as written, stop and report the requirement ID and the problem instead of guessing.
End with a table: ID, test name, failed before (yes/no), passes now (yes/no).

Jak wykryć dryf między specyfikacją a kodem?

Dryf ma dwie postacie. Dryf strukturalny jest mechaniczny: wymaganie bez testu, test powołujący się na wymaganie, którego już nie ma, albo zmiana zachowania bez delty specyfikacji. Dryf semantyczny to scenariusz z początku strony: test istnieje, ale kod i specyfikacja nie zgadzają się już co do tego, co powinien sprawdzać. Pierwszy łap przy każdym PR-ze deterministycznymi kontrolami, drugi cyklicznie, audytem agenta w trybie tylko do odczytu.

Sprawdzaj śledzenie wymagań w każdym pull requeście

Ten skrypt przerywa build, gdy wymaganie nie ma testu albo test powołuje się na nieistniejące wymaganie. Zakłada nagłówki wymagań w postaci ### EXPORT-1: w specs/ i nazwy testów zawierające [EXPORT-1] w tests/; dopasuj oba wzorce do swojego układu katalogów.

// scripts/check-spec-trace.mjs: fails CI on untested or orphaned requirement IDs
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';

const walk = (dir) =>
  readdirSync(dir).flatMap((name) => {
    const path = join(dir, name);
    return statSync(path).isDirectory() ? walk(path) : [path];
  });

const idsIn = (dir, fileRe, idRe) => {
  const ids = new Set();
  for (const file of walk(dir).filter((f) => fileRe.test(f))) {
    for (const m of readFileSync(file, 'utf8').matchAll(idRe)) ids.add(m[1]);
  }
  return ids;
};

const specIds = idsIn('specs', /\.md$/, /^###\s+([A-Z]+-\d+):/gm);
const testIds = idsIn('tests', /\.(test|spec)\.[cm]?[jt]sx?$/, /\[([A-Z]+-\d+)\]/g);

const untested = [...specIds].filter((id) => !testIds.has(id));
const orphaned = [...testIds].filter((id) => !specIds.has(id));

if (untested.length) console.error(`Requirements without a test: ${untested.join(', ')}`);
if (orphaned.length) console.error(`Tests citing unknown requirements: ${orphaned.join(', ')}`);
if (untested.length || orphaned.length) process.exit(1);
console.log(`Spec trace OK: ${specIds.size} requirements, all tested.`);

Wzorzec po stronie testów łapie każdy token w nawiasach kwadratowych o tym kształcie, więc [UTF-8] w tytule testu zostanie uznane za osierocone wymaganie. Nadaj każdemu obszarowi funkcjonalnemu osobny prefiks identyfikatorów, którego nie używa żaden inny tekst w nawiasach, i poszerz oba wyrażenia regularne (na przykład do [A-Z]+(?:-[A-Z]+)*-\d+), jeśli identyfikatory zawierają kilka łączników, jak BILLING-INVOICE-1.

Druga kontrola pilnuje zasady 2: PR-a, który dotyka ścieżek zachowania, a nie dotyka specs/. Furtka w postaci etykiety sprawia, że refaktoring pozostaje tani, a deklaracja „to nie zmienia zachowania” jest widoczna dla recenzenta. Workflow reaguje też na zdarzenia labeled i unlabeled, więc dodanie lub usunięcie etykiety uruchamia kontrolę ponownie bez nowego pusha.

name: spec
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  spec-gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Requirements are traceable to tests
        run: node scripts/check-spec-trace.mjs
      - name: Behaviour changes carry a spec delta
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-behaviour-change') }}
        env:
          BASE: ${{ github.event.pull_request.base.sha }}
        run: |
          changed=$(git diff --name-only "$BASE"...HEAD)
          if echo "$changed" | grep -qE '^src/(api|domain)/' && ! echo "$changed" | grep -q '^specs/'; then
            echo "src/api or src/domain changed without a spec delta. Update specs/ or add the no-behaviour-change label."
            exit 1
          fi

Ustaw wzorzec src/(api|domain)/ na katalogi, w których w twoim repozytorium znajduje się kod odpowiedzialny za obserwowalne zachowanie. Chroń specs/ wpisem w CODEOWNERS dla właścicieli obszarów, żeby każda zmiana specyfikacji wymagała ich zgody, niezależnie od tego, kto ją napisał.

Audytuj dryf semantyczny cyklicznie

Raz w tygodniu albo przed wydaniem uruchom przebieg agenta w trybie tylko do odczytu, który porównuje każde wymaganie z kodem i testami i zgłasza rozbieżności z dowodem w postaci pliku i linii. Agent raportuje; człowiek decyduje, która strona jest w błędzie. Jeśli błędny jest kod, to bug z nieprzechodzącym testem. Jeśli błędna jest specyfikacja, kod zawiera nieudokumentowaną decyzję, a ta decyzja dostaje deltę specyfikacji i osobę zatwierdzającą jak każda inna.

Uruchom audyt w trybie headless, udostępniając wyłącznie narzędzia tylko do odczytu. --tools ogranicza sesję do wymienionych wbudowanych narzędzi; --allowedTools tylko zatwierdzałoby je z góry i zostawiało Edit lub Bash dostępne, jeśli pozwalają na nie twoje ustawienia. Prompt umieść przed --tools: ta flaga przyjmuje listę o zmiennej długości i inaczej potraktowałaby prompt jako nazwę narzędzia (sprawdzone w Claude Code 2.1.283).

claude -p "$(cat .github/prompts/spec-drift.md)" \
  --tools "Read,Grep,Glob" > drift-report.md

Uruchom audyt przez codex exec w sandboksie tylko do odczytu i zapisz ostatnią wiadomość do pliku.

codex exec --sandbox read-only -o drift-report.md \
  "$(cat .github/prompts/spec-drift.md)"

Uruchom prompt w Plan Mode, który planuje bez pisania kodu, i zapisz raport. Żeby uruchamiać go cyklicznie, wykonaj ten sam prompt w CI przez tryb print (-p) w Cursor CLI. Nazwę polecenia i sposób instalacji weź z dokumentacji Cursora o trybie headless.

You are auditing whether the code still does what specs/ says. Do not edit any file.
For every requirement heading (### ID: ...) under specs/:
1. Find the code that implements it and the tests whose names contain [ID].
2. Classify it as MATCHES, DRIFTED, UNTESTED or UNIMPLEMENTED.
3. For DRIFTED, quote the requirement sentence, quote the code (file:line) that behaves
   differently, and describe one concrete input where the two disagree.
4. For MATCHES, say whether the test would fail if the behaviour changed, or only
   checks that the code runs.
Then list behaviour you found in src/ that no requirement describes (file:line).
Output a markdown table sorted DRIFTED first. Report only what you can cite; if you are
unsure, mark the row "needs a human" instead of guessing which side is right.

Każdy wiersz DRIFTED traktuj jak hipotezę, dopóki człowiek jej nie potwierdzi, najlepiej zapisując rozbieżne dane wejściowe jako test. Audyt, który nie wskazuje pliku i linii, nie jest dowodem.

Co recenzują ludzie zamiast kodu?

Gdy specyfikacja jest wiążąca i powiązana z testami, pytanie recenzenta zmienia się z „czy ten diff jest poprawny?” na „czy to jest zachowanie, którego chcemy, i czy jest udowodnione?”. Podziel zatwierdzanie tak, żeby każdy oceniał to, co potrafi ocenić.

Co jest recenzowane	Kto zatwierdza	Jakich dowodów potrzebuje	Czytanie kodu
Delta specyfikacji: zachowanie widoczne dla użytkownika	Product owner	Diff specyfikacji, przykłady, cele wyłączone z zakresu	Brak
Delta specyfikacji: limity, opóźnienia, bezpieczeństwo	Tech lead	Diff specyfikacji oraz test lub benchmark, który to wymusza	Brak
Implementacja zgodna z deltą	Autor, potem recenzent albo agent recenzujący	Zielona kontrola śledzenia, tabela per identyfikator (wcześniej nie przechodził, teraz przechodzi), cały zestaw testów zielony	Tylko tam, gdzie dowody są słabe
Klasy eskalacji: uwierzytelnianie, pieniądze, schemat, migracje	Właściciel kodu (code owner)	Wszystko powyżej	Tak, zawsze
Wyniki audytu dryfu	Właściciel obszaru	Wiersze DRIFTED z odtwarzającym testem	Tylko wskazane linie

Uzasadnienie tego podziału i sposób budowania zaufania potrzebnego, by go stosować, opisuje czytanie dowodów zamiast kodu. Zamianę historyjki na nieprzechodzący test, na którym opiera się ta tabela, omawiają wykonywalne kryteria akceptacji.

Zwykły markdown czy framework do specyfikacji?

Zacznij od zwykłego markdownu i dwóch kontroli CI opisanych wyżej. Każdy framework z tabeli generuje dobre dokumenty, ale żaden sam z siebie nie sprawia, że specyfikacja jest aktualna i powiązana z testami, a kontrole działają z każdym z nich. Sięgnij po framework, gdy chcesz jego ceremonii: etapów z bramkami, „konstytucji” projektu albo przepływu opartego na propozycjach zmian. Wersje i gwiazdki odczytano 2026-09-26 z npm, PyPI i GitHuba.

Opcja	Artefakty	Jak utrzymuje „bieżące zachowanie”	Narzędzia	Wybierz, gdy	Unikaj, gdy
Zwykły markdown	`specs/<capability>/spec.md` + szablon PR	Każdą deltę scalasz ręcznie; kontrole CI to wymuszają	Dowolny agent	Chcesz najmniejszego procesu, który działa	Nikt nie jest właścicielem plików specyfikacji
Spec Kit (GitHub; `specify-cli` 1.0.12; 138,9 tys. gwiazdek)	Konstytucja, potem spec, plan i zadania na funkcję	Dokumenty na funkcję; scalenie ich w bieżącą specyfikację należy do ciebie	Ponad 40 integracji, w tym Claude Code, Codex i Cursor	Nowe funkcje, które wymagają spisanego śladu i konstytucji	Małe zmiany w dużym kodzie: każda funkcja tworzy kilka dokumentów
OpenSpec (Fission AI; `@fission-ai/openspec` 1.13.2; 70,4 tys. gwiazdek)	Na zmianę: `proposal.md`, delty specyfikacji, `design.md`, `tasks.md`	Archiwizacja zmiany scala jej delty do `openspec/specs/`, żywej specyfikacji	Claude Code, Codex, Cursor i inne	Istniejący kod i wiele przyrostowych zmian	Potrzebujesz rozbudowanego śladu na potrzeby governance
Specyfikacje Kiro (AWS; wbudowane w Kiro)	`.kiro/specs/<feature>/`: `requirements.md` (EARS), `design.md`, `tasks.md`	Na funkcję, jak w Spec Kit	Tylko Kiro; `cc-sdd` 3.1.0 daje ten sam kształt innym agentom	Zespół już pracuje w Kiro	Zespół używa Claude Code, Codex lub Cursora
BMAD Method (BMad Code; `bmad-method` 6.12.0; 53,5 tys. gwiazdek)	Product brief, PRD, architektura, spec, historyjki	Na dokument; jego wartość to przekazania między personami	Claude Code, Codex, Cursor i ok. 40 innych identyfikatorów narzędzi	Praca produktowa z wieloma interesariuszami i epikami	Samodzielny programista dostarczający małe funkcje

W starych tutorialach czyhają dwie pułapki. Spec Kit usunął specify init --ai claude w wersji 0.10.0; flaga nazywa się teraz --integration. Polecenia /openspec:proposal, /openspec:apply i /openspec:archive w OpenSpec to wycofany przepływ; obecny to /opsx:*. Pakiet npm openspec to niepowiązana atrapa, więc instaluj pakiet z zakresem @fission-ai/openspec. Całą kategorię, łącznie z Tessl i Superpowers, porównuje przegląd frameworków.

Zainstaluj dwa frameworki najbliższe temu przepływowi

OpenSpec najbardziej bezpośrednio pasuje do modelu z tej strony, bo jego krok archiwizacji tworzy scaloną, bieżącą specyfikację, której wymaga zasada 1. Spec Kit pasuje do nowych projektów, w których chcesz bramki na każdym etapie. Zapis poleceń różni się między narzędziami.

# OpenSpec (Node >= 20.19.0)
npm install -g @fission-ai/openspec@latest
openspec init --tools claude
# in the agent: /opsx:propose audit-export-streaming → /opsx:apply → /opsx:archive

# Spec Kit (needs uv)
uv tool install specify-cli
specify init --here --integration claude
# in the agent: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement

# OpenSpec: installs skills under .agents/skills/ (no slash commands for Codex)
npm install -g @fission-ai/openspec@latest
openspec init --tools codex
# in the agent: $openspec-propose audit-export-streaming, then the apply and archive skills

# Spec Kit
uv tool install specify-cli
specify init --here --integration codex
# in the agent: $speckit-specify, $speckit-plan, $speckit-tasks, $speckit-implement

# OpenSpec: writes .cursor/commands/ and .cursor/skills/
npm install -g @fission-ai/openspec@latest
openspec init --tools cursor
# in the agent: /opsx-propose audit-export-streaming (hyphen, not colon), then apply and archive

# Spec Kit
uv tool install specify-cli
specify init --here --integration cursor-agent
# in the agent: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement (skills in .cursor/skills/)

W istniejącym repozytorium specify init --here prosi o potwierdzenie, zanim zapisze pliki w niepustym katalogu; dodaj --force, żeby pominąć to pytanie, a w skryptach i CI także --non-interactive (specify init --here --force --non-interactive --integration claude).

Po openspec init polecenie openspec validate --all --json sprawdza w CI pliki zmian i specyfikacji. Waliduje dokumenty, a nie kod, więc trzymaj obok niego kontrolę śledzenia wymagań.

Write specs/billing-invoices/spec.md describing what src/billing/invoices currently DOES,
not what it should do. Read the code and the existing tests first.
- One requirement per observable behaviour, with a stable ID (INVOICE-1, INVOICE-2, ...),
  in WHEN ... THE SYSTEM SHALL ... form with one concrete example taken from a test or the code.
- Mark every requirement that no test covers with "(untested)".
- Add a "Suspicious behaviour" section for anything that looks like a bug; do not describe it
  as intended behaviour and do not fix it.
- No class names, file paths or library names inside requirements.
Do not edit code or tests.

Odtworzona specyfikacja zapisuje to, co kod robi, łącznie z bugami. Zanim stanie się wiążąca, właściciel obszaru powinien przejść listę „Suspicious behaviour”, a brakujące testy trzeba dopisać przed włączeniem kontroli śledzenia dla tego obszaru.

Co się psuje, gdy specyfikacja jest źródłem prawdy?

Specyfikacja butwieje po pierwszej funkcji. Objaw: spec.md nie zmienił się od miesięcy, a kod tak. Wyjście: uruchom audyt dryfu, każdy wiersz DRIFTED zamień w deltę specyfikacji albo w bug, a potem włącz kontrolę ścieżek zachowania, żeby problem nie wrócił po cichu.

Agent zmienia specyfikację, żeby pasowała do jego kodu. Objaw: PR z implementacją zawiera zmianę specyfikacji, o którą nikt nie prosił, a testy przechodzą. To specyfikacyjna wersja agenta osłabiającego własne testy. Wyjście: prompty implementacyjne zabraniają edycji w specs/, CODEOWNERS wymaga zgody właściciela obszaru przy każdej zmianie specyfikacji, a sesje implementacyjne mają zablokowany zapis do specs/ (zobacz uprawnienia i sandboksy).

Specyfikacja opisuje implementację. Objaw: każdy refaktoring wymaga delty specyfikacji, więc ludzie zaczynają dodawać no-behaviour-change do wszystkiego. Wyjście: przenieś nazwy klas, schematy i wybór bibliotek do plan.md albo rekordu decyzji architektonicznej, a w specyfikacji zostaw tylko obserwowalne zachowanie.

Wymagania są zbyt ogólne, by je przetestować. Objaw: agent pisze test, który przechodzi dla każdej implementacji, na przykład „eksport działa”. Wyjście: wymagaj jednego konkretnego przykładu na wymaganie i odrzucaj deltę bez niego. Testy oparte na właściwościach zamieniają niezmienniki ze specyfikacji w kontrole, których agent nie spełni pojedynczym przykładem.

Ceremonia frameworka przygniata małe zmiany. Objaw: poprawka jednej linii tworzy cztery dokumenty, a programiści omijają proces. Wyjście: deltę specyfikacji pisz tylko wtedy, gdy zmienia się obserwowalne zachowanie. Poprawka przywracająca wyspecyfikowane zachowanie potrzebuje testu z istniejącym identyfikatorem, a nie nowej specyfikacji.

Audyt dryfu wymyśla dryf. Objaw: raport wskazuje rozbieżności, których nie ma, i ludzie przestają go czytać. Wyjście: prompt wymaga dowodu w postaci pliku i linii oraz konkretnych rozbieżnych danych wejściowych, a wiersz DRIFTED liczy się dopiero wtedy, gdy ktoś zapisze te dane jako nieprzechodzący test.

Polecenia ze starych tutoriali nie działają. Objaw: specify init --ai claude kończy się błędem albo /openspec:proposal nic nie robi. Wyjście: używaj --integration (Spec Kit) oraz /opsx:* lub zapisu właściwego dla narzędzia (OpenSpec), jak w zakładkach instalacji powyżej.

Dokąd dalej ze spec-driven development

Projektowanie: napisz spec.md Warunek wstępny: pierwsza specyfikacja na podstawie zaakceptowanego intent.md.

Wykonywalne kryteria akceptacji Zamień przykład z każdego wymagania w nieprzechodzący test, zanim powstanie kod.

Code review PR-a agenta Protokół triażu, który zaczyna od delty specyfikacji i dowodów.

Czytanie dowodów zamiast kodu Dlaczego delta specyfikacji z dowodami może zastąpić czytanie linia po linii i kiedy nie może.

Poziom 4: piszesz specyfikacje Gdzie praca oparta na specyfikacji leży na drabinie autonomii i co trzyma długie przebiegi w ryzach.

Frameworki pracy z agentami: porównanie Spec Kit, OpenSpec, BMAD, Superpowers i pozostałe w jednej tabeli.