OpenSpec vs. die Specification-Framework-Landschaft: Warum DevOps AI-native Specs benötigt

Back openDesk Edu for a sovereign, open-source education — every vote counts.

OpenSpec vs. die Specification-Framework-Landschaft: Warum DevOps AI-native Specs benötigt | Technology | Tobias Weiss

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.

Das Spektrum der Spezifikationen

Bevor wir einzelne Frameworks vergleichen, hilft es zu verstehen, was ein Framework für Spezifikationen eigentlich bietet:

Loading diagram...

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.

Die Kandidaten

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 / Swagger: Der Goldstandard, der ein Problem gelöst hat

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:

Contract-First-Entwicklung mit Codegenerierung
Umfangreiches Tooling-Ökosystem (Swagger UI, Editor, Codegen, Validator)
Klare, versionierte Interface-Grenzen zwischen Services
CI-Pipeline-Validierung (Konformität von Request/Response)

Wo es für modernes DevOps zu kurz greift:

Enger Umfang – nur die API-Oberfläche, keine Deployment-, Infrastruktur- oder Operational-Spezifikationen
Kein Change-Lifecycle-Management – die Versionierung der Spec erfolgt manuell, und es gibt keinen Artifact-Trail vom Vorschlag bis zur Implementierung
Statisches Contract-Format – OpenAPI 3.1 hat die Dinge mit JSON Schema verbessert, aber die Spec beschreibt einen Endpunkt, nicht den Engineering-Prozess dahinter
Agenten können ihr nicht folgen – ein KI-Agent kann eine OpenAPI-Spec lesen, um eine API-Oberfläche zu verstehen, aber er kann sie nicht nutzen, um eine Änderung zu planen, vorzuschlagen, zu entwerfen, zu implementieren und zu verifizieren

# 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: OpenAPI für Events

AsyncAPI erweitert das Contract-First-Modell auf eventgesteuerte Architekturen – Kafka-Topics, RabbitMQ-Queues, WebSocket-Channels, MQTT-Broker.

Was es gut macht:

Maschinenlesbare Channel-Definitionen mit Publish/Subscribe-Semantik
Validierung von Message-Schemas über Event-Grenzen hinweg
Codegenerierung für Producer und Consumer
Wachsendes Tooling-Ökosystem (Generator, Modelina, CLI)

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.

ADRs: Leichtgewichtig, menschenzentriert, agentenfeindlich

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 $\rightarrow$ Entscheidung $\rightarrow$ Konsequenzen. Das Format ist bewusst minimal – prosabasiert und darauf ausgelegt, von Menschen geschrieben und gelesen zu werden.

Wo ADRs überzeugen:

Geringe Hürden bei der Erstellung (eine Datei, kein Tooling erforderlich)
Liegen im Repo neben dem Code (kein Drift zu externen Systemen)
Perfekt, um festzuhalten, warum Entscheidungen getroffen wurden
Unveränderliche, nummerierte Aufzeichnung der architektonischen Evolution

Wo sie scheitern:

Keine Struktur, der ein Agent folgen kann – ADRs sind freie Prosa. Ein KI-Agent müsste natürliche Sprache parsen, um Entscheidungskriterien, Alternativen und den Umfang zu extrahieren. Das ist möglich (LLMs sind darin gut), aber nicht zuverlässig für eine automatisierte Durchsetzung.
Keine Verbindung zur Implementierung – ein ADR besagt: „Wir haben uns entschieden, PostgreSQL zu verwenden.“ Es trackt nicht, ob die Implementierung dieser Entscheidung entspricht, welche Aufgaben noch offen sind oder ob Code ihr widerspricht.
Kein Lifecycle-Management – ADRs sind „append-only“. Entscheidungen werden getroffen und aufgezeichnet, aber es gibt keinen Workflow, um sie zu überarbeiten, zu ersetzen oder zu archivieren.
Keine Task-Generierung – „Wir haben X entschieden“ erzeugt keine Checkliste von Implementierungsschritten. Ein Mensch (oder Agent) muss die Entscheidung interpretieren und herausfinden, was zu bauen ist. ADRs sind wertvolle Dokumentationen. Sie sind jedoch kein Framework zur Steuerung von Veränderungen.

BDD / Gherkin: Ausführbare Specs mit einer Obergrenze

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:

Ausführbare Specs — die Spec IST der Test. Es gibt keinen Documentation Drift, da die Spec in der CI ausgeführt wird.
Gemeinsame Sprache — die strukturierte natürliche Sprache von Gherkin schlägt eine Brücke zwischen Business-Stakeholdern und Ingenieuren.
Living Documentation — bestandene Specs = aktuelle Dokumentation.
Agentenfreundliches Format — das strukturierte Given/When/Then-Format ist für KI-Agenten ohne Mehrdeutigkeit parsbar.

Warum BDD für das DevOps Change Management nicht ausreicht:

Nur Scope auf Feature-Ebene — ein Gherkin-Szenario beschreibt ein einzelnes Verhalten. Es kann keine mehrstufige technische Änderung darstellen (Infrastruktur bereitstellen → Service deployen → Monitoring konfigurieren → verifizieren).
Kein Design-Artefakt — BDD erfasst Akzeptanzkriterien, aber nicht die Design-Entscheidungen, Trade-offs oder in Betracht gezogenen Alternativen.
Kein Change-Lifecycle — BDD-Specs werden geschrieben und automatisiert, aber es gibt kein Konzept für Vorschläge, Genehmigungen, Implementierungs-Tracking oder Archivierung.
Hoher Wartungsaufwand — Gherkin-Szenarien sind bekanntlich fragil. Eine UI-Änderung kann Dutzende von in Business-Sprache geschriebenen Szenarien brechen, was teure Überarbeitungen erfordert.

BDD besetzt eine nützliche Nische: Spec-as-Test für spezifische Verhaltensweisen. Es ersetzt kein Change-Management-Framework.

Der RFC-Prozess: Kollaboratives Design, alles manuell

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:

Strukturiertes, wiederholbares Vorschlagsformat
Community-Review als fester Bestandteil des Prozesses
Entscheidungsdokumentation (akzeptiert/abgelehnt mit Begründung)
Historisches Archiv der Design-Evolution

Die DevOps-Lücke bei RFCs:

Keine Automatisierungsgrenze — ein RFC ist ein Markdown-Dokument mit Prosa-Abschnitten. Es gibt keinen maschinell erzwingbaren Vertrag zwischen dem Vorschlag und der Implementierung.
Keine Aufgabenzerlegung — eine Annahme bedeutet: „Wir sind uns einig, dass dies der richtige Ansatz ist.“ Jemand muss dies immer noch in Implementierungsaufgaben unterteilen.
Keine CI-Integration — die CI kann nicht verifizieren, ob die Implementierung mit den Design-Entscheidungen des RFC übereinstimmt.
Agenten-unfreundliche Struktur — wie ADRs verlassen sich RFCs auf menschliche Leser, um die Absicht zu interpretieren. Ein KI-Agent, der einen RFC mit 50 Abschnitten parst, hätte Schwierigkeiten, deterministische Action-Items zu extrahieren.

Der RFC-Prozess liefert exzellente Design-Artefakte. Aber die Brücke von „RFC akzeptiert“ zu „Code deployed“ ist vollständig manuell.

GitHub Issues + PRs: Der unstrukturierte Standard

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:

Null Setup-Kosten
Jeder weiß, wie man es benutzt
PR-Reviews bieten menschliche Quality Gates
CI-Integration ist integriert

Was für ein systematisches Change Management falsch ist:

Issue = unstrukturierter Blob — ein Issue kann ein Bug-Report, ein Feature-Request, eine Frage, eine Design-Diskussion oder eine Aufgabe sein. Es gibt keine strukturelle Unterscheidung.
Kein Design-Artefakt — der PR ist die Implementierung. Design-Entscheidungen sind in Kommentar-Threads vergraben oder bleiben implizit.
Keine Traceability von Spec → Implementierung — wurde implementiert, was beabsichtigt war? Der einzige Weg, dies zu wissen, ist, den Diff zu lesen und ihn mit der Erinnerung an die Diskussion zu vergleichen.
Agenten-unfreundlich — ein KI-Agent kann Issues und PRs lesen, aber er kann keinem strukturierten Workflow vom Vorschlag über die Implementierung bis zur Verifizierung folgen, da diese Struktur schlicht nicht existiert.
Documentation Drift ist der Standard — sobald gemergt wurde, wird das Issue geschlossen und die Diskussion archiviert. Die Implementierung entwickelt sich weiter, aber das Issue wird nie aktualisiert.

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: GitHubs Toolkit für Spec-Driven Development

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:

Agent-First Design — Wie OpenSpec behandelt Spec Kit KI-Agenten als First-Class-Consumer. Seine Commands erzeugen strukturierte, maschinenlesbare Artefakte mit expliziten Abhängigkeiten, keine freie Prosa.
Breite Kompatibilität — Funktioniert mit über 30 KI-Coding-Agenten (Copilot, Codex, Claude, Gemini, Kilo Code und mehr) ohne Vendor-Lock-in. Ein einziger specify init Command konfiguriert die Integration.
Erweiterbares Ökosystem — Über 105 Community-Extensions von mehr als 60 Autoren, 22 Presets zur Anpassung von Workflows und ein Bundle-System für rollenbasierte Setups (Product Manager, Developer, Security Researcher).
Operationelle Flexibilität — Funktioniert offline, hinter Firewalls sowie auf Windows, macOS und Linux.

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: AI-Native Change Management

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.

Der OpenSpec Change Lifecycle

Jede Änderung in OpenSpec folgt einer definierten Artefakt-Abhängigkeitskette:

Loading diagram...

Was OpenSpec unterscheidet

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:

Proposal lesen $\rightarrow$ Scope verstehen
Design lesen $\rightarrow$ Architektur verstehen
Specs lesen $\rightarrow$ Anforderungen verstehen
Tasks lesen $\rightarrow$ wissen, was zu implementieren ist
Tasks als erledigt markieren $\rightarrow$ Artefakt aktualisieren
Delta-Specs generieren $\rightarrow$ dokumentieren, was sich geändert hat
Archivieren $\rightarrow$ aufräumen

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.

Die Trade-offs

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.

Head-to-Head: Ein Deployment-Szenario

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 $\leftrightarrow$ 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.

Wann man was einsetzt

Das richtige Tool hängt davon ab, wer die Spezifikation konsumiert und was sie erzwingen soll.

Loading diagram...

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._

Cart

Wishlist

Your wishlist is empty

opencode-ansible: Agent-Native Infrastructure as Code with OpenCode

Das Spektrum der Spezifikationen

Die Kandidaten

OpenAPI / Swagger: Der Goldstandard, der ein Problem gelöst hat

AsyncAPI: OpenAPI für Events

ADRs: Leichtgewichtig, menschenzentriert, agentenfeindlich

BDD / Gherkin: Ausführbare Specs mit einer Obergrenze

Der RFC-Prozess: Kollaboratives Design, alles manuell

GitHub Issues + PRs: Der unstrukturierte Standard

Spec Kit: GitHubs Toolkit für Spec-Driven Development

OpenSpec: AI-Native Change Management

Der OpenSpec Change Lifecycle

Was OpenSpec unterscheidet

Die Trade-offs

Head-to-Head: Ein Deployment-Szenario

Wann man was einsetzt