# OpenSpec: propozycje zmian i żywe specyfikacje

URL: https://developertoolkit.ai/pl/ecosystem/frameworks/openspec/
Description: Pętla propose, apply i archive w OpenSpec na istniejącym kodzie w Claude Code, Codex i Cursorze oraz reguła, kiedy wygrywa ze Spec Kit.

OpenSpec to otwartoźródłowa warstwa specyfikacji od Fission AI dla agentów kodujących, które pracują na istniejącym kodzie. Każda zmiana dostaje propozycję, delty wymagań i listę zadań; gdy agent ją zaimplementuje, archiwizacja scala delty w `openspec/specs/`, żywy opis tego, jak system działa teraz. Działa w Claude Code, Codex i Cursorze.

Endpoint resetu hasła ma sześć lat, nikt nie spisał, jak się zachowuje, a dział bezpieczeństwa chce w tym sprincie limitu żądań, a w następnym krótszego czasu życia tokenu. Możesz dać agentowi ticket i przejrzeć diff albo uruchomić Spec Kit i wyprodukować specyfikację, plan, notatki z researchu i kontrakty dla dwugodzinnej zmiany. Żadna z tych dróg nie zostawia ci spisanej, aktualnej odpowiedzi na pytanie „co dziś robi reset hasła?”.

Ta strona jest dla programisty, który uruchamia agenta na kodzie z historią. Przeprowadza obie te zmiany przez OpenSpec, pokazuje dokładne pliki i polecenia, a na końcu daje regułę, kiedy lepszym wyborem jest Spec Kit.

**Wersje na tej stronie**

Sprawdzone 2026-09-26 na `@fission-ai/openspec` **1.13.2** (npm, wydanie z 2026-09-23): pomoc CLI, skille i polecenia wygenerowane przez `openspec init --tools claude,codex,cursor` oraz kod archiwizacji i walidacji w opublikowanym pakiecie. Claude Code 2.1.283 i codex-cli 0.157.1. Popularność: 70,4 tys. gwiazdek i 4,8 tys. forków na [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), odczyt z 2026-09-26. Gwiazdki mierzą zainteresowanie, nie użycie.

## Co zyskujesz, uruchamiając OpenSpec na istniejącym kodzie

- Działającą instalację dla Claude Code, Codex i Cursora w jednym repozytorium oraz pisownię poleceń w każdym narzędziu.
- Regułę, która rozstrzyga o pierwszej zmianie w kodzie bez specyfikacji: tylko wymagania `ADDED` mogą utworzyć specyfikację, i dlatego testy charakteryzacyjne są krokiem zerowym.
- Dwie prawdziwe delty dla endpointu resetu hasła: jedną, która tworzy specyfikację, i drugą, która modyfikuje i usuwa w niej wymagania.
- Prompty do skopiowania dla explore, propose, apply i pull requesta.
- Job CI, który odrzuca źle sformatowaną zmianę i archiwizację, która zapomniała zaktualizować żywą specyfikację.
- Tabelę decyzyjną: OpenSpec czy Spec Kit, gdy kod już istnieje.

## Jak działa model zmian w OpenSpec?

OpenSpec rozdziela dwie rzeczy: to, co system robi teraz (`openspec/specs/`), i to, co zmieni jedna zmiana (`openspec/changes/<nazwa>/`). Tak wygląda drzewo po zarchiwizowaniu pierwszej zmiany z tego tutorialu i zaproponowaniu drugiej:

- openspec/
  - config.yaml schemat `spec-driven`, opcjonalne `context:` i `rules:`
  - specs/
    - password-reset/spec.md żywa specyfikacja, zapisywana wyłącznie przez archive
  - changes/
    - shorten-reset-token-ttl/ w toku
      - proposal.md dlaczego, co się zmienia, których obszarów dotyczy
      - specs/password-reset/spec.md delta
      - design.md opcjonalny, dla zmian przekrojowych albo ryzykownych
      - tasks.md numerowane checkboksy, przez które przechodzi apply
    - archive/
      - 2026-09-26-add-reset-rate-limit/ pierwsza zmiana, zachowana jako historia

Plik delty używa czterech nagłówków sekcji. Krok archive nakłada je na odpowiadający plik w `openspec/specs/` i przy każdym jest rygorystyczny:

