OpenSpec vs. die Specification-Framework-Landschaft: Warum DevOps AI-native Specs benötigt
🇬🇧 Read in English~18 min read
openspecdevopsspecification-frameworksopenapiadrsai-agentschange-managementinfrastructure-as-code
Back openDesk Edu for a sovereign, open-source education — every vote counts.
Vote nowSave products you love by clicking the heart icon.
Kurzreferenz für Terraform Infrastructure as Code, HCL-Syntax und Best Practices
Jedes DevOps-Team pflegt Spezifikationen. API-Contracts, Architecture Decision Records, Design-Dokumente, Runbooks, Change Proposals. Die Frage ist nicht, ob Sie spezifizieren – sondern ob Ihre Spezifikationen den Kontakt mit der Realität überleben.
Die meisten Frameworks für Spezifikationen wurden für die Kommunikation von Mensch zu Mensch entwickelt. Sie setzen einen Leser voraus, der die Absicht aus dem Fließtext ableiten, Lücken aus dem Kontext füllen und Querverweise intuitiv navigieren kann. Diese Annahme bricht zusammen, wenn der primäre Konsument Ihrer Spezifikationen kein Mensch mehr ist.
Wir treten in eine Ära ein, in der KI-Agenten neben Menschen Code schreiben, prüfen und deployen. Die Frameworks für Spezifikationen, die wir wählen, entscheiden darüber, ob diese Agenten mit uns oder gegen uns arbeiten.
Dieser Artikel vergleicht sechs Ansätze für Spezifikationen und Change Management – einschließlich OpenSpec, dem KI-nativen Framework, das in diesem Projekt verwendet wird – anhand praktischer DevOps-Dimensionen: Agentenfreundlichkeit, CI/CD-Integration, Documentation Drift und operationaler Overhead.
Bevor wir einzelne Frameworks vergleichen, hilft es zu verstehen, was ein Framework für Spezifikationen eigentlich bietet:
Jedes Framework adressiert eine Teilmenge dieser Pipeline. Der Unterschied liegt darin, wo sie die Automatisierungsgrenze ziehen – was sie in maschinenlesbaren Formaten kodieren und was sie der menschlichen Interpretation überlassen.
| Framework | Primäres Format | Konsument | Umfang | KI-Nativ? |
|---|---|---|---|---|
| OpenAPI/Swagger | YAML/JSON | Tools + Menschen | API-Contracts | Teilweise |
| AsyncAPI | YAML/JSON | Tools + Menschen | Event-Contracts | Teilweise |
| ADRs | Markdown | Menschen | Architektur-Entscheidungen | Nein |
| RFC Process | Markdown | Menschen (Team) | Design-Vorschläge | Nein |
| BDD/Gherkin | Plain text (Gherkin) | Tests + Menschen | Verhaltens-Spezifikationen | Ja (strukturiert) |
| Spec Kit | Markdown + Slash commands | KI-Agenten + Menschen | Agenten-gesteuerter SDD-Workflow | Ja (nativ) |
| OpenSpec | Markdown + CLI | KI-Agenten + Menschen | Vollständiger Change-Lifecycle | Ja (nativ) |
| GitHub Issues/Projects | UI + Markdown | Menschen | Task-Tracking | Nein |
| JIRA + Confluence | UI + Rich text | Menschen (Org) | Projektmanagement | Nein |
OpenAPI ist das erfolgreichste Framework für Spezifikationen in DevOps. Es definierte ein maschinenlesbares Contract-Format für REST-APIs, das Dokumentationen, Client-SDKs, Server-Stubs und Test-Harnesses aus einer einzigen „Source of Truth“ generiert.
Wo es glänzt:
Wo es für modernes DevOps zu kurz greift:
# It does NOT tell you HOW to change it safely
paths:
/deployments:
get:
summary: List deployments
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Deployment"
OpenAPI ist essenzielle Infrastruktur. Aber es ist ein Contract-Format, kein Framework für Change Management. Es löst das Interface-Problem und lässt den Engineering-Prozess unangetastet.
AsyncAPI erweitert das Contract-First-Modell auf eventgesteuerte Architekturen – Kafka-Topics, RabbitMQ-Queues, WebSocket-Channels, MQTT-Broker.
Was es gut macht:
Gleiche fundamentale Einschränkung wie OpenAPI: AsyncAPI beschreibt die Event-Oberfläche – nicht den Prozess, der sie hervorgebracht hat. Man weiß, welche Kafka-Topics existieren, aber es gibt keinen Artifact-Trail darüber, warum sie hinzugefügt wurden, welche Alternativen in Betracht gezogen wurden oder ob die Implementierung dem beabsichtigten Design entspricht.
Sowohl OpenAPI als auch AsyncAPI leiden unter derselben DevOps-Lücke: Die Spezifikation existiert getrennt von dem Change-Prozess, der sie erschaffen hat, und die beiden driften unweigerlich auseinander.
Architecture Decision Records (ADRs) sind ein wunderbar einfaches Muster: eine kurze Markdown-Datei pro Architektur-Entscheidung, die zusammen mit dem Code im Repository gespeichert wird. Ursprünglich 2011 von Michael Nygard vorgeschlagen.
adr/
├── 001-use-postgresql-for-primary-storage.md
├── 002-adopt-kubernetes-for-orchestration.md
├── 003-use-redis-for-session-caching.md
└── 004-migrate-to-opensearch-for-logging.md
Jedes ADR folgt einer Vorlage: Kontext Entscheidung Konsequenzen. Das Format ist bewusst minimal – prosabasiert und darauf ausgelegt, von Menschen geschrieben und gelesen zu werden.
Wo ADRs überzeugen:
Wo sie scheitern:
Behavior-Driven Development mit Gherkin (Given/When/Then) ist der engste Vorläufer dessen, was OpenSpec anstrebt. Es definiert ausführbare Spezifikationen, die gleichzeitig als Dokumentation und Akzeptanztests dienen.
Feature: Deployment Rollback
Scenario: Rollback on health check failure
Given a deployment with 3 replicas
When the health check fails for 2 replicas
Then the orchestrator initiates a rollback
And the previous revision is restored within 60 seconds
Die tatsächlichen Stärken von BDD:
Warum BDD für das DevOps Change Management nicht ausreicht:
BDD besetzt eine nützliche Nische: Spec-as-Test für spezifische Verhaltensweisen. Es ersetzt kein Change-Management-Framework.
Der RFC-Prozess (Request For Comments), der durch die IETF popularisiert und von React, Rust, Python und Kubernetes übernommen wurde, ist der Goldstandard für kollaboratives Design. Eine vorgeschlagene Änderung wird in einem strukturierten Template dokumentiert, von der Community diskutiert, durch Review-Zyklen verfeinert und entweder akzeptiert oder abgelehnt.
rfcs/
├── text/
│ ├── 0000-template.md
│ ├── 0001-new-rfc-process.md
│ ├── 0002-adopt-openspec.md
│ └── 0003-spec-first-change-management.md
Was RFCs so leistungsfähig macht:
Die DevOps-Lücke bei RFCs:
Der RFC-Prozess liefert exzellente Design-Artefakte. Aber die Brücke von „RFC akzeptiert“ zu „Code deployed“ ist vollständig manuell.
Die meisten DevOps-Teams nutzen standardmäßig GitHub Issues für das Change-Tracking und Pull Requests für das Code-Review. Dies ist der Weg des geringsten Widerstands — es geht schnell und erfordert keine zusätzlichen Tools.
Was daran richtig ist:
Was für ein systematisches Change Management falsch ist:
GitHub Issues + PRs sind eine Kommunikationsplattform, die Teams zu einem Workflow zweckentfremden. Das funktioniert für kleine Teams mit guter Disziplin. Es skaliert jedoch schlecht.
Spec Kit, 2025 von GitHub veröffentlicht und bereits über 120.000 Sterne aufweisend, bringt Spec-Driven Development (SDD) zu KI-Coding-Agenten. Im Gegensatz zu OpenAPI oder AsyncAPI, die Schnittstellen beschreiben, oder ADRs, die Entscheidungen protokollieren, bietet Spec Kit einen ausführbaren Workflow, dem KI-Agenten von der Spezifikation bis zur Implementierung folgen können — der bisher nächste Ansatz an dem, was OpenSpec auf der Ebene des Change Managements versucht.
Der Spec Kit Workflow:
Jedes Feature durchläuft eine strukturierte Pipeline, die über Agent-Slash-Commands ausgeführt wird:
| Command | Zweck |
|---|---|
/speckit.constitution | Projektprinzipien und Entwicklungsrichtlinien festlegen |
/speckit.specify | Definieren, was gebaut werden soll (Requirements und User Stories) |
/speckit.clarify | Unklarheiten vor der Planung identifizieren und lösen |
/speckit.plan | Technischen Implementierungsplan mit Tech-Stack-Entscheidungen erstellen |
/speckit.checklist | Qualitäts-Checklisten zur Validierung der Anforderungen generieren |
/speckit.tasks | Plan in ausführbare, geordnete Implementierungsaufgaben unterteilen |
/speckit.analyze | Konsistenz zwischen den Artefakten vor der Implementierung validieren |
/speckit.implement | Alle Aufgaben gegen die Codebasis ausführen |
/speckit.converge | Vollständigkeit prüfen und Aufgaben für verbleibende Lücken generieren |
Jeder Command erzeugt strukturierte Markdown-Artefakte — SPEC.md, PLAN.md, TASKS.md, CHECKLIST.md — die deterministisch in die nächste Phase einfließen. Das Ergebnis ist ein wiederholbarer, agentengesteuerter Entwicklungszyklus, der die Lücke zwischen „was sollen wir bauen“ und „es ist gebaut“ schließt.
Wo Spec Kit glänzt:
specify init Command konfiguriert die Integration.Vergleich von Spec Kit und OpenSpec:
Beide teilen eine Kernphilosophie — strukturierte, agentenlesbare Spezifikationen —, zielen aber auf unterschiedliche Teile des Engineering-Lifecycles ab:
| Dimension | Spec Kit | OpenSpec |
|---|---|---|
| Scope | SDD-Workflow auf Feature-Ebene | Voller Change-Lifecycle (Vorschlag → Archiv) |
| Primäres Interface | Slash-Commands (/speckit.*) via Agent-Chat | CLI (openspec / /opsx-*) |
| Lifecycle-Phasen | Spec → Plan → Tasks → Implement → Converge | Proposal → Design → Specs → Tasks → Implement → Delta → Archive |
| Upfront Design | Minimal (Constitution + Specify) | Erforderlich (Proposal + Design-Artefakte) |
| Delta-Tracking | Implizit (converge erkennt Lücken) | Explizit (Delta-Specs werden mit Haupt-Specs synchronisiert) |
| Archiv | Kein Kern-Primitiv | Zeitgestempeltes Archivverzeichnis pro Änderung |
| Ökosystem | 105+ Extensions, 22 Presets, Bundles | Integrierte Skills, CLI-gesteuerte Orchestrierung |
| Team-Skalierung | Solo bis kleines Team | Strukturierte Teams mit AI-Agents |
Spec Kit ist die richtige Wahl, wenn Sie einen leichtgewichtigen, agentenfreundlichen Workflow wünschen, der Sie schnell von der Spezifikation zur Implementierung führt – ideal für die Feature-Entwicklung in kleinen Teams. OpenSpec bietet von vornherein mehr Struktur (Proposal-Review, Design-Artefakte, formales Delta-Tracking), die wertvoll wird, wenn Compliance-Anforderungen, Teamgröße oder die Komplexität der Änderungen zunehmen. Die Tools ergänzen sich: Einige Teams nutzen Spec Kit für schnelle Feature-Arbeiten und OpenSpec für Infrastrukturänderungen, die eine vollständige Rückverfolgbarkeit über Proposal, Design und Archiv erfordern.
OpenSpec tritt in diese Landschaft als ein Framework ein, das explizit für die Ära der AI-Agents entwickelt wurde. Es kombiniert den strukturierten Artefakt-Ansatz von RFCs, die Rückverfolgbarkeit von ADRs, die Ausführbarkeit von BDD und fügt etwas hinzu, das keines dieser Formate besitzt: einen maschinen erzwingbaren Change-Lifecycle, dem AI-Agents autonom folgen können.
Jede Änderung in OpenSpec folgt einer definierten Artefakt-Abhängigkeitskette:
1. AI-Agent als First-Class Consumer
Jedes Artefakt in einer OpenSpec-Änderung hat ein definiertes Schema, bekannte Output-Pfade und explizite Abhängigkeiten. Die CLI stellt maschinenlesbare Anweisungen (openspec instructions <artifact-id> --json) bereit, die einem AI-Agenten genau sagen, was zu erstellen ist, welchem Template zu folgen ist und welchen Kontext er lesen muss.
Dies unterscheidet sich grundlegend von einem Markdown-RFC oder einem ADR. Der Agent muss nicht herleiten, wie ein „guter“ Vorschlag aussieht – das Schema definiert dies. Der Agent muss nicht herausfinden, welche Dateien zu erstellen sind – die CLI löst die Pfade auf. Der Agent muss nicht raten, welche Artefakte als Nächstes benötigt werden – der Abhängigkeitsgraph gibt dies vor.
# Agent asks: "What do I need to create next?"
openspec instructions design --change "add-metrics-pipeline" --json
# Response: structured, actionable, unambiguous
{
"artifact": "design",
"template": "...",
"dependencies": ["proposal"],
"resolvedOutputPath": ".openspec/changes/add-metrics-pipeline/design.md",
"context": "..."
}
2. Vollständiger Change-Lifecycle, kein Fragment
OpenAPI liefert Ihnen den API-Kontrakt. ADRs liefern Ihnen das Entscheidungsprotokoll. BDD liefert Ihnen die Akzeptanztests. OpenSpec liefert Ihnen die gesamte Kette vom Proposal bis zum Archiv, wobei die Outputs jedes Artefakts in das nächste einfließen.
Das bedeutet, ein AI-Agent kann:
Kein anderes Framework bietet diesen vollständigen Lifecycle in einem maschinen erzwingbaren Format.
3. Delta-Specs als Primitiv
Wenn die Implementierung zeigt, dass die Spezifikation falsch oder unvollständig war, erfasst OpenSpec das Delta – was sich tatsächlich im Vergleich zur Planung geändert hat. Diese Delta-Specs können zurück in die Hauptspezifikation synchronisiert werden, wodurch die Spezifikation lebendig bleibt, anstatt zu versteinern.
Dies löst das Problem des „Documentation Drift“, das jedes andere Framework plagt. Die Spezifikation liegt nicht im Regal – sie entwickelt sich mit der Implementierung weiter, und die Deltas bieten einen Audit-Trail jeder Divergenz.
4. Archiv ist Teil des Workflows, kein nachträglicher Gedanke
Jede abgeschlossene Änderung wird in ein Archivverzeichnis mit einem Datumspräfix verschoben. Die Änderung wird zu einem historischen Datensatz, nicht zu einem vergessenen Verzeichnis. Dies ist wichtig für Compliance, Post-Mortems und das Training von AI-Agents anhand vergangener Muster.
OpenSpec ist kein Ersatz für jedes Spezifikations-Tool. Es gibt reale Kompromisse:
| Dimension | OpenSpec | Traditionelle Ansätze |
|---|---|---|
| Setup-Aufwand | Erfordert CLI, Schema-Initialisierung | ADR: eine Datei. Issues: null Setup |
| Lernkurve | Artefakt-Lifecycle muss erlernt werden | Jeder weiß, wie man Markdown schreibt |
| Tooling-Reife | Aufstrebendes Ökosystem | OpenAPI: über ein Jahrzehnt Tooling |
| Lesbarkeit für Menschen | Strukturierte Artefakte, weniger narrativ | RFCs: natürliche Prosa, leicht zu lesen |
| Scope | Engineering Change Management | OpenAPI: nur API-Kontrakte |
| Eignung Teamgröße | Am besten mit AI-Agents oder strukturierten Teams | ADRs: funktioniert auch für 2-Personen-Teams |
OpenSpec bringt einen Struktur-Overhead mit sich. Für einen Solo-Entwickler, der einen Tippfehler korrigiert, ist ein GitHub-Issue angemessener. Für eine mehrstufige Infrastrukturänderung, die Provisioning, Deployment, Konfiguration und Verifizierung umfasst – insbesondere wenn AI-Agents die Arbeit ausführen – ist die Struktur kein Overhead, sondern ein Hebel.
Um den Vergleich konkret zu machen, betrachten wir ein realistisches DevOps-Szenario: das Hinzufügen einer Prometheus-Metrics-Pipeline mit benutzerdefinierten Applikations-Metrics zu einem Produktionsservice.
| Phase | OpenAPI | ADR | BDD | RFC | Issues/PRs | OpenSpec |
|---|---|---|---|---|---|---|
| Proposal | N/A | N/A | N/A | RFC #0032 | Issue "add metrics" | proposal.md |
| Design | N/A | ADR-005 "use Prometheus" | N/A | In RFC enthalten | PR-Beschreibung | design.md |
| Specs | /metrics Endpoint-Def | N/A | Given/When/Then Szenarien | N/A | N/A | specs/metrics/spec.md |
| Tasks | N/A | N/A | N/A | N/A | Issue-Checkliste | tasks.md |
| Implement | Manuell | Manuell | Manuell | Manuell | PR | /opsx-apply |
| Verify | Schema valide? | N/A | Cucumber pass? | N/A | CI-Checks | Agent-Checks + CI |
| Trace | N/A (kein Link) | N/A (kein Link) | N/A (separat) | N/A (separat) | Issue PR Link | Vollständige Artefaktkette |
| Archive | N/A | N/A | N/A | Geschlossener RFC | Geschlossener Issue | Zeitgestempeltes Archiv |
Im OpenSpec-Workflow kann ein einziger Agent den gesamten Lifecycle durchlaufen. Bei jedem anderen Ansatz gibt es manuelle Übergaben, Informationsverluste zwischen den Phasen und keine automatisierte Verifizierung, ob die Implementierung mit der Absicht übereinstimmt.
Das richtige Tool hängt davon ab, wer die Spezifikation konsumiert und was sie erzwingen soll.
TRACK["GitHub Issues / PRs / JIRA
Allgemeines Tracking"]
ENF["ENFORCEMENT
maschinenlesbar → verifizierbar"]
HUMAN["Mensch (ad hoc)"]
AGENT --> OPS --> BDD --> API BDD --> RFC BDD --> ADR API --> TRACK RFC --> TRACK ADR --> TRACK TRACK --> ENF HUMAN --> TRACK
**Nutzen Sie Spec Kit, wenn:**
- Sie einen leichtgewichtigen, agentengesteuerten Spec-to-Implement-Workflow wünschen
- Ihr Team klein ist und minimalen Prozess-Overhead benötigt
- Sie eine breite Agenten-Kompatibilität (30+ Integrationen) ohne Vendor-Lock-in suchen
- Community-Extensions und Presets wichtiger sind als ein formaler Change-Lifecycle
**Nutzen Sie OpenSpec, wenn:**
- AI-Agenten die Implementierung gemeinsam mit Menschen ausführen
- Änderungen mehrere Schritte über Infrastruktur- und Anwendungscode hinweg umfassen
- Sie eine vollständige Rückverfolgbarkeit vom Vorschlag bis zum Archiv benötigen
- Documentation Drift Sie wertvolle Debugging-Zeit kostet
- Compliance einen Audit-Trail darüber erfordert, was geändert wurde und warum
**Nutzen Sie OpenAPI/AsyncAPI, wenn:**
- Sie API-Contract-Validierung und Codegenerierung benötigen
- Ihr Hauptaugenmerk auf der Schnittstellenkompatibilität zwischen Services liegt
- Sie ein Service Mesh oder ein API Gateway einsetzen, das die Spec direkt konsumiert
**Nutzen Sie ADRs, wenn:**
- Sie ein leichtgewichtiges Log für Architektur-Entscheidungen wünschen
- Keine AI-Agenten involviert sind
- Sie darauf vertrauen, dass Menschen die Repo-Beschreibung aktuell halten
**Nutzen Sie BDD/Gherkin, wenn:**
- Sie ausführbare Spezifikationen benötigen, die in der CI laufen
- Business-Stakeholder die Akzeptanzkriterien lesen müssen
- Die Spec-Grenze ein einzelnes Feature oder ein bestimmtes Verhalten ist
**Nutzen Sie RFCs, wenn:**
- Sie breites Community-Feedback zu einem Design benötigen
- Die Änderung langfristige architektonische Auswirkungen hat
- Die Qualität der Diskussion wichtiger ist als die Automatisierung
**Nutzen Sie Issues/PRs, wenn:**
- Die Änderung trivial ist (Tippfehler, Fix in einer einzelnen Datei)
- Sie keine AI-Agenten und ein kleines Team haben
- Struktur-Overhead Sie eher bremsen würde, als dass er hilft
## Das DevOps-Urteil
Die Spezifikations-Frameworks, die die meisten DevOps-Teams heute verwenden, wurden für eine Welt entwickelt, in der Menschen Code schreiben, Menschen Code reviewen und Menschen Code deployen. Diese Welt geht zu Ende.
Wenn AI-Agenten am Engineering-Lifecycle teilnehmen – Änderungen vorschlagen, Implementierungscode schreiben, Anforderungen verifizieren, Tests generieren –, wird das Spezifikations-Framework zur **Control Plane** für das Verhalten der Agenten. Ein freiformiger RFC oder ein unstrukturiertes GitHub-Issue gibt einem Agenten mehrdeutige Anweisungen. Ein strukturiertes OpenSpec-Artefakt mit einem definierten Schema, aufgelösten Output-Pfaden und expliziten Abhängigkeiten gibt einem Agenten deterministische Anweisungen.
Das bedeutet nicht, dass OpenSpec jedes andere Tool ersetzt. Dieses Projekt nutzt OpenAPI für den Stripe-Integrations-Contract, ADRs für Architektur-Entscheidungen und OpenSpec für das Change-Management. Sie bedienen unterschiedliche Ebenen des Spezifikations-Stacks.
Aber für die **Change-Management-Ebene** – den Teil des Workflows, der die Verbindung zwischen „wir sollten das tun“ und „es ist deployed und verifiziert“ herstellt – lassen die bestehenden Tools eine Lücke, die AI-native Agenten nicht ohne menschliche Unterstützung überbrücken können. OpenSpec schließt diese Lücke, indem es den gesamten Lifecycle maschinell erzwingbar (machine-enforceable) macht.
Die Frameworks, die in der DevOps-Ära gewinnen, werden nicht diejenigen sein, die die meisten Features oder die hübschesten Dokumentations-Generatoren haben. Es werden diejenigen sein, denen **AI-Agenten ohne menschliche Interpretation folgen können**.
---
_Dieser Artikel ist Teil der DevOps Infrastructure-Serie auf tobias-weiss.org. Das OpenSpec-Framework wird im Rahmen des OpenCode-Projekts entwickelt und wird zur Verwaltung aller Änderungen auf dieser Seite verwendet._