Markdown ist das richtige Format für den Inhalt von Specs, und die Zahlen stützen das. Wer HTML in Markdown umwandelt, kann den Token-Verbrauch um etwa 68 % bei sauberem Inhalt und bis zu 87 % bei echten Webseiten senken. Ein Benchmark meldete 60,7 % Genauigkeit für Markdown gegenüber 53,6 % für HTML-Tabellen, und RAG-Pipelines gewannen bis zu 35 % Genauigkeit, wenn sie Markdown statt rohem HTML verarbeiteten. Das zählt, wenn dein Agent mit der Qualität seines Kontexts steht und fällt (Beam über HTML vs. Markdown für AI Agents).

Aber bei Markdown machen sich auch viele Teams selbst etwas vor. Die Gegenbewegung ist real. Viele nennen Spec-driven Development „Wasserfall mit Markdown“, „Spec Drift“ und „Token verbrennende Zeremonie“, und sie liegen nicht falsch, wenn der Prozess zum Friedhof veralteter .md-Dateien wird. Der Fehler ist nicht, Markdown zu nutzen. Der Fehler ist, von Markdown-Dateien zu verlangen, sich wie eine Datenbank zu verhalten.

Diese Unterscheidung ist wichtig. Fragst du dich: Ist Markdown das richtige Format für KI-Specs? Meine Antwort ist Ja für die Worte, die dein Agent liest, und Nein für das System, das Status, Ablösungen, Abhängigkeiten und Entscheidungen über viele Specs hinweg trackt.

Inhalt

Die Kritik an Markdown-Specs

Die Kritik hat einen Punkt. Ein Ordner voller Specs kann schnell zur Zeremonie werden. Du schreibst einen schönen Plan, lieferst die Hälfte davon aus, änderst die Richtung, und jetzt lügt dich die Datei an.

Eine Person, überwältigt von einem riesigen Stapel Markdown-Dokumentation mit der Aufschrift „Waterfall development“.

Die Reddit-Threads im April in r/VibeCodeDevs und der Crosspost bei Codex trafen genau den Nerv. Builder beschwerten sich nicht darüber, dass Aufschreiben schlecht ist. Sie beschwerten sich darüber, dass Kontextmanagement zusammenbricht, sobald dein „System“ nur aus Dokumenten und Vibes besteht. Simon Willison hat ähnliche Skepsis gegenüber überladenen Agent-Workflows geäußert, und Birgitta Böckelers Taxonomie hilft hier: spec-first, spec-anchored und spec-as-source sind nicht dasselbe. Viele werfen sie in einen Topf und geben dann Markdown die Schuld.

Nicht Markdown hat das Chaos angerichtet, sondern ein Lebenszyklus, den niemand verwaltet hat.

Wenn du den Nutzen ohne den Schlamm willst, behalte Markdown für die Spec selbst und werde strenger beim Betriebsmodell. Das beginnt damit, Specs zu schreiben, die Agents beim Produzieren von Code helfen, statt dekorative Prozessdokumente zu sein – und genau darum geht es, wenn du bessere Specs schreibst, statt ewig KI-Output zu debuggen.

Warum Markdown beim Inhalt von Specs gewinnt

Markdown hat gewonnen, weil es das am wenigsten nervige Format ist, das Menschen und Modelle gleichermaßen lesen können. Du kannst es überall entwerfen. Du kannst es in Git diffen. Du kannst es Cursor, Claude Code, Codex oder Gemini geben, ohne dass sich das Modell durch Tag-Suppe kauen muss.

Eine Infografik, die vier zentrale Vorteile von Markdown für KI-Dokumentation und Specs hervorhebt.

Deshalb basieren die gängigen Spec-Formate auf Markdown. Addy Osmanis Spec-Format mit sechs Abschnitten ist Markdown. GitHubs Spec Kit ist Markdown. Die Repo-Struktur und die Projektseite von OpenSpec setzen ebenfalls stark auf Markdown. Das ist keine Mode. Das ist Pragmatismus.

Das Format ist für Modelle billig zu lesen

Markdown ist im Vergleich zu HTML oder XML-artigem Markup oft token-effizient. Laut einem zitierten Beispiel kostet ein einfacher „Über uns“-Block in Markdown etwa 3 Tokens, das entsprechende HTML dagegen 12–15 Tokens (Digiday über Markdown für AI Agents). Das zählt, wenn dein Coding-Agent ohnehin schon Kontext an Stacktraces, Dateibäume und halbgare Implementierungsnotizen verschwendet.