| Sekcja delty | Do czego służy | Co robi archive | Co ją wykoleja |
| ------------ | -------------- | --------------- | -------------- |
| `## ADDED Requirements` | Nowe zachowanie albo istniejące zachowanie, które spisujesz po raz pierwszy | Dopisuje wymaganie; tworzy plik specyfikacji, jeśli go nie ma | Wymaganie, którego nagłówek już istnieje w specyfikacji z inną treścią (nawet jeśli różni się tylko wielkością liter lub spacjami); do tego służy `MODIFIED`. `ADDED` to jedyna operacja, która może utworzyć specyfikację |
| `## MODIFIED Requirements` | Zmienione zachowanie | Zastępuje cały blok wymagania twoim | Odmawia, gdy plik specyfikacji nie istnieje, gdy nagłówek się nie zgadza albo gdy twój blok gubi scenariusz, który ma aktualna specyfikacja |
| `## REMOVED Requirements` | Zachowanie, które wycofujesz, z liniami `**Reason**` i `**Migration**` | Usuwa wymaganie | Na specyfikacji, która jeszcze nie istnieje, ignoruje usunięcie z ostrzeżeniem |
| `## RENAMED Requirements` | Sama zmiana nazwy, w formie `FROM:` / `TO:` | Zmienia nagłówek | Blok `MODIFIED`, który używa starej nazwy |

W każdej sekcji wymaganie to `### Requirement: <nazwa>` z tekstem normatywnym (SHALL albo MUST), a pod nim co najmniej jeden `#### Scenario: <nazwa>` z liniami **WHEN** i **THEN**. Scenariusz ma dokładnie cztery krzyżyki; kolejne sekcje pokazują, co się dzieje, gdy ich brakuje.

Wartość tego modelu leży w scalaniu. Za pół roku `openspec/specs/password-reset/spec.md` odpowie na pytanie „co robi reset hasła?”, a każdy zarchiwizowany katalog zmiany na pytanie „kiedy i dlaczego to się zmieniło?”. Narzędzie ze specyfikacją na funkcję daje ci tylko to drugie.

## Zainstaluj OpenSpec i podłącz go do agenta

OpenSpec wymaga Node.js 20.19.0 lub nowszego (`engines` w pakiecie 1.13.2). Pakiet npm to `@fission-ai/openspec`, a polecenie to `openspec`.

1. Zainstaluj CLI raz na maszynę (terminal):

   ```bash
   npm install -g @fission-ai/openspec@latest
   openspec --version        # oczekuj 1.13.2 lub nowszej
   ```

   README wymienia też oficjalną formułę Homebrew: `brew install openspec`. CLI wysyła anonimowe statystyki użycia (według README nazwy poleceń i wersję) i sam je wyłącza w CI; żeby zrezygnować na swojej maszynie, ustaw `OPENSPEC_TELEMETRY=0` albo uruchom `openspec config set telemetry.enabled false`.

2. Zainicjuj repozytorium dla agentów, których używa zespół. Jeden `init` obsłuży wszystkie trzy:

   ```bash
   cd twoje-repo
   openspec init --tools claude,codex,cursor
   ```

     **Claude Code**

       Zapisuje sześć skilli w `.claude/skills/openspec-*/` i sześć poleceń w `.claude/commands/opsx/`: `explore`, `propose`, `apply`, `archive`, `sync` i `update`. W sesji wpisujesz `/opsx:propose`. Polecenia mają `allowed-tools: Bash(openspec:*)`, więc agent może wołać CLI bez pytania o zgodę; nic więcej nie jest wstępnie dozwolone.

     **Codex**

       Zapisuje te same sześć skilli w `.agents/skills/openspec-*/` i żadnych poleceń, bo Codex wywołuje skille bezpośrednio. W sesji wpisujesz `$openspec-propose`, `$openspec-apply-change` albo `$openspec-archive-change` lub opisujesz zadanie i pozwalasz Codexowi wybrać skill. Według komunikatu `openspec init` w aplikacji desktopowej Codex wybierasz skill z sekcji **Skills** na pasku bocznym.

     **Cursor**

       Zapisuje skille w `.cursor/skills/openspec-*/`, a polecenia w `.cursor/commands/opsx-*.md`. Wyjście `init` podaje dla Cursora pisownię `/opsx-propose`, z łącznikiem zamiast dwukropka. Obsługi poleceń po stronie Cursora nie sprawdzono ponownie na potrzeby tej strony, bo cursor.com był niedostępny 2026-09-26.

