SDD in Brownfield-Projekten: So setzt du es richtig ein

In der Softwareentwicklung stoßen viele Entwickler auf ein vertrautes Szenario: Ein Tutorial zeigt, wie eine KI in 20 Minuten eine saubere Anwendung erstellt – doch im echten Projekt wartet ein monolithischer Codeberg mit undokumentierter Logik, überladenen Tabellen und unzähligen Inkonsistenzen.

Das nennt man ein Brownfield-Projekt. Und hier versagt die KI – es sei denn, man setzt Spec-Driven Development (SDD) richtig ein. Nicht als revolutionäre Methode für neue Projekte, sondern als taktisches Werkzeug für jeden einzelnen Change.

Warum SDD in Brownfield-Projekte passt

Die häufigste Fehleinschätzung ist, SDD mit grünen Wiesen-Projekten zu verbinden. Doch SDD ist kein Framework für den Projektstart – sondern für jeden Code-Change, den du heute, morgen oder nächste Woche vornimmst. Jede neue Funktion, jeder Bugfix, jede Modifikation an bestehendem Code.

Der Schlüssel liegt im Perspektivwechsel: SDD zwingt dich, den aktuellen Zustand des Systems präzise zu beschreiben – bevor du ihn änderst. Das löst drei zentrale Probleme in Brownfield-Projekten:

• Transparenz statt Blackbox: Viele Teams arbeiten seit Jahren mit Systemen, deren Funktionsweise niemand genau kennt. SDD erzwingt Klarheit: Was tut der Code aktuell? Welche Nebenwirkungen hat er? Diese Dokumentation bleibt im Repository und wird mit jeder weiteren Spec aktualisiert.
• Präzise KI-Anweisungen: Ein häufiger Frustpunkt bei der KI-Unterstützung ist, dass Agenten unkontrolliert Code modifizieren. Eine gut strukturierte Spec definiert klare Grenzen: Was darf der Agent ändern? Was bleibt unberührt? Das reduziert ungewollte Seiteneffekte drastisch.
• Automatische Validierung: Eine Spec beschreibt nicht nur das gewünschte Verhalten, sondern auch Invarianten – Bedingungen, die nach dem Change weiterhin gelten müssen. Diese Regeln lassen sich als Tests umsetzen, was Regressionen vorbeugt.

Die Vorteile, die niemand erwartet

Neben den offensichtlichen Verbesserungen bringt SDD drei unmittelbare Nebeneffekte mit sich, die oft unterschätzt werden:

1. Wissen wird institutionalisiert

Jede Spec, die du für einen Change schreibst, ist nicht nur eine Anleitung für den Agenten – sondern Dokumentation für das gesamte Team. Statt in Confluence oder Notion zu verschwinden, bleibt sie direkt im Code-Repository. Mit der Zeit entsteht so eine lebendige Wissensbasis, die Onboarding-Prozesse beschleunigt und Wissenstransfer überflüssig macht.

2. Codequalität verbessert sich schleichend

SDD zwingt dich, über Architekturgrenzen nachzudenken. Wenn du für jeden Change zunächst den aktuellen Zustand dokumentierst, erkennst du schnell redundante Logik, veraltete Patterns oder überladene Module. Zwar ersetzt SDD keine gezielte Refaktorisierung – aber es macht technische Schulden sichtbar, bevor neue entstehen.

3. KI wird zum kontrollierten Werkzeug

Agenten wie GitHub Copilot oder Cursor funktionieren am besten, wenn sie konkrete Spezifikationen erhalten. Eine gut geschriebene Spec reduziert die Notwendigkeit manueller Code-Review und minimiert das Risiko von Fehlanpassungen. Der Agent wird zum verlängerter Arm des Entwicklers – nicht zum unberechenbaren Autopiloten.

Wo SDD an seine Grenzen stößt

Es wäre unrealistisch, SDD als Allheilmittel zu betrachten. Drei typische Fallstricke solltest du kennen:

1. SDD löst keine strukturellen Probleme

Wenn dein Codebase aus einem 800-Zeilen-Modul mit verstreuten Seiteneffekten besteht, hilft dir eine Spec zwar, sichere Änderungen daran vorzunehmen – aber das Modul bleibt ein Wartungstrauma. SDD ist kein Ersatz für gezielte Refaktorisierung, sondern ein Werkzeug zur Risikominimierung während des Changes.

2. Ohne Tests ist die Spec nur ein Dokument

Eine Spec beschreibt das gewünschte Verhalten – aber sie garantiert es nicht. Erst wenn diese Spezifikationen in automatisierte Tests überführt werden (z. B. als Contract Tests oder Integrationstests), wird aus der Theorie Praxis. Ohne Tests ist SDD nur halb so wertvoll.

3. Großflächige Dokumentation ist kein Sprint

Wenn du versuchst, ein fünf Jahre altes Monolithen-System vollständig zu spezifizieren, bevor du überhaupt einen Change vornimmst, wirst du scheitern. Die Lösung liegt nicht in der perfekten Dokumentation – sondern im iterativen Ansatz: Beginne mit den kritischen Pfaden, die du gerade änderst, und baue die Specs Change für Change aus.

Die Schritt-für-Schritt-Strategie für Brownfield-Projekte

Der häufigste Fehler ist, SDD als Großprojekt anzugehen. Erfolgreich ist stattdessen ein agiler, minimalistischer Ansatz, der sich in den Entwicklungsflow integriert. So geht’s:

Schritt 1: Definiere den kleinstmöglichen Scope

Beginne nicht mit dem gesamten Modul – sondern mit der einzelnen Funktion oder Klasse, die du ändern willst. Je kleiner der Scope, desto:

• einfacher ist die Spec zu schreiben,
• geringer ist das Risiko von Regressionen,
• höher ist die Chance, dass du die Spec tatsächlich umsetzt.

Ein Beispiel: Statt zu versuchen, die gesamte Benutzerverwaltung zu spezifizieren, konzentriere dich auf die neue Validierungslogik für E-Mail-Adressen in einem bestimmten Formular.

Schritt 2: Dokumentiere den aktuellen Zustand – nicht den gewünschten

Das ist der entscheidende Unterschied zu vielen SDD-Ansätzen. Bevor du beschreibst, was der Code tun soll, musst du festhalten, was er aktuell tut. Das bedeutet:

• Genauigkeit über Abstraktion: Nicht "Das Formular validiert Eingaben", sondern:
• Welche Felder werden geprüft?
• Welche Validierungsregeln gelten?
• Welche Fehler werden zurückgegeben?
• Welche Nebenwirkungen hat die Validierung?
• Beispielbasierte Spezifikation: Gib konkrete Input-Output-Paare an, die das aktuelle Verhalten illustrieren.

Dieser Schritt zwingt dich, das System tatsächlich zu verstehen – und deckt oft versteckte Annahmen oder Inkonsistenzen auf.

Schritt 3: Spezifiziere den gewünschten Change – inklusive Grenzen

Jetzt beschreibst du, was sich ändern soll. Wichtig:

• Fokus auf das Delta: Was ist der Unterschied zum aktuellen Zustand?
• Out-of-Scope definieren: Welche Teile des Systems dürfen nicht berührt werden?
• Invarianten festhalten: Welche Bedingungen müssen nach dem Change weiterhin gelten?

Ein Beispiel für eine klare Spec:

**Change**: Neue E-Mail-Validierung für das Anmeldeformular

**Aktueller Zustand**:
- Validiert nur auf leere Eingaben
- Akzeptiert alle Zeichenketten mit '@'
- Keine Prüfung auf Top-Level-Domains

**Gewünschter Zustand**:
- Validiert auf RFC 5322 (E-Mail-Format)
- Blockiert bekannte Spam-Domains (z. B. mailinator.com)
- Rückgabe spezifischer Fehlercodes für jede Validierungsstufe

**Out of Scope**:
- Änderungen an der Datenbank-Struktur
- Anpassungen an der Authentifizierungslogik

**Invarianten**:
- Die Speicherung der E-Mail-Adresse bleibt unverändert
- Die bestehende Benutzer-ID-Generierung wird nicht modifiziert

Schritt 4: Implementiere und validiere automatisch

Mit der Spec als Leitfaden kannst du nun:

• den Agenten oder dich selbst bei der Implementierung führen,
• die neuen Regeln direkt als Tests umsetzen (z. B. mit Jest, Pytest oder Jest),
• die Änderungen in kleinen Schritten deployen und überwachen.

Fazit: SDD als evolutionsfähiges Framework

Spec-Driven Development ist kein Heiliger Gral – aber es ist eine pragmatische Methode, um Brownfield-Projekte ohne radikale Refaktorisierung sicherer und nachvollziehbarer zu machen. Der Schlüssel liegt im iterativen Aufbau:

• Beginne mit kleinen Changes und erweitere die Specs schrittweise.
• Nutze die Dokumentation nicht als Last, sondern als Investition in die Zukunft.
• Kombiniere SDD mit automatisierten Tests, um echte Qualitätssicherung zu erreichen.

In einer Welt, in der Legacy-Code und KI-Tools aufeinandertreffen, ist SDD kein Luxus – sondern eine Überlebensstrategie. Und die beste Nachricht: Du musst nicht warten, bis das Projekt perfekt ist, um damit zu beginnen.

Die ersten drei Specs, die du für deine nächsten Changes schreibst, werden bereits einen spürbaren Unterschied machen.