Schreib eine Spec pro auslieferbarer Verhaltensänderung. In einer McKinsey-Umfrage von 2023 unter 1.994 Führungskräften aus 105 Ländern gaben 42 % an, generative KI-Tools regelmäßig in mindestens einem Unternehmensbereich zu nutzen. Das macht kleine, klare Specs wertvoller, denn Agents kommen mit abgegrenzter Arbeit besser zurecht als mit ausufernden Milestones.

Ein Großteil des Gegenwinds gegen Spec-driven Development ist verdient. Man nennt es „Wasserfall mit Markdown“, eine Produktivitätsfalle, eingefrorene Doku, Token verbrennende Zeremonie. Das passiert, wenn die Spec die falsche Größe hat. Ist sie zu groß, verliert sich dein Coding-Agent in matschigen Zielen. Ist sie zu klein, fehlt ihm der Kontext, der die Änderung stimmig macht.

Die nützliche Regel ist einfach. Schreib die kleinste Spec, die du noch als eine eigenständige Änderung reviewen würdest. Nicht standardmäßig einen Milestone. Nicht ein Dokument pro winzigem Task. Eine auslieferbare Verhaltensänderung.

Diese Spannung taucht ständig auf, wenn du mit Cursor, Claude Code, Codex oder Gemini baust. Jemand auf Reddit, der Spec-driven Development mit AI Agents zum Laufen bringen wollte, hat es klar formuliert: „Die größte Hürde ist für mich, den richtigen Detailgrad zu finden. Zu vage, und die KI halluziniert; zu detailliert, und ich kann den Code genauso gut selbst schreiben.“ Das ist das Problem – nicht die Frage, ob Specs abstrakt betrachtet gut sind. Wenn du an die Grenzen von Vibe Coding und die Prompting Wall gestoßen bist, die viele zu SDD gebracht haben, ist die Granularität meist der Engpass.

Inhalt

Warum Spec-Granularität der neue Engpass ist

Die Qualität einer Spec ist weniger wichtig, als oft angenommen wird. Die Größe der Spec ist wichtiger.

Wenn das Dokument ein ganzes Release abdeckt, hat dein AI Agent kein klares Ziel. Akzeptanzkriterien werden zu Stakeholder-Sprache. Das Testen wird unscharf. Der Agent fängt an zu raten – über zu viele Dateien, zu viele Annahmen, zu viele versteckte Abhängigkeiten hinweg.

Ist das Dokument zu kleinteilig, bekommst du den umgekehrten Fehler. Du verteilst ein zusammenhängendes Verhalten auf fünf Mini-Specs. Der Agent folgt jeder einzelnen präzise und verfehlt die eigentliche Absicht.

Praktische Regel: Wenn du den entstehenden Code nicht als eine Änderung in PR-Größe reviewen würdest, hat die Spec wahrscheinlich die falsche Größe.

Viele Teams machen einen typischen Fehler: Sie übertragen die Anforderungsgewohnheiten menschlicher Teams auf Workflows mit AI Agents. Menschen können fehlenden Kontext aus Meetings, der Code-Historie und Gesprächen auf dem Flur erschließen. Agents nicht. Sie brauchen Grenzen, keine Zeremonie.

Die Literatur zum Requirements Engineering gibt ein besseres Ziel vor als der Großteil der Debatte über KI-Tooling. Das IREB definiert Granularität als den Detailgrad einer Anforderungsbeschreibung und empfiehlt eine Ebene, die die „beste Referenz für eine eindeutige Definition des Software-Scopes“ ist, in seinem Artikel über funktionale Anforderungen und ihre Granularitätsebenen. Das ist der richtige Maßstab. Nicht detailliert um seiner selbst willen. Detailliert genug, dass der Scope eindeutig ist.

Die drei Ebenen der Spec-Granularität

Eigentlich gibt es drei nützliche Ebenen. Alles andere ist eine Variante davon.

Ein Diagramm der drei Granularitätsebenen von Specs: Milestone-, Subsystem- und Feature-Specs.

Feature-Spec

Eine Feature-Spec definiert eine Verhaltensänderung, die im Produkt oder im System sichtbar ist und die du für sich allein ausliefern und prüfen kannst.

Beispiel: Auf dem Login-Screen einen „Passwort vergessen“-Link samt funktionierendem Einstieg in den Reset-Flow ergänzen.

Subsystem-Spec

Eine Subsystem-Spec deckt einen abgegrenzten Bereich des Systems ab, in dem mehrere zusammenhängende Änderungen gemeinsamen Kontext brauchen.

Beispiel: das gesamte Subsystem zur Passwort-Wiederherstellung neu gestalten, inklusive Token-Handling, E-Mail-Templates, Audit-Logging und Regeln für Admin-Resets.

Ein Vergleich mit einem Haus passt hier. Das ist der Plan für die Wasserleitungen, nicht ein einzelner Wasserhahn.

Ein nützlicher Bezugspunkt für Grenzen ist Addy Osmanis Leitfaden für eine gute Spec für AI Agents, besonders sein dreistufiges System für Grenzen. Es bringt dich dazu festzulegen, was der Agent immer tun darf, was eine Freigabe braucht und was er nie tun darf.

Wenn du das mentale Modell verinnerlicht hast, lohnt sich das kurze Video unten.

Milestone-Spec

Eine Milestone-Spec definiert ein Ergebnis, keinen Ausschnitt der Implementierung.

Beispiel: V1 der Authentifizierung für den Beta-Launch ausliefern.

Für die Planung kann das nützlich sein. Als direkter Input für einen KI-Coding-Agent taugt es meistens nicht.

Ebene Am besten für Risiko
Feature Implementierung und Tests zu eng, wenn die Änderung querschnittlich ist
Subsystem koordinierte Änderungen in einem abgegrenzten Bereich kann ausufern, wenn der Scope nicht gedeckelt ist
Milestone Planung und Reihenfolge zu vage, um direkt zu coden

Die Standardregel: eine Spec pro auslieferbarer Änderung

Nimm standardmäßig Specs auf Feature-Ebene.

Eine Infografik zur Standardregel in der KI-Entwicklung: eine Feature-Spec pro auslieferbarer Änderung.

Das beste Argument dafür ist nicht Geschmack. Es ist die Physik der Auslieferung. In der DORA-Forschung von 2023 wurden Elite-Teams über eine Deployment-Leistung von mehr als 1.000 Deployments pro Jahr definiert, während die schwächsten Teams zwischen null- und einmal pro Monat deployten. Dieselbe Arbeit brachte kleinere Batches mit besserem Fluss und geringerem Risiko in Verbindung, wie dieser Artikel über granulare Statistiken und kleinere Auslieferungs-Batches zusammenfasst.

Eine Feature-Spec passt sauber zu einem kleinen Batch. Eine Milestone-Spec meistens nicht.

Mit KI-Coding-Agents ist das noch wichtiger. Je breiter die Spec, desto wahrscheinlicher ist es, dass der Agent:

  • Klebelogik erfindet, die Änderungen ohne Bezug zueinander verbindet
  • Akzeptanzkriterien verwischt, bis nur vage „fertig“-Zustände übrig sind
  • in einem Durchgang zu viele Dateien anfasst
  • in einem breiten Rundumschlag bei der Implementierung Fehler versteckt

Wenn du die kürzeste Fassung davon willst, was Spec-driven Development wirklich ist, dann diese: Du gibst dem Agent ein abgegrenztes Ziel mit klarer Validierung, keinen großen Traum mit unausgesprochenen Schritten.

Was als eine Spec zählt

Nimm eine Spec, wenn die Änderung Folgendes hat:

  • Eine reviewbare Absicht. Das Code Review hat eine Hauptfrage.
  • Eine stimmige Akzeptanzfläche. Du kannst sagen, wie Erfolg aussieht, ohne Ergebnisse zu vermischen, die nichts miteinander zu tun haben.
  • Eine Rollback-Geschichte. Wenn es schiefgeht, weißt du, was du zurücknimmst.
  • Eine offensichtliche Testgrenze. Die Änderung lässt sich als Einheit prüfen.

Eine gute Feature-Spec ist meist das Kleinste, das du benennen kannst, ohne „und außerdem“ zu sagen.

Drei konkrete Beispiele

  1. Kleine Änderung Ein Tastenkürzel ergänzen, das die Command Palette öffnet.
    Eine Spec. Klares Verhalten. Einfache Tests.

  2. Vertikaler Schnitt Neue Accounts sollen sich registrieren, ihre E-Mail bestätigen und auf dem Onboarding-Screen landen können.
    Immer noch eine Spec, wenn der ganze Flow ein auslieferbares Verhalten ist. Teil ihn nur auf, wenn du die Teile unabhängig voneinander reviewen und ausliefern würdest.

  3. Querschnittliches Refactoring Das alte Parsing von Auth-Tokens in API-Middleware, Jobs und Admin-Tools ersetzen.
    Keine Feature-Spec. Das verlangt wahrscheinlich einen Subsystem-Scope.

Ausnahmen: Wann du herauszoomst

Regeln sind nützlich, weil sie klare Ausnahmen haben.

Eine Infografik, die zeigt, wann Subsystem- oder Milestone-Specs für breite, weitreichende Produktvorhaben passen.

Wann Subsystem besser ist als Feature

Nimm eine Subsystem-Spec, wenn der Agent gemeinsamen Architekturkontext braucht, damit er keine lokalen Optimierungen baut, die die Änderung als Ganzes kaputt machen.

Typische Fälle:

  • Querschnittliches Refactoring. Beispiel: der Wechsel von einem Datenzugriffsmuster zu einem anderen über mehrere Module hinweg.
  • Neugestaltung eines gemeinsamen Vertrags. Beispiel: Regeln für Validierung, Speicherung und Serialisierung gemeinsam ändern.
  • Kernverhalten der Plattform. Beispiel: Berechtigungen, Caching oder die Ausführung von Hintergrundjobs überarbeiten.

In der Sprache des Systems Engineering entspricht das der Trennung zwischen Grob- und Feinentwurf. Die FHWA-Leitlinien unterscheiden zwischen der Festlegung, WAS Subsysteme tun müssen, und WIE Komponenten funktionieren, und das passt hier genau, nachzulesen im Abschnitt über Anforderungs-Traceability und Entwurfsebenen. Milestones und der Blick aufs Subsystem helfen beim WAS. Feature-Specs helfen dem Agent, das WIE umzusetzen.

Wann Milestone beide schlägt

Nimm eine Milestone-Spec, wenn sich die Details noch bewegen und die Hauptaufgabe Planung, Reihenfolge und Risikokontrolle ist.

Gute Fälle für Milestones:

  • Das frühe Grundgerüst eines Produkts
  • Ein Ziel für den Beta-Launch
  • Ein breites Ergebnis mit mehreren unbekannten Wegen zur Implementierung

Milestone-Specs sind nicht das Ende. Sie sind der Anfang. Du nutzt sie, um die Grenzen des Ergebnisses festzulegen, und zerlegst die Implementierung dann in Subsystem- oder Feature-Specs.

Gib einem Coding-Agent keine Milestone-Spec direkt in die Hand und erwarte saubere Ergebnisse. So bekommst du vagen Code, der an vagen Zielen hängt.

Die einfache Aufteilung sieht so aus:

  • Milestone-Specs verringern Unklarheit in der Planung
  • Subsystem-Specs verringern Hin und Her in der Architektur
  • Feature-Specs verringern Nacharbeit bei der Implementierung

Ein praktisches Spec-Template für AI Agents

Eine gute Spec für einen KI-Coding-Agent braucht Struktur, keine Masse.

Ein Diagramm eines AI-Agent-Blueprints mit zentralen Bausteinen wie Inputs, Logik, Gedächtnis, Tools und Sicherheit.

Das Template

Nimm das hier:

  1. TL;DR
    Ein Satz. Was ändert sich?

  2. Scope-Grenzen
    Nutze Addy Osmanis drei Kategorien aus seinem Spec-Leitfaden:

    • Immer tun
      Sichere Standards, denen der Agent folgen soll
    • Erst fragen
      Änderungen, die eine Freigabe brauchen
    • Nie tun
      Harte Grenzen

  3. Teilaufgaben
    Kurze Checkliste. Logische Reihenfolge, kein Aufsatz.

  4. Akzeptanzkriterien
    Beobachtbare Ergebnisse. Keine vagen Formulierungen wie „funktioniert gut“.

  5. Annahmen und Risiken
    Was du für wahr hältst. Was kaputtgehen könnte.

  6. Validierungsszenarien
    Manuelle Checks oder Testfälle, die die Änderung belegen.

Wenn du einen strukturierten Ausgangspunkt willst, ist ein schlichtes Product Requirements Document Template besser als eine leere Markdown-Datei.

Für alle, die sich das breitere Handwerk der AI-Agent-Entwicklung ansehen, ist die Lektion dieselbe. Agents arbeiten besser, wenn das Artefakt, das sie verarbeiten, explizite Constraints, explizite Tests und explizite Fehlergrenzen hat.

Granularität anpassen, während dein Prozess reift

Birgitta Böckeler beschreibt in ihrer Analyse von Spec-driven Development auf Martin Fowlers Website einen Reifepfad von spec-first über spec-anchored zu spec-as-source. Das ist für die Granularität wichtig.

Am Anfang schreibst du oft gröbere Specs, weil dein System und dein Workflow noch instabil sind. Später kannst du feiner werden, weil du deinen Grenzen, Tests und deinem Review-Prozess vertraust.

Das ist normal. Schief geht es, wenn du so tust, als wäre dein Prozess reif, obwohl er es nicht ist.

Deinen Spec-driven Workflow aufbauen

Du brauchst kein riesiges Framework, damit das funktioniert. Du brauchst einen wiederholbaren Loop.

Screenshot von https://tekk.coach

Die manuelle Variante

Viele Solo Builder machen das mit:

  • Markdown-Dateien in /specs
  • GitHub Spec Kit
  • OpenSpec
  • Kiro
  • Traycer
  • Vibe Kanban
  • Workflows im BMAD-Stil

Dieser Weg funktioniert. Er erzeugt aber auch Drift, wenn du schlampig bist.

Der Loop ist einfach:

  • Schreib die Spec
  • Gib sie an Cursor, Claude Code, Codex oder Gemini
  • Prüf das Ergebnis gegen die Akzeptanzkriterien
  • Aktualisier die Spec, wenn sich die Annahmen geändert haben
  • Liefere aus oder teil weiter auf

Zur Kritik: Das Anti-Spec-Lager hat teilweise recht. Wenn du Specs einfrierst, verrotten sie. Wenn du zu viel festlegst, schreibst du Pseudocode mit Extraschritten. Wenn du die Akzeptanzkriterien weglässt, promptest du nur mit hübscherer Formatierung.

Die Variante mit klarer Meinung

Wenn du weniger von Hand aufsetzen willst, nimm ein Tool, das sich auf das Erzeugen von Specs und auf Repo-Kontext konzentriert, nicht auf magische Versprechen voller Automatisierung.

Tekk.coach passt zu diesem engeren Job. Die Spec ist seine Arbeitseinheit. Es verbindet sich mit deinem GitHub-Repo, und seine Loops lesen, was sich geändert hat, und schreiben die Spec für dich als Proposal – höchstens eines pro Lauf, so zugeschnitten, dass es ein zusammenhängendes Stück Arbeit ist. Gibst du es mit Greenlight frei, landet es mit Akzeptanzkriterien und einer Checkliste auf deinem Board; du kannst auch selbst eine Spec von Hand schreiben. Dein Coding-Agent (Cursor, Claude Code, Codex) baut sie über den Tekk-MCP-Server. Tekk schreibt den Code nicht und öffnet auch keinen PR; der PR, in dem Closes TEK-123 steht, schließt die Spec mit seinem Merge.

Diese engere Form ist die richtige für Solo Builder. Bessere Spec rein. Besserer Agent-Output raus.

Specs von Hand zu schreiben ist der manuelle Weg. Die Loops von Tekk.coach schreiben sie für dich aus dem, was sich in deinem Code geändert hat: dasselbe Board, dieselben Akzeptanzkriterien, geschlossen mit dem Merge des PRs.

Teil des Leitfadens zu Spec-driven Development – ein ehrliches Playbook dafür, mit KI-Coding-Agents auszuliefern. Die andere Hälfte ist Loop Engineering: An der Spec erkennt ein Loop, dass er fertig ist.