3. Opisz projekt agentowi raz, w `openspec/config.yaml`. Pole `context:` jest czytane przed każdą propozycją, a `rules:` dodają ograniczenia dla poszczególnych artefaktów:

   ```yaml
   schema: spec-driven
   context: |
     Express 4 API in TypeScript, Postgres through Knex, Vitest + supertest.
     Password reset lives in src/routes/auth/password-reset.ts.
   rules:
     tasks:
       - Every task names the test that proves it
     proposal:
       - Always include a Non-goals section
   ```

4. Zacommituj `openspec/`, katalogi skilli i katalogi poleceń, żeby każdy członek zespołu i każdy agent czytał ten sam workflow.

**Pułapki OpenSpec ze starych tutoriali (sprawdzone na 1.13.2)**

- `npm i -g openspec` instaluje niezwiązany placeholder z 2022 roku, a `openspec` z PyPI to niezwiązany klient API. Właściwy pakiet to `@fission-ai/openspec`.
- `/openspec:proposal`, `/openspec:apply` i `/openspec:archive` należą do wycofanego workflow. Obecny to `/opsx:*`.
- Pisownia różni się między narzędziami: `/opsx:propose` w Claude Code, `/opsx-propose` w Cursorze, `$openspec-propose` w Codex.
- Domyślny profil nie ma `/opsx:verify`, `/opsx:ff` ani `/opsx:onboard`. Pojawiają się dopiero w profilu rozszerzonym: `openspec config profile`, potem `openspec update`.

## Przeprowadź pierwszą zmianę w kodzie bez specyfikacji

Pierwsza zmiana dotyczy obszaru funkcjonalnego (w OpenSpec: capability), czyli resetu hasła, który nie ma pliku w `openspec/specs/`. To przesądza o tym, jak ją zapisać: archive odrzuca deltę `MODIFIED` wobec nieistniejącej specyfikacji, a deltę `REMOVED` pomija, wypisując jedynie ostrzeżenie. Dlatego pierwsza zmiana opisuje reset hasła wyłącznie jako wymagania `ADDED`: dodawany limit żądań oraz istniejące zachowanie, które chcesz spisać i chronić.

1. **Przypnij obecne zachowanie testami, zanim agent czegokolwiek dotknie.** Wszystko, co zapiszesz w specyfikacji jako „istniejące”, potrzebuje testu, który dowodzi, że jest prawdą dziś. Napisz [testy charakteryzacyjne](/pl/workflows/test/characterization-tests/) dla endpointu resetu: odpowiedź dla nieznanego adresu e-mail, wygasanie tokenu i jednorazowe użycie. Zacommituj je osobno.

2. **Explore.** `explore` czyta kod i zadaje pytania; jego skill zabrania pisania kodu.

   **Prompt do skopiowania: explore w istniejącym obszarze przed propozycją**

   ```text
   /opsx:explore Map how password reset works today in src/routes/auth/password-reset.ts and everything it calls: how a reset is requested, how tokens are created, stored, expired and consumed, and what the response looks like for an unknown email. List every behaviour you find, and for each one name the test in tests/auth/ that covers it or say UNTESTED. Do not propose a change yet.
   ```

   Każde zachowanie oznaczone UNTESTED wraca do kroku 1, zanim złożysz propozycję, albo zostaje poza specyfikacją.

3. **Propose.** Jedno polecenie tworzy katalog zmiany i wszystkie jej artefakty, po czym się zatrzymuje. Skill propose stwierdza, że żądanie „authorizes planning only”, więc agent nie zacznie implementacji w tej samej turze.

   **Prompt do skopiowania: pierwsza zmiana jako wymagania ADDED**

   ```text
   /opsx:propose add-reset-rate-limit
   Add a rate limit to POST /auth/password-reset: at most 5 requests per email address per rolling hour; the 6th gets HTTP 429 with a Retry-After header, and no email is sent.
   There is no openspec/specs/password-reset/ yet, so write the delta with a ## Purpose section and ADDED requirements only. Besides the rate limit, add requirements for these existing behaviours, each with the scenario our characterization tests already check: the endpoint returns 202 whether or not the email exists; a reset token expires 24 hours after issue; a token works once. Also add "Legacy reset link": links of the form /reset?token=<token> are still accepted.
   Non-goals: CAPTCHA, per-IP limits, changes to the email template.
   ```

