Zarządzanie specyfikacjami: przechowywanie, wersjonowanie i przegląd specyfikacji jako kodu
Zarządzanie specyfikacjami to sposób, w jaki zespół przechowuje specyfikację oprogramowania, zapisuje każdą zmianę, przegląda tę zmianę i utrzymuje specyfikację aktualną. Zarządzanie specyfikacją to ta sama praca: specyfikacja jest dokumentem, który mówi, co oprogramowanie musi robić, a zarządzanie nią sprawia, że dokument pozostaje znajdowalny i wiarygodny. Zarządzanie specyfikacjami jako kodem oznacza, że te dokumenty są plikami w systemie kontroli wersji, więc zmiana specyfikacji jest commitem, który recenzent może porównać w diffie. Wersjonowanie specyfikacji to historia tych commitów razem ze statusem zapisanym w każdym dokumencie. Utrzymywanie specyfikacji zsynchronizowanych z kodem oznacza, że proponowana zmiana, która łamie strukturę specyfikacji, nie przechodzi tego samego automatycznego sprawdzenia, przez które przechodzi zmiana kodu. Rozwój sterowany specyfikacją (SDD, spec-driven development) to praktyka pisania specyfikacji przed kodem i traktowania specyfikacji jako źródła prawdy. Ciągła integracja (CI, continuous integration) to automatyczne sprawdzenie każdej proponowanej zmiany. Dokument wymagań produktu (PRD, product requirements document) to proza, która określa problem i zakres; szablon PRD w Markdown to jeden plik funkcji SpecScore w tym kształcie. Easy Approach to Requirements Syntax (EARS) to wzorzec zdania dla wymagania. W SpecScore wymaganie (REQ) to nazwana reguła wewnątrz funkcji, a kryterium akceptacji (AC, acceptance criterion) to opcjonalny abstrakcyjny warunek, który wskazuje jedną lub więcej z tych reguł. Sprawdzenie jest poleceniem interfejsu wiersza poleceń (CLI, command-line interface), specscore spec lint, opisanym w Lintowanie specyfikacji w CI linterem specyfikacji. Format jest w publicznym repozytorium specscore/specscore (CC BY 4.0). CLI jest w specscore/specscore-cli (Apache-2.0).
Ostatnia aktualizacja: 9 listopada 2026
Gdzie przechowywana jest specyfikacja
Zarządzanie specyfikacjami zaczyna się od miejsca, w którym mogą leżeć pliki. W tym repozytorium specyfikacja jest Markdownem pod spec/. README spec wymienia katalogi: features, plans, ideas, decisions i lessons. Funkcja to jeden katalog z README.md. Specyfikacja funkcji jest kontraktem tego pliku, a szablon PRD jest wypełnionym przykładem, który linter zaakceptował.
specscore spec lint nie zgaduje, które drzewo czytać. internal/cli/spec.go przy tagu v0.55.1, a ta sama funkcja przy tagu v0.39.1, idzie w górę od katalogu roboczego, aż znajdzie specscore.yaml. Komentarz przy tej funkcji mówi, że polecenie wymaga tego pliku, zwraca kod wyjścia 3, gdy go brakuje, i mówi, aby uruchomić specscore init. Workflow dogfood w tym repozytorium instaluje CLI v0.39.1, a potem uruchamia specscore spec lint, więc checkout, który jest lintowany, ma ten plik konfiguracji.
Obok plików funkcji leży indeks. Reguła feature-index-row-sync jest błędem w katalogu lint przy v0.39.1 i przy v0.55.1. Linia katalogu mówi, że wymaga, aby każdy wiersz indeksu funkcji zgadzał się ze swoim plikiem funkcji. To indeks pozostający w zgodzie z dokumentem, na który wskazuje. Nie jest to porównanie sformułowania wymagania z plikiem źródłowym.
Wersjonowanie specyfikacji
Wersjonowanie specyfikacji, dla plików zapisanych w commitach gita, to historia commitów tych plików. SpecScore nie dodaje drugiego numeru wersji do funkcji. Rewizja, na którą patrzy recenzent, to commit na gałęzi. Linia statusu w dokumencie mówi, na jakim etapie cyklu życia jest ta funkcja, a to inny fakt niż hash gita.
Specyfikacja funkcji w repozytorium sama ma **Status:** Stable. Wymaga linii **Status:** bezpośrednio po tytule, a wartość musi być jedną z Draft, In Review, Approved, Implementing, Stable, Amending, Rejected lub Deprecated. Reguła status-mirror, w obu katalogach nazwanych wyżej, wymaga, aby status: we frontmatter artefaktu, który ma status, zgadzał się z tą linią treści, i zabrania status: w typie, który nie ma statusu. Zgodność dwóch kopii nie jest tym samym co odrzucenie słowa spoza ośmiu wartości. Żadna z tych linii katalogu nie opisuje reguły, która odrzuca status funkcji spoza tego zbioru, więc ta strona nie twierdzi, że taka reguła istnieje.
Plany używają innego zbioru. Reguła P-006, w obu katalogach, wymaga, aby **Status:** w treści planu w jednym pliku był jednym z Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded lub Deprecated. Reguła idea-status-values odrzuca status pomysłu spoza zbioru, który ta reguła dopuszcza. Katalog jest listą. Ta strona nie powtarza słów pomysłu.
Specyfikacja planu opisuje też opcjonalną tabelę ## Snapshots z kolumnami Date, Git Hash, Action i Comment. Mówi, że każda migawka odwołuje się do hasha commita gita stanu planu w tamtej chwili. Dwa katalogi lint sprawdzone na potrzeby tej strony nie nazywają reguły, która rozwiązuje ten hash, więc ta strona nie twierdzi, że linter sprawdza, czy commit istnieje. Hash jest wskaźnikiem, za którym osoba może pójść w git. Opublikowana specyfikacja planu jest stroną formatu tego dokumentu.
Przegląd specyfikacji
Przegląd specyfikacji w Markdown to pull request, który ją zmienia. dogfood.yml uruchamia się przy pull_request i przy pushu do main. Job robi checkout repozytorium, instaluje CLI z SPECSCORE_VERSION ustawioną na v0.39.1 i uruchamia specscore spec lint bez dodatkowych flag. GitHub Actions oznacza krok jako nieudany, gdy ten proces kończy się kodem innym niż zero. Uprawnienia workflow to contents: read.
Status funkcji In Review oznacza, że funkcja jest przedstawiona do przeglądu. Zapisanie tego słowa jest edycją pliku Markdown. Pull request jest miejscem, w którym osoba czyta diff. status-mirror sprawdza, że frontmatter i treść nazywają ten sam status. Nie zapisuje, że recenzent zgodził się z prozą. Strona walidatorów oddziela to sprawdzenie strukturalne od lektury, którą osoba nadal musi wykonać. Omówienie reguła po regule tego, co zgłasza specscore spec lint, jest w Lintowanie specyfikacji w CI linterem specyfikacji.
Utrzymywanie specyfikacji zsynchronizowanych z kodem
Utrzymywanie specyfikacji zsynchronizowanych z kodem, na tej witrynie, oznacza, że specyfikacja jest w repozytorium razem z projektem, a CI uznaje pull request za nieudany, gdy drzewo specyfikacji narusza format. Pull request może zmienić plik funkcji i kod w tym samym diffie. Reguła feature-index-row-sync utrzymuje wiersz indeksu w zgodzie z plikiem funkcji, który nazywa. Nie czyta pliku źródłowego i nie rozstrzyga, czy kod realizuje wymaganie.
Poniższy fragment to kroki instalacji i lintu z dogfood.yml. Plik workflow ustawia też uprawnienia, grupę współbieżności i komentarz, dlaczego pin nie jest latest. Te linie są tu pominięte. Polecenia są tymi, które uruchamia ten plik.
name: Dogfood lint
on:
push:
branches: [main]
pull_request:
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- name: Install specscore CLI (pinned)
env:
SPECSCORE_VERSION: v0.39.1
run: |
curl -fsSL https://specscore.md/install/get-cli | \
SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
specscore --version
- name: Lint spec tree
run: specscore spec lint
Komentarz w tym pliku mówi, że pływający pin latest zmienia bramkę pod repozytorium: pull request i gałąź main, na którą on jest skierowany, mogą widzieć różne reguły. Pin to v0.39.1. Job nie przekazuje --fix. Czysty przebieg i przebieg kończący się niepowodzeniem, łącznie z linią file:line [severity] rule: message, są pokazane w Lintowanie specyfikacji w CI linterem specyfikacji.
Zdanie w specyfikacji, które już nie opisuje kodu, nie jest jednym z tych znalezisk. specscore spec lint waliduje strukturę: wymagane pliki i sekcje, wiersze indeksu, kształt nagłówków i odwołania, które reguły nazywają. Nie punktuje, czy implementacja zgadza się z wymaganiem. Ta granica jest sensem strony walidatorów. Utrzymanie prawdziwości prozy nadal jest przeglądem diffa.
Jak inne narzędzia rozwoju sterowanego specyfikacją sprawdzają specyfikację
Akapity poniżej korzystają ze stron pobranych 9 listopada 2026. Opisują własne sprawdzenia tych narzędzi. Nie mówią, ile produktów istnieje, i nie szeregują rynku. Narzędzia rozwoju sterowanego specyfikacją to dłuższe porównanie.
GitHub Spec Kit — dokumentacja agentowego SDD (/speckit.analyze) opisuje /speckit.analyze jako sprawdzenie tylko do odczytu obejmujące spec.md, plan.md i tasks.md. Zgłasza konflikty, luki i niejednoznaczności, nigdy nie edytuje plików i uruchamia się je w agencie przed implementacją. Lista poleceń na tej samej stronie nie opisuje joba CI, który uruchamia specscore spec lint na drzewie SpecScore.
OpenSpec przechowuje zmianę jako katalog bezpośrednio pod openspec/changes/. openspec validate sprawdza zmiany i specyfikacje pod kątem problemów strukturalnych. Dokumentacja mówi, że kod wyjścia 0 oznacza, że każdy walidowany element przeszedł, a kod wyjścia 1 oznacza, że element nie przeszedł, żądanie raportu jest nieprawidłowe, konfiguracji nie można odczytać albo przebieg się nie powiódł. To sprawdzenie jest kształtem OpenSpec, łącznie z blokami wymagania i scenariusza, a nie nagłówkiem SpecScore ### AC:. Przy innym poleceniu, openspec status, ta sama dokumentacja mówi, że partia, która nie może wczytać jednej zmiany, i tak kończy się kodem 1, “so CI doesn’t accept an incomplete report as successful.” To zdanie dotyczy openspec status, a nie openspec validate.
Najczęstsze pytania
Czym jest zarządzanie specyfikacjami?
Zarządzanie specyfikacjami to przechowywanie specyfikacji oprogramowania, zapisywanie każdej zmiany, przegląd tej zmiany i utrzymywanie specyfikacji aktualnej. W SpecScore pliki są Markdownem w repozytorium git, a specscore spec lint jest sprawdzeniem strukturalnym, które job CI może oblać.
Czym jest zarządzanie specyfikacją?
Zarządzanie specyfikacją to ta sama praktyka. Specyfikacja jest dokumentem, który mówi, co oprogramowanie musi robić. Zarządzanie nią oznacza, że dokument ma znane miejsce, historię, przegląd i sprawdzenie, że jego struktura nadal zgadza się z formatem.
Jak działa zarządzanie specyfikacjami jako kodem?
Specyfikacja to drzewo plików Markdown pod spec/ oraz specscore.yaml w korzeniu repozytorium. Zmiana jest commitem. Pull request przegląda diff. dogfood.yml uruchamia specscore spec lint przy tym pull requeście.
Jak działa wersjonowanie specyfikacji?
Historia gita jest historią wersji plików. Funkcja niesie też **Status:** z jedną z ośmiu wartości, których wymaga specyfikacja funkcji. Plan może zapisać wiersz ## Snapshots, którego Git Hash jest commitem stanu planu. Katalogi lintera cytowane tutaj nie opisują reguły, która rozwiązuje ten hash.
Jak utrzymywać specyfikacje zsynchronizowane z kodem?
Umieść specyfikację w repozytorium i uznaj pull request za nieudany, gdy specscore spec lint zgłasza naruszenie strukturalne, w tym wiersz indeksu, który nie zgadza się ze swoim plikiem funkcji. Polecenie nie rozstrzyga, czy kod realizuje wymaganie. Zdanie, które oddaliło się od kodu, nadal wymaga, aby osoba przeczytała diff.
Źródła
Pliki CLI i katalogi lint czytane 9 listopada 2026 przy tagach specscore-cli v0.39.1 (wersji, którą instaluje dogfood.yml) i v0.55.1. Wymagania funkcji i planu to pliki powiązane poniżej w specscore/specscore. Strony konkurentów pobrano tego samego dnia.
- specscore/specscore — spec/README.md
- specscore/specscore — wartości statusu funkcji
- specscore/specscore — migawki planu
- specscore/specscore
- specscore/specscore — licencja CC BY 4.0
- specscore/specscore-cli
- specscore-cli — licencja Apache-2.0
- specscore-cli v0.39.1 — internal/cli/spec.go
- specscore-cli v0.55.1 — internal/cli/spec.go
- specscore-cli v0.39.1 — katalog reguł lint
- specscore-cli v0.55.1 — katalog reguł lint
- specscore/specscore — dogfood.yml (CLI v0.39.1)
- Co waliduje SpecScore
- Lintowanie specyfikacji w CI linterem specyfikacji
- Składnia wymagań EARS wyjaśniona, z przykładami
- Jak pisać kryteria akceptacji, które agent AI może zweryfikować
- Szablon PRD w Markdown do programowania z AI
- Specyfikacja funkcji
- Specyfikacja planu
- GitHub Spec Kit — dokumentacja agentowego SDD (/speckit.analyze)
- Dokumentacja CLI OpenSpec — openspec validate i openspec status
- Fission-AI/OpenSpec
- Narzędzia rozwoju sterowanego specyfikacją
Powiązane
- Lintowanie specyfikacji w CI linterem specyfikacji
- Szablon PRD w Markdown do programowania z AI
- Jak pisać kryteria akceptacji, które agent AI może zweryfikować
- Składnia wymagań EARS wyjaśniona, z przykładami
- Rozwój sterowany specyfikacją
- Narzędzia rozwoju sterowanego specyfikacją
- Specyfikacja funkcji
- Specyfikacja planu
- CLI
- Co waliduje SpecScore