Artikel

Spec-Management: Spezifikationen speichern, versionieren und als Code reviewen

Spec-Management ist die Art, wie ein Team eine Softwarespezifikation speichert, jede Änderung festhält, diese Änderung prüft und die Spezifikation aktuell hält. Spezifikationsmanagement ist dieselbe Arbeit: eine Spezifikation ist das Dokument, das sagt, was die Software tun muss, und sie zu verwalten hält das Dokument auffindbar und vertrauenswürdig. Spezifikationen als Code zu verwalten bedeutet, dass diese Dokumente Dateien in der Versionsverwaltung sind, sodass eine Änderung an einer Spezifikation ein Commit ist, dessen Diff ein Reviewer lesen kann. Die Spec-Versionierung ist die Historie dieser Commits, zusammen mit dem Status, der auf jedem Dokument steht. Spezifikationen mit dem Code synchron zu halten bedeutet, dass eine vorgeschlagene Änderung, die die Struktur der Spezifikation bricht, dieselbe automatische Prüfung nicht besteht, die die Codeänderung durchläuft. Die 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. Die kontinuierliche Integration (CI, continuous integration) ist eine automatische Prüfung bei jeder vorgeschlagenen Änderung. Ein Produktanforderungsdokument (PRD, product requirements document) ist die Prosa, die das Problem und den Umfang nennt; die PRD-Vorlage in Markdown ist eine SpecScore-Feature-Datei in dieser Form. Easy Approach to Requirements Syntax (EARS) ist ein Satzmuster für eine Anforderung. 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, dokumentiert in Spezifikationen in CI linten. Das Format liegt im öffentlichen Repository specscore/specscore (CC BY 4.0). Die CLI liegt in specscore/specscore-cli (Apache-2.0).

Zuletzt aktualisiert: 9. November 2026

Wo die Spezifikation gespeichert wird

Spec-Management beginnt bei einem Ort, an dem die Dateien leben können. In diesem Repository ist die Spezifikation Markdown unter spec/. Das Spec-README listet die Verzeichnisse: features, plans, ideas, decisions und lessons. Ein Feature ist ein Verzeichnis mit einer README.md. Die Feature-Spezifikation ist der Vertrag für diese Datei, und die PRD-Vorlage ist ein ausgefülltes Beispiel, das ein Linter akzeptiert hat.

specscore spec lint rät nicht, welchen Baum es lesen soll. internal/cli/spec.go beim Tag v0.55.1, und dieselbe Funktion beim Tag v0.39.1, geht vom Arbeitsverzeichnis aufwärts, bis sie specscore.yaml findet. Der Kommentar zu dieser Funktion sagt, dass der Befehl die Datei verlangt, den Exit-Code 3 zurückgibt, wenn sie fehlt, und dir sagt, specscore init auszuführen. Der Dogfood-Workflow dieses Repositorys installiert die CLI v0.39.1 und führt dann specscore spec lint aus, sodass der Checkout, den er lintet, diese Konfigurationsdatei hat.

Ein Index steht neben den Feature-Dateien. Die Regel feature-index-row-sync ist ein Fehler im Lint-Katalog von v0.39.1 und von v0.55.1. Die Katalogzeile sagt, dass sie verlangt, dass jede Feature-Indexzeile zu ihrer Feature-Datei passt. Das ist der Index, der mit dem Dokument ausgerichtet bleibt, auf das er zeigt. Es ist kein Vergleich des Wortlauts der Anforderung mit einer Quelldatei.

Spec-Versionierung

Die Spec-Versionierung von Dateien, die in git committet sind, ist die Commit-Historie dieser Dateien. SpecScore fügt einem Feature keine zweite Versionsnummer hinzu. Die Revision, die ein Reviewer ansieht, ist der Commit auf dem Branch. Die Statuszeile auf dem Dokument sagt, wo dieses Feature in seinem Lebenszyklus steht, und das ist eine andere Tatsache als der Git-Hash.

Die Feature-Spezifikation im Repository ist selbst **Status:** Stable. Sie verlangt eine Zeile **Status:** unmittelbar nach dem Titel, und der Wert muss einer von Draft, In Review, Approved, Implementing, Stable, Amending, Rejected oder Deprecated sein. Die Regel status-mirror, in den beiden oben genannten Katalogen, verlangt, dass das status: im Frontmatter eines Artefakts mit Status mit dieser Zeile im Body übereinstimmt, und verbietet status: bei einem Typ, der keinen Status hat. Die beiden Kopien zur Deckung zu bringen ist nicht dasselbe wie ein Wort außerhalb der acht Werte abzulehnen. Keine der beiden Katalogzeilen beschreibt eine Regel, die einen Feature-Status außerhalb dieser Menge ablehnt, daher behauptet diese Seite keine solche Regel.

Pläne nutzen eine andere Menge. Die Regel P-006, in beiden Katalogen, verlangt, dass das **Status:** im Body eines Plans aus einer einzelnen Datei eines von Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded oder Deprecated ist. Die Regel idea-status-values lehnt einen Ideen-Status außerhalb der Menge ab, die diese Regel erlaubt. Der Katalog ist die Liste. Diese Seite wiederholt die Wörter der Ideen nicht.

Die Planspezifikation beschreibt außerdem eine optionale Tabelle ## Snapshots mit den Spalten Date, Git Hash, Action und Comment. Sie sagt, dass jeder Snapshot einen Git-Commit-Hash des Zustands des Plans in diesem Moment referenziert. Die beiden für diese Seite geprüften Lint-Kataloge nennen keine Regel, die diesen Hash auflöst, daher behauptet diese Seite nicht, dass der Linter prüft, ob der Commit existiert. Der Hash ist ein Zeiger, dem eine Person in git folgen kann. Die veröffentlichte Planspezifikation ist die Formatseite für dieses Dokument.

Eine Spezifikation reviewen

Die Prüfung einer Markdown-Spezifikation ist der Pull Request, der sie ändert. dogfood.yml läuft bei pull_request und bei einem Push auf main. Der Job macht den Checkout des Repositorys, installiert die CLI mit SPECSCORE_VERSION auf v0.39.1 und führt specscore spec lint ohne zusätzliche Flags aus. GitHub Actions lässt den Schritt fehlschlagen, wenn dieser Prozess mit einem Wert ungleich null endet. Die Berechtigungen des Workflows sind contents: read.

Der Feature-Status In Review bedeutet, dass das Feature zur Prüfung vorgelegt wird. Dieses Wort zu schreiben ist eine Änderung der Markdown-Datei. Der Pull Request ist der Ort, an dem eine Person den Diff liest. status-mirror prüft, dass Frontmatter und Body denselben Status nennen. Es hält nicht fest, dass ein Reviewer der Prosa zugestimmt hat. Die Validatoren-Seite trennt diese strukturelle Prüfung von einer Lektüre, die eine Person noch machen muss. Die Darstellung Regel für Regel dessen, was specscore spec lint meldet, steht in Spezifikationen in CI linten.

Spezifikationen mit dem Code synchron halten

Spezifikationen mit dem Code synchron zu halten bedeutet auf dieser Website, dass die Spezifikation im Repository beim Projekt liegt und dass die CI den Pull Request fehlschlagen lässt, wenn der Spezifikationsbaum das Format verletzt. Ein Pull Request kann eine Feature-Datei und den Code im selben Diff ändern. Die Regel feature-index-row-sync hält eine Indexzeile mit der Feature-Datei ausgerichtet, die sie nennt. Sie liest keine Quelldatei, um zu entscheiden, ob der Code die Anforderung implementiert.

Der Auszug unten zeigt die Installations- und Lint-Schritte aus dogfood.yml. Die Workflow-Datei setzt außerdem Berechtigungen, eine Concurrency-Gruppe und einen Kommentar, warum der Pin nicht latest ist. Diese Zeilen sind hier weggelassen. Die Befehle sind die, die diese Datei ausführt.

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

Der Kommentar in dieser Datei sagt, dass ein gleitender latest-Pin das Gate unter dem Repository ändert: ein Pull Request und der Branch main, auf den er zielt, können unterschiedliche Regeln sehen. Der Pin ist v0.39.1. Der Job gibt --fix nicht mit. Ein sauberer Lauf und ein fehlschlagender Lauf, einschließlich der Zeile file:line [severity] rule: message, stehen in Spezifikationen in CI linten.

Ein Satz in der Spezifikation, der den Code nicht mehr beschreibt, ist keiner dieser Funde. specscore spec lint prüft die Struktur: Pflichtdateien und Pflichtabschnitte, Indexzeilen, die Form der Überschriften und die Verweise, die die Regeln nennen. Es benotet nicht, ob die Implementierung zur Anforderung passt. Diese Grenze ist der Sinn der Validatoren-Seite. Die Prosa wahr zu halten bleibt eine Prüfung des Diffs.

Wie andere spezifikationsgetriebene Werkzeuge eine Spezifikation prüfen

Die Absätze unten verwenden die Seiten, die am 9. November 2026 abgerufen wurden. Sie beschreiben die eigenen Prüfungen dieser Werkzeuge. Sie sagen nicht, wie viele Produkte es gibt, und sie ordnen keinen Markt. Die Werkzeugrunde ist der längere Vergleich.

Die Referenz für agentisches SDD von GitHub Spec Kit beschreibt /speckit.analyze als eine Nur-Lese-Prüfung über spec.md, plan.md und tasks.md. Sie meldet Konflikte, Lücken und Mehrdeutigkeiten, sie bearbeitet nie Dateien, und du führst sie im Agenten vor der Implementierung aus. Die Befehlsliste derselben Seite beschreibt keinen CI-Job, der specscore spec lint gegen einen SpecScore-Baum ausführt.

OpenSpec speichert eine Änderung als Verzeichnis direkt unter openspec/changes/. openspec validate prüft Änderungen und Spezifikationen auf strukturelle Probleme. Die Referenz sagt, dass Exit-Code 0 bedeutet, dass jedes geprüfte Element bestanden hat, und dass Exit-Code 1 bedeutet, dass ein Element fehlgeschlagen ist, die Berichtsanfrage ungültig ist, die Konfiguration nicht gelesen werden kann oder der Lauf fehlgeschlagen ist. Diese Prüfung ist die Form von OpenSpec, einschließlich seiner Blöcke für Anforderung und Szenario, nicht eine SpecScore-Überschrift ### AC:. Bei einem anderen Befehl, openspec status, sagt dieselbe Referenz, dass ein Stapel, der eine Änderung nicht laden kann, trotzdem mit 1 endet, „so CI doesn’t accept an incomplete report as successful.“ Dieser Satz gilt für openspec status, nicht für openspec validate.

FAQ

Was ist Spec-Management?

Spec-Management ist, eine Softwarespezifikation zu speichern, jede Änderung festzuhalten, diese Änderung zu prüfen und die Spezifikation aktuell zu halten. In SpecScore sind die Dateien Markdown im git-Repository, und specscore spec lint ist die strukturelle Prüfung, die ein CI-Job fehlschlagen lassen kann.

Was ist Spezifikationsmanagement?

Spezifikationsmanagement ist dieselbe Praxis. Die Spezifikation ist das Dokument, das sagt, was die Software tun muss. Sie zu verwalten bedeutet, dass das Dokument einen bekannten Ort, eine Historie, einen Review und eine Prüfung hat, dass seine Struktur noch zum Format passt.

Wie verwalte ich Spezifikationen als Code?

Die Spezifikation ist ein Baum von Markdown-Dateien unter spec/, plus specscore.yaml an der Wurzel des Repositorys. Eine Änderung ist ein Commit. Ein Pull Request prüft den Diff. dogfood.yml führt specscore spec lint auf diesem Pull Request aus.

Wie funktioniert die Spec-Versionierung?

Die Git-Historie ist die Versionshistorie der Dateien. Ein Feature trägt außerdem **Status:** mit einem der acht Werte, die die Feature-Spezifikation verlangt. Ein Plan kann eine Zeile ## Snapshots festhalten, deren Git Hash ein Commit des Zustands des Plans ist. Die hier zitierten Linter-Kataloge beschreiben keine Regel, die diesen Hash auflöst.

Wie halte ich Spezifikationen mit dem Code synchron?

Leg die Spezifikation ins Repository und lass den Pull Request fehlschlagen, wenn specscore spec lint einen strukturellen Verstoß meldet, einschließlich einer Indexzeile, die nicht zu ihrer Feature-Datei passt. Der Befehl entscheidet nicht, ob der Code die Anforderung implementiert. Ein Satz, der vom Code abgedriftet ist, braucht weiterhin eine Person, die den Diff liest.

Halte die Spezifikation im Repository.

Have an idea how to improve this page?