# GitHub Spec Kit: spec-driven development w praktyce

URL: https://developertoolkit.ai/pl/ecosystem/frameworks/spec-kit/
Description: GitHub Spec Kit od początku do końca w Claude Code, Codex i Cursorze: konstytucja, specify, plan, tasks, implement i converge, z generowanymi plikami.

GitHub Spec Kit to otwartoźródłowy zestaw narzędzi GitHuba do spec-driven development z agentami kodującymi. CLI `specify` instaluje skille agenta, które prowadzą funkcję przez etapy constitution, specify, plan, tasks, implement i converge, a każdy etap zapisuje plik Markdown do recenzji. Działa w Claude Code, Codex i Cursorze i opłaca się przy funkcjach na tyle dużych, że zasługują na pisemny ślad.

Administratorzy zespołów chcą eksportować dziennik audytu do CSV. W zeszłym kwartale podobna funkcja trafiła do agenta jako jednoakapitowy ticket i wróciła jako 1400 linii: eksport ignorował filtr dat dla jednej z ról i nikt nie potrafił powiedzieć, które zachowanie jest zamierzone, bo niczego nie zapisano. Chcesz, żeby następna funkcja przyszła ze specyfikacją zatwierdzoną przez product ownera, planem zatwierdzonym przez tech leada i dowodem, że kod robi to, co mówi specyfikacja.

Ta strona jest dla programisty, który uruchamia agenta, i dla tech leada, który decyduje, czy zespół przyjmie Spec Kit. Przeprowadza jedną prawdziwą funkcję, eksport dziennika audytu, przez wszystkie etapy we wszystkich trzech narzędziach.

**Wersje na tej stronie**

Sprawdzone 2026-09-26 przez uruchomienie `specify-cli` **1.0.12** (PyPI, wydanie z 2026-09-25) w roboczym repozytorium z Claude Code 2.1.283 i codex-cli 0.157.1. Spec Kit 1.0.0 ukazał się 2026-08-21 i od tego czasu nowe wydanie pojawia się co kilka dni (12 do 2026-09-25), więc przed skopiowaniem układu plików uruchom `specify version`. Popularność: 138,9 tys. gwiazdek i 12,4 tys. forków na [github/spec-kit](https://github.com/github/spec-kit), odczyt z 2026-09-26. Gwiazdki mierzą zainteresowanie, nie użycie.

## Co zyskujesz, przeprowadzając jedną funkcję przez Spec Kit

- Działającą instalację w Claude Code, Codex albo Cursorze, łącznie z repozytorium obsługującym wszystkie trzy naraz.
- Dokładną pisownię poleceń w każdym narzędziu: `/speckit-specify` w Claude Code i Cursorze, `$speckit-specify` w Codex.
- Plik, który zapisuje każdy etap, pokazany na eksporcie dziennika audytu, i pytanie, które zadajesz, zanim go przyjmiesz.
- Pętlę implement–converge, która kończy się dopiero wtedy, gdy agent zgłosi „Converged”, oraz pull request niosący ślad specyfikacji zamiast prośby, żeby recenzent przeczytał diff.
- Rozszerzenia `bug` i `assess` do pracy, która nie jest nową funkcją.
- Jasną regułę, kiedy Spec Kit dokłada ceremonii, którą lepiej pominąć.

## Gdzie Spec Kit mieści się w łańcuchu artefaktów?

[Łańcuch artefaktów](/pl/method/lifecycle/artifact-chain/) mówi, że każdy etap commituje jeden plik, który czyta następny etap. Spec Kit generuje większość tego łańcucha za ciebie, pod własnymi nazwami plików.

| Łańcuch artefaktów | Etap Spec Kit | Plik zapisywany przez Spec Kit | Kto go akceptuje |
| ------------------ | ------------- | ------------------------------ | ---------------- |
| Zasady projektu | `speckit-constitution` (raz na projekt) | `.specify/memory/constitution.md` | Tech lead |
| `intent.md` | `speckit-assess-*` (opcjonalne rozszerzenie) | `.specify/assessments/<slug>/` | Product owner |
| `spec.md` | `speckit-specify`, potem `speckit-clarify` | `specs/001-<funkcja>/spec.md` | Product owner |
| `plan.md` | `speckit-plan`, potem `speckit-checklist` | `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md` | Tech lead |
| Lista zadań | `speckit-tasks`, potem `speckit-analyze` | `tasks.md` | Programista prowadzący agenta |
| Diff i testy | `speckit-implement` | Kod i zadania odhaczone `[X]` | CI |
| Dowód zgodności ze specyfikacją | `speckit-converge` | Sekcja `## Phase N: Convergence` w `tasks.md` albo brak zmian | Programista, potem recenzent PR |

Dwie luki pozostają twoim zadaniem. Spec Kit zapisuje jeden katalog na funkcję, więc nic nie scala `specs/001-audit-log-export/spec.md` w aktualny opis całego systemu; utrzymanie żywej specyfikacji i wykrywanie dryfu opisuje strona o [spec-driven development](/pl/workflows/plan/spec-driven-development/). Poza tym `speckit-converge` to ocena modelu, więc każde wymaganie nadal potrzebuje testu, który nie przejdzie, gdy zachowanie jest złe.

## Zainstaluj Spec Kit i podłącz go do agenta

Spec Kit wymaga Pythona 3.11 lub nowszego (PyPI `requires_python >=3.11`), [uv](https://docs.astral.sh/uv/) i Gita. Pakiet w PyPI to `specify-cli`, a instalowane polecenie to `specify`.

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

   ```bash
   uv tool install specify-cli
   specify version        # oczekuj CLI Version 1.0.12 lub nowszej
   ```

   Żeby przypiąć wydanie dla całego zespołu, instaluj z taga: `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.12`. `specify self check` zgłasza nowsze wydanie, a `specify self upgrade` je instaluje.

2. Zainicjuj repozytorium dla swojego agenta. Flaga to `--integration`; dawną flagę `--ai` usunięto w 0.10.0.

     **Claude Code**

       ```bash
       cd your-repo
       specify init --here --integration claude --script sh
       # zapisuje .claude/skills/speckit-*/SKILL.md (10 skilli)
       claude
       # w sesji: /speckit-constitution, /speckit-specify, ...
       ```

     **Codex**

       ```bash
       cd your-repo
       specify init --here --integration codex --script sh
       # zapisuje .agents/skills/speckit-*/SKILL.md (10 skilli)
       codex
       # w sesji: $speckit-constitution, $speckit-specify, ...
       ```

     **Cursor**

       ```bash
       cd your-repo
       specify init --here --integration cursor-agent --script sh
       # zapisuje .cursor/skills/speckit-*/SKILL.md (10 skilli)
       # otwórz repo w Cursorze; w czacie Agent: /speckit-constitution, /speckit-specify, ...
       ```

   W skrypcie albo w CI użyj `specify init --here --force --integration claude --script sh --non-interactive`; `--here` w niepustym repozytorium wymaga `--force`, gdy nikt nie może odpowiedzieć na pytanie. Bez `--integration` uruchomienie nieinteraktywne wybiera Copilota, a nie twojego agenta.

3. Jeśli zespół używa więcej niż jednego agenta, dodaj pozostałe do tego samego repozytorium. Dzielą `.specify/` i katalogi `specs/`, więc specyfikację napisaną w Claude Code można zaimplementować w Codex:

   ```bash
   specify integration install codex
   specify integration install cursor-agent
   specify integration status   # "Installed integrations: claude, codex, cursor-agent"
   ```

4. Opcjonalnie dodaj dołączone rozszerzenia: `specify extension add git` (gałęzie funkcji i automatyczne commity wokół każdego etapu), `specify extension add bug` i `specify extension add assess`. Rozszerzenia rejestrują hooki w `.specify/extensions.yml`; przeczytaj ten plik, zanim go zacommitujesz.

5. Zacommituj `.specify/`, `specs/` i katalogi skilli `speckit-*`. Komunikat po `init` sugeruje dodanie katalogu agenta do `.gitignore`, bo agenci mogą tam trzymać dane uwierzytelniające. Ignoruj pliki w rodzaju `.claude/settings.local.json`, a nie skille potrzebne reszcie zespołu.

**Pułapki Spec Kit ze starych tutoriali (sprawdzone na 1.0.12)**

- `specify init --ai claude` kończy się błędem: `--ai`, `--ai-commands-dir` i `--ai-skills` usunięto w 0.10.0. Użyj `--integration claude`.
- `/speckit.specify` z kropką to notacja z dokumentacji referencyjnej Spec Kit. W trybie skilli Claude Code i Cursor udostępniają `/speckit-specify`, a Codex `$speckit-specify`.
- `pip install specify`, `pip install speckit` i `npm i spec-kit` instalują niepowiązane pakiety albo nic. Pakiet nazywa się `specify-cli`.
- Identyfikator integracji dla Cursora to `cursor-agent`, nie `cursor`.

## Co `specify init` zapisuje w repozytorium?

Tak wygląda drzewo po `specify init --here --integration claude` w 1.0.12, zanim uruchomisz jakikolwiek etap. Codex dostaje te same 10 skilli w `.agents/skills/`, a Cursor w `.cursor/skills/`.

- .claude/skills/
  - speckit-constitution/SKILL.md
  - speckit-specify/SKILL.md
  - speckit-clarify/SKILL.md
  - speckit-plan/SKILL.md
  - speckit-checklist/SKILL.md
  - speckit-tasks/SKILL.md
  - speckit-analyze/SKILL.md
  - speckit-implement/SKILL.md
  - speckit-converge/SKILL.md
  - speckit-taskstoissues/SKILL.md
- .specify/
  - memory/constitution.md szablon, dopóki nie uruchomisz etapu constitution
  - templates/ szablony spec, plan, tasks, checklist i constitution
  - scripts/bash/ create-new-feature.sh, setup-plan.sh i skrypty pomocnicze
  - workflows/speckit/workflow.yml
  - integrations/ manifesty plików zarządzanych przez Spec Kit
  - init-options.json numeracja funkcji, typ skryptów, wersja
  - .gitignore ignoruje feature.json, lokalny wskaźnik bieżącej funkcji

Skille to zwykłe [Agent Skills](/pl/ecosystem/skills/installing-managing/) w twoim repozytorium, a nie plugin, więc nie ma wpisu w marketplace ani wyniku `claude plugin details`. `specify integration status` pokazuje, czy ktoś edytował zarządzane pliki.

## Przeprowadź pełny cykl na eksporcie dziennika audytu

Poniższe polecenia mają pisownię Claude Code i Cursora. W Codex zamień początkowy `/` na `$`. Uruchamiaj jeden etap naraz i recenzuj jego plik, zanim zaczniesz następny; etapy są osobnymi skillami właśnie po to, żeby człowiek mógł zatrzymać łańcuch.

1. **Constitution (raz na projekt).** Zasady, z którymi porównuje się każdy późniejszy etap.

   ```text
   /speckit-constitution Test-first: every functional requirement gets a failing test before code. No new runtime dependency without an ADR in docs/adr/. Every endpoint enforces authorization server-side. p95 latency under 200 ms for interactive endpoints.
   ```

   Skill wypełnia `.specify/memory/constitution.md`, nadaje mu wersję semantyczną i datę ratyfikacji, a na górze umieszcza Sync Impact Report w komentarzu HTML. Zaakceptuj go, gdy każdą zasadę da się przetestować. „Kod ma być czysty” się nie da.

2. **Specify.** Opisz co i dlaczego, nigdy jak.

   **Prompt do skopiowania: specyfikacja eksportu dziennika audytu**

   ```text
   /speckit-specify Team admins can export their organization's audit log as CSV, filtered by date range (max 90 days) and optionally by actor. Members who are not admins must not be able to export. Exports of up to 100,000 rows complete in a single download; larger ranges are refused with a message telling the admin to narrow the range. Every export is itself recorded in the audit log with who exported, the filters used and the row count. Out of scope: scheduled exports, JSON format, exports across organizations.
   ```

   Skill wybiera kolejny numer, tworzy `specs/001-audit-log-export/spec.md` z szablonu i zapisuje checklistę jakości w `specs/001-audit-log-export/checklists/requirements.md`. Numeracja jest sekwencyjna, chyba że `init-options.json` mówi inaczej. Gałąź powstaje tylko wtedy, gdy zainstalowałeś rozszerzenie `git`. Poglądowy fragment w formacie szablonu (numeracja FR i SC, scenariusze Given/When/Then):

   ```markdown
   ### User Story 1 - Export filtered audit log (Priority: P1)
   **Acceptance Scenarios**:
   1. **Given** an admin and 1,200 events in the last 30 days, **When** they export
      with that range, **Then** they receive a CSV with 1,200 data rows and a header row.
   2. **Given** a member without the admin role, **When** they request an export,
      **Then** the request is refused and no file is produced.

   ### Functional Requirements
   - **FR-001**: System MUST let admins export audit events for a date range of at most 90 days.
   - **FR-004**: System MUST refuse exports over 100,000 rows with a message to narrow the range.
   - **FR-006**: System MUST record each export as an audit event [NEEDS CLARIFICATION: should
     the export event appear in exports that cover its own timestamp?]

   ### Success Criteria
   - **SC-001**: An admin completes an export of 30 days of events in under 10 seconds.
   ```

   Skill dopuszcza najwyżej trzy znaczniki `[NEEDS CLARIFICATION]` i na końcu przebiegu pyta cię o nie. Zaakceptuj specyfikację, gdy każdy scenariusz akceptacyjny ma konkretne wejście i wyjście, a nie pojawia się w niej żadna nazwa klasy, tabeli ani biblioteki.

3. **Clarify (opcjonalnie, przed planem).** `/speckit-clarify` zadaje ustrukturyzowane pytania o znalezione luki i zapisuje twoje odpowiedzi z powrotem w `spec.md`. Uruchamiaj go zawsze, gdy w specyfikacji został znacznik albo przypadek brzegowy, o którym nikt nie zdecydował.

4. **Plan.** Teraz jak.

   **Prompt do skopiowania: plan pod istniejący stos**

   ```text
   /speckit-plan Next.js App Router route handler at app/api/audit-log/export/route.ts. PostgreSQL through the existing Drizzle schema in src/db/schema.ts; add an index on (organization_id, created_at) only if research shows the current indexes cannot serve the query. Stream the CSV response; do not buffer 100,000 rows in memory. Reuse requireRole() from src/lib/auth.ts for authorization. Vitest for unit and integration tests, Playwright for one end-to-end download. No new dependencies unless the Constitution Check justifies one.
   ```

   `speckit-plan` zapisuje `plan.md` z szablonu, a potem `research.md` (każde otwarte pytanie rozstrzygnięte), `data-model.md`, `contracts/` (tu: żądanie i odpowiedź endpointu eksportu) oraz `quickstart.md`, przewodnik walidacji do wypróbowania funkcji. `plan.md` zawiera bramkę **Constitution Check**, ocenianą przed researchem i ponownie po projekcie. Zaakceptuj plan, gdy Constitution Check przechodzi bez nieuzasadnionego naruszenia, a każdy wymieniony plik istnieje albo jest nowy celowo.

5. **Checklist (opcjonalnie, po planie).** `/speckit-checklist security` generuje checklistę, która testuje *wymagania* pod kątem kompletności i jednoznaczności, na przykład „Czy reguła autoryzacji jest podana dla każdego punktu wejścia?”. To test jednostkowy specyfikacji, nie kodu.

6. **Tasks.** `/speckit-tasks` zapisuje `tasks.md`: fazy przygotowania i fundamentów, potem jedną fazę na każdą historyjkę użytkownika; każde zadanie ma identyfikator, opcjonalny znacznik `[P]` dla zadań, które mogą iść równolegle, i etykietę historyjki.

   ```markdown
   ## Phase 3: User Story 1 - Export filtered audit log (Priority: P1)
   - [ ] T010 [P] [US1] Integration test: admin exports 30-day range in tests/integration/audit-export.test.ts
   - [ ] T011 [P] [US1] Integration test: non-admin gets 403 in tests/integration/audit-export.test.ts
   - [ ] T012 [US1] Implement streaming CSV route in app/api/audit-log/export/route.ts
   ```

   Szablon zadań oznacza zadania testowe jako „OPTIONAL - only if tests requested”. Zamawia je zasada test-first w twojej konstytucji, i właśnie dlatego konstytucja idzie pierwsza.

7. **Analyze (opcjonalnie, przed implementacją).** `/speckit-analyze` działa wyłącznie w trybie odczytu: porównuje `spec.md`, `plan.md` i `tasks.md` i zgłasza wymagania bez zadania, zadania bez wymagania oraz konflikty z konstytucją. Konflikty z konstytucją mają zawsze poziom CRITICAL. Rozwiąż każde znalezisko CRITICAL przed implementacją.

8. **Implement.** `/speckit-implement` przechodzi przez `tasks.md` faza po fazie i oznacza każde ukończone zadanie `[X]`. Przed startem liczy nieodhaczone pozycje we wszystkich plikach w `checklists/` i pyta, czy kontynuować, jeśli jakieś zostały.

9. **Converge.** `/speckit-converge` porównuje kod z `spec.md`, `plan.md`, `tasks.md` i konstytucją. Nigdy nie edytuje kodu, specyfikacji ani planu. Gdy czegoś brakuje, dopisuje nową sekcję `## Phase N: Convergence` z ponumerowanymi zadaniami, najpierw CRITICAL i HIGH. Gdy niczego nie brakuje, zostawia `tasks.md` bez zmian co do bajta i zgłasza „Converged — the implementation satisfies the spec, plan, and tasks.”

## Powtarzaj implement i converge, aż funkcja osiągnie zbieżność

Kroki 8 i 9 tworzą pętlę, która zastępuje czytanie diffa: implement, converge i ponowna implementacja dopisanych zadań, aż converge niczego nie dopisze. Wtedy otwierasz pull request ze śladem.

**Claude Code**

    Prowadź pętlę w jednej sesji, żeby agent zachował kontekst funkcji, a polecenie testów niech będzie bramką między rundami.

    ```text
    /speckit-implement
    /speckit-converge
    ```

    Powtarzaj tę parę, dopóki converge dopisuje fazę Convergence. Gdy runda implementacji pójdzie źle, `/rewind` (albo Esc Esc) cofa sesję do punktu kontrolnego. Żeby oddać agentowi całą pętlę, wklej prompt pętli poniżej.

**Codex**

    Te same dwa skille, w pisowni Codex.

    ```text
    $speckit-implement
    $speckit-converge
    ```

    Codex czyta `AGENTS.md`, więc wpisz tam polecenie testów (na przykład `npm test && npx playwright test`), a prompt pętli może odwoływać się do „polecenia testów z AGENTS.md”.

**Cursor**

    W czacie Agent wpisz `/speckit-implement`, potem `/speckit-converge`, z tymi samymi nazwami skilli co w Claude Code. Commituj po każdej rundzie, która przechodzi testy, żeby nieudana runda implementacji była o jedno `git restore` od cofnięcia, a `tasks.md` miał czystą historię.

**Prompt do skopiowania: implement ↔ converge aż do Converged**

```text
Work on the feature in specs/001-audit-log-export/. Loop:
1. Run the speckit-implement skill on tasks.md.
2. Run the full test suite (npm test && npx playwright test). If it fails, fix the code, never the tests or the spec.
3. Run the speckit-converge skill.
4. If converge appended a "Phase N: Convergence" section, go back to step 1. If it reported "Converged", stop.
Stop after 3 rounds even if not converged, and report which findings keep reappearing.
Never edit spec.md, plan.md or the constitution. If a requirement looks wrong, stop and tell me.
Finish with: rounds run, tasks completed, test command output summary, and the converge verdict.
```

Limit rund ma znaczenie. Znalezisko, które wraca po dwóch rundach, zwykle oznacza, że specyfikacja i plan sobie przeczą, a kolejny przebieg implementacji nie naprawi sprzeczności między dokumentami.

**Prompt do skopiowania: pull request ze śladem specyfikacji**

```text
Open a pull request for specs/001-audit-log-export/. The description must contain, in this order:
- Links to spec.md, plan.md and tasks.md, and the constitution version it was checked against.
- A table: each FR-### and SC-### from spec.md → the test file and test name that proves it → pass/fail from the last test run. Mark any requirement with no test as UNTESTED.
- The last speckit-converge verdict, verbatim.
- Any speckit-analyze finding that was accepted instead of fixed, with the reason.
- Files changed outside the paths named in plan.md, each with one line of justification.
Do not summarise the diff line by line.
```

Ta tabela to [pakiet dowodów](/pl/workflows/ship/evidence-bundle/) dla tej funkcji. Recenzent zaczyna od delty specyfikacji i tabeli wymaganie–test, jak opisuje [recenzja pull requestu agenta](/pl/workflows/ship/agent-pr-review/), a kod czyta tylko tam, gdzie tabela pokazuje UNTESTED albo plik spoza planu.

## Jak zweryfikować wynik Spec Kit bez czytania każdej linii?

Każda bramka łapie inną klasę błędów i tylko część z nich jest deterministyczna.

| Bramka | Co dowodzi | Czego nie dowodzi | Kto zatwierdza |
| ------ | ---------- | ----------------- | -------------- |
| Recenzja specyfikacji | Zapisano właściwe zachowanie, z przykładami | Że kod je realizuje | Product owner |
| `speckit-checklist` | Wymagania są kompletne i jednoznaczne | Niczego o kodzie | Product owner lub tech lead |
| Constitution Check w `plan.md` | Projekt respektuje zasady projektu | Że implementacja też je respektuje | Tech lead |
| `speckit-analyze` | Specyfikacja, plan i zadania są ze sobą zgodne | Że którekolwiek z nich jest poprawne | Programista |
| Testy pisane ze scenariuszy akceptacyjnych | Kod zachowuje się zgodnie ze specyfikacją dla tych wejść | Zachowania, którego nikt nie wyspecyfikował | CI |
| „Converged” z `speckit-converge` | Model nie znalazł niezbudowanego wymagania | Poprawności; to ocena, nie test | Programista, potem recenzent PR |

Traktuj „Converged” jako warunek konieczny, nie wystarczający. Deterministycznym dowodem jest tabela wymaganie–test: każdy scenariusz akceptacyjny staje się czerwonym testem przed implementacją, jak w [wykonywalnych kryteriach akceptacji](/pl/workflows/plan/acceptance-criteria/), a CI go uruchamia. Trzymaj `specs/` poza zakresem zapisu agenta implementującego dzięki [uprawnieniom i sandboksom](/pl/workflows/harness/permissions-and-sandboxing/) oraz regule w `CODEOWNERS`, żeby agent nie mógł przepchnąć testu, zmieniając specyfikację.

**Prompt do skopiowania: krytyczna recenzja spec.md przed planem**

```text
Review specs/001-audit-log-export/spec.md as a skeptical QA lead. Do not edit it.
List, with the requirement ID:
1. Requirements with no concrete example input and output.
2. Acceptance scenarios a wrong implementation could still pass (for example, a filter test with data that would pass unfiltered).
3. Missing edge cases: empty range, range exactly 90 days, exactly 100,000 rows, deleted actor, timezone boundaries.
4. Anything that names an implementation (tables, libraries, files).
End with a verdict: READY FOR PLAN or NOT READY, and the three changes that matter most.
```

## Naprawiaj błędy i oceniaj pomysły rozszerzeniami bug i assess

Nie każda zmiana to nowa funkcja. Spec Kit 1.0 dołącza jako rozszerzenia jeszcze dwa procesy.

**Naprawa błędów** (`specify extension add bug`) dodaje trzy skille, które zapisują do `.specify/bugs/<slug>/`:

```text
/speckit-bug-assess "Exporting a range that ends today returns an empty CSV." slug=export-empty-today
/speckit-bug-fix slug=export-empty-today
/speckit-bug-test slug=export-empty-today
```

`bug-assess` zapisuje `assessment.md` z podejrzaną przyczyną i propozycją naprawy, `bug-fix` ją stosuje i zapisuje `fix.md`, a `bug-test` zapisuje `test.md` z jednym werdyktem: `verified` (objaw już się nie odtwarza i krytyczne sprawdzenia przechodzą), `partial` albo `failed`. Błąd zamyka tylko `verified`. Poprawka przywracająca zachowanie, które specyfikacja już opisuje, nie potrzebuje nowej specyfikacji, tylko testu powołującego się na istniejący identyfikator FR.

**Ocena pomysłów** (`specify extension add assess`) dodaje `speckit-assess-intake`, `-research`, `-define`, `-shape` i `-decide`, które zapisują do `.specify/assessments/<slug>/`. `assess-decide` zapisuje w `decision.md` werdykt go, needs-clarification albo kill i tylko go przechodzi dalej do `speckit-specify`. Używaj go, gdy product owner przynosi mglisty pomysł: odrzucenie pomysłu, zanim powstanie specyfikacja, to najtańszy wynik, jaki ten proces oferuje.

## Ile Spec Kit kosztuje w kontekście i ceremonii?

**Kontekst.** 10 podstawowych skilli dokłada do każdej sesji około 1300 znaków opisów (pomiar na 1.0.12; mniej więcej 300 tokenów przy czterech znakach na token). Każdy etap ładuje pełne instrukcje dopiero przy uruchomieniu: `speckit-specify` ma 18,7 KB, a `speckit-converge` 13,5 KB. To niewiele przy pakietach pluginów, które porównuje [przegląd frameworków](/pl/ecosystem/frameworks/). Większym kosztem są same dokumenty: jedna funkcja daje specyfikację, checklistę wymagań, plan, research, model danych, kontrakty, quickstart i listę zadań, a każdy późniejszy etap je czyta.

**Wywoływanie.** W Claude Code wszystkie 10 skilli ma `disable-model-invocation: false`, więc agent może sam uruchomić etap, gdy prośba pasuje do opisu skilla. Jeśli chcesz, żeby każdy etap uruchamiał człowiek, zapisz to w `CLAUDE.md` i wywołuj etapy jawnymi poleceniami. Żeby to wymusić, ustaw `disable-model-invocation: true` w każdym `SKILL.md` skilli `speckit-*`; `specify integration status` zgłosi wtedy te pliki jako zmodyfikowane pliki zarządzane, a `specify integration upgrade --force` może je nadpisać. Zdecyduj świadomie.

**Ceremonia.** O decyzji niech przesądzi liczba etapów:

| Zmiana | Spec Kit? | Zamiast tego |
| ------ | --------- | ------------ |
| Nowa funkcja z kilkoma historyjkami albo taka, którą musi zatwierdzić product owner | Tak, pełny cykl | — |
| Nowa usługa lub produkt od zera | Tak, zaczynając od konstytucji | — |
| Błąd przywracający wyspecyfikowane zachowanie | Rozszerzenie `bug` | Czerwony test powołujący się na identyfikator FR |
| Mała zmiana w dużej istniejącej bazie kodu | Zwykle nie | [OpenSpec](/pl/ecosystem/frameworks/openspec/), który zapisuje deltę specyfikacji dla każdej zmiany |
| Refaktoryzacja bez zmiany zachowania | Nie | Testy przed i po; bez specyfikacji |
| Spike albo prototyp do wyrzucenia | Nie | Tryb planowania w twoim agencie |

## Co się psuje, gdy używasz Spec Kit?

**Stare flagi i pisownia nie działają.** Objaw: `specify init --ai claude` zwraca błąd albo `/speckit.specify` nic nie robi. Naprawa: używaj `--integration` i pisowni właściwej dla narzędzia, `/speckit-specify` albo `$speckit-specify`.

**`init` wybiera złego agenta.** Objaw: `init` w CI albo w skrypcie tworzy pliki Copilota. Naprawa: zawsze podawaj `--integration`; istniejące repozytorium przełączysz przez `specify integration switch claude`, a kolejną integrację dodasz przez `specify integration install`.

**Agent pracuje nad złą funkcją.** Objaw: `speckit-plan` zapisuje do `specs/001-…`, a chodziło ci o `002`. Bieżąca funkcja jest zapisana w `.specify/feature.json`, który jest lokalny dla checkoutu i ignorowany przez Gita. Naprawa: podawaj katalog funkcji w prompcie i daj każdemu równoległemu agentowi osobny worktree, żeby każdy miał własny wskaźnik.

**Nie powstały żadne testy.** Objaw: `tasks.md` nie ma zadań testowych, a `implement` od razu pisze kod. Naprawa: dodaj do konstytucji zasadę test-first albo napisz w prompcie `speckit-tasks` „include test tasks for every acceptance scenario”, a potem uruchom `speckit-analyze`.

**Converge nigdy się nie zbiega.** Objaw: każda runda dopisuje to samo znalezisko. Naprawa: zatrzymaj pętlę i uruchom `speckit-analyze`. Powracające znalezisko to prawie zawsze konflikt między `spec.md` a `plan.md`; popraw dokument za zgodą właściciela i dopiero wtedy implementuj ponownie.

**Agent zmienia specyfikację pod swój kod.** Objaw: PR z implementacją zmienia `spec.md`, a testy przechodzą. Naprawa: zablokuj zapis do `specs/` w sesjach implementacyjnych, wymagaj właściciela specyfikacji w `CODEOWNERS` i odrzuć PR.

**Zespół przestaje recenzować dokumenty.** Objaw: specyfikacje są zatwierdzane kilka minut po wygenerowaniu, a błędy prowadzą do wymagań, których nikt nie przeczytał. Nierecenzowana specyfikacja przesuwa halucynację wyżej w łańcuchu. Naprawa: zrób z zatwierdzenia specyfikacji przez product ownera i planu przez tech leada jawne sprawdzenia w PR i przed zatwierdzeniem użyj promptu krytycznej recenzji powyżej.

**Ceremonia zalewa drobną pracę.** Objaw: programiści pomijają Spec Kit przy wszystkim, co trwa krócej niż dzień, i proces zanika. Naprawa: opublikuj tabelę decyzyjną powyżej i puszczaj drobne zmiany przez rozszerzenie `bug` albo OpenSpec.

## Dokąd dalej ze Spec Kit

- [Spec-driven development](/pl/workflows/plan/spec-driven-development/) — Koncepcja bazowa: jak utrzymać spec.md jako źródło prawdy i wykrywać dryf po wdrożeniu funkcji.
- [Wykonywalne kryteria akceptacji](/pl/workflows/plan/acceptance-criteria/) — Zamień każdy scenariusz akceptacyjny ze spec.md w czerwony test przed implementacją.
- [Pakiet dowodów](/pl/workflows/ship/evidence-bundle/) — Kontrakt PR zasilany śladem specyfikacji, z testem CI, który odrzuca niekompletny pakiet.
- [OpenSpec](/pl/ecosystem/frameworks/openspec/) — Lżejsza alternatywa oparta na zmianach, dla istniejących baz kodu.
- [Porównanie frameworków agentowych](/pl/ecosystem/frameworks/) — Spec Kit obok Superpowers, BMAD, GSD i pozostałych, z kosztami kontekstu.
- [Łańcuch artefaktów](/pl/method/lifecycle/artifact-chain/) — Model „jeden plik na etap”, który realizuje Spec Kit, z szablonami, jeśli wolisz zwykły Markdown.