Der Leitfaden von Webex kommt zum selben Schluss. Er beschreibt Markdown als bevorzugten Standard für die meisten LLM-Anwendungen, weil es einfach und lesbar ist und für Modelle in vielen Fällen leichter zu parsen als JSON oder XML. Er merkt auch an, dass ein möglicher Crawl-Vorteil klein ausfällt. Ein kontrollierter A/B-Test über 381 Seiten auf sechs Websites ergab für Markdown-Seiten nur etwa einen zusätzlichen Bot-Besuch im Median über drei Wochen und einen um rund 16 % höheren Mittelwert; das Fazit: Der Effekt sei statistisch nicht überzeugend und vermutlich klein (Webex über LLM-freundliches Markdown).

Ein guter Walkthrough zum Spec-Muster im Allgemeinen lohnt sich:

Auch der Schreibstil passt dazu, wie Agents arbeiten

Der Spec-Leitfaden von Syncfusion trifft den wichtigen Punkt. Specs sollten festhalten, was das System tun muss, nicht wie es umzusetzen ist, damit der Agent den Weg selbst wählen kann und trotzdem innerhalb echter Grenzen bleibt (Syncfusion über Spec-driven KI-Entwicklung mit Markdown-Prompts).

Praxisregel: Nutze Markdown für Absicht, Scope, Akzeptanzkriterien und Beispiele. Nutze es nicht, um eine Workflow-Engine zu simulieren.

Wo Markdown als Spec-Datenbank scheitert

Ein Haufen .md-Dateien ist kein System. Er ist ein Aktenschrank.

Eine Infografik mit dem Titel „The Database Dilemma“, die erklärt, warum Markdown-Dateien für komplexes Datenmanagement nicht ausreichen.

Die laute Beschwerde auf Reddit lief im Grunde darauf hinaus: „Es muss einen besseren Weg geben, Kontext zu managen.“ Das ist das Kernproblem. Sobald du mehr als eine Handvoll aktiver Specs hast, brauchst du Antworten auf langweilige, aber entscheidende Fragen:

  • Was ist gerade aktiv
    Welche Specs sind Entwurf, freigegeben, blockiert, ausgeliefert oder obsolet?

  • Was hat was ersetzt
    Wenn Spec B Spec A ablöst, wo ist das festgehalten?

  • Was berührt dieselbe Fläche
    Zeig alle Specs, die Billing, Auth oder die API betreffen.

  • Was ist von der Realität weggedriftet
    Welche Docs beschreiben noch Verhalten, das der Code nicht mehr hat?

Markdown allein beantwortet diese Fragen nicht gut. Dateisysteme liefern dir keine Statusmodelle, keine Beziehungsgraphen und keine Abfragen über mehrere Specs hinweg. Und in großem Maßstab wird das Problem operativ. Die Berichterstattung von Box bringt es sauber auf den Punkt: Es geht nicht nur um Lesbarkeit, sondern um Ingestion-Kosten, Update-Aufwand, Verluste bei der Konvertierung und Druck auf das Context Window – Probleme, bei denen eine strukturierte Metadatenschicht hilft (Box über Markdown und KI-Ingestion).

Das Scheitern ist subtil

Weil eine einzelne Spec gut lesbar ist, glauben viele, das ganze Setup sei gesund. Eine Datei sieht ordentlich aus. Zehn Dateien wirken organisiert. Fünfzig Dateien werden zur Archäologie.

Daher kommen „Frozen Specs“. Nicht, weil Markdown schlecht ist, sondern weil du lebendigen Produktzustand in Prosadateien speicherst, die kein eingebautes Lebenszyklusmodell haben.

Gängige Muster, um Struktur hinzuzufügen

Die meisten Builder bemerken das und erfinden dieselben Lösungen. Das sind gute Instinkte. Sie bringen die Sache nur nicht zu Ende.

Eine Cartoon-Illustration: eine gestresste Person mit chaotischen Markdown-Dateien im Vergleich zu einem geordneten Dateisystem.

Was viele zu Markdown hinzufügen

  • YAML-Frontmatter
    Felder wie status, owner, area oder supersedes ganz oben.

  • Starre Templates für Überschriften
    Jede Spec muss Ziel, Einschränkungen, Akzeptanzkriterien und Out of Scope enthalten.

  • Typisierte Codeblöcke
    Setz JSON- oder Schema-Snippets in Codeblöcke, wo Präzision wichtiger ist als Prosa.

  • Ordnerkonventionen
    Trenne specs/, changes/, archived/ und decisions/.

Das hilft viel. OpenSpec macht einen Teil dieser Trennung gut, indem es laufende Änderungen vom Kernbestand der Specs trennt. Auch Addy Osmanis Struktur hilft, den Inhalt knapp und reviewbar zu halten. Aber keines dieser Muster macht aus Markdown ein abfragbares System of Record.

Eine gute Spec braucht trotzdem die Disziplin, zu beschreiben, was passieren muss, statt die Umsetzung nachzuerzählen. Das ist der Teil, den viele Teams vergessen, und genau dort bleibt Markdown nützlich. Wenn dir daran liegt, typische Probleme in der Dokumentation anzugehen, gilt hier dieselbe Regel: Verringere zuerst die Mehrdeutigkeit für die Lesenden, dann füge gerade so viel Struktur hinzu, wie die Pflege braucht.

Die Datei soll leicht zu lesen sein. Die Metadaten sollen leicht zu berechnen sein.

Wenn du eine praktische Grundlage fürs Schreiben willst, ist dieser Leitfaden dazu, wie du technische Specs schreibst, genau richtig streng, ohne dein Repo in Prozess-Cosplay zu verwandeln.

Dein Spec-Framework auswählen

Du hast drei echte Optionen.

Ansatz Lesbarkeit für Menschen Maschinelle Verarbeitbarkeit Verwaltungsaufwand
Rein strukturierte Daten Gering bei prosalastiger Planung Hoch Hoch für Menschen
Reines Markdown Hoch Gut genug für Inhalte Hoch, sobald sich Specs stapeln
Hybrid aus Markdown plus Schema Hoch Hoch, wo es zählt Mittel

Reines YAML oder JSON ist gut für Maschinen und furchtbar für Produktabsicht. Reines Markdown ist angenehm, bis du Status, Historie und Querverweise brauchst. Das hybride Modell ist die vernünftige Mitte.

Wenn du an UI-lastigen Produkten arbeitest, zeigen Beispiele wie detaillierte Specs für UI-Komponenten, warum Prosa und Struktur nebeneinander existieren müssen. Die Absicht der Komponente gehört in gut lesbaren Text. Das Zustandsmodell und die Metadaten brauchen strengere Regeln.

Eine Option aus diesem hybriden Lager ist Tekk.coach. Die Spec ist die Arbeitseinheit: lesbare Prosa und Akzeptanzkriterien, plus die Struktur, die Markdown fehlt (ein Status auf einem Board, verknüpfte Pull Requests, Fortschritt der Checkliste). Seine Loops schreiben Specs für dich aus dem, was sich in deinem GitHub-Repo geändert hat, oder du schreibst selbst eine. Dein Coding-Agent (Cursor, Claude Code, Codex) liest sie über den Tekk-MCP-Server.

Ein schlankes Spec-Template, das ausliefert

Die meisten Builder schreiben zu viel.

Nutze eine kleine Markdown-Datei für den Teil, den der Agent verstehen muss. Wenn du vorher dein Produktdenken schärfen willst, hilft dieser Leitfaden dazu, wie du ein PRD schreibst – aber gib deinem Agent kein aufgeblähtes PRD in der Hoffnung, dass es schon gut geht.

Fang damit an:

Minimale Spec

  • Das Ziel
    Ein Satz. Was soll existieren, wenn das hier fertig ist?

  • Akzeptanzkriterien
    Stichpunkte. Woran würdest du festmachen, dass es „fertig“ ist?

  • Zu bearbeitende Dateien
    Nenne die wahrscheinlichen Pfade oder Verzeichnisse.

  • Nicht im Scope
    Sag, was der Agent nicht anfassen darf.

Das reicht für überraschend viel Arbeit. Halte die Spec lesbar. Halte die Lebenszyklusdaten woanders. Wenn du einen strafferen Startpunkt willst, nutze dieses minimale Spec-Format.

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, und der PR schließt sie beim Merge – so muss Markdown nie so tun, als wäre es eine Datenbank.

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.