GitHub Spec Kit: spec-driven development w praktyce

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, 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 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. 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 i Gita. Pakiet w PyPI to specify-cli, a instalowane polecenie to specify.

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

   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

   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

   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

   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:

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

• Folder.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
• Folder.specify/

  • memory/constitution.md szablon, dopóki nie uruchomisz etapu constitution
  • Foldertemplates/ szablony spec, plan, tasks, checklist i constitution

    • …
  • Folderscripts/bash/ create-new-feature.sh, setup-plan.sh i skrypty pomocnicze

    • …
  • workflows/speckit/workflow.yml
  • Folderintegrations/ 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 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.

   /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

   /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):

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

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

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

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

$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

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

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 dla tej funkcji. Recenzent zaczyna od delty specyfikacji i tabeli wymaganie–test, jak opisuje recenzja pull requestu agenta, 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, a CI go uruchamia. Trzymaj specs/ poza zakresem zapisu agenta implementującego dzięki uprawnieniom i sandboksom oraz regule w CODEOWNERS, żeby agent nie mógł przepchnąć testu, zmieniając specyfikację.

Prompt do skopiowania: krytyczna recenzja spec.md przed planem

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>/:

/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. 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, 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 Koncepcja bazowa: jak utrzymać spec.md jako źródło prawdy i wykrywać dryf po wdrożeniu funkcji.

Wykonywalne kryteria akceptacji Zamień każdy scenariusz akceptacyjny ze spec.md w czerwony test przed implementacją.

Pakiet dowodów Kontrakt PR zasilany śladem specyfikacji, z testem CI, który odrzuca niekompletny pakiet.

OpenSpec Lżejsza alternatywa oparta na zmianach, dla istniejących baz kodu.

Porównanie frameworków agentowych Spec Kit obok Superpowers, BMAD, GSD i pozostałych, z kosztami kontekstu.

Łańcuch artefaktów Model „jeden plik na etap”, który realizuje Spec Kit, z szablonami, jeśli wolisz zwykły Markdown.