OpenSpec entmystifiziert

Ich bin in OpenSpec mit der Erwartung gegangen, es seien ein paar Befehle und etwas Markdown. Zumindest war das der Eindruck, als ich es in seinen frühen Tagen zum ersten Mal ausprobierte.

Dann öffnete ich die Dokumentation und fand Profile, Schemas, Artefakte, Config-Dateien, Archive-Flows, OPSX und Delta-Specs. Ich habe mehr Zeit verbracht, als ich zugeben möchte, beim Hin- und Herwechseln zwischen Tabs, um all das im Kopf zu behalten. Was genau ist ein Artefakt? Warum gibt es Profile und Schemas? Wenn beide den Workflow beeinflussen, warum müssen dann beide existieren?

Das ist die Erklärung, die ich mir damals statt der Tabs gewünscht hätte.

Was ist OpenSpec?

OpenSpec ist ein spec-driven Entwicklungsframework. Es lebt im Repository neben dem Code und funktioniert mit den meisten Coding-Agents: Claude Code, Cursor, Codex, GitHub Copilot, OpenCode und andere. Man installiert es mit npm install -g @fission-ai/openspec@latest, und es fügt dem Agent Planungs-Befehle hinzu.

Die Idee ist einfach. Bevor man Code schreibt, beschreibt man die Änderung, die man vornehmen will. OpenSpec generiert einen Proposal, ein Design-Dokument, eine Aufgaben-Aufschlüsselung und einen Spec-Delta, der zeigt, wie sich die Anforderungen ändern werden. Man überprüft diesen Plan, verfeinert ihn und implementiert dann. Wenn die Änderung fertig ist, wird der Spec-Delta auf die kanonischen Specs angewendet, damit die Anforderungen im Repository aktuell bleiben.

Dieser letzte Teil ist es, der OpenSpec vom eingebauten Plan-Modus des Agents unterscheidet. Der Plan-Modus verschwindet, wenn die Chat-Session endet. OpenSpec-Specs bleiben als lebendige Dokumentation im Repository, in Git eingecheckt, in PRs überprüfbar.

Das Projekt ist Open Source unter openspec.dev.

Die Kurzfassung

OpenSpec wurde für mich deutlich leichter, als ich es auf vier Fragen reduzierte:

Konzept	Die Frage, die es beantwortet
Profile	Welche Workflow-Aktionen stehen meinem Agent zur Verfügung?
Schema	Welche Planungs-Artefakte existieren, und was hängt wovon ab?
Config	Welcher Projekt-Kontext und welche zusätzlichen Regeln sollten diese Artefakte prägen?
Skills	Wie führt mein KI-Tool jede Workflow-Aktion aus?

Artefakte sind die Outputs, die dieses System produziert: Proposals, Specs, Designs, Aufgaben oder was auch immer das Schema definiert.

Warum sich die Terminologie geschichtet anfühlt

Einiges an Verwirrung ergibt mehr Sinn, wenn man sich ansieht, wie OpenSpec entstanden ist.

Der frühe Workflow war absichtlich klein:

propose -> apply -> archive

Der Proposal-Schritt erzeugte die Planungs-Dokumente, der Agent implementierte die Änderung, und Archive fügte das Ergebnis zurück in die Specs des Projekts ein.

Dann machte OPSX das System flexibler. Planung wurde zu einem Satz einzelner Artefakte, die über Abhängigkeiten verbunden waren. Man konnte sie schrittweise erstellen, überarbeiten, während man lernte, und den Graphen anpassen, statt einen fest einprogrammierten Prozess zu akzeptieren.

Diese Flexibilität brachte weitere Aktionen:

new -> continue or ff -> apply -> verify -> archive

OpenSpec 1.2 führte dann Profile ein. Der Punkt war nicht, eine weitere Planungs-Abstraktion hinzuzufügen. Profile steuern, welche Workflow-Skills und Befehle installiert werden, sodass Leute, die den kurzen Weg wollen, nicht jeden erweiterten Befehl im Kontext ihres Agents benötigen.

Das aktuelle Core-Profil gibt den schnellen Weg:

explore -> propose -> apply -> sync -> archive

Der erweiterte Workflow zeigt Aktionen wie new, continue, ff und verify, wenn man feinere Kontrolle will.

Diese Geschichte ist wichtig. Profile und Schemas können wie zwei Generationen derselben Idee aussehen. Das sind sie nicht, und diese Verwirrung ist es, wo ich die meiste Zeit verschwendet habe.

Profile vs. Schemas

Hier hing ich am längsten fest. Ich nahm an, Profile und Schemas seien konkurrierende Wege, einen Workflow zu definieren.

Sie sind orthogonal.

Ein Profil steuert die Aktionen, die einem zur Verfügung stehen. Ein Schema steuert die Planungs-Struktur, auf der diese Aktionen arbeiten.

Ich habe diesen Satz in der Doku drei Mal gelesen, bevor er ankam, also will ich hier etwas Zeit darauf verwenden.

Profile wählen die Steuerungen

Ein Profil definiert nicht proposal.md, design.md oder tasks.md. Es entscheidet, welche Workflow-Aktionen OpenSpec für das KI-Tool installiert.

Mit dem Core-Profil gibt /opsx:propose einem das einfache Erlebnis: die Änderung beschreiben und die Planungs-Artefakte in einem Durchgang generieren.

Mit einer erweiterten Auswahl kann man gezielter vorgehen:

/opsx:new erstellt das Gerüst für die Änderung.
/opsx:continue erstellt das nächste verfügbare Artefakt.
/opsx:ff erstellt alle Planungs-Artefakte, die generiert werden können.
/opsx:verify vergleicht die Implementierung mit den Artefakten vor dem Archive.

Meine ursprüngliche Kurzformel war also nah dran, aber nicht ganz richtig. Das Profil sagt nicht "generiere alles" oder "generiere eines". Das Profil macht diese Aktionen verfügbar; der Befehl, den man wählt, entscheidet, was als Nächstes passiert.

Schemas definieren den Planungs-Graphen

Schemas beantworten eine andere Frage: Was sollte diese Änderung enthalten?

Das Standard-spec-driven-Schema enthält Artefakte wie Proposal, Specs, Design und Aufgaben. Es beschreibt auch ihre Abhängigkeiten. Eine vereinfachte Ansicht sieht so aus:

              proposal
              /      \
           specs    design
              \      /
                tasks

Dieser Graph ist der Grund, warum /opsx:continue sagen kann, welches Artefakt bereit ist und welches noch blockiert ist. OpenSpec prüft, was auf der Festplatte existiert, und folgt den Abhängigkeitsregeln des Schemas.

Ein benutzerdefiniertes Schema könnte ein Research- oder Security-Review-Artefakt hinzufügen:

research -> proposal -> specs -> security-review -> tasks

Das Profil muss sich nicht ändern. Dieselbe continue- oder ff-Aktion kann ein anderes Schema durchlaufen.

Da trennten sich Profile und Schemas in meinem Kopf endlich: das Profil gibt einem die Steuerungen; das Schema gibt diesen Steuerungen etwas, worauf sie arbeiten.

Was OpenSpec mit "Artefakt" meint

Das Wort Artefakt ließ das System abstrakter klingen, als es ist.

Ein Artefakt ist ein Output, der durch das Schema definiert wird. Die meisten sind Markdown-Dateien oder eine Gruppe von Markdown-Dateien:

proposal.md
design.md
tasks.md
specs/<capability>/spec.md

Es gibt kein spezielles Artefakt-Objekt, das im Hintergrund läuft. OpenSpec leitet den Zustand größtenteils aus dem Dateisystem ab: wenn der geforderte Output existiert, ist dieses Artefakt erledigt und seine Abhängigen können verfügbar werden.

Der Begriff ist dennoch wichtig, weil ein Schema mehr als eine Datei-Form definieren kann. Das specs-Artefakt zum Beispiel kann ein Verzeichnis von Delta-Specs generieren statt einer festen Datei. Aber als Nutzer ist die nützliche Übersetzung:

Artefakt = ein Planungs-Output, der während einer Änderung produziert wird.

Proposal, Specs, Design und Aufgaben in vertrauten Begriffen

Diese habe ich viel leichter verstanden, wenn ich sie in gewöhnlicher Projekt-Sprache fasste:

OpenSpec-Artefakt	Vertraute Entsprechung	Hauptfrage
Proposal	Business Case	Warum machen wir das, und was ist im Scope?
Specs	Anforderungen	Was muss das System tun?
Design	Technische Lösung	Wie werden wir es bauen?
Tasks	Implementierungs-Checkliste	Welche Arbeit muss erledigt werden?

Als ich aufhörte, diese als OpenSpec-spezifische Erfindungen zu behandeln, fühlte sich der Workflow vertraut an. Es sind einfach die Dokumente, die ein ordentliches Team ohnehin produzieren würde, nur dass hier das Tooling davon weiß.

Main Specs vs. Delta Specs

Es gibt einen Unterschied, den ich eine Weile übersehen habe: OpenSpec arbeitet mit zwei Arten von Spezifikationen.

Die Specs unter openspec/specs/ beschreiben das System, wie es sich jetzt verhält. Sie sind die kanonische Quelle der Wahrheit, nach Fähigkeit organisiert.

Die Specs innerhalb einer Änderung beschreiben nur, was diese Änderung hinzufügt, modifiziert oder entfernt. Das sind Delta-Specs.

openspec/specs/                 current system
openspec/changes/add-2fa/specs/ proposed difference

Darum kann die Änderung überprüft werden, ohne die gesamte Spezifikation neu zu schreiben. Reviewer sehen den Unterschied, nicht eine zweite Kopie von allem.

Wenn die Änderung synchronisiert oder archiviert wird, werden diese Deltas auf die kanonischen Specs angewendet. Hinzugefügte Anforderungen werden angehängt, modifizierte Anforderungen ersetzen ihre vorherigen Versionen, entfernte Anforderungen werden gelöscht.

Das meint OpenSpec, wenn es davon spricht, Spezifikationen als lebendige Dokumentation zu bewahren.

Was config.yaml tatsächlich tut

Ich hatte erwartet, dass openspec/config.yaml den Workflow definiert. Tut es nicht.

Es konfiguriert das Projekt um den Workflow herum:

schema: spec-driven

context: |
  Stack: TypeScript, React, PostgreSQL
  Public APIs must remain backwards compatible

rules:
  proposal:
    - Include a rollback plan
  tasks:
    - Include tests for every requirement

Die Datei hat drei Hauptaufgaben:

Das Standard-Schema wählen.
Projekt-Kontext in die Anweisungen jedes Artefakts injizieren.
Zusätzliche Regeln nach ID in bestimmte Artefakte injizieren.

Sie fügt keine neuen Artefakte hinzu und ändert nicht deren Abhängigkeiten. Das gehört in ein Schema.

Diese Unterscheidung gibt eine nützliche Faustregel:

Wenn man ändern will, welche Dateien existieren, ändert man das Schema.
Wenn man ändern will, was die generierten Dateien berücksichtigen sollen, ändert man die Config.

Schemas vs. Skills

Hier irrte ich mich als Nächstes. Ich dachte, Schemas seien auch der Ort, an dem das gesamte Agent-Verhalten leben sollte.

Schemas können Templates und Anweisungen zur Generierung ihrer Artefakte enthalten, aber sie ersetzen keine Skills.

Ein Schema beschreibt das Planungs-Modell: Artefakt-IDs, Output-Pfade, Templates und Abhängigkeiten. Die generierten OpenSpec-Skills bringen dem KI-Tool bei, wie es Aktionen wie propose, continue, apply, sync und archive ausführt.

Wenn ich also ein neues security-review.md vor den Aufgaben will, ist das eine Schema-Änderung.

Wenn ich will, dass mein Coding-Agent bei der Implementierung TDD befolgt, gehört das in einen Implementierungs-Skill oder eine Projekt-Anweisung. Wenn ich lediglich will, dass jede generierte Aufgabenliste Tests erwähnt, reicht vielleicht eine tasks-Regel in config.yaml.

Das sind verwandte Anliegen, aber sie sitzen auf unterschiedlichen Schichten, und sie zu verwechseln war die Quelle der meisten meiner Verwirrung.

Verhindert Archive veraltete Dokumentation?

Das war das Letzte, was ich nicht loswerden konnte.

Archive tut zwei nützliche Dinge: es verschiebt die abgeschlossene Änderung in die Historie, und es stellt sicher, dass die Delta-Specs in die kanonischen Specs synchronisiert werden können. Das vermeidet es, mehrere konkurrierende Versionen der Anforderungen über aktive Change-Ordner verstreut zu lassen.

Was Archive nicht tut, ist zu beweisen, dass der Code zur Spezifikation passt.

Die erweiterte Aktion /opsx:verify prüft Vollständigkeit, Korrektheit und Kohärenz zwischen der Implementierung und den Planungs-Artefakten. Selbst dann hängt der Prozess immer noch an Review und ingenieurmäßiger Disziplin. Kein Archive-Befehl kann eine ungenaue Spec wahr machen.

OpenSpec reduziert also eine Art von Dokumentations-Drift: verwaiste oder konkurrierende Anforderungsdokumente. Es schließt die Lücke zwischen geschriebener Absicht und tatsächlicher Software nicht von selbst aus. Dieser Teil liegt weiter bei einem.

Das mentale Modell, das endlich Sinn ergab

Hier ist die Version, die ich jetzt im Kopf behalte:

Profile -> chooses the available workflow actions
Schema  -> defines the artifact dependency graph
Config  -> injects project context and artifact-specific rules
Skills  -> teach the agent how to perform those actions
Files   -> record the state of the change

Oder als ein Satz:

OpenSpec installiert einen Satz von Agent-Aktionen, führt sie über einen schema-definierten Graphen aus, formt ihren Output mit Projekt-Config und zeichnet den Fortschritt als Dateien im Repository auf.

Als ich es so sah, hörten Begriffe wie Profil, Schema und Artefakt auf, miteinander zu konkurrieren. Jeder hatte eine klare Grenze.

Das Schwierigste an OpenSpec ist nicht die Anzahl der Befehle. Es ist, dass vertraute Wörter innerhalb des Systems sehr spezifische Bedeutungen tragen, und die Doku macht diese Grenzen nicht immer offensichtlich. Wer an der Terminologie hängt, ist nicht allein, es hat bei mir eine Weile gedauert, und dieser Beitrag ist größtenteils der Weg, den ich dorthin genommen habe.