4. **Recenzuj deltę, nie prozę.** Otwórz `openspec/changes/add-reset-rate-limit/specs/password-reset/spec.md`. Fragment tego, co powinieneś zaakceptować:

   ```markdown
   ## Purpose
   Lets users regain access to their account by email without revealing which addresses have accounts.

   ## ADDED Requirements

   ### Requirement: Reset request rate limit
   The system SHALL accept at most 5 reset requests per email address per rolling hour.

   #### Scenario: Sixth request within an hour
   - **WHEN** a client sends a 6th reset request for alice@example.com within 60 minutes
   - **THEN** the system responds 429 with a Retry-After header and sends no email

   ### Requirement: Reset token lifetime
   The system SHALL reject a reset token 24 hours after it was issued.

   #### Scenario: Token used after 25 hours
   - **WHEN** a user submits a token issued 25 hours earlier
   - **THEN** the system rejects it and the password is unchanged
   ```

   Zaakceptuj ją, gdy każdy scenariusz ma konkretne wejście i sprawdzalne wyjście, gdy każde „istniejące” wymaganie odpowiada przechodzącemu testowi charakteryzacyjnemu i gdy `tasks.md` przy każdym zadaniu wskazuje test. W schemacie `spec-driven` plik `design.md` jest opcjonalny; przy limicie żądań, który wymaga wspólnego licznika dla wielu instancji, poproś o niego.

5. **Zwaliduj strukturę** (terminal):

   ```bash
   openspec validate add-reset-rate-limit --strict
   openspec show add-reset-rate-limit
   ```

6. **Apply.** `/opsx:apply` przechodzi przez `tasks.md` po kolei, odhacza każde ukończone zadanie jako `- [x]` i zatrzymuje się, gdy zadanie jest niejasne albo zablokowane. Prompt w następnej sekcji dokłada bramkę testów.

7. **Archive.** `/opsx:archive` sprawdza artefakty i zadania, nakłada deltę i przenosi zmianę do `openspec/changes/archive/2026-09-26-add-reset-rate-limit/`. Ponieważ ten obszar nie miał specyfikacji, archive tworzy `openspec/specs/password-reset/spec.md` z wymagań `ADDED` i sekcji `## Purpose`. Z terminala ten sam krok to `openspec archive add-reset-rate-limit --yes`.

## Zmień wyspecyfikowane zachowanie deltami MODIFIED i REMOVED

Sprint później dział bezpieczeństwa prosi o 30-minutowy czas życia tokenu i koniec starego linku z tokenem w query stringu. Teraz `openspec/specs/password-reset/spec.md` istnieje, więc delta może w niej modyfikować i usuwać wymagania.

**Prompt do skopiowania: propozycja zmiany wyspecyfikowanego zachowania**

```text
/opsx:propose shorten-reset-token-ttl
Reset tokens must expire 30 minutes after issue instead of 24 hours, and links of the form /reset?token=<token> must stop working; only /reset/<token> is accepted.
Read openspec/specs/password-reset/spec.md first. For the lifetime, copy the entire existing "Reset token lifetime" requirement block, every scenario included, under ## MODIFIED Requirements and edit it. Remove "Legacy reset link" under ## REMOVED Requirements with a Reason and a Migration line. Do not restate requirements that are not changing.
```

Delta, którą widzi recenzent:

```markdown
## MODIFIED Requirements

### Requirement: Reset token lifetime
The system SHALL reject a reset token 30 minutes after it was issued.

#### Scenario: Token used after 25 hours
- **WHEN** a user submits a token issued 25 hours earlier
- **THEN** the system rejects it and the password is unchanged

#### Scenario: Token used after 31 minutes
- **WHEN** a user submits a token issued 31 minutes earlier
- **THEN** the system rejects it and the password is unchanged

## REMOVED Requirements

### Requirement: Legacy reset link
**Reason**: Tokens in query strings leak through referrer headers and proxy logs.
**Migration**: Emails sent since the 2024 template change use /reset/<token>; users with an older email request a new reset.
```

Scenariusz „25 hours” wciąż tu jest, choć nowy go obejmuje. To celowe: `MODIFIED` zastępuje cały blok, a w 1.13.2 zarówno `openspec validate`, jak i archive odrzucają blok `MODIFIED`, który gubi scenariusz obecny w aktualnej specyfikacji. Jeśli chcesz usunąć scenariusz, zmień żywą specyfikację w osobnej, zrecenzowanej zmianie, a nie pomijając go w delcie.

Zanim uruchomisz apply, obejrzyj zmianę tak, jak zobaczy ją recenzent (terminal):

```bash
openspec show shorten-reset-token-ttl --type change --diff
```

`--diff` wypisuje diff każdej delty względem aktualnej specyfikacji, wymaganie po wymaganiu. To najszybszy sposób, żeby potwierdzić, że zmieniają się tylko linie, o które prosił dział bezpieczeństwa.

## Zapętl apply z testami, aż zmiana będzie gotowa

Skill apply odhacza zadania; niczego nie dowodzi. Uczyń zestaw testów bramką między zadaniami i nie pozwól agentowi edytować specyfikacji, żeby jego kod przeszedł.

**Claude Code**

    ```text
    /opsx:apply shorten-reset-token-ttl
    ```

    Uruchom to w sesji, która złożyła propozycję, żeby agent zachował kontekst. Jeśli zadanie pójdzie źle, `/rewind` (albo Esc Esc) przywraca sesję do ostatniego checkpointu. Żeby wymusić zasadę „nigdy nie edytuj specyfikacji”, uruchom sesję implementacyjną z regułą deny dla żywych specyfikacji:

    ```bash
    claude --disallowedTools "Edit(/openspec/specs/**)"
    ```

    Reguła `Edit` obejmuje wszystkie wbudowane narzędzia edytujące pliki, a początkowy `/` wiąże ścieżkę z katalogiem głównym projektu. Trzymaj regułę na poziomie sesji, nie w `.claude/settings.json`: `/opsx:archive` musi zapisywać do `openspec/specs/`, więc archive uruchamiaj w sesji bez niej. Składnię reguł opisuje strona [Uprawnienia, sandboksy i tryby zatwierdzania](/pl/workflows/harness/permissions-and-sandboxing/).

**Codex**

    ```text
    $openspec-apply-change shorten-reset-token-ttl
    ```

    Wpisz polecenie testów do `AGENTS.md` (na przykład `npm test -- tests/auth`), żeby prompt apply poniżej mógł się do niego odwołać, i uruchom sesję z profilem uprawnień `:workspace` (`-c default_permissions=":workspace"`, beta), a nie z pełnym dostępem.

    Codex nie ma tu sesyjnej reguły deny dla ścieżki `openspec/specs/`; zasadę „nigdy nie edytuj specyfikacji” egzekwuje reguła `CODEOWNERS` na `openspec/specs/` i job CI z następnej sekcji.

**Cursor**

    ```text
    /opsx-apply shorten-reset-token-ttl
    ```

    Commituj po każdym zadaniu, po którym testy przechodzą, żeby nieudane zadanie było o jedno `git restore` od cofnięcia, a `tasks.md` miał czystą historię.

    Cursor nie ma tu sesyjnej reguły deny dla ścieżki `openspec/specs/`; zasadę „nigdy nie edytuj specyfikacji” egzekwuje reguła `CODEOWNERS` na `openspec/specs/` i job CI z następnej sekcji.

**Prompt do skopiowania: apply z bramką testów**

```text
Apply the OpenSpec change shorten-reset-token-ttl, one task at a time from tasks.md:
1. Before each task, write or update the test named in the task and run it; it must fail.
2. Implement until that test and the whole suite pass (npm test -- tests/auth). Fix code, never tests written from scenarios.
3. Tick the task only after the suite passes.
Never edit openspec/specs/ or the delta in openspec/changes/shorten-reset-token-ttl/specs/. If a scenario looks wrong, stop and tell me which one and why.
Finish with: each scenario in the delta → the test that proves it → pass/fail.
```

Archiwizuj dopiero wtedy, gdy wszystkie zadania są odhaczone, a testy zielone. Skill archive ostrzega przed nieodhaczonymi zadaniami, ale po twoim potwierdzeniu i tak archiwizuje, a do tego proponuje opcję „Archive without syncing”, która przenosi zmianę do archiwum bez dotykania `openspec/specs/`. Przy zmianie zachowania zawsze wybieraj synchronizację.

## Jak zweryfikować zmianę w OpenSpec bez czytania każdej linii?

Rozdziel kontrole na deterministyczne i na te, które są oceną:

| Bramka | Czego dowodzi | Czego nie dowiedzie | Kto zatwierdza |
| ------ | ------------- | ------------------- | -------------- |
| Testy charakteryzacyjne przed pierwszą zmianą | Że „istniejące” wymagania są dziś prawdziwe | Niczego o nowym zachowaniu | Programista |
| Recenzja delty przed apply | Że zapisano właściwą zmianę zachowania, z przykładami | Że kod ją realizuje | Właściciel kodu danego obszaru |
| `openspec validate --strict` | Strukturę delty, tekst SHALL/MUST, scenariusz przy każdym wymaganiu, brak zgubionego scenariusza w bloku `MODIFIED` | Że wymagania są słuszne albo że kod je spełnia | CI |
| Testy napisane z każdego scenariusza | Że kod zachowuje się zgodnie ze specyfikacją dla tych wejść | Zachowania, którego nikt nie wyspecyfikował | CI |
| Archive aktualizuje `openspec/specs/` | Że żywa specyfikacja odpowiada zmianie | Że kod będzie jej odpowiadał później | Recenzent PR |

Dodaj bramki strukturalne do CI. Ten job waliduje wszystkie zmiany i specyfikacje, odrzuca scenariusz zapisany z trzema krzyżykami i odrzuca pull request, który archiwizuje zmianę z deltami, nie dotykając `openspec/specs/`:

```yaml
# .github/workflows/openspec.yml
name: openspec
on: pull_request
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Validate changes and specs
        run: npx -y @fission-ai/openspec@1.13.2 validate --all --strict --no-interactive
      - name: No three-hash scenarios
        run: |
          if grep -rnE '^### Scenario:' openspec/; then
            echo "Scenarios need four hashes (#### Scenario:)"; exit 1
          fi
      - name: Archived deltas reached the living spec
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          archived=$(git diff --name-only --diff-filter=A "origin/$BASE_REF"...HEAD -- 'openspec/changes/archive/*/specs/*')
          if [ -n "$archived" ] && git diff --quiet "origin/$BASE_REF"...HEAD -- openspec/specs; then
            echo "Archived deltas but openspec/specs/ is unchanged:"; echo "$archived"; exit 1
          fi
```

Krok z grepem istnieje, bo walidacja nie łapie każdego źle zapisanego scenariusza. W 1.13.2 `### Scenario:` pod wymaganiem, które ma też poprawny `#### Scenario:`, przechodzi `validate --strict` z samą linią INFO, że nagłówek „is ignored by validation”. Archive przebudowuje potem specyfikację, czyta zabłąkany nagłówek jako wymaganie bez scenariusza i przerywa pracę, czyli dopiero po napisaniu kodu. Grep przenosi ten błąd do pull requesta. GitHub uruchamia ten workflow z merge refa pull requesta, więc pull request może zmienić także sam job; obejmij `.github/workflows/openspec.yml` tą samą wymaganą recenzją `CODEOWNERS` co `openspec/specs/`.

**Prompt do skopiowania: pull request z deltą jako powierzchnią recenzji**

```text
Open a pull request for the OpenSpec change shorten-reset-token-ttl (archived or not). The description must contain, in this order:
- A link to the delta spec and to openspec/specs/password-reset/spec.md.
- The output of: openspec show shorten-reset-token-ttl --type change --diff (or, if archived, the diff of openspec/specs/ in this branch).
- A table: each scenario in the delta → the test file and test name that proves it → pass/fail from the last run. Mark any scenario with no test UNTESTED.
- The output of: openspec validate --all --strict --no-interactive
- Files changed outside the paths named in tasks.md, each with one line of justification.
Do not summarise the diff line by line.
```

Taki opis to [pakiet dowodowy](/pl/workflows/ship/evidence-bundle/) tej zmiany. Recenzent czyta diff specyfikacji i tabelę scenariusz–test, jak opisuje [recenzja pull requesta od agenta](/pl/workflows/ship/agent-pr-review/), a kod otwiera tylko tam, gdzie wiersz mówi UNTESTED albo plik leży poza listą zadań.

## OpenSpec czy Spec Kit, gdy kod już istnieje?

Oba piszą Markdown przed kodem. Różnią się jednostką pracy i tym, co przetrwa zmianę. Spec Kit zapisuje jeden katalog na funkcję, z konstytucją, specyfikacją, planem, researchem, modelem danych, kontraktami i zadaniami, i stawia bramkę na każdym etapie. OpenSpec zapisuje jeden katalog na zmianę, z propozycją, deltą, opcjonalnym designem i zadaniami, i scala deltę w specyfikację całego systemu. [Tutorial Spec Kit](/pl/ecosystem/frameworks/spec-kit/) pokazuje drugą stronę tego porównania.

| Twoja sytuacja | Użyj | Dlaczego |
| -------------- | ---- | -------- |
| Mała albo średnia zmiana w działającym systemie, kilka razy w tygodniu | OpenSpec | Jeden punkt recenzji na zmianę, a archive utrzymuje `openspec/specs/` w aktualności |
| Musisz odpowiedzieć z repozytorium na pytanie „co ta funkcja systemu robi teraz?” | OpenSpec | Spec Kit zostawia katalogi na funkcję i żadnej scalonej specyfikacji |
| Nowa usługa albo produkt, albo funkcja z kilkoma user stories do zatwierdzenia przez product ownera | Spec Kit | Konstytucja, clarify, analyze i converge dają ślad z bramką na każdym etapie |
| Praca regulowana, która wymaga udokumentowanego planu, researchu i kontraktów dla każdej funkcji | Spec Kit | `design.md` w OpenSpec jest opcjonalny i nie ma bramek etapów |
| Błąd, którego poprawka przywraca zachowanie opisane już w `openspec/specs/` | Żaden framework | Nieprzechodzący test powołujący się na wymaganie |
| Refaktoryzacja bez zmiany zachowania | Żaden framework | Testy przed i po; jeśli używasz OpenSpec, ustaw `skip_specs: true` w `.openspec.yaml` zmiany |

Rozsądny podział to Spec Kit dla nowej usługi i OpenSpec dla strumienia zmian po jej wdrożeniu. Wybierz jeden framework na repozytorium i zapisz to w `CLAUDE.md` albo `AGENTS.md`; dwa frameworki specyfikacji na tym samym kodzie dają agentowi dwa źródła prawdy. [Porównanie frameworków spec-driven](/pl/ecosystem/frameworks/spec-driven-frameworks/) przeprowadza jedną funkcję przez oba.

## Ile OpenSpec kosztuje w kontekście i ceremonii?

**Kontekst.** OpenSpec instaluje skille i polecenia w projekcie, nie plugin, więc `claude plugin details` tu nie działa. Zmierzone 2026-09-26 na plikach, które zapisało `openspec init --tools claude` (1.13.2): sześć opisów skilli i sześć opisów poleceń dokłada do każdej sesji około 2200 znaków, czyli mniej więcej 550 tokenów przy czterech znakach na token. Każdy skill ładuje pełne instrukcje dopiero przy uruchomieniu: `openspec-explore` ma 22,8 KB, a `openspec-propose` 16,3 KB. [Przegląd frameworków](/pl/ecosystem/frameworks/) porównuje to z pakietami pluginów, które kosztują dziesiątki tysięcy tokenów.

**Ceremonia.** Jedna zmiana to trzy albo cztery pliki, a recenzent czyta deltę, zwykle krótszą niż strona. Prawdziwym kosztem jest dyscyplina: ktoś musi zrecenzować deltę przed apply i ktoś musi potwierdzić, że archive zaktualizował żywą specyfikację. Pomiń którykolwiek krok, a zostaniesz z katalogiem Markdownu, któremu nikt nie ufa.

## Co się psuje, gdy uruchamiasz OpenSpec na istniejącym kodzie?

**Archive odmawia przy pierwszej zmianie.** Objaw: archive zatrzymuje się z komunikatem „target spec does not exist; only ADDED requirements are allowed for new specs”. Agent zapisał `MODIFIED` dla zachowania, które istnieje w kodzie, ale jeszcze nie w `openspec/specs/`, a `validate --strict` tego nie zatrzymał: uznaje zmianę za poprawną i wypisuje tylko linię INFO, że archive odrzuci tę deltę. Naprawa: przepisz deltę na wymagania `ADDED` z sekcją `## Purpose`, podparte testami charakteryzacyjnymi.

**Usunięcie po cichu nic nie robi.** Objaw: zarchiwizowana zmiana wymienia wymaganie `REMOVED`, a żywa specyfikacja nigdy o nim nie wspomina. Dla obszaru bez specyfikacji archive ignoruje `REMOVED` z ostrzeżeniem. Naprawa: w pierwszej zmianie w ogóle nie wpisuj wycofywanego zachowania do specyfikacji, a usunięcie odnotuj w `proposal.md`.

**Archive odrzuca deltę MODIFIED.** Objaw: „current spec contains scenario(s) not present in the modified block”. Agent zapisał fragment zamiast całego wymagania. Naprawa: skopiuj pełny blok z `openspec/specs/`, ze wszystkimi scenariuszami, i dopiero go edytuj.

**Scenariusz zostaje zignorowany, a potem archive się wywraca.** Objaw: `validate --strict` jest zielone, testy wygenerowane z delty pomijają jeden scenariusz, a archive przerywa później z komunikatem „Requirement must have at least one scenario”. Scenariusz zapisano jako `### Scenario:`, więc walidacja go zignorowała, a archive odczytał go jako wymaganie. Naprawa: zmień nagłówek na `#### Scenario:`, dopisz test i zostaw krok z grepem w jobie CI powyżej, żeby następny taki błąd wyszedł na recenzji.

**Żywa specyfikacja rozjeżdża się z kodem.** Objaw: ktoś zarchiwizował zmianę przez „Archive without syncing” albo zmienił zachowanie bez propozycji, i `openspec/specs/` opisuje system sprzed kwartału. Naprawa: krok CI sprawdzający, czy zarchiwizowane delty dotarły do żywej specyfikacji, reguła `CODEOWNERS` na `openspec/specs/` i kontrole dryfu opisane w [spec-driven development](/pl/workflows/plan/spec-driven-development/).

**Agent edytuje specyfikację, żeby pasowała do jego kodu.** Objaw: commit implementacyjny zmienia deltę albo `openspec/specs/`, a testy przechodzą. Naprawa: zablokuj zapis do `openspec/specs/` w sesjach implementacyjnych, wymagaj zgody właściciela obszaru na każdą zmianę w tym katalogu i [chroń testy](/pl/workflows/test/protect-the-oracle/), które kodują scenariusze.

**Stare tutoriale prowadzą na manowce.** Objaw: `npm i -g openspec` instaluje wersję 0.0.0 albo `/openspec:proposal` nic nie robi. Naprawa: zainstaluj `@fission-ai/openspec` i używaj poleceń `/opsx:*` w pisowni twojego narzędzia.

## Dokąd dalej z OpenSpec

- [Spec-driven development](/pl/workflows/plan/spec-driven-development/) — Koncepcja stojąca za tą stroną: specyfikacja jako źródło prawdy i wykrywanie dryfu po wdrożeniu zmiany.
- [Testy charakteryzacyjne](/pl/workflows/test/characterization-tests/) — Przypnij, co dziś robi stary kod, zanim pierwsza zmiana w OpenSpec to zapisze.
- [Wykonywalne kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/) — Zamień każdy scenariusz WHEN/THEN w nieprzechodzący test przed apply.
- [GitHub Spec Kit](/pl/ecosystem/frameworks/spec-kit/) — Alternatywa na miarę funkcji, z bramkami etapów, dla nowych usług i większych funkcji.
- [Porównanie frameworków spec-driven](/pl/ecosystem/frameworks/spec-driven-frameworks/) — Spec Kit, OpenSpec, BMAD i Superpowers na tej samej funkcji.
- [Porównanie frameworków pracy z agentami](/pl/ecosystem/frameworks/) — OpenSpec obok wszystkich innych frameworków, z kosztami kontekstu.
