Spec-Driven Architecture: Wenn Agenten bauen, muss Architektur sprechen

This blog post is also available in English

TL;DR

• Agentische Spec-Driven Development beschleunigt Implementierung, verschärft aber Architekturdrift in Systemlandschaften.
• Spec-Driven Architecture macht implizite Konventionen als versionierte, agentenlesbare Contracts durchsetzbar.
• Domain-, Architecture-, Ops- und Security-Contracts definieren Grenzen, Invarianten und erlaubte Abhängigkeiten.
• Ein Gatekeeper-Skill liefert Contract-Kontext vorab und validiert Ergebnisse nach jedem Workflow-Schritt.
• Automatisierte Contract-Prüfung macht Governance zur Prozesseigenschaft, nicht zur Wächterrolle.

Agentische Entwicklung verändert gerade, wo der eigentliche Engpass in der Softwareentwicklung liegt. Wer heute mit Tools wie BMAD, Claude Code oder Cursor arbeitet und strukturierte Spezifikationen als Grundlage nutzt, erlebt das direkt: Implementierung wird schnell, günstig, skalierbar. Ein neuer Service, ein Refactoring, eine zusätzliche Feature-Unit: Stunden statt Wochen.

Aber Implementierungsgeschwindigkeit löst kein Architekturproblem. Sie verstärkt es.

Das Problem: Implizite Architektur und verteilte Systeme

Stell dir vor, du entwickelst eine neue Anwendung spec-driven mit einem agentischen Workflow. Die Spezifikation ist klar, der Agent liefert sauber, die Tests sind grün. Dann kommt der Moment, wo diese Anwendung in eine bestehende Enterprise-Landschaft integriert werden soll, und plötzlich tauchen Fragen auf, die in keiner Spec stehen: Welches Logging-Format gilt hier? Welche Auth-Infrastruktur wird genutzt? Darf dieser Service direkt in die Datenbank eines Nachbarsystems schreiben? Welche Events muss er publizieren, damit andere Systeme mitbekommen, was passiert?

Diese Fragen sind keine Implementierungsdetails. Sie sind Architekturentscheidungen, die systemweit gelten und die im verteilten System kollektiv eingehalten werden müssen. Solange du eine standalone-Anwendung baust, kannst du darüber hinwegsehen. Sobald du in einer verteilten Systemlandschaft operierst, werden sie zum Pflichtprogramm.

Genau hier beginnt das eigentliche Problem. Architektur lebt in den meisten Projekten implizit: in ADRs, die niemand mehr liest, in Confluence-Seiten, die beim letzten Sprint nicht aktualisiert wurden, in Framework-Konventionen, die als selbstverständlich gelten, bis ein Agent sie nicht kennt. Das Problem ist nicht, dass diese Architektur falsch ist. Das Problem ist, dass sie nicht durchsetzbar ist. Kein Build schlägt fehl, weil eine Domänengrenze überschritten wurde. Kein CI-Job meldet, dass eine verbotene Abhängigkeit eingeführt wurde. Drift entsteht leise und wird erst sichtbar, wenn er teuer ist.

In agentischen Setups potenziert sich der Effekt. Jede autonom generierte Einheit ist ein neuer Punkt, an dem eine Architekturkonvention stillschweigend verletzt werden kann. Nicht aus Böswilligkeit, sondern weil der Agent es schlicht nicht wissen kann, wenn das Wissen nirgendwo explizit steht.

Spec-Driven Architecture

Spec-Driven Development ist der Ansatz, Spezifikation als primäres Artefakt zu behandeln, aus dem Implementierung und Tests abgeleitet werden. SDD beschreibt, wie ein System korrekt implementiert wird. Es beschreibt nicht, wie ein Portfolio von Systemen kohärent bleibt.

Genau diese Lücke adressiert Spec-Driven Architecture (SDA).

SDA überträgt das Kernprinzip von SDD auf die Architekturebene: Nicht Diagramme, nicht ADRs sind die Architektur, sondern versionierte, agenten-optimierte Contracts. In einem verteilten, agentisch entwickelten System wirken sie auf mehreren Ebenen gleichzeitig:

• Entwicklungsprozess: Contracts für Architektur, Operations oder Security definieren Leitplanken, innerhalb derer Agenten autonom implementieren dürfen.

• Zwischen Systemen: Architecture Contracts können erlaubte Abhängigkeiten und Kommunikationsmuster über Systemgrenzen hinweg festlegen.

• Innerhalb eines Systems: Contracts für das Domain Design können Semantik, Invarianten und Schnittstellen einer Domain verbindlich machen.

SDA ersetzt dabei keine bestehende Governance. Sie automatisiert sie. Was heute in Architecture Review Boards diskutiert, in ADRs dokumentiert und in Retrospektiven korrigiert wird, wird in SDA zum überprüfbaren Artefakt, das nicht mehr im nächsten Sprint vergessen werden kann.

Contracts: Grenzen und Garantien für Agenten und Teams

Ein Contract in SDA ist keine abstrakte Idee. Er ist eine explizite, überprüfbare Aussage über Erwartungen, Garantien und Grenzen zwischen Domains, Services, Teams und Agenten, ein Artefakt, das genauso behandelt wird wie Quellcode: versioniert, reviewed, Teil der Pipeline.

Der Begriff meint hier etwas anderes als API- oder Consumer-Driven Contracts wie Pact: Während diese das Verhalten zwischen zwei Services auf Implementierungsebene regeln, operieren SDA Contracts auf Architektur-, Governance- und Domain-Ebene. Sie legen nicht fest, wie zwei Services miteinander sprechen, sondern was in einem System überhaupt erlaubt ist.

Welche Contracts ein System braucht, hängt von dessen konkreten Anforderungen ab. Es gibt keine abschließende Liste. Die folgenden Beispiele sind typisch für verteilte Systeme.

Domain Contracts beschreiben die fachliche Semantik einer Domain nach außen: welche Begriffe sie definiert, welche Invarianten sie garantiert, über welche API- oder Event-Schnittstellen sie konsumiert werden darf. Ein Domain Contract schützt die Integrität der Domain, nicht nur gegenüber anderen Teams, sondern auch gegenüber Agenten, die autonom neue Implementierungen erzeugen. Er legt fest, was stabil bleiben muss, damit Konsumenten sich darauf verlassen können. Domain Contracts formalisieren Konzepte von DDD: Sie grenzen die Ubiquitous Language einer Domain nach außen ab und legen fest, welche Begriffe und Invarianten für andere Domains relevant und stabil sind, und was intern bleibt. Was bisher oft in Event-Storming-Boards und Team-Köpfen lebte, wird in SDA zum versionierten Artefakt.

Architecture Contracts regeln die Struktur des Gesamtsystems: welche Abhängigkeiten zwischen Modulen erlaubt sind, welche Kommunikationsmuster gelten, wo Schichtgrenzen verlaufen. Sie übersetzen implizite Konventionen wie „wir rufen nie direkt in die Datenbank einer anderen Domain" in überprüfbare Regeln, die ein Linter oder CI-Job automatisch validiert.

Ops Contracts definieren die Betriebsanforderungen, die für jede Einheit gelten: Metriken, Tracing, Logging-Standards. Gerade wenn neue Services schnell entstehen, verhindern sie, dass Observability ein nachträgliches Aufräumprojekt wird.

Security Contracts legen fest, welche Datenklassifikationen ein Service verarbeiten darf, welche Auth-Mechanismen vorgeschrieben sind und welche Compliance-Regeln gelten. Das klingt nach klassischem Security-Overhead, wird aber im agentischen Kontext konkret kritisch. Ein Agent, der autonom einen neuen Service erzeugt, der Kundendaten verarbeitet, hat ohne expliziten Security Contract keine Grundlage zu wissen, dass diese Daten verschlüsselt gespeichert, nur über interne Netze übertragen und nicht in generische Log-Ausgaben geschrieben werden dürfen. Ein Security Contract macht genau diese Anforderungen zu einem prüfbaren Build-Artefakt, nicht zu einer Checkliste, die jemand nach dem Deployment ausfüllt. Tools wie Open Policy Agent (OPA) zeigen, dass das kein theoretisches Konzept ist, sondern heute produktiv umsetzbar ist.

Dazu kommen je nach Kontext weitere: Test Contracts, die definieren, welche Qualitätsgates für eine Domain gelten, oder Deployment Contracts, die Infrastructure-Anforderungen regeln. Das Prinzip ist immer dasselbe: Implizites Architekturwissen wird explizit, versionierbar und automatisiert prüfbar gemacht, damit Agenten wie Teams gleichermaßen wissen, wo die Grenzen sind.

Wie sieht ein Contract konkret aus?

Der einfachste Einstieg ist eine Markdown-Datei im Repository. Kein spezielles Format, kein Tool-Zwang, nur explizites, versioniertes Wissen, das für Menschen wie Agenten gleichermaßen lesbar ist. Ein Domain Contract für eine Ordering-Domain könnte so aussehen:

# Domain Contract: Ordering


#### Owner

Team Checkout, [email protected]

## Ubiquitous Language

- **Order**: A confirmed purchase intent by a customer, containing at least one item.
- **OrderItem**: A single product line with quantity and price fixed at the time of ordering.
- **OrderStatus**: Enum — PENDING, CONFIRMED, SHIPPED, CANCELLED

#### Invariants

- An Order always contains at least one OrderItem.
- The total price is frozen at the time of order creation and never changes retroactively.
- A CANCELLED Order cannot be reactivated.

#### Published Interface

- REST API: `POST /orders`, `GET /orders/{id}`
- Events: `OrderConfirmed`, `OrderCancelled` (schema see /contracts/events/ordering.json)

#### What this domain does NOT own

- Payment processing (→ Payment Domain)
- Inventory management (→ Inventory Domain)

#### Consumption Rules

- Direct database access is not permitted.
- Status changes only via the API — never through direct event manipulation.

Das ist keine Dokumentation im klassischen Sinne, es ist ein Vertrag. Ein Agent, der einen neuen Service in der Ordering-Domain implementiert, bekommt diesen Contract als Kontext und weiß damit: welche Begriffe verbindlich sind, welche Invarianten er einhalten muss, welche Schnittstellen existieren und wo die Grenzen der Domain liegen. Das ist der Unterschied zwischen einem Agenten, der rät, und einem Agenten, der innerhalb klarer Leitplanken arbeitet.

Das gleiche Prinzip funktioniert für Architecture Contracts als YAML-Policy, für Security Contracts als OPA-Regeldatei, für Ops Contracts als Teil einer Plattform-Konfiguration. Das Format folgt dem Kontext, die Eigenschaft bleibt dieselbe: versioniert, prüfbar, Teil der Pipeline.

Von Markdown zu einem Contract-System

Markdown im Repository ist ein pragmatischer Einstieg, aber kein Endzustand. Wenn Contracts über viele Domains, Teams und Systeme wachsen, stellt sich die Frage der Verwaltung: Wie bleiben Contracts konsistent? Wie werden Abhängigkeiten zwischen Contracts sichtbar? Wie bekommen Agenten zur Laufzeit den richtigen Contract-Kontext?

Eine naheliegende Entwicklungsstufe ist ein dediziertes Contract-Repository, ein zentraler Ort, an dem alle Contracts versioniert gepflegt, auf Konsistenz geprüft und mit den betroffenen Domains verknüpft werden. Änderungen an einem Contract lösen automatisierte Checks aus: Welche Konsumenten sind betroffen? Welche Agenten-Workflows müssen neu validiert werden?

Der nächste Schritt ist die aktive Bereitstellung von Contracts an Agenten zur Laufzeit. Statt Contracts statisch in den Kontext eines Agenten zu laden, könnte ein Contract-Server über das Model Context Protocol (MCP) als Tool oder Resource bereitstehen. Der Agent fragt aktiv nach dem gültigen Domain Contract für die Ordering-Domain, bevor er eine Implementierung erzeugt. Er ruft den aktuellen Security Contract für Kundendaten ab, bevor er Datenbankzugriffe generiert. Contracts werden damit nicht nur Governance-Artefakte, sondern aktiver Teil des agentischen Entwicklungsprozesses: dynamisch, kontextabhängig und immer auf dem aktuellen Stand.

Das ist noch Zukunft. Aber eine, deren Grundlage heute schon gelegt werden kann, mit einer Markdown-Datei im Repository.

Contracts in der agentischen Entwicklung: Der Gatekeeper

Ein Contract im Repository ist ein guter Anfang. Aber ein Agent, der diesen Contract nicht kennt, hält sich auch nicht daran. Die entscheidende Frage ist deshalb nicht, wo Contracts liegen, sondern wann und wie sie in den agentischen Workflow gelangen.

Die naheliegendste Antwort: als Skill.

Ein Gatekeeper-Skill ist ein spezialisierter Agent, der die relevanten Contracts kennt und im Workflow eine doppelte Rolle spielt. Er ist Berater und Prüfer gleichzeitig. Bevor ein Implementierungs-Agent mit einer Aufgabe beginnt, kann er den Gatekeeper konsultieren: Welche Begriffe muss ich in dieser Domain einhalten? Welche Abhängigkeiten sind verboten? Welche Schnittstellen darf ich konsumieren? Der Gatekeeper antwortet mit dem relevanten Contract-Kontext, und der Implementierungs-Agent baut von Anfang an innerhalb der Leitplanken.

Am Ende jedes Workflow-Schritts wechselt der Gatekeeper die Rolle. Er übernimmt das Ergebnis und validiert es gegen die Contracts: Werden die Invarianten der Domain eingehalten? Verletzt die neue Abhängigkeit die Architecture Contracts? Fehlt das Tracing, das der Ops Contract vorschreibt? Erst wenn der Gatekeeper grünes Licht gibt, geht der Workflow weiter. Anderenfalls liefert er konkretes Feedback zurück an den Implementierungs-Agenten.

---

name: contract-gatekeeper

description: Use this skill to validate implementation decisions against active

  domain, architecture, ops, and security contracts. Invoke before any

  non-trivial implementation step and after each workflow step completes.

---


### Contract Gatekeeper


You are the contract gatekeeper for this system.
You know all active Domain Contracts, Architecture Contracts, Ops Contracts,
and Security Contracts.

#### When consulted (pre-implementation)


An agent asks whether a planned approach is contract-compliant.

1. Identify which contracts are relevant to the request.
2. Respond with the relevant contract sections.
3. Return a clear assessment:
   - **green**: compliant, proceed.
   - **yellow**: risk identified, document justification before proceeding.
   - **red**: violation, do not proceed without contract change.

#### When reviewing (post-step)


An agent submits an implementation result for review.

1. Check the result against all relevant contracts.
2. Return structured feedback:
   - which contracts were checked
   - what is compliant
   - what is not compliant, with specific reference to the violated rule

#### Contracts


[Embed relevant contracts here or retrieve via MCP at runtime]

Der Workflow-Agent seinerseits wird so instruiert, dass er den Gatekeeper nicht überspringen kann. Er weiß: Vor jedem nicht-trivialen Implementierungsschritt frage ich den Gatekeeper. Nach jedem Schritt lasse ich das Ergebnis prüfen. Das ist keine Empfehlung, das ist Teil der Workflow-Struktur.

### Implementation Agent — Workflow Instructions (excerpt)


#### Contract Compliance


Before any implementation decision that touches a domain boundary, a dependency,
or an interface: consult the contract-gatekeeper skill.

Provide: what you intend to implement, in which domain, and which resources
you plan to use.

After completing each step: submit the result to the contract-gatekeeper for review.
Do not proceed until the gatekeeper returns green, or a justified yellow
is documented.

Dieses Muster löst beide Probleme gleichzeitig. Der Agent bekommt Contract-Kontext zur richtigen Zeit, nicht irgendwo als Anhang, sondern aktiv im Workflow verankert. Und Enforcement passiert nicht nur am Ende, sondern kontinuierlich: früh genug, um schlechte Entscheidungen zu verhindern, bevor sie in Code gegossen sind.

Die gleiche Logik funktioniert in einer klassischen CI/CD-Pipeline, ohne dass der Entwicklungsworkflow schon agentisch sein muss. Ein dedizierter Pipeline-Step ruft einen Agenten auf, der jeden Commit gegen die relevanten Contracts prüft. Bestehende CI/CD-Tools müssen lediglich ergänzt werden.

Das macht Contracts zu einem pragmatischen Einstieg. Teams, die noch nicht auf agentische Workflows umgestellt haben, können Contracts trotzdem einführen und sofort von der automatisierten Prüfung profitieren. Der Contract-Linter im CI-Job und der Gatekeeper-Skill im agentischen Workflow sind zwei Ausprägungen desselben Prinzips. Wer mit dem CI-Step beginnt, hat die Grundlage bereits gelegt, wenn der Schritt zu SDD-Workflows folgt.

Governance ohne permanenten Einspruch

In den meisten Projekten ist Governance eine Rolle, die jemand spielen muss. Jemand, der im Architecture Review Board den Überblick behält. Jemand, der im PR-Kommentar schreibt: „Aber haben wir eigentlich gecheckt, ob das unsere Layering-Regeln verletzt?" Jemand, der nach dem Sprint fragt, warum der neue Service kein Tracing hat. Diese Person ist nicht böswillig. Sie ist notwendig, weil das Wissen sonst nirgendwo steht.

SDA verändert diese Rolle grundlegend. Wer bisher Governance im Review einfordern musste, bekommt jetzt ein Werkzeug, das früher greift: Contracts, die vom ersten Commit an gelten, nicht erst, wenn alles fertig gebaut ist. Die Verantwortung bleibt dieselbe. Was sich ändert, ist der Zeitpunkt der Wirkung. Wenn Architekturentscheidungen in versionierten Contracts stehen, wenn der Gatekeeper-Skill jeden Workflow-Schritt gegen diese Contracts prüft, wenn der CI-Job bei jedem Commit validiert: Governance ist einfach da. Nicht als Kontrolle, die jemand ausübt, sondern als Eigenschaft des Prozesses.

Meetings und Architecture Review Boards verschwinden dadurch nicht. Sie gewinnen ihren eigentlichen Zweck zurück: Entscheidungen treffen, Contracts formulieren, Grenzen bewusst setzen. Was wegfällt, ist der dauernde Overhead, diese Entscheidungen in jedem Kontext erneut einzufordern und zu erklären. Das Architecture Review Board entscheidet, was gilt. Der Rest des Prozesses sorgt dafür, dass es gilt.

SDA ist kein Framework, kein Tool, kein Ersatz für DDD oder Microservice-Muster. Es ist ein Governance-Prinzip für eine Welt, in der Implementierung billig geworden ist und Architektur das Letzte ist, was Systeme kohärent hält.