TDD und OpenSpec: Wie Spec-Driven Development eure AI-Coding-Workflows auf ein neues Level hebt

„Die AI hat mir perfekt aussehenden Code generiert – aber er macht nicht das, was ich wollte.“ Kennt ihr das? Genau hier kommt die Kombination aus Test-Driven Development (TDD) und OpenSpec ins Spiel. Nach über 15 Jahren Erfahrung in Softwarequalität, Open Source und Remote Consulting zeigen wir euch heute, warum diese Kombination nicht nur Spaß macht, sondern eure Produktivität mit AI-Coding-Assistenten drastisch verbessert.

Warum TDD allein nicht mehr reicht – und OpenSpec die perfekte Ergänzung ist

TDD hat uns gelehrt: Tests zuerst, dann Code. Das funktioniert hervorragend – solange ihr den Code selbst schreibt. Aber was passiert, wenn Claude, Cursor oder GitHub Copilot den Code für euch generieren? Plötzlich habt ihr das Problem, dass die AI zwar syntaktisch korrekten Code liefert, aber eure eigentliche Intention verfehlt.

OpenSpec löst genau dieses Problem durch Spec-Driven Development: Ihr definiert was gebaut werden soll, bevor die AI entscheidet wie. Das ist der Game-Changer für AI-Assisted Development.

Die drei Säulen der perfekten Kombination:

• TDD definiert die Validierung: Eure Tests sagen, ob das Ergebnis korrekt ist
• OpenSpec definiert die Intention: Eure Specs sagen, was gebaut werden soll
• AI übernimmt die Implementation: Der Coding-Assistant setzt die Specs um

Was ist OpenSpec eigentlich – und wie unterscheidet es sich von anderen Tools?

OpenSpec ist ein Spec-Driven Development Framework, das speziell für AI-Coding-Assistenten entwickelt wurde. Im Gegensatz zu anderen Tools wie Kiro oder spec-kit hat OpenSpec einen entscheidenden Vorteil: Es ist brownfield-first designt.

Der OpenSpec-Workflow in der Praxis:

openspec/
├── specs/              # Source of Truth (aktuelle Wahrheit)
│   └── authentication/
│       └── spec.md
└── changes/           # Proposals (geplante Änderungen)
    └── add-2fa/
        ├── proposal.md    # Warum und Was
        ├── tasks.md       # Implementierungs-Checkliste
        └── specs/
            └── authentication/
                └── spec.md  # Delta (nur Änderungen)

Diese Trennung zwischen specs/ (was ist) und changes/ (was wird) macht den entscheidenden Unterschied. Ihr könnt Features hinzufügen, ohne eure bestehenden Specs zu überschreiben. Das ist perfekt für echte Projekte mit Legacy-Code.

Unser Consulting-Tipp: GitHub’s spec-kit ist stark für Greenfield-Projekte (0→1), aber OpenSpec glänzt bei der Weiterentwicklung bestehender Systeme (1→n). Genau da, wo die meisten von euch täglich arbeiten.

Wie installiere ich OpenSpec in meinem Projekt – ohne Kopfschmerzen?

Die Installation ist bewusst simpel gehalten. OpenSpec setzt auf Node.js und läuft überall dort, wo Node läuft.

Schnellstart in 3 Schritten:

Schritt 1: Globale Installation

npm install -g @fission-ai/openspec@latest

Voraussetzung: Node.js >= 20.19.0. Prüft eure Version mit node --version.

Schritt 2: Projekt initialisieren

cd euer-projekt
openspec init

Während der Initialisierung werdet ihr gefragt, welche AI-Tools ihr nutzt. OpenSpec konfiguriert automatisch die passenden Slash-Commands für Claude Code, Cursor, GitHub Copilot und andere.

Schritt 3: Verifizieren

openspec list

Wenn ihr eine leere Liste seht – perfekt! Ihr seid startklar.

Integration mit euren AI-Tools

OpenSpec funktioniert mit zwei Mechanismen:

Nativ unterstützte Tools (mit Slash-Commands):

• Claude Code: /openspec:proposal, /openspec:apply, /openspec:archive
• Cursor: /openspec-proposal, /openspec-apply, /openspec-archive
• GitHub Copilot, Gemini CLI, und viele mehr

Andere Tools (via AGENTS.md):
Für Tools ohne native Integration liest OpenSpec automatisch aus openspec/AGENTS.md. Das funktioniert mit Jules, Amp und allen anderen AGENTS.md-kompatiblen Tools.

Praxis-Tipp aus Remote Consulting: Nach der Installation startet euren AI-Assistant neu. Slash-Commands werden beim Start geladen, nicht dynamisch nachgeladen.

Warum passen TDD und OpenSpec so gut zusammen – die perfekte Synergie?

TDD und OpenSpec ergänzen sich auf drei Ebenen, die in der Kombination mehr sind als die Summe ihrer Teile:

1. Intention vor Implementation

TDD ohne OpenSpec: „Ich schreibe einen Test für Login-Funktionalität“ → AI generiert irgendeine Login-Implementation
TDD mit OpenSpec: „Spec sagt: OAuth2 mit PKCE“ → AI generiert genau das → Test validiert es

2. Dokumentation die lebt

Eure OpenSpec-Specs sind nicht nur für die AI – sie dokumentieren eure Architektur-Entscheidungen. Kombiniert mit TDD habt ihr:

• Specs: WAS das System können soll
• Tests: WIE es validiert wird
• Code: Die Implementation (von AI generiert)

Alles bleibt synchron, weil die Specs die AI treiben und die Tests die Korrektheit sichern.

3. Refactoring mit Sicherheitsnetz

Der TDD-Zyklus (Red-Green-Refactor) wird durch OpenSpec verstärkt:

• Red: Test schlägt fehl
• Green: OpenSpec treibt die AI zur korrekten Implementation
• Refactor: Tests sichern ab, Specs bleiben das North Star

Aus der Praxis: In einem Projekt für einen Fintech-Kunden haben wir durch diese Kombination die Code-Review-Zeit um 60% reduziert. Warum? Weil die Reviewer die Specs lesen konnten, statt den AI-generierten Code Zeile für Zeile zu verstehen.

Welche AI-Coding-Tools werden von OpenSpec unterstützt – und welches solltet ihr wählen?

OpenSpec ist tool-agnostisch, aber mit unterschiedlichen Integrations-Leveln:

Tier 1: Native Integration (Slash-Commands)

• Claude Code – Unser Favorit für komplexe Architekturen
• Cursor – Hervorragend für VS Code-Workflows
• GitHub Copilot – Beste IDE-Integration
• Gemini CLI – Stark für Google-Workspace-Integration
• CodeBuddy, Qoder, RooCode – Spezialisten für bestimmte Workflows

Tier 2: AGENTS.md-basiert

• Jules, Amp, und viele andere – Funktionieren über die AGENTS.md-Konvention

Tier 3: Custom Integration

Jedes Tool, das Dateien lesen kann, funktioniert mit OpenSpec. Ihr fragt einfach natürlichsprachlich: „Erstelle eine OpenSpec Proposal für Feature X“

Entscheidungshilfe:

• Große Teams mit verschiedenen Präferenzen? → OpenSpec, weil jeder sein Tool nutzen kann
• Fokus auf Remote Consulting? → Claude Code (beste Context-Handling)
• IDE-zentriert? → Cursor oder GitHub Copilot
• Neu bei AI-Coding? → Startet mit GitHub Copilot (niedrigste Einstiegshürde)

Wie erstelle ich meine erste Change Proposal mit OpenSpec – Step by Step?

Der Moment der Wahrheit: Eure erste Proposal. Wir machen das an einem echten Beispiel.

Szenario: Zwei-Faktor-Authentifizierung hinzufügen

Schritt 1: Proposal erstellen (natürlichsprachig)

// In Claude Code, Cursor etc:
Erstelle eine OpenSpec Change Proposal für 2FA-Implementierung

Oder mit Slash-Command:

/openspec:proposal Add two-factor authentication

Was OpenSpec automatisch generiert:

openspec/changes/add-2fa/
├── proposal.md          # Ziele, Scope, Nicht-Ziele
├── tasks.md            # Implementierungs-Tasks
└── specs/
    └── authentication/
        └── spec.md     # Spec-Delta mit ## ADDED Requirements

Schritt 2: Review und Iterieren

openspec show add-2fa

Lest die Proposal. Passt sie zu eurem Intent? Wenn nicht, sagt der AI: „Ergänze in der Proposal: TOTP mit 30-Sekunden-Window“

Schritt 3: Specs validieren

openspec validate add-2fa

Dieser Command prüft:

• Sind alle Requirements korrekt formatiert?
• Hat jedes Requirement mindestens ein Scenario?
• Verwenden die Requirements SHALL/MUST?

Schritt 4: Implementation starten

// Natürlichsprachig:
Implementiere die Tasks aus add-2fa gemäß der Specs

// Oder Slash-Command:
/openspec:apply add-2fa

Schritt 5: Nach Completion archivieren

openspec archive add-2fa --yes

Dies merged die Spec-Deltas zurück in eure Source-of-Truth Specs.

Team-Best-Practice: In unserem Consulting empfehlen wir, jeden Schritt in Git zu committen:

git add openspec/changes/add-2fa
git commit -m "spec: Add 2FA proposal"
# ... nach Review ...
git commit -m "feat: Implement 2FA (closes add-2fa)"

Was sind die Vorteile von Spec-Driven Development gegenüber „Vibe Coding“ – ehrlich beantwortet?

„Vibe Coding“ ist der informelle Begriff für das Arbeiten mit AI ohne strukturierten Prozess. Ihr beschreibt was ihr wollt, die AI generiert Code, ihr iteriert.

Vibe Coding: Die Realität

Vorteil: Schneller Start, super für Prototypen
Nachteil:

• Context geht verloren („Warum haben wir das nochmal so gemacht?“)
• AI vergisst frühere Entscheidungen
• Code-Reviews werden zum Rätselraten
• Architektur-Drift

Spec-Driven Development: Der strukturierte Weg

Vorteil:

• Expliziter Kontext bleibt erhalten
• AI-generierter Code ist nachvollziehbar
• Code-Reviews fokussieren sich auf „Erfüllt es die Spec?“
• Architektur-Entscheidungen sind dokumentiert

Nachteil:

• Upfront-Invest in Spec-Erstellung
• Disziplin erforderlich

Die ehrliche Einschätzung nach 15 Jahren Praxis:

Für Prototypen und Experimente: Vibe Coding ist perfekt. Schnell, unkompliziert, kreativ.

Für Production Code und Team-Projekte: Spec-Driven Development ist essentiell. Der Mehraufwand zahlt sich spätestens beim ersten Bug-Fix oder Feature-Request aus.

Pragmatischer Ansatz: Startet mit Vibe Coding für das Feature-Exploration. Sobald ihr wisst was ihr wollt, erstellt die OpenSpec und lasst die AI neu generieren. Beste aus beiden Welten.

Funktioniert OpenSpec auch mit Legacy-Code – oder nur für neue Projekte?

Hier glänzt OpenSpec besonders! Das Framework wurde explizit für Brownfield-Projekte designed.

Legacy-Integration in 4 Schritten:

Schritt 1: Reverse-Engineering der existierenden Architektur
Erstellt Specs für eure kritischen Module. Nicht alles auf einmal – startet mit dem was ihr ändern wollt.

## Requirement: User Authentication
Das System NUTZT aktuell Session-Cookies für Authentication.
DIESE Implementierung IST Legacy und SOLL auf JWT migriert werden.

### Scenario: Aktuelles Verhalten (zu erhalten)
- WHEN User logged in successfully
- THEN Session-Cookie wird gesetzt
- AND Cookie ist 24h gültig

Schritt 2: Change Proposals für Modernisierung

openspec/changes/migrate-to-jwt/
└── specs/
    └── authentication/
        └── spec.md    # ## MODIFIED Requirements

Die Spec-Deltas zeigen explizit WAS sich ändert.

Schritt 3: Schritt-für-Schritt-Migration
Die tasks.md kann Migrations-Phasen definieren:

## Phase 1: Parallel Authentication
- [ ] JWT-Handler implementieren (neben Session)
- [ ] Feature-Flag für JWT-Auth

## Phase 2: Cutover
- [ ] Default auf JWT umstellen
- [ ] Session-Auth als Fallback

## Phase 3: Cleanup
- [ ] Session-Code entfernen

Schritt 4: Mit TDD absichern
Für Legacy-Code schreibt ihr Tests, die das aktuelle Verhalten festnageln (Characterization Tests), bevor ihr ändern.

Real-World-Beispiel: Bei einem E-Commerce-Kunden haben wir so ein 8 Jahre altes Monolith-System in Microservices umgebaut. OpenSpec dokumentierte jeden Schritt, TDD sicherte ab, dass nichts kaputt ging.

Wie validiere ich meine Specs vor der Implementierung – und vermeide böse Überraschungen?

Validation ist in OpenSpec eingebaut und rettet euch vor häufigen Fehlern.

Der validate Command

openspec validate add-2fa

Was wird geprüft:

1. Format-Compliance: Sind Requirements richtig strukturiert?
2. Scenario-Coverage: Hat jedes Requirement mindestens ein Scenario?
3. Keyword-Usage: Werden SHALL/MUST korrekt verwendet?
4. Delta-Konsistenz: In Changes, sind die Deltas korrekt formatiert?

Strict Mode für CI/CD

openspec validate add-2fa --strict

Im Strict Mode werden auch Warnungen zu Errors. Nutzt das in euren Pull-Request-Checks.

JSON Output für Automation

openspec show add-2fa --json

Perfekt für Scripts und Tooling-Integration.

Die vier häufigsten Validation-Fehler:

1. Fehlende Scenarios

❌ ## Requirement: User Login
Das System SHALL authenticate users.

✅ ## Requirement: User Login
Das System SHALL authenticate users.

### Scenario: Valid credentials
- WHEN user submits valid email and password
- THEN access token is returned

2. Falsche Keywords

❌ Das System SHOULD validate emails (zu schwach!)
✅ Das System SHALL validate emails

3. Unvollständige Deltas

❌ ## MODIFIED Requirements
### Requirement: User Login
(Fehlt: Was wurde geändert?)

✅ ## MODIFIED Requirements
### Requirement: User Login
Das System SHALL authenticate users via OAuth2 (previously: Session-based).
(Komplette neue Version des Requirements)

4. Inkonsistente Struktur
OpenSpec erwartet:

• ### Requirement: für Top-Level
• #### Scenario: für Test-Scenarios

Best Practice aus Consulting: Führt openspec validate --strict in eurem Pre-Commit-Hook aus. Spart Zeit in Code-Reviews.

Wie integriere ich OpenSpec in CI/CD Pipelines – für automatische Qualitätssicherung?

OpenSpec ist CLI-first designed und integriert sich nahtlos in eure CI/CD-Workflows.

GitHub Actions Integration

.github/workflows/openspec-validation.yml

name: OpenSpec Validation

on:
  pull_request:
    paths:
      - 'openspec/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install OpenSpec
        run: npm install -g @fission-ai/openspec@latest

      - name: Validate all changes
        run: |
          for change in openspec/changes/*/; do
            openspec validate $(basename $change) --strict
          done

GitLab CI Integration

.gitlab-ci.yml

openspec:validation:
  stage: test
  image: node:20
  script:
    - npm install -g @fission-ai/openspec@latest
    - openspec list
    - openspec validate --strict
  only:
    changes:
      - openspec/**

Pre-Commit Hook (lokal)

.git/hooks/pre-commit

#!/bin/bash
# OpenSpec Validation Hook

if git diff --cached --name-only | grep -q "^openspec/changes/"; then
  echo "Validating OpenSpec changes..."
  openspec validate --strict

  if [ $? -ne 0 ]; then
    echo "❌ OpenSpec validation failed!"
    echo "Fix errors or use 'git commit --no-verify' to bypass"
    exit 1
  fi
fi

Integration mit TDD-Workflows

Kombiniert OpenSpec-Validation mit euren Test-Suites:

# GitHub Actions
- name: Validate Specs and Run Tests
  run: |
    openspec validate --strict
    npm test  # Eure TDD-Tests

# Nur wenn beide erfolgreich → Grüne Pipeline

Consulting-Empfehlung:

• Development: Lokale Pre-Commit-Hooks (soft failure, mit override)
• Pull Requests: GitHub Actions (hard failure, muss grün sein)
• Main Branch: Additional deployment checks

Besonderheit für Remote Teams: OpenSpec-Validation ist deterministisch – das gleiche Ergebnis auf allen Maschinen. Perfekt für verteilte Teams.

Welche häufigen Fehler sollte ich bei TDD und OpenSpec vermeiden – Lessons Learned?

Nach über 15 Jahren und unzähligen Projekten haben wir diese Pattern-Fails gesehen:

Fehler 1: Specs zu detailliert schreiben

Das Problem: Ihr versucht, die Implementation in der Spec zu beschreiben.

❌ Falsch:

## Requirement: Password Hashing
Das System SHALL bcrypt mit Rounds=12 nutzen und
ein 16-Byte Salt via crypto.randomBytes generieren.

✅ Richtig:

## Requirement: Password Hashing
Das System SHALL passwords mit einem sicheren, 
modernen Hashing-Algorithmus speichern.

### Scenario: Hash ist nicht reproduzierbar
- GIVEN gleiches Password zweimal gehasht
- THEN unterschiedliche Hashes entstehen

Die Spec sagt was, nicht wie. Die AI entscheidet das „wie“ oder ihr gebt es in der design.md an.

Fehler 2: Tests und Specs doppelt führen

Das Problem: Ihr schreibt die Anforderungen in die Spec UND in die Tests.

Besserer Ansatz:

• Specs = Anforderungen in natürlicher Sprache
• Tests = Executable Validierung der Specs

Verlinkt die Tests auf die Specs:

// auth.test.ts
// Validates: openspec/specs/authentication/spec.md 
// Requirement: "User Authentication"
describe('User Authentication', () => {
  // Scenario: Valid credentials
  it('returns JWT for valid credentials', () => {
    // ...
  });
});

Fehler 3: Zu große Change Proposals

Das Problem: Eine Proposal für „Complete Authentication System“ – 50 Tasks, 3 Wochen Arbeit.

Besser: Kleine, iterative Changes:

• add-user-login
• add-password-reset
• add-2fa
• add-session-management

Faustregel: Eine Proposal sollte in 1-2 Tagen implementierbar sein.

Fehler 4: Specs nicht aktualisieren nach Archivierung

Das Problem: Change ist implementiert und archiviert, aber ihr schaut nie wieder in die Specs.

Lösung: Specs sind eure Living Documentation. Nach großen Features:

openspec list --specs  # Was haben wir?
openspec show authentication --type spec  # Aktuelle Auth-Spec

Fehler 5: TDD-Zyklus mit AI brechen

Das Problem: Ihr lasst die AI riesige Code-Chunks generieren, ohne Tests.

Richtig mit OpenSpec:

1. Spec-Delta definiert EINE Capability
2. Test für diese Capability schreiben (Red)
3. AI generiert Implementation basierend auf Spec (Green)
4. Refactor mit Tests als Sicherheitsnetz

Bleibt im TDD-Zyklus, auch mit AI!

Fehler 6: Validation ignorieren

Das Problem: „Ich weiß was ich tue, validation brauche ich nicht.“

Realität: Validation fängt 80% der Spec-Inkonsistenzen. Nutzt sie.

Fehler 7: Zu früh optimieren

Das Problem: Perfekte Spec-Struktur von Tag 1.

Pragmatischer Ansatz:

• Start: Einfache Proposals mit Minimum-Specs
• Iterativ: Specs verbessern, wenn ihr das System besser versteht
• Refactor: Auch Specs dürfen refactored werden!

Lessons Learned aus Remote Consulting: Die besten Teams starten klein, lernen schnell und iterieren häufig. Perfektionismus bremst mehr als er hilft.

Best Practices aus über 15 Jahren Softwarequalität und Remote Consulting

Nach unzähligen Projekten haben wir bei Never Code Alone diese Standards etabliert:

✅ OpenSpec als Single Source of Truth

Specs in OpenSpec sind euer Architektur-Journal. Jede wichtige Entscheidung dokumentiert.

✅ TDD-Zyklus einhalten – auch mit AI

Red-Green-Refactor bleibt die Basis. AI beschleunigt die Green-Phase, Tests sichern die Refactor-Phase.

✅ Specs und Tests im gleichen PR

PR #123: Add 2FA Authentication
- openspec/changes/add-2fa/      # Specs
- tests/auth/2fa.test.ts         # Tests
- src/auth/2fa-handler.ts        # Implementation (AI-generiert)

Reviewer sehen Intention (Specs), Validierung (Tests) und Code auf einen Blick.

✅ Team-Standards für Specs

Einigt euch auf:

• Requirement-Format
• Scenario-Struktur
• SHALL vs MUST usage
• Wann design.md nutzen

✅ Change-IDs als Git-Convention

git commit -m "spec: add-password-reset proposal"
git commit -m "feat(auth): implement password reset (closes add-password-reset)"

Traceability von Spec zu Implementation.

Der entscheidende Vorteil für eure Projekte

TDD + OpenSpec ist mehr als nur eine Technik – es ist ein Mindset-Shift:

Alte Welt: AI generiert Code → Ihr hofft es passt → Debugging
Neue Welt: Ihr definiert Intention → AI implementiert → Tests validieren

Konkret bedeutet das:

• Schnelleres Onboarding: Neue Teammitglieder lesen Specs statt Code zu reverse-engineeren
• Bessere Code-Reviews: „Erfüllt der Code die Spec?“ statt „Was macht dieser Code?“
• Weniger Rework: Klare Intention = weniger Missverständnisse
• Dokumentation die lebt: Specs bleiben aktuell, weil sie Teil des Workflows sind

Direkte Unterstützung für euer Team

Ihr wollt TDD und OpenSpec optimal in euren Workflow integrieren? Oder braucht ihr Unterstützung bei der Strukturierung eurer AI-Coding-Prozesse?

Mit über 15 Jahren Expertise in Softwarequalität, Open Source und Remote Consulting helfen wir euch gerne weiter. Wir haben Teams von 3 bis 30 Developern durch diese Transformation begleitet – mit messbaren Ergebnissen in Code-Qualität und Team-Produktivität.

Kontakt: roland@nevercodealone.de

Gemeinsam schaffen wir Workflows, die euer Team voranbringen – keine theoretischen Konzepte, sondern praktische Lösungen, die in eurem Projekt funktionieren.

Fazit: Der Spaß-Faktor von TDD und OpenSpec

Warum macht die Kombination aus TDD und OpenSpec besonders Spaß?

1. Klarheit statt Chaos: Ihr wisst immer, wo ihr steht. Specs zeigen das Ziel, Tests zeigen den Fortschritt.

2. AI als Pair-Programmer: Die AI ist nicht mehr ein unberechenbarer Code-Generator, sondern ein Teammate, der eure Specs umsetzt.

3. Schnelle Iteration: Der TDD-Zyklus mit AI ist unglaublich schnell. Red (10 Sekunden Test schreiben) → Green (20 Sekunden AI generiert) → Refactor (Tests geben Sicherheit).

4. Weniger Frustration: Keine Diskussionen mehr über „Warum hat die AI das so gemacht?“ – die Spec hat es definiert.

5. Messbare Erfolge: Grüne Tests + erfüllte Specs = Dopamin-Hit für Developer!

Startet heute: Installiert OpenSpec mit npm install -g @fission-ai/openspec@latest, erstellt eure erste Proposal und erlebt selbst, wie viel Spaß strukturierte AI-Development machen kann.

Never Code Alone – Gemeinsam für bessere Software-Qualität!