Die meisten Ratschläge zu Specs für AI Agents sind verkehrt herum.

Man sagt dir, du sollst mehr schreiben. Mehr Details. Mehr Planung. Mehr Dokumente. Mehr Templates. Und dann wundert man sich, wenn Leute Spec-driven Development „Wasserfall mit Markdown“ nennen oder sich über eingefrorene Docs, Spec Drift und Zeremonien beschweren, die Tokens verbrennen. Sie liegen nicht falsch.

Die Lösung ist nicht, Specs aufzugeben. Die Lösung ist, keine aufgeblähten mehr zu schreiben.

Eine gute Spec für KI-Arbeit ist eine minimale Spec. Nicht vage. Nicht faul. Minimal im strengen Sinn: Behalte nur die Einschränkungen, die für einen korrekten Build nötig sind. Das deckt sich mit der alten Designregel für Standards der Free Software Foundation Europe, „Entferne alles, was nicht absolut notwendig ist“ – ein Prinzip, das sie bei technischen Formaten mit Effizienz, Erlernbarkeit, Einfachheit und Langlebigkeit verbindet, mit offenen Standards als Basis für Interoperabilität und langfristigen Zugang in Systemen wie dem Web (FSFE über minimalistische Standards).

Meine Sicht ist einfach. Sechs Abschnitte, in dieser Reihenfolge.
(1) TL;DR.
(2) Scope.
(3) Teilaufgaben.
(4) Annahmen.
(5) Validierung.
(6) Offene Fragen.
Sonst nichts. Alles darüber hinaus ist meist Zeremonie.

Inhalt

Specs sind eine Falle – und warum minimale Specs der Ausweg sind

Der Gegenwind ist verdient.

Wenn du schwergewichtige Spec-Workflows ausprobiert hast, hast du den Bremsklotz wahrscheinlich gespürt. Du bittest einen Agent um ein Feature und liegst am Ende begraben unter Verfassungen, Plänen, Aufgabenbäumen und Markdown, das niemand noch einmal lesen will. GitHub Spec Kit hat diesen Stil in den Mainstream gebracht, und die Kritik ist vorhersehbar, weil vieles davon fair ist. Manche auf Reddit beschreiben diesen Workflow offen als erschöpfend und zu schwer für das tägliche Ausliefern, vor allem, wenn du allein bist und das Reviewen der Docs mehr kostet als das Reviewen des Codes selbst (OpenAIDev-Thread über den Overhead von Spec Kit).

Das heißt nicht, dass Specs das Problem sind. Aufblähung ist das Problem.

Die nützliche Frage ist nicht „Solltest du Specs schreiben?“. Sondern: „Was ist die kleinste Spec, die Nacharbeit noch verhindert?“ Diese Grenze ist wichtig. Die ursprüngliche Min-Specs-Methode ist da unverblümt. Fang mit einer längeren Liste an Muss- und Darf-nicht-Regeln an und streich dann jede Regel, die sich brechen lässt, ohne den Kernzweck zu verlieren. Das Schwierige: Teams hören oft genau dort auf und testen nie, ob eine Regel unverzichtbar ist. Das Ergebnis ist entweder eine schwammige Unterspezifizierung oder eine zeremonielle Überspezifizierung. Liberating Structures sagt genau das und weist auch darauf hin, dass Mehrdeutigkeit und unvollständige Anforderungen Nacharbeit verursachen – deshalb muss „minimal“ diszipliniert sein und nicht bloß kurz (Min-Specs-Methode).

Der Gegenwind zielt auf das Falsche

Kluge Kritik sagt nicht „Klarheit ist schlecht“. Sie sagt, dass das Ganze schnell zu Prozesstheater wird.

Birgitta Böckelers Taxonomie hilft hier. Spec-first, spec-anchored und spec-as-source sind nicht dasselbe. Viel vom Gegenwind richtet sich eigentlich gegen die starrste Version, in der die Spec zum Mittelpunkt des Universums wird und jede Änderung durch ein Markdown-Ritual muss. Das ist eine berechtigte Sorge. Specs können einfrieren. Sie können driften. Sie können zu Compliance-Artefakten werden statt zu Arbeitsdokumenten.

Praxisregel: Wenn das Prüfen der Spec länger dauert als das Prüfen des Codes, hast du schon verloren.

Minimale Specs lösen das eigentliche Problem

Eine minimale Spec ist nicht gegen Agilität. Sie ist gegen Rauschen.

Deshalb kommt Addy Osmanis sechsteilige Struktur in der Praxis so gut an. Sie ist klein genug, um sie im Kopf zu behalten, und konkret genug, um sie umzusetzen. Sie gibt dem Agent Grenzen und dir eine Fläche fürs Review, die nicht absurd ist. Du kannst weiterhin iterieren. Du kannst den Scope weiterhin mitten im Flug kürzen. Du kannst schlechten Code weiterhin wegwerfen.

Womit du aufhörst: so zu tun, als wäre ein riesiger Planungsstapel Fortschritt.

Die Struktur mit sechs Abschnitten

Addy Osmanis kanonische Fassung ist die sauberste, die ich kenne: Schreib die Spec wie ein Arbeits-Briefing, nicht wie ein Konzernartefakt. Es geht darum, dem Agent genug Struktur zum Handeln zu geben, ohne den Prompt mit Ballast zu füllen, den er nicht braucht (Addy Osmani darüber, wie man eine gute Spec für AI Agents schreibt).

Ein Diagramm der sechs wesentlichen Abschnitte eines minimalen Spec-Dokuments für ein Projekt.

Warum sechs Abschnitte reichen

Diese Struktur würde ich für fast jedes Feature nutzen:

  1. TL;DR
    Ein Absatz. Was du baust, warum es wichtig ist und das zentrale Ergebnis.

  2. Scope
    Zwei Listen: Wird gebaut und Wird nicht gebaut. Das killt versehentlichen Scope Creep früh.

  3. Teilaufgaben
    Eine kleine Zahl vertikaler Slices. Jeder sollte Akzeptanzkriterien und, wo möglich, Dateiverweise enthalten.

  4. Annahmen
    Was du für wahr hältst, nach Risiko markiert. Bricht eine Annahme, ändert sich der Build.

  5. Validierung
    End-to-End-Szenarien. Keine vagen „teste das“-Notizen. Konkrete Prüfungen, die ein Mensch durchführen kann.

  6. Offene Fragen
    Ungeklärte Entscheidungen, die die Umsetzung blockieren oder zu falschen Entscheidungen führen können, wenn sie implizit bleiben.

Das reicht, weil auch eine minimale Spec die zentralen Kontrollen einer echten technischen Spec braucht. Die Empfehlungen aus der Branche sind bei den Grundlagen klar: Zweck und Scope, funktionale Anforderungen, technische Standards, Testanforderungen sowie Liefer- oder Support-Bedingungen sind die Schwelle für ein Dokument, aus dem man ohne ständige Rückfragen bauen kann (Heretto über technische Specs).

Was bewusst draußen bleibt

Du brauchst keine Fake-Executive-Summary. Du brauchst keinen erzählenden Hintergrund, außer er ändert die Umsetzung. Du brauchst keine Architektur-Fanfiction. Du brauchst keine Verfassung für ein Ein-Personen-Produktteam, das am Donnerstagabend einen Billing-Fix ausliefern will.

Viele Teams stopfen Specs voll, weil sie Vollständigkeit mit Nützlichkeit verwechseln.

Minimale Specs sind nicht zufällig kurz. Sie sind kurz, weil jede Zeile, die überlebt, einen Job hat.

Deshalb würde ich auch nicht blind die Infografik-Kategorien übernehmen, die oft für Projektdokumente genutzt werden, etwa Motivation, Ziele, Nicht-Ziele, Anforderungen, Meilensteine und offene Fragen. Die können als Linsen fürs Brainstorming helfen, aber für die Umsetzung mit AI Agents sind die sechs Abschnitte oben straffer. Sie bilden direkt ab, was der Agent als Nächstes braucht.

Ein Rezept ist ein besseres Modell als ein Manifest. Zutaten. Grenzen. Schritte. Prüfungen. Unbekannte. Fertig.

Warum AI Agents ein Gerüst brauchen, keinen Bauplan

AI Agents brauchen keinen Roman. Sie brauchen einen Rahmen.

Gibst du Cursor, Claude Code, Codex oder Gemini einen einzeiligen Prompt, bekommst du Rätselraten. Gibst du ihnen einen überladenen Planungsstapel, bekommst du Streuung. Das Modell beginnt, auf Details zu achten, die noch keine Rolle spielen, oder schlimmer: auf Details, die du hinzugefügt hast, weil sie verantwortungsvoll klangen. So verbrennst du Zyklen für Code, um den du nie gebeten hast.

Drei Roboter stehen für unterschiedlich erfolgreiche Projektplanung, von strukturiertem Bauen bis zu chaotischer Überladung.

Toleranzgrenzen schlagen Prompten nach dem Prinzip Hoffnung

Hier hilft eine Analogie aus dem Qualitätsmanagement. In der statistischen Prozesslenkung sind Toleranzgrenzen die von außen festgelegten Anforderungen, während Eingriffsgrenzen aus dem Prozessverhalten abgeleitet und üblicherweise bei ±3 Sigma vom Mittelwert gesetzt werden. Die Unterscheidung ist wichtig, weil sie trennt, „was wahr sein muss“ und „was normalerweise passiert“ (6Sigma über Toleranz- und Eingriffsgrenzen).

Genau das leistet eine minimale Spec für KI-Arbeit. Sie legt die kleinste Menge wesentlicher Grenzen fest, die bestimmen, ob der Output akzeptabel ist.

Ohne diese Grenzen führst du keinen Agent. Du hoffst.

Eine gute minimale Spec beantwortet Fragen wie:

  • Was existieren muss: ein Button, ein Endpoint, eine Migration, ein State-Update
  • Was nicht passieren darf: Schema-Änderungen, zusätzliche UI-Zustände, neue Abhängigkeiten
  • Was als fertig gilt: sichtbares Verhalten, erwartete API-Antwort, Bedingung für bestandene Tests
  • Was eine menschliche Antwort braucht: offene Entscheidungen zu Produkt oder Edge Cases

Das ist ein Gerüst. Es reicht, um den Bau zu stützen. Es ist kein fertiger Bauplan.

Warum das in echten Agent-Workflows besser funktioniert

In der Praxis willst du, dass der Agent in einer schmalen Spur arbeitet. Diese Spur wird noch klarer, wenn deine Spec messbare Anforderungen und explizite Schnittstellenvorgaben enthält. Gute Leitfäden für technische Specs drängen genau darauf: Endpoint-Parameter, Fehlercodes, Rate Limits, Timeout-Parameter, Versionierungsregeln, Abwärtskompatibilität und Testverfahren. Solche Details verringern den Interpretationsspielraum und machen Validierung zu etwas Objektivem statt Verhandelbarem (Docsie-Glossar zu technischen Specs).

Das zählt auch jenseits der Code-Generierung. Wenn du Browser-Flows testen, Seiten mit Zustand scrapen oder sichtbares Verhalten validieren musst, kombinierst du einen Coding-Agent vielleicht mit Tools, mit denen du mit diesem KI-Browser-Agent bauen kannst. Es geht nicht um Tool-Hype. Es geht darum, dass bessere Specs jedes nachgelagerte Tool weniger verwirren.

Für die tägliche Umsetzung ist das bessere Muster meist eine Planungsschicht plus eine Coding-Schicht. Halte die Spec stabil genug, um die Umsetzung zu leiten, und gib sie dem Coding-Agent dann in fokussierten Häppchen. Wenn dein aktueller Workflow locker und chatgetrieben ist, hilft ein Spec-first-Durchgang oft mehr, als noch einen riesigen Prompt auf den Stapel zu legen. Die Mechanik ähnelt dem Ansatz in diesem Guide zu einem AI-Agent-Workflow, um Features auszuliefern.

Baupläne versuchen, alles vorab zu beantworten. Ein Gerüst beantwortet nur, was wahr sein muss, bevor die Arbeit beginnt.

Dieser Unterschied ist der Grund, warum minimale Specs den Kontakt mit echter Produktarbeit überleben.

Anatomie einer minimalen Spec

Das minimale Spec-Format funktioniert nur, wenn jeder Abschnitt sein Gewicht trägt. Ist ein Abschnitt vage, muss ein anderer die Mehrdeutigkeit auffangen – und genau dann beginnt das Dokument aus den falschen Gründen zu wachsen.

Die sechs Teile, die zählen

1. TL;DR

Das ist die Version des Builds in einem einzigen Absatz. Sie sollte in einfacher Sprache sagen, was sich ändert, warum es wichtig ist und woran man den Erfolg erkennt.

Gutes Beispiel:
„Füge Blogposts einen Like-Button hinzu: Wer angemeldet ist, kann einen Post liken und das Like wieder entfernen. Speichere die Reaktion, zeig die aktualisierte Anzahl sofort an und verhindere doppelte Likes vom selben Account.“

Schlechte TL;DRs klingen wie Klappentexte für ein Projekt. Gute klingen nach Umsetzungsabsicht.

2. Scope

Hier ziehst du harte Kanten. Nutze Wird gebaut und Wird nicht gebaut. Wenn du das überspringst, erfindet der Agent benachbarte Features, weil sie sich naheliegend anfühlen.

Gutes Beispiel:

  • Wird gebaut: Liken und Like entfernen, Anzeige der Anzahl, Prüfung auf Anmeldung
  • Wird nicht gebaut: Dislikes, Auswertungen der Reaktionen, Benachrichtigungs-E-Mails

Kurz ist hier gut. Scharf ist besser.

3. Teilaufgaben

Das ist der Kern der Umsetzung. Zerleg die Arbeit in vertikale Slices. Füg Dateiverweise hinzu, wenn du sie kennst. Jede Teilaufgabe braucht Akzeptanzkriterien, sonst ist sie nur ein To-do im schickeren Hemd.

Gutes Beispiel:

  • POST /api/posts/:id/like hinzufügen
  • PostFooter.tsx aktualisieren, damit der aktuelle Like-Status gerendert wird
  • Persistenzlogik in likes.repository.ts hinzufügen

Jede Teilaufgabe sollte sich unabhängig reviewen lassen.

Wie guter Minimalismus in der Praxis aussieht

4. Annahmen

Annahmen verhindern, dass sich versteckte Entscheidungen in den Code schleichen. Markiere sie nach Risiko. Ich mag Niedrig, Mittel, Hoch, weil es dich zwingt zu bemerken, wenn das halbe Feature an einer Vermutung hängt.

Beispiele:

  • Niedriges Risiko: Wer eine Post-Seite sieht, ist bereits angemeldet
  • Mittleres Risiko: Der bestehende Post-Serializer kann die Like-Anzahl ohne Performance-Probleme zurückgeben
  • Hohes Risiko: Das aktuelle Schema unterstützt eindeutige Likes pro Account und Post ohne schmerzhafte Migration

Wenn eine Annahme fragil ist, benenne sie. Vergrab sie nicht im Fließtext.

5. Validierung

Genau hier scheitern schwache Specs meist. „Teste das Feature“ ist keine Validierung. Validierung sollte von einem Menschen ausführbar sein und so präzise, dass zwei Leute im Review zum selben Ergebnis kämen.

Nutze die Sprache von Szenarien:

  1. Eine angemeldete Person öffnet einen Post, den sie noch nicht geliked hat.
  2. Sie klickt auf Like.
  3. Der Button-Status ändert sich sofort, und die Anzahl steigt.
  4. Nach dem Neuladen der Seite bleibt der Like-Status erhalten.
  5. Ein erneuter Klick entfernt das Like und verringert die Anzahl.

Das reicht, damit ein Mensch oder ein Agent es prüfen kann.

6. Offene Fragen

Diesen Abschnitt gibt es, damit Unsicherheit sichtbar bleibt. Wenn du offene Fragen in den Annahmen versteckst, beantwortet der Agent sie gern stillschweigend.

Gute Beispiele:

  • Sollen alle die Anzahl sehen oder nur, wer angemeldet ist?
  • Löschen wir Likes per Soft Delete oder per Hard Delete?
  • Brauchen wir jetzt einen Index auf der Likes-Tabelle oder erst, wenn die Query-Latenz spürbar wird?

Eine harte Regel: Wenn eine Frage die Umsetzung wesentlich verändern kann, halte sie aus dem Hauptteil heraus und setz sie unter Offene Fragen.

Eine minimale Spec ist erst vollständig, wenn man auf dem Kernpfad daraus bauen kann, ohne immer wieder nachzufragen. Das heißt, die Umsetzungskontrollen zu erhalten, die zählen, und Kürze nicht mit Weglassen zu verwechseln. Wenn du eine ausführlichere Anleitung zum Aufbau einer vollständigen technischen Spec willst, lohnt es sich, diesen Guide dazu, wie man technische Specs schreibt, griffbereit zu haben.

Eine minimale Spec aus der Praxis für ein neues Feature

Schwere Specs scheitern ständig an kleinen Features. Das Fehlerbild ist vertraut: Leute verbringen mehr Zeit damit, das Dokument zu pflegen, als die Änderung auszuliefern, der Agent verbrennt Tokens, um offensichtlichen Kontext zu wiederholen, und die Spec driftet in dem Moment, in dem die Umsetzung auf die Codebase trifft.

Eine minimale Spec verdient sich ihren Platz, indem sie den Kontakt mit der Arbeit überlebt. Wenn dir dieses Beispiel fast zu kurz vorkommt, ist genau das der Punkt.

Eine visuelle Anleitung zur minimalen Spec-Struktur für ein Like-Button-Feature in Blogposts.

Beispiel-Spec

TL;DR
Füge jeder Blogpost-Seite einen Like-Button für angemeldete Accounts hinzu. Wer angemeldet ist, kann einen Post einmal liken, das eigene Like wieder entfernen und sieht, wie sich die Anzahl ohne komplettes Neuladen der Seite aktualisiert. Ziel ist einfaches Engagement-Feedback, kein umfassenderes System für Reaktionen.

Scope
Wird gebaut

  • Liken und Like entfernen für angemeldete Accounts
  • Sichtbare Like-Anzahl auf Blogpost-Seiten
  • Gespeicherter Like-Status pro Account und Post
  • Optimistisches UI-Update mit Rollback bei Fehlern

Wird nicht gebaut

  • Dislike-Button
  • Emoji-Reaktionen
  • Push- oder E-Mail-Benachrichtigungen
  • Dashboard mit Statistiken zu eigenen Posts
  • Anonyme Likes

Teilaufgaben

  1. Backend-Endpoint und Persistenz
    Anlegen und Löschen von Likes in app/api/posts/[id]/like/route.ts und Persistenzlogik in lib/likes.ts hinzufügen.
    Akzeptanzkriterien: Ein authentifizierter Request legt genau ein Like pro Account und Post an; ein wiederholter Like-Request erzeugt keine Duplikate; Unlike entfernt den bestehenden Eintrag; ein nicht authentifizierter Request gibt einen klaren Auth-Fehler zurück.

  2. Button-Status im Frontend
    components/PostActions.tsx aktualisieren, damit die aktuelle Anzahl und der Like-Status des Accounts gerendert werden.
    Akzeptanzkriterien: Wer angemeldet ist, sieht beim ersten Rendern korrekt den Status Like oder Liked; ein Klick schaltet den Status ohne Neuladen der Seite um; die Anzahl aktualisiert sich sofort; im Fehlerfall wird der vorherige UI-Zustand wiederhergestellt.

  3. Daten laden
    Den Loader der Post-Detailseite in lib/posts.ts erweitern, damit er likeCount und viewerHasLiked zurückgibt.
    Akzeptanzkriterien: Das Rendern der Seite enthält beide Werte; Seiten ohne angemeldeten Account zeigen weiterhin die Anzahl, aber keine interaktive Aktion.

Annahmen

  • Niedriges Risiko: Blogpost-Seiten haben bereits Zugriff auf die aktuellen Session-Daten.
  • Mittleres Risiko: Der bestehende Post-Loader lässt sich erweitern, ohne unbeteiligte Listenseiten anzufassen.
  • Hohes Risiko: Das aktuelle Datenbankschema unterstützt einen eindeutigen (user_id, post_id)-Constraint ohne Migrationskonflikte.

Validierung

  • Eine angemeldete Person öffnet einen Post, den sie noch nicht geliked hat, klickt auf Like und sieht, wie die Anzahl steigt und der Button auf Liked wechselt.
  • Sie lädt die Seite neu und sieht weiterhin Liked mit derselben Anzahl.
  • Sie klickt erneut, und die Anzahl sinkt.
  • Eine abgemeldete Person öffnet denselben Post, sieht die Anzahl und kann kein Like auslösen.
  • Doppelte Like-Versuche vom selben Account erzeugen nie mehr als ein aktives Like für denselben Post.

Offene Fragen

  • Soll, wer nicht angemeldet ist, einen deaktivierten Button sehen oder gar keinen?
  • Wollen wir für Likes eine Soft-Delete-Historie, oder reicht ein Hard Delete?
  • Brauchen wir für Post-Seiten mit viel Lesetraffic einen Index über den Unique-Constraint hinaus?

Warum dieses Beispiel funktioniert

Das ist der Detailgrad, den ich einem AI Agent und jemand anderem aus dem Engineering anvertraue. Er legt Verhalten, Einschränkungen, berührte Dateien und Fehlerbehandlung fest, ohne aus einem Feature mit zwei Zuständen ein Mini-Produkt-Briefing zu machen.

Der Trade-off ist gewollt. Ein schwereres Template wie GitHub Spec Kit kann nützlich sein, wenn mehrere Teams, Freigaben oder langlebige Designentscheidungen im Spiel sind. Für ein Feature wie dieses wird die zusätzliche Struktur meist zur Zeremonie. Das Team füllt Kästchen aus, weil das Template danach fragt, nicht weil die Umsetzung sie braucht.

Die minimale Version umgeht diese Falle.

Sie gibt dem Agent genug Gerüst, um selbstsicher zu handeln, aber nicht genug Raum, um in vorgetäuschte Vollständigkeit abzuschweifen. Der Scope schneidet benachbarte Ideen ab. Die Teilaufgaben bilden echte Code-Änderungen ab statt Übergaben im Organigramm. Die Annahmen benennen die Stellen, die am ehesten brechen. Die Validierungsschritte sind konkret genug, um Regressionen zu finden. Die offenen Fragen verhindern, dass ungeklärte Produktentscheidungen stillschweigend im Code getroffen werden.

Dieser letzte Punkt ist wichtiger, als manche, die für Specs werben, zugeben. Kluge Engineers wehren sich gegen Specs, weil aufgeblähte Specs schlecht altern. Sie erinnern sich an veraltete Anforderungen, vorgetäuschte Gewissheit und lange Dokumente, die niemand noch einmal liest. Eine kurze Spec wie diese begegnet dieser Kritik direkt. Sie bleibt billig zu aktualisieren und hat deshalb eine Chance, wahr zu bleiben.

Wenn ich das einem Agent übergeben würde, würde ich einen brauchbaren ersten Wurf erwarten. Wenn ich es als Mensch reviewen würde, wüsste ich, wo ich den Plan infrage stellen muss, bevor Code landet. Das ist die Messlatte.

Minimale Specs in der Praxis: Tools und Frameworks

Es gibt nicht den einen richtigen Weg, das minimale Spec-Format in den Alltag zu bringen. Die richtige Wahl hängt davon ab, ob du volle manuelle Kontrolle willst, ein schwereres Framework oder Hilfe beim Erzeugen von Specs, die deine Codebase kennen.

Spec-Frameworks im Vergleich

Ansatz Overhead Portabilität zwischen AI Agents Kennt die Codebase Lernkurve
DIY-Markdown im Repo Niedrig Hoch Manuell Niedrig
GitHub Spec Kit Hoch Hoch Teilweise, je nach Workflow Mittel bis hoch
Starter-Repo-Muster wie micmcc/spec-driven-development-starter Niedrig bis mittel Hoch Manuell Niedrig
Specs, geschrieben von den Loops von Tekk.coach oder von Hand auf seinem Board Mittel Hoch: Claude Code, Codex oder Cursor baut die Spec über den Tekk-MCP-Server Ja, Loops lesen, was sich in deinem GitHub-Repo geändert hat Niedrig bis mittel

Was jeder Ansatz richtig und falsch macht

DIY-Markdown passt am saubersten zu einem minimalistischen Ansatz. Ein specs/-Ordner mit einer Datei pro Feature reicht. Repos wie spec-driven-development-starter von micmcc zeigen eine praktische Form dafür. Du behältst die Kontrolle, hältst das Format schlank und vermeidest Framework-Dogmen.

Der Haken ist die Disziplin. Du musst gut schreiben. Und du musst die Docs selbst aktuell halten.

GitHub Spec Kit ist formeller. Der Vorteil ist Struktur. Der Nachteil ist allen klar, die es schon bei einem kleinen Produkt ausprobiert haben: Es kann schnell schwer werden. Der Launch-Post zu GitHub Spec Kit legt den breiteren Workflow klar dar, aber genau diese Breite ist der Grund, warum viele Solo Builder davon abprallen. Die Beschwerde ist nicht, dass es Ideen hat. Die Beschwerde ist, dass es oft zu viel Zeremonie verlangt, bevor nützlicher Code entsteht.

Die Kritik taucht auch in echten Diskussionen auf. In der Claude-Code-Community haben Leute schlankere Spec-Gewohnheiten geteilt, die viel eher nach einem kompakten Umsetzungs-Briefing aussehen als nach einem kompletten Planungsstapel, weil sie genug Struktur wollen, um das Modell zu führen, ohne sich selbst auszubremsen (Claude-Code-Diskussion mit einem schlanken Spec-Beispiel).

Generierte Spec-Workflows liegen in der Mitte. Sie können Zeit sparen, wenn das System das Repo liest, Rückfragen stellt und eine Spec mit sechs Abschnitten ausgibt, die du nutzen kannst. Das Risiko: Generierte Docs können zu poliertem Fluff werden, wenn das Tool Optik über Umsetzungsdetails stellt.

Das Format ist wichtiger als das Tool. Ein schlechtes Tool kann trotzdem eine gute Spec liefern, wenn die Struktur straff ist. Ein schickes Tool kann trotzdem deine Zeit verschwenden, wenn die Struktur aufgebläht ist.

Für Solo Builder ist das der Filter. Nimm das leichteste System, das zuverlässig baubare Specs liefert.

Specs lebendig halten, ohne Zeremonie

Spec Drift entsteht, wenn das Dokument gleichzeitig Historie, Plan und Compliance-Artefakt sein will.

Eine Spec sollte nur so lange lebendig bleiben, wie sie Umsetzung oder Review verbessert. Danach übernehmen Code und Tests. Wer Specs wie Steintafeln behandelt, erzeugt eingefrorene Docs, denen niemand traut. Wer sie wie Wegwerf-Output aus dem Chat behandelt, erzeugt das gegenteilige Problem: Du verlierst das eine Artefakt, das dem Agent und dem Menschen sagt, was „fertig“ bedeutet hat.

Eine vergleichende Infografik: die Vorteile lebendiger Dokumente gegenüber den Nachteilen eingefrorener, veralteter Projekt-Specs.

Eine einfache Regel gegen Spec Drift

Nutze eine einzige Regel.

Aktualisiere die Spec nur, wenn die Änderung ein noch nicht erfülltes Akzeptanzkriterium, eine Scope-Grenze oder eine offene Frage betrifft.

Das war’s.

Wenn du eine Variable umbenennst, fass die Spec nicht an. Wenn du eine Helper-Datei verschiebst, fass die Spec nicht an. Wenn du entscheidest, dass das Feature jetzt anonymen Lesezugriff braucht: ja, aktualisiere die Spec. Wenn sich die Validierung geändert hat: ja. Wenn eine Annahme mit hohem Risiko gebrochen ist: ja.

Was du aktualisierst und was du ignorierst

Halte den Pflege-Loop brutal klein:

  • TL;DR aktualisieren, wenn sich das Ergebnis geändert hat.
  • Scope aktualisieren, wenn du eine für User sichtbare Grenze hinzugefügt oder entfernt hast.
  • Teilaufgaben aktualisieren, aber nur, wenn sich der Umsetzungsweg wesentlich geändert hat.
  • Annahmen aktualisieren, wenn aus einer Vermutung ein Fakt wird oder sie scheitert.
  • Validierung aktualisieren, wenn sich die Erfolgsbedingungen ändern.
  • Offene Fragen aktualisieren, wenn eine Entscheidung fällt oder ein neuer Blocker auftaucht.

Alles andere gehört ins Code Review, in die Commit-Historie oder in Tests.

Wenn du ein klassischeres Artefakt brauchst, um Stakeholder abzuholen, nimm ein schlankes Planungsdokument oder ein kompaktes PRD-Template. Schieb dieses Material nur nicht standardmäßig in die Umsetzungs-Spec. Ein separates Product Requirements Document Template kann helfen, wenn du einen breiteren Produktrahmen brauchst, ohne das Umsetzungs-Briefing zu verwässern.

Einer lebendigen Spec sollte man leicht vertrauen können, weil sie leicht zu aktualisieren ist. Fühlt sich die Pflege teuer an, verrottet sie.

Das minimale Spec-Format funktioniert, weil es dir ein kleines Dokument gibt, das den Kontakt mit echter Feature-Arbeit überlebt. Nicht weil es gerade angesagt ist. Nicht weil es rigoros klingt. Sondern weil es alles wegschneidet, was dir nicht direkt beim Ausliefern hilft.

Wenn du solche Specs nicht Zeile für Zeile selbst schreiben willst: Die Loops von Tekk.coach schreiben Specs in diesem Stil für dich, aus dem, was sich in deinem GitHub-Repo geändert hat. Eine von Hand zu schreiben ist der manuelle Weg auf dasselbe Board, und es sind die Akzeptanzkriterien, die sie beim Merge des PR schließen.

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.