Lintowanie specyfikacji w CI linterem specyfikacji

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 (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ą (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 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, z CLI w specscore/specscore-cli (Apache-2.0). Easy Approach to Requirements Syntax (EARS) to wzorzec zdania dla wymagania. Ten linter sprawdza nagłówki, wymagane sekcje i odwołania. Nie ocenia angielskiego.

Ostatnia aktualizacja: 4 listopada 2026

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 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 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 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) wymaga pliku README.md w każdym katalogu specyfikacji. Reguła oq-section (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) 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) 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: <id> z jedną spacją po dwukropku i identyfikatorem w kebab-case. Akceptowany jest też nagłówek w postaci ### AC: <id> (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.

Odwołania planu do tych identyfikatorów

W planie, który nazywa funkcję źródłową, 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 <feature-slug>#ac:<ac-slug> 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:<slug>) 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 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. 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

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)

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

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 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 to workflow agenta, który zapisuje artefakty Markdown. Dokumentacja agentowego SDD 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 publikuje sprawdzenie strukturalne. openspec validate, opisane w dokumentacji 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 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.

README BMAD Method opisuje artefakty metody i workflow agentów. Nie dokumentuje polecenia, które lintuje stały schemat specyfikacji w CI. README 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 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ę.