# Lintowanie specyfikacji w CI linterem specyfikacji Canonical: https://specscore.md/pl/articles/lint-specs-in-ci/ Ostatnia aktualizacja: 4 listopada 2026 Linter specyfikacji to program, który sprawdza specyfikację pod kątem błędów struktury i kończy działanie kodem niepowodzenia, gdy je znajdzie. [Ciągła integracja](https://specscore.md/pl/validators/) (CI, continuous integration) to automatyczne sprawdzenie przy każdej proponowanej zmianie. Ciągła integracja i ciągłe dostarczanie (CI/CD, continuous integration and continuous delivery) to potok, który uruchamia to sprawdzenie i utrzymuje przechodzącą zmianę jako gotową do wydania. [Rozwój sterowany specyfikacją](https://specscore.md/pl/spec-driven-development/) (SDD, spec-driven development) to praktyka pisania specyfikacji przed kodem i traktowania specyfikacji jako źródła prawdy. Dokument wymagań produktu (PRD, product requirements document) to proza, która określa problem i zakres. W [SpecScore](https://specscore.md/) 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ń](https://specscore.md/pl/cli/) (CLI, command-line interface), `specscore spec lint`, z CLI w [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)). [Easy Approach to Requirements Syntax](https://specscore.md/pl/articles/ears-requirements/) (EARS) to wzorzec zdania dla wymagania. Ten linter sprawdza nagłówki, wymagane sekcje i odwołania. Nie ocenia angielskiego. ## Co oznacza lintowanie specyfikacji Lintowanie specyfikacji to ten sam rodzaj sprawdzenia co lintowanie kodu. Deterministyczny program czyta pliki i zgłasza naruszenia reguł. Nie rozstrzyga, czy produkt jest dobrym pomysłem, i nie przepisuje wymagania na lepszą prozę. [Strona walidatorów](https://specscore.md/pl/validators/) oddziela to sprawdzenie strukturalne od ręcznego przeglądu z AI. `specscore spec lint` jest tym sprawdzeniem strukturalnym. Opis polecenia, w [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) przy tagu CLI v0.55.1 i przy tagu v0.39.1, który instaluje workflow tego repozytorium, mówi, że waliduje drzewo specyfikacji pod kątem naruszeń konwencji strukturalnych. Czysty przebieg wypisuje `0 violations found` i kończy się kodem 0. Przebieg, który znajduje naruszenia, wypisuje jedną linię na znalezisko i kończy się kodem 1. Ten kod wyjścia powoduje niepowodzenie joba CI. Nieprawidłowe argumenty kończą się kodem 2. Brak `specscore.yaml` kończy się kodem 3, a komunikat każe uruchomić `specscore init`. ## Co sprawdza linter specyfikacji Reguły należą do CLI, nie do osobnej usługi w chmurze. Wygenerowany katalog [docs/lint-rules.md](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md) przy tagu v0.55.1 wymienia 183 reguły. Workflow tej witryny instaluje v0.39.1, starsze wydanie, więc reguła, która istnieje tylko w późniejszym tagu, nie jest tym, co uruchamia ten job. Reguły nazwane w tej sekcji są w obu tagach. Domyślne `--severity` to `error`. Ostrzeżenie jest wypisywane tylko wtedy, gdy podasz `--severity warning` albo `info`, a domyślne polecenie nie kończy się błędem z powodu ostrzeżenia. Katalog oznacza `dogfood-version-bump` jako ostrzeżenie, więc domyślne polecenie nie kończy się błędem, gdy pin workflow jest za binarką. ### Wymagane pliki i sekcje Reguła `readme-exists` ([readme_exists.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/readme_exists.go)) wymaga pliku `README.md` w każdym katalogu specyfikacji. Reguła `oq-section` ([oq_section.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/oq_section.go)) wymaga, aby README funkcji zawierało sekcję `## Open Questions`. Odziedziczony nagłówek `## Outstanding Questions` jest osobnym znaleziskiem, a `--fix` przepisuje ten nagłówek w miejscu. Komunikat w przykładzie poniżej, „Open Questions section not found”, to znalezisko z README funkcji, z którego usunięto sekcję. ### Wiersze indeksu i katalogi potomne Reguła `index-entries` ([index_entries.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/index_entries.go)) sprawdza indeks funkcji względem katalogów potomnych na dysku. Potomek, którego nie ma na liście, jest naruszeniem, i wiersz, którego link wskazuje potomka, którego nie ma, jest naruszeniem. `--fix` może usunąć wiersz widmo i wstawić brakujący. To integralność katalogu i indeksu. To nie jest przejście po każdym URL w prozie. ### Kształt nagłówka kryterium akceptacji Reguła `ac-heading-format` ([ac_heading.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/ac_heading.go)) dotyczy README funkcji, pliku, którego tytuł to `# Feature:`. Linia, która wygląda jak nagłówek kryterium akceptacji, musi mieć dokładnie postać `### AC: ` z jedną spacją po dwukropku i identyfikatorem w kebab-case. Akceptowany jest też nagłówek w postaci `### AC: (verifies ...)`. `--fix` poprawia tylko odstępy. Identyfikator z wielkimi literami albo podkreśleniami jest zgłaszany i zostawiany osobie. Reguła nie wymaga linii `**Requirements:**`, nie punktuje słów takich jak „graceful” albo „fast” i nie ostrzega, gdy proza zawiera Given, When albo Then. Jak napisać samo kryterium, jest w [jak pisać kryteria akceptacji](https://specscore.md/pl/articles/acceptance-criteria/). ### Odwołania planu do tych identyfikatorów W planie, który nazywa funkcję źródłową, [plan_rules.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/plan_rules.go) czyta nagłówki `### AC:` w README tej funkcji. Reguła `P-002` zgłasza wartość `**Verifies:**` zadania, która nie rozwiązuje się do `#ac:` dla jednego z tych nagłówków, pustą linię `**Verifies:**`, brakującą albo nierozpoznaną linię źródła, albo funkcję źródłową, która nie rozwiązuje się do README funkcji. Reguła `P-001` zgłasza nagłówek, którego nie pokrywa żadne zadanie i który nie jest wymieniony pod `## Deferred AC Coverage`. Plany o źródle w pomyśle (`**Source:** idea:`) i plany z `**Source:** none` są wyłączone, tak samo jak plan w terminalnym statusie dyspozycji. Jednoliniowy tekst katalogu dla `P-002` mówi „valid dependency references”; sprawdzanie w tym pliku to właśnie opisane sprawdzanie odwołań AC. ### Czym nie jest zaliczony lint To samo polecenie nie rozstrzyga, czy wymaganie rozwiązuje podany problem, czy nazwa ma sens, ani czy dwie funkcje przeczą sobie w znaczeniu. Strona walidatorów wymienia to jako leżące poza linterem CLI. Nie sprawdza też słów kluczowych kroków scenariusza. `specscore rehearse` uruchamia pliki scenariuszy. Workflow w tym repozytorium uruchamia `specscore spec lint` i nie wywołuje rehearse. Katalog nazywa dalsze rodziny — pomysły, decyzje, encje, właściwości, lekcje, issues i resztę reguł planu — a każda reguła stosuje się do plików, do których należy. Katalog jest listą. Ta strona nie powtarza wszystkich 183 opisów. ## Uruchamianie specscore spec lint w CI Polecenie szuka w górę od katalogu roboczego pliku `specscore.yaml`. Bez tego pliku kończy się kodem 3 i wskazuje `specscore init`. Job CI potrzebuje więc pliku konfiguracji w checkoutcie. [scripts/install.sh](https://github.com/specscore/specscore-cli/blob/v0.55.1/scripts/install.sh) czyta `SPECSCORE_VERSION` i przyjmuje `latest`, gdy zmienna nie jest ustawiona. Przypnij tag, jeśli przy każdym uruchomieniu mają obowiązywać te same reguły. Sprawdzeniem tego repozytorium jest [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml). Instaluje CLI z `SPECSCORE_VERSION` ustawioną na `v0.39.1`, a potem uruchamia `specscore spec lint` bez dodatkowych flag, przy pull requestach i przy pushach na main. GitHub Actions oznacza krok jako nieudany, gdy ten proces kończy się kodem innym niż zero. Fragment poniżej zachowuje te kroki instalacji i lintu. Plik ustawia też `permissions: contents: read`, grupę współbieżności i komentarz, dlaczego pin nie jest `latest`. ### Kroki instalacji i lintu z dogfood.yml ```yaml 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 ``` ### Raport niepowodzenia (specscore 0.55.0, ten sam kształt linii w v0.39.1) ```text features/apply-discount/README.md:0 [error] oq-section: Open Questions section not found features/apply-discount/README.md:0 [error] index-entries: Child directory not listed in index: refunds features/apply-discount/refunds:0 [error] readme-exists: README.md not found 3 violations found (3 errors) ``` ### Czysty raport ```text 0 violations found ``` Każde znalezisko ma postać `file:line [severity] rule: message`. Podsumowanie to `N violations found` plus liczba w nawiasie, na przykład `(3 errors)`. Kod wyjścia to status procesu, nie linia w raporcie. Trzy linie powyżej zebrano ze specscore 0.55.0 na funkcji, której sekcję Open Questions usunięto i której indeks pominął pusty katalog potomny. To ten sam raport, który pokazuje strona CLI. `--format` przyjmuje `text` (domyślnie), `json` albo `yaml`. `--rules` i `--ignore` wybierają reguły i nie mogą być łączone. `--fix` przepisuje znaleziska, które mają korektor, w tym nagłówek Outstanding Questions. Job dogfood nie przekazuje `--fix`. ## Narzędzia, które nie lintują tego formatu w CI Kontrola jakości wymagań w tej CLI to sprawdzenie strukturalne opisane wyżej. To nie jest ocena prozy. Inne narzędzia rozwoju sterowanego specyfikacją publikują inne sprawdzenia. Akapity poniżej używają tylko tego, co mówią własne strony tych projektów. [Przegląd narzędzi](https://specscore.md/pl/spec-driven-development/tools/) zapisuje te same strony jako czytane 30 października 2026, poza stroną główną dokumentacji Spec Kit, która drukuje 28 września 2026, i stroną specyfikacji funkcji Kiro, która drukuje 4 sierpnia 2026. [GitHub Spec Kit](https://github.github.io/spec-kit/) to workflow agenta, który zapisuje artefakty Markdown. [Dokumentacja agentowego SDD](https://github.github.io/spec-kit/reference/agentic-sdd.html) opisuje `/speckit.analyze` jako raport niespójności między specyfikacją, planem i zadaniami, bez edytowania plików. Uruchamia się go w agencie. Strona główna dokumentacji wymienia też rozszerzenia społeczności, w tym jedno o nazwie CI Guard, które dodają bramki zgodności. To nie jest polecenie, które lintuje README funkcji SpecScore. [OpenSpec](https://github.com/Fission-AI/OpenSpec) publikuje sprawdzenie strukturalne. `openspec validate`, opisane w [dokumentacji CLI](https://openspec.dev/docs/cli), sprawdza strukturę zmiany i specyfikacji OpenSpec, kończy się kodem innym niż zero, gdy walidacja się nie powiedzie, a dokumentacja zawiera fragment powłoki, który może uruchomić job CI. To sprawdzenie jest kształtem OpenSpec, nie nagłówkami `### AC:` ani indeksem SpecScore. [Strona specyfikacji funkcji Kiro](https://kiro.dev/docs/specs/feature-specs/) opisuje Analyze Requirements jako sprawdzenie wewnątrz Kiro, przed projektem, które szuka niespójności, niejednoznaczności, sprzecznych ograniczeń i luk. To nie jest polecenie z `dogfood.yml`. Wzorce zdań, które zapisuje Kiro, są w [składni wymagań EARS](https://specscore.md/pl/articles/ears-requirements/). README [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) opisuje artefakty metody i workflow agentów. Nie dokumentuje polecenia, które lintuje stały schemat specyfikacji w CI. README [Task Master](https://github.com/eyaltoledano/claude-task-master) opisuje przekształcenie PRD w zadania za pomocą `task-master parse-prd`. Nie opisuje lintera dla tego PRD. PRD nadal może być wejściem funkcji SpecScore, a `specscore spec lint` jest tym, co wtedy sprawdza plik funkcji. ## Najczęstsze pytania ### Czym jest linter specyfikacji? Linter specyfikacji czyta pliki specyfikacji i zgłasza naruszenia strukturalne. `specscore spec lint` jest tym poleceniem dla drzewa SpecScore. Kończy się kodem 0, gdy przy wybranym poziomie ważności nic nie znajduje, i kodem 1, gdy znajduje naruszenia. ### Czy linter specyfikacji ocenia jakość wymagań po sformułowaniu? Nie. `ac-heading-format` sprawdza nagłówek `### AC:`. Nie punktuje słów takich jak „graceful” albo „fast” i nie ostrzega, gdy kryterium zawiera Given, When albo Then. Sformułowanie to zadanie pisarskie. Strona walidatorów oddziela ten deterministyczny lint od ręcznego przeglądu z AI. ### Jak lintować specyfikacje w CI? Zainstaluj CLI z `SPECSCORE_VERSION` ustawioną na tag wydania, a potem uruchom `specscore spec lint`. Checkout potrzebuje pliku `specscore.yaml`. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) to działający przykład GitHub Actions. Przypina v0.39.1. ### Co wypisuje nieudany przebieg? Jedną linię na znalezisko, `file:line [severity] rule: message`, a potem podsumowanie takie jak `3 violations found (3 errors)`. Proces kończy się kodem 1. Czyste drzewo wypisuje `0 violations found` i kończy się kodem 0. ### Czy inne narzędzia rozwoju sterowanego specyfikacją walidują specyfikacje w CI/CD? Polecenie `openspec validate` OpenSpec może spowodować niepowodzenie joba CI i sprawdza własną strukturę zmiany OpenSpec. Polecenie `/speckit.analyze` Spec Kit działa w sesji agenta. Analyze Requirements Kiro działa wewnątrz Kiro. README BMAD Method i Task Master nie dokumentują lintera formatu dla CI. Workflow dogfood SpecScore uruchamia `specscore spec lint` na drzewie SpecScore. ## Źródła Zachowanie CLI sprawdzone 4 listopada 2026 względem tagów v0.55.1 i v0.39.1 specscore-cli. Strony konkurentów to te powiązane poniżej; przegląd narzędzi zapisuje je jako czytane 30 października 2026, poza miejscami, gdzie strona drukuje własną datę. - [specscore/specscore-cli](https://github.com/specscore/specscore-cli) - [specscore-cli — licencja Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE) - [specscore/specscore](https://github.com/specscore/specscore) - [specscore-cli v0.55.1 — katalog reguł lint (183 reguły)](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md) - [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) - [specscore-cli — install.sh (SPECSCORE_VERSION)](https://github.com/specscore/specscore-cli/blob/v0.55.1/scripts/install.sh) - [specscore-cli v0.55.1 — readme-exists](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/readme_exists.go) - [specscore-cli v0.55.1 — oq-section](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/oq_section.go) - [specscore-cli v0.55.1 — index-entries](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/index_entries.go) - [specscore-cli v0.55.1 — ac-heading-format](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/ac_heading.go) - [specscore-cli v0.55.1 — reguły planu P-001 i P-002](https://github.com/specscore/specscore-cli/blob/v0.55.1/pkg/lint/plan_rules.go) - [Co waliduje SpecScore](https://specscore.md/pl/validators/) - [Jak pisać kryteria akceptacji, które agent AI może zweryfikować](https://specscore.md/pl/articles/acceptance-criteria/) - [Składnia wymagań EARS wyjaśniona, z przykładami](https://specscore.md/pl/articles/ears-requirements/) - [Dokumentacja GitHub Spec Kit (data strony 28 września 2026)](https://github.github.io/spec-kit/) - [GitHub Spec Kit — dokumentacja agentowego SDD (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html) - [Dokumentacja CLI OpenSpec — openspec validate](https://openspec.dev/docs/cli) - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) - [Kiro — specyfikacje funkcji (zaktualizowano 4 sierpnia 2026)](https://kiro.dev/docs/specs/feature-specs/) - [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) - [eyaltoledano/claude-task-master](https://github.com/eyaltoledano/claude-task-master) - [Narzędzia rozwoju sterowanego specyfikacją](https://specscore.md/pl/spec-driven-development/tools/) ## Powiązane - [Rozwój sterowany specyfikacją z Claude Code i Cursor](https://specscore.md/pl/articles/claude-code-specs/) - [Szablon PRD w Markdown do programowania z AI](https://specscore.md/pl/articles/feature-spec-template/) - [Jak pisać kryteria akceptacji, które agent AI może zweryfikować](https://specscore.md/pl/articles/acceptance-criteria/) - [Składnia wymagań EARS wyjaśniona, z przykładami](https://specscore.md/pl/articles/ears-requirements/) - [Co waliduje SpecScore](https://specscore.md/pl/validators/) - [CLI](https://specscore.md/pl/cli/) - [Zainstaluj CLI](https://specscore.md/pl/cli/install/) - [Rozwój sterowany specyfikacją](https://specscore.md/pl/spec-driven-development/) - [Narzędzia rozwoju sterowanego specyfikacją](https://specscore.md/pl/spec-driven-development/tools/) - [Specyfikacja funkcji](https://specscore.md/feature-specification) - [Specyfikacja kryteriów akceptacji](https://specscore.md/acceptance-criteria-specification)