Spezifikationen in CI linten mit einem Spezifikationslinter

Ein Spezifikationslinter ist ein Programm, das eine Spezifikation auf strukturelle Fehler prüft und mit einem Fehlercode endet, wenn es welche findet. Die kontinuierliche Integration (CI, continuous integration) ist eine automatische Prüfung bei jeder vorgeschlagenen Änderung. Kontinuierliche Integration und kontinuierliche Auslieferung (CI/CD, continuous integration and continuous delivery) ist die Pipeline, die diese Prüfung ausführt und eine bestandene Änderung auslieferbar hält. Spezifikationsgetriebene Entwicklung (SDD, spec-driven development) ist die Praxis, die Spezifikation vor dem Code zu schreiben und die Spezifikation als Quelle der Wahrheit zu behandeln. Ein Produktanforderungsdokument (PRD, product requirements document) ist die Prosa, die das Problem und den Umfang nennt. In SpecScore ist eine Anforderung (REQ) eine benannte Regel in einem Feature, und ein Akzeptanzkriterium (AC, acceptance criterion) ist eine optionale abstrakte Bedingung, die auf eine oder mehrere dieser Regeln zeigt. Die Prüfung ist ein Befehl der Kommandozeile (CLI, command-line interface), specscore spec lint, aus der CLI in specscore/specscore-cli (Apache-2.0). Easy Approach to Requirements Syntax (EARS) ist ein Satzmuster für eine Anforderung. Dieser Linter prüft Überschriften, Pflichtabschnitte und Verweise. Er benotet nicht das Englisch.

Zuletzt aktualisiert: 4. November 2026

Was das Linten einer Spezifikation bedeutet

Eine Spezifikation zu linten ist dieselbe Art von Prüfung wie Code zu linten. Ein deterministisches Programm liest die Dateien und meldet Regelverstöße. Es entscheidet nicht, ob das Produkt eine gute Idee ist, und es schreibt die Anforderung nicht in bessere Prosa um. Die Validatoren-Seite trennt diese Strukturprüfung von einer manuellen KI-Prüfung. specscore spec lint ist die Strukturprüfung.

Die Beschreibung des Befehls, in internal/cli/spec.go beim CLI-Tag v0.55.1 und beim Tag v0.39.1, den der Workflow dieses Repositories installiert, sagt, dass er den Spezifikationsbaum auf Verstöße gegen strukturelle Konventionen prüft. Ein sauberer Lauf gibt 0 violations found aus und endet mit 0. Ein Lauf, der Verstöße findet, gibt eine Zeile je Fund aus und endet mit 1. Dieser Exit-Code lässt einen CI-Job fehlschlagen. Ungültige Argumente enden mit 2. Eine fehlende specscore.yaml endet mit 3, und die Meldung fordert auf, specscore init auszuführen.

Was der Spezifikationslinter prüft

Die Regeln gehören zur CLI, nicht zu einem separaten Cloud-Dienst. Der erzeugte Katalog docs/lint-rules.md beim Tag v0.55.1 listet 183 Regeln. Der Workflow dieser Website installiert v0.39.1, eine ältere Version, sodass eine Regel, die nur in einem späteren Tag existiert, nicht das ist, was dieser Job ausführt. Die in diesem Abschnitt genannten Regeln sind in beiden Tags. Das voreingestellte --severity ist error. Eine Warnung wird nur ausgegeben, wenn du --severity warning oder info übergibst, und der voreingestellte Befehl schlägt bei einer Warnung nicht fehl. Der Katalog markiert dogfood-version-bump als Warnung, sodass der voreingestellte Befehl nicht fehlschlägt, wenn der Pin des Workflows hinter dem Binary zurückliegt.

Pflicht-Dateien und Pflichtabschnitte

Die Regel readme-exists (readme_exists.go) verlangt eine README.md in jedem Spezifikationsverzeichnis. Die Regel oq-section (oq_section.go) verlangt, dass das README eines Features einen Abschnitt ## Open Questions enthält. Eine veraltete Überschrift ## Outstanding Questions ist ein eigener Fund, und --fix schreibt diese Überschrift an Ort und Stelle um. Die Meldung im Beispiel unten, „Open Questions section not found“, ist der Fund aus einem Feature-README, dem der Abschnitt entfernt wurde.

Indexzeilen und Kindverzeichnisse

Die Regel index-entries (index_entries.go) prüft einen Feature-Index gegen die Kindverzeichnisse auf dem Datenträger. Ein Kind, das nicht aufgeführt ist, ist ein Verstoß, und eine Zeile, deren Link auf ein Kind zeigt, das nicht vorhanden ist, ist ein Verstoß. --fix kann die Phantomzeile löschen und die fehlende einfügen. Das ist die Integrität von Verzeichnis und Index. Es ist kein Durchsuchen jeder URL in der Prosa.

Form der Überschrift für Akzeptanzkriterien

Die Regel ac-heading-format (ac_heading.go) gilt für das README eines Features, eine Datei, deren Titel # Feature: ist. Eine Zeile, die wie eine Überschrift für ein Akzeptanzkriterium aussieht, muss genau ### AC: <id> sein, mit einem Leerzeichen nach dem Doppelpunkt und einer Id in kebab-case. Eine Überschrift der Form ### AC: <id> (verifies ...) wird ebenfalls akzeptiert. --fix repariert nur die Abstände. Eine Id mit Großbuchstaben oder Unterstrichen wird gemeldet und einer Person überlassen. Die Regel verlangt die Zeile **Requirements:** nicht, bewertet Wörter wie „graceful“ oder „fast“ nicht und warnt nicht, wenn die Prosa Given, When oder Then enthält. Wie man das Kriterium selbst schreibt, steht in wie man Akzeptanzkriterien schreibt.

Planverweise auf diese Kennungen

Bei einem Plan, der ein Quell-Feature nennt, liest plan_rules.go die Überschriften ### AC: im README dieses Features. Die Regel P-002 meldet einen Task-Wert **Verifies:**, der sich nicht zu <feature-slug>#ac:<ac-slug> für eine dieser Überschriften auflöst, eine leere Zeile **Verifies:**, eine fehlende oder nicht erkannte Quellzeile oder ein Quell-Feature, das sich nicht zu einem Feature-README auflöst. Die Regel P-001 meldet eine Überschrift, die keine Task abdeckt und die nicht unter ## Deferred AC Coverage aufgeführt ist. Pläne mit einer Idee als Quelle (**Source:** idea:<slug>) und Pläne mit **Source:** none sind ausgenommen, ebenso ein Plan in einem terminalen Dispositionsstatus. Der einzeilige Katalogtext für P-002 lautet „valid dependency references“; die Prüfung in dieser Datei ist die eben beschriebene Prüfung der AC-Referenzen.

Was ein bestandener Lint nicht ist

Derselbe Befehl entscheidet nicht, ob eine Anforderung das genannte Problem löst, ob ein Name sinnvoll ist oder ob zwei Features sich in der Bedeutung widersprechen. Die Validatoren-Seite führt das als außerhalb des CLI-Linters auf. Er prüft auch nicht die Schlüsselwörter der Szenarioschritte. specscore rehearse führt Szenariodateien aus. Der Workflow in diesem Repository führt specscore spec lint aus und ruft rehearse nicht auf. Der Katalog nennt weitere Familien — Ideen, Entscheidungen, Entitäten, Eigenschaften, Lektionen, Issues und die übrigen Planregeln — und jede Regel gilt für die Dateien, die ihr gehören. Der Katalog ist die Liste. Diese Seite wiederholt nicht alle 183 Beschreibungen.

specscore spec lint in CI ausführen

Der Befehl sucht vom Arbeitsverzeichnis aus aufwärts nach specscore.yaml. Ohne diese Datei endet er mit 3 und nennt specscore init. Ein CI-Job braucht daher die Konfigurationsdatei im Checkout. scripts/install.sh liest SPECSCORE_VERSION und verwendet latest, wenn die Variable nicht gesetzt ist. Lege einen Tag fest, wenn bei jedem Lauf dieselben Regeln gelten sollen.

Die Prüfung dieses Repositories ist dogfood.yml. Sie installiert die CLI mit SPECSCORE_VERSION auf v0.39.1 und führt dann specscore spec lint ohne zusätzliche Flags aus, bei Pull Requests und bei Pushes auf main. GitHub Actions lässt den Schritt fehlschlagen, wenn dieser Prozess mit einem Wert ungleich null endet. Der Auszug unten behält diese Installations- und Lint-Schritte. Die Datei setzt außerdem permissions: contents: read, eine Concurrency-Gruppe und einen Kommentar, warum der Pin nicht latest ist.

Installations- und Lint-Schritte aus 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

Fehlerbericht (specscore 0.55.0, dieselbe Zeilenform in 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)

Sauberer Bericht

0 violations found

Jeder Fund ist file:line [severity] rule: message. Die Zusammenfassung ist N violations found plus eine Zählung in Klammern, etwa (3 errors). Der Exit-Code ist der Prozessstatus, keine Zeile im Bericht. Die drei Zeilen oben stammen von specscore 0.55.0 bei einem Feature, dessen Abschnitt Open Questions entfernt worden war und dessen Index ein leeres Kindverzeichnis ausließ. Es ist derselbe Bericht, den die CLI-Seite zeigt. --format akzeptiert text (die Voreinstellung), json oder yaml. --rules und --ignore wählen Regeln aus und lassen sich nicht kombinieren. --fix schreibt die Funde um, die einen Fixer haben, einschließlich der Überschrift Outstanding Questions. Der Dogfood-Job übergibt --fix nicht.

Werkzeuge, die dieses Format nicht in CI linten

Eine Qualitätsprüfung von Anforderungen ist in dieser CLI die Strukturprüfung oben. Sie ist keine Bewertung der Prosa. Andere spezifikationsgetriebene Werkzeuge veröffentlichen andere Prüfungen. Die Absätze unten verwenden nur das, was die eigenen Seiten dieser Projekte sagen. Die Werkzeugrunde verzeichnet dieselben Seiten als gelesen am 30. Oktober 2026, außer der Dokumentationsstartseite von Spec Kit, die den 28. September 2026 druckt, und der Feature-Spezifikationsseite von Kiro, die den 4. August 2026 druckt.

GitHub Spec Kit ist ein Agenten-Workflow, der Markdown-Artefakte schreibt. Die Referenz für agentisches SDD beschreibt /speckit.analyze als einen Bericht über Inkonsistenzen zwischen Spezifikation, Plan und Tasks, ohne die Dateien zu bearbeiten. Man führt es im Agenten aus. Die Dokumentationsstartseite nennt außerdem Community-Erweiterungen, darunter eine namens CI Guard, die Compliance-Gates hinzufügen. Das ist kein Befehl, der ein SpecScore-Feature-README lintet.

OpenSpec veröffentlicht eine Strukturprüfung. openspec validate, dokumentiert in der CLI-Referenz, prüft die Change- und Spezifikationsstruktur von OpenSpec, endet ungleich null, wenn die Validierung fehlschlägt, und die Referenz enthält einen Shell-Schnipsel, den ein CI-Job ausführen kann. Diese Prüfung ist die Form von OpenSpec, nicht die Überschriften ### AC: oder ein SpecScore-Index.

Die Feature-Spezifikationsseite von Kiro beschreibt Analyze Requirements als eine Prüfung innerhalb von Kiro, vor dem Entwurf, die nach Inkonsistenzen, Mehrdeutigkeit, widersprüchlichen Einschränkungen und Lücken sucht. Es ist nicht der Befehl in dogfood.yml. Die Satzmuster, die Kiro schreibt, stehen in der EARS-Anforderungssyntax.

Das README von BMAD Method beschreibt die Artefakte der Methode und die Agenten-Workflows. Es dokumentiert keinen Befehl, der ein festes Spezifikationsschema in CI lintet. Das README von Task Master beschreibt, ein PRD mit task-master parse-prd in Tasks zu zerlegen. Es beschreibt keinen Linter für dieses PRD. Ein PRD kann weiterhin die Eingabe für ein SpecScore-Feature sein, und specscore spec lint ist dann das, was die Feature-Datei prüft.

FAQ

Was ist ein Spezifikationslinter?

Ein Spezifikationslinter liest Spezifikationsdateien und meldet strukturelle Verstöße. specscore spec lint ist dieser Befehl für einen SpecScore-Baum. Er endet mit 0, wenn er beim gewählten Schweregrad nichts findet, und mit 1, wenn er Verstöße findet.

Beurteilt der Spezifikationslinter die Qualität der Anforderungen an der Formulierung?

Nein. ac-heading-format prüft die Überschrift ### AC:. Es bewertet Wörter wie „graceful“ oder „fast“ nicht und warnt nicht, wenn ein Kriterium Given, When oder Then enthält. Die Formulierung ist eine Schreibaufgabe. Die Validatoren-Seite trennt diesen deterministischen Lint von der manuellen KI-Prüfung.

Wie linte ich Spezifikationen in CI?

Installiere die CLI mit SPECSCORE_VERSION auf einem Release-Tag und führe dann specscore spec lint aus. Der Checkout braucht eine specscore.yaml. dogfood.yml ist ein funktionierendes GitHub-Actions-Beispiel. Es pinnt v0.39.1.

Was gibt ein fehlgeschlagener Lauf aus?

Eine Zeile je Fund, file:line [severity] rule: message, und danach eine Zusammenfassung wie 3 violations found (3 errors). Der Prozess endet mit 1. Ein sauberer Baum gibt 0 violations found aus und endet mit 0.

Validieren andere Werkzeuge der spezifikationsgetriebenen Entwicklung Spezifikationen in CI/CD?

Das openspec validate von OpenSpec kann einen CI-Job fehlschlagen lassen, und es prüft die eigene Change-Struktur von OpenSpec. Das /speckit.analyze von Spec Kit läuft in der Agenten-Sitzung. Analyze Requirements von Kiro läuft innerhalb von Kiro. Die READMEs von BMAD Method und Task Master dokumentieren keinen Format-Linter für CI. Der Dogfood-Workflow von SpecScore führt specscore spec lint auf dem SpecScore-Baum aus.

Quellen

CLI-Verhalten geprüft am 4. November 2026 gegen die Tags v0.55.1 und v0.39.1 von specscore-cli. Die Seiten der Wettbewerber sind die unten verlinkten; die Werkzeugrunde verzeichnet sie als gelesen am 30. Oktober 2026, außer wo die Seite ihr eigenes Datum druckt.