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

URL: https://developertoolkit.ai/pl/workflows/plan/spec-driven-development/
Description: Jak utrzymać spec.md jako źródło prawdy: delta specyfikacji w każdym PR-ze, testy CI wykrywające dryf oraz zwykły markdown kontra Spec Kit, OpenSpec, Kiro i BMAD.

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 „People have to be in charge of the spec and plan” ([opublikowany transkrypt jego wystąpienia na Sequoia Ascent](https://karpathy.bearblog.dev/sequoia-ascent-2026/), 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](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/), 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](/pl/method/lifecycle/design/). 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](/pl/method/lifecycle/artifact-chain/).

## 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](/pl/comparison/kiro/)). Wymagania i prompty zostaw po angielsku: agent i narzędzia czytają je bez tłumaczenia.

```markdown
# 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](/pl/workflows/plan/architecture-decisions/). 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.

1. **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.

2. **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.

3. **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.

4. **Uruchom bramki.** Kontrola śledzenia wymagań i kontrola ścieżek zachowania (następna sekcja) działają w CI obok typów, lintera i testów.

5. **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ł:

```markdown
## 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](/pl/workflows/ship/evidence-bundle/); protokół recenzji, który go czyta, to [code review PR-a agenta](/pl/workflows/ship/agent-pr-review/).

### 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ą.

**Claude Code**

    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.

**Codex**

    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.

**Cursor**

    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/`.

**Prompt do skopiowania: szkic delty specyfikacji**

```text
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.
```

**Prompt do skopiowania: implementacja według zatwierdzonej specyfikacji**

```text
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.

```js
// 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.

```yaml
# .github/workflows/spec.yml
name: spec
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
permissions:
  contents: read
jobs:
  spec-gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
          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ł. Dodaj do `CODEOWNERS` także `/.github/` i `/scripts/check-spec-trace.mjs` i włącz **Require review from Code Owners**: przy wyzwalaczu `pull_request` GitHub uruchamia ten workflow i skrypt z gałęzi pull requesta, więc bez takiego przeglądu pull request agenta może osłabić jedno lub drugie i przejść. Etykieta `no-behaviour-change` to deklaracja do sprawdzenia przez recenzenta, a nie zabezpieczenie, bo każdy, kto może nadać etykietę, może pominąć drugi krok.

**Kontrola śledzenia dowodzi pokrycia, nie poprawności**

Zielony wynik oznacza, że każde wymaganie ma test z jego identyfikatorem w nazwie. Nie dowodzi, że test sprawdza to, co mówi wymaganie. Do tego służą audyt semantyczny poniżej i [siła wyroczni](/pl/workflows/test/oracle-strength/). Przed osłabianiem testów przez samych agentów chronią mechanizmy opisane w [ochronie wyroczni](/pl/workflows/test/protect-the-oracle/).

### 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.

**Claude Code**

    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).

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

**Codex**

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

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

**Cursor**

    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. Polecenie Cursor CLI to `agent`, więc wywołanie headless wygląda jak `agent -p "…"` (dokumentacja Cursora, sprawdzone 2026-10-12).

**Prompt do skopiowania: audyt dryfu specyfikacji (.github/prompts/spec-drift.md)**

```text
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](/pl/ladder/evidence-not-diffs/). Zamianę historyjki na nieprzechodzący test, na którym opiera się ta tabela, omawiają [wykonywalne kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/).

## 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](/pl/ecosystem/frameworks/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](/pl/ecosystem/frameworks/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](/pl/comparison/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](/pl/ecosystem/frameworks/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](/pl/ecosystem/frameworks/).

### 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.

**Claude Code**

    ```bash
    # 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
    ```

**Codex**

    ```bash
    # 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
    ```

**Cursor**

    ```bash
    # 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ń.

**Prompt do skopiowania: odtworzenie specyfikacji dla istniejącego kodu**

```text
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](/pl/workflows/harness/permissions-and-sandboxing/)).

**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](/pl/workflows/test/property-based-testing/) 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](/pl/method/lifecycle/design/) — Warunek wstępny: pierwsza specyfikacja na podstawie zaakceptowanego intent.md.
- [Wykonywalne kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/) — Zamień przykład z każdego wymagania w nieprzechodzący test, zanim powstanie kod.
- [Code review PR-a agenta](/pl/workflows/ship/agent-pr-review/) — Protokół triażu, który zaczyna od delty specyfikacji i dowodów.
- [Czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/) — Dlaczego delta specyfikacji z dowodami może zastąpić czytanie linia po linii i kiedy nie może.
- [Poziom 4: piszesz specyfikacje](/pl/ladder/level-4-write-specs/) — Gdzie praca oparta na specyfikacji leży na drabinie autonomii i co trzyma długie przebiegi w ryzach.
- [Frameworki pracy z agentami: porównanie](/pl/ecosystem/frameworks/) — Spec Kit, OpenSpec, BMAD, Superpowers i pozostałe w jednej tabeli.
