DESIGN.md für Coding-Agents: Warum der Code so ist

Was DESIGN.md ist und was AGENTS.md nicht abdeckt

DESIGN.md ist eine Markdown-Datei im Stammverzeichnis Ihres Repositorys. Sie erklärt einem KI-Coding-Agent, warum der Code so aufgebaut ist. AGENTS.md beantwortet eine andere Frage: Wie soll hier gearbeitet werden? Dazu gehören der Build-Befehl, der Test-Befehl, die erfolgreiche Lint-Prüfung und die Pfade, die unverändert bleiben müssen. DESIGN.md dokumentiert bereits getroffene Entscheidungen und beschreibt, was nicht mehr funktioniert, wenn eine dieser Entscheidungen rückgängig gemacht wird.

Ein Coding-Agent, also ein Tool wie Claude Code oder Cursor, das Ihr Repository selbstständig liest und bearbeitet, geht standardmäßig selbstbewusst vor. Er findet ein Muster, das er nicht erkennt, und verbessert es. Ein von Hand geschriebener Cache wird zu Redis (einem In-Memory-Datenspeicher), weil ein Cache in den meisten Codebeispielen, die das Modell gelesen hat, so aussieht. AGENTS.md verhindert das nicht, weil make test in beiden Fällen erfolgreich ist. Die verletzte Regel wurde nirgends dokumentiert, wo der Agent sie hätte lesen können.

Wenn Sie die erste Datei noch nicht geschrieben haben, beginnen Sie dort. AGENTS.md und die danebenliegende HUMAN.md beschreibt das Format und wo die einzelnen Tools danach suchen. Das folgende Kapitel schließt daran an.

Was steht tatsächlich in einer veröffentlichten DESIGN.md?

Am schnellsten lernen Sie das Format kennen, indem Sie die Dateien lesen, die Unternehmen über sich selbst veröffentlichen. Das Repository official-design-md erfasst ausschließlich solche Dateien. Die Aufnahmeregel besteht aus einer Zeile, und genau das ist der Kern dieser Sammlung:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Im Oktober 2026 sind es elf: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel und VoltAgent. Jede Datei ist unter einer öffentlichen URL verfügbar, die meisten auf der eigenen Domain des Herausgebers, die übrigen in einem öffentlichen GitHub-Repository. Sie können eine davon also sofort in einem Terminal lesen.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Beide Dokumente sind Design-System-Dokumente. Sie beschreiben, wie ein Produkt aussehen soll: Farben, Typografie, Abstände und Animationen. Achten Sie auf die Struktur der Texte und nicht nur auf das Thema. Darin liegt der nützliche Teil.

Die Nuxt-Datei umfasst am 27. Oktober 2026 ungefähr 2.000 Wörter. Der größte Teil besteht aus einer Regel mit der zugehörigen Begründung. Zu Beginn wird festgelegt, dass der Dark Mode das Standard-Theme ist. Anschließend wird das Markengrün #00DC82 mit dem Hinweis aufgeführt, dass die Markenfarben „Für Logos, Social-Media-Bilder und Druck. Nicht als Rohwerte im UI-Code verwenden.“ vorgesehen sind. Gegen Ende enthält ein Abschnitt mit der Überschrift Reject these Folgendes:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Die Vercel-Datei ist mit ungefähr 6.000 Wörtern im Oktober 2026 länger und geht einen Schritt weiter. Eine ihrer Überschriften lautet Reject generated-design reflexes. Darunter steht eine Liste mit den Elementen, zu denen ein leistungsfähiger Generator greift, wenn ihm niemand etwas anderes vorgibt:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Dieser Satz definiert den Dateityp. Die Datei enthält eine schriftliche Liste der Standardwerte, die ein selbstsicheres Modell erzeugt, und wird veröffentlicht, damit das Modell sie nicht mehr erzeugt. Jede DESIGN.md, die das Committen wert ist, enthält diese Liste für einen bestimmten Anwendungsbereich.

Warum veröffentlichen Unternehmen ihre eigene DESIGN.md?

Die Community war zuerst da. awesome-design-md enthält laut der Zählung in seiner README mit Stand vom 27. Oktober 2026 84 Dateien, die von öffentlichen Websites extrahiert wurden. Jede Datei folgt demselben Format mit neun Abschnitten, sodass ein Agent auf eine davon verwiesen werden kann und etwas erzeugt, das diesem Erscheinungsbild nahekommt. Diese Dateien sind nützlich, aber weiterhin Vermutungen. Niemand in den Unternehmen hat sie geprüft.

Eine Datei aus erster Hand ist etwas anderes, weil sie die Quelle und nicht eine Interpretation des Ergebnisses ist. Wenn Vercel seine Schriftskalierung ändert, ändert sich vercel.com/design.md mit. Eine im März extrahierte Kopie vermittelt Ihrem Agenten weiterhin die alte Skalierung, und nichts in Ihrem Repository weist darauf hin, dass die Kopie veraltet ist.

Elf Herausgeber sind weiterhin eine kleine Zahl, und das Repository sagt dies auch ausdrücklich: Der Standard ist neu, und die offizielle Verbreitung nimmt zu. Beide Sammlungen werden von VoltAgent gepflegt, einem Open-Source-Agent-Framework, das ebenfalls eine eigene Datei veröffentlicht. Die Liste sollte daher als Übersicht und nicht als neutale Erhebung verstanden werden. Sie ist dennoch beobachtenswert, weil es darauf ankommt, wer darin vertreten ist. Mehrere Einträge gehören zu den Unternehmen, deren Frontend-Code andere Entwickler am häufigsten kopieren. Die neueren Einträge, Ant Design, Microsoft FAST, Juspay und Oxide Computer, sind Designsysteme, auf denen andere Teams aufbauen. Ihre Dateien werden zum ausgearbeiteten Beispiel dafür, was eine DESIGN.md ist. Vergleichen Sie den Weg von AGENTS.md: agents.md zählt inzwischen über 60,000 Open-Source-Projekte, die das Format verwenden, und die Betreuung liegt bei der Agentic AI Foundation unter der Linux Foundation. DESIGN.md hat denselben Weg eingeschlagen. Am 21. April 2026 veröffentlichte Google einen Entwurf der Spezifikation für das Format als Open Source. Er ist unter google-labs-code/design.md verfügbar und enthält ein Token-Schema sowie eine CLI unter der Apache-2.0-Lizenz. Mit Stand Oktober 2026 befindet sich das Format in Version alpha und wird weiterhin aktiv entwickelt. Es wird von Google Labs und nicht von einer neutralen Stiftung gepflegt. Außerdem beschreibt es eine visuelle Identität und sagt daher nichts über die Invarianten aus, die eine Backend-Datei benötigt. Konventionen für agentenlesbare Dateien etablieren sich schnell, und sie werden von oben geprägt.

Was gehört in eine DESIGN.md, wenn das Projekt keine Benutzeroberfläche hat

Für die meiste Software, die auf einem VPS läuft, gibt es keine visuelle Sprache festzulegen. Die Datei ist trotzdem sinnvoll, weil es dabei nicht um Farben geht. Sie hält die Einschränkungen fest, die ein sicher arbeitender Editor sonst unbemerkt verletzen würde.

Invarianten. Formulieren Sie jeweils einen Satz, der beschreibt, was nach jeder Änderung weiterhin gelten muss. „Jeder Schreibvorgang läuft über queue.enqueue(). Ein direkter Datenbankschreibvorgang umgeht das Audit-Log, aus dem der Compliance-Export seine Daten bezieht.“ Eine Invariante mit angefügter Begründung bleibt auch bei Aufgaben verständlich, die Sie nicht vorhergesehen haben. Eine Invariante ohne Begründung wirkt wie eine Präferenz, und Präferenzen werden bei der Optimierung entfernt.

Verworfene Alternativen. Nennen Sie die naheliegende Option und den Grund, aus dem sie verworfen wurde. „Wir verwenden Redis nicht für das Caching. Der Dienst läuft auf einem einzelnen VPS, daher ist eine Map im Prozess schneller. Außerdem entfällt ein weiterer Daemon, der aktiv gehalten werden muss. Überprüfen Sie diese Entscheidung erneut, sobald ein zweiter Anwendungsserver vorhanden ist.“ Ohne diesen Absatz fügt ein Agent, der den Cache beschleunigen soll, Redis hinzu. Das ist dann richtig, weil Sie die Einschränkung nicht angegeben haben. Dieser Abschnitt rechtfertigt die gesamte Datei.

Grenzen. Nennen Sie die Stellen, an denen eine kleine Änderung große Auswirkungen hat. Dazu gehören das Datenbankschema, das öffentliche Routenpräfix, gegen das Kunden bereits Skripte ausführen, die Konfigurationsdatei, die ein Deployment vor dem Start der Anwendung liest, und der Cron-Eintrag, der voraussetzt, dass nur eine Kopie des Dienstes läuft. Benennen Sie diese Stellen und erklären Sie, welche Kosten eine Änderung jeweils verursacht. Wenn der Agent auch das offene Web erreichen kann, beispielsweise über eine selbst gehostete SearXNG-Instanz, die als Such-Backend eingerichtet ist, ist auch das eine Grenze, die dokumentiert werden sollte. Die Datei sollte festlegen, welcher abgerufene Text den Code beeinflussen darf und welcher Ihnen ausschließlich zurückzitiert werden darf.

Terminologie. Wenn der Code tenant sagt und das Team customer verwendet, dokumentieren Sie die Zuordnung. Ein Agent, der hier falsch schließt, erzeugt Code, der sich korrekt liest, aber das falsche Konzept modelliert. Das ist die am schwersten zu erkennende Art von Fehler bei einem Review.

Eine DESIGN.md, die Sie heute kopieren können

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Füllen Sie heute die beiden Abschnitte aus, die Sie aus dem Gedächtnis schreiben können: Invarianten und verworfene Alternativen. Lassen Sie den restlichen Inhalt als Überschriften stehen. Eine Datei mit vier ehrlichen Zeilen ist sinnvoll. Eine Datei mit vierzig geratenen Zeilen ist es nicht. Wenn das Repository mehrere Pakete enthält, passt eine einzelne Datei im Root-Verzeichnis nicht für alle. Die gleiche Aufteilung nach Verzeichnissen, die für verschachtelte AGENTS.md-Dateien in einem Monorepo funktioniert, gilt auch hier: eine kurze Datei im Root-Verzeichnis für die gemeinsamen Entscheidungen und eine kleinere Datei neben jedem Paket mit eigenen Entscheidungen.

Einige Tools laden jede Markdown-Datei im Root-Verzeichnis des Repositorys. Andere laden nur die Datei, die ihnen angegeben wurde. Gehen Sie daher nicht von einem bestimmten Verhalten aus. Fügen Sie einen Verweis auf AGENTS.md hinzu:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Das Anti-Pattern: eine DESIGN.md, die die README wiederholt

Die häufigste schlechte Variante liest sich gut und vermittelt nichts. Sie beginnt mit einer Beschreibung des Projekts, listet die Funktionen auf, erklärt die Installation und endet mit der Lizenz. Jede dieser Informationen steht bereits in der README. Keine davon erklärt, warum etwas auf diese Weise umgesetzt ist.

Das kostet Sie zweimal. Die ersten Kosten entstehen beim Kontext. Eine Datei, die der Agent zu Beginn jeder Aufgabe liest, wird bei jeder Aufgabe erneut berücksichtigt. Ein doppelt vorhandener Installationsabschnitt ist innerhalb eines begrenzten Kontextfensters reiner Overhead. Die Planung dieses Fensters ist eine eigene Fähigkeit, die in Verwalten des Kontextfensters in Claude Code behandelt wird. Die Kurzfassung: Alles, was automatisch geladen wird, sollte der wertvollste Text im Repository sein.

Die zweiten Kosten wiegen schwerer. Zwei Kopien derselben Aussage driften auseinander. Die README sagt, dass der Dienst auf 8080 lauscht, während DESIGN.md weiterhin 3000 nennt. Der Agent kann nicht feststellen, welche Angabe Vorrang hat. Er wählt eine davon und schreibt den Code entsprechend. Eine Datei, die manchmal falsch ist, wird mit derselben Sicherheit herangezogen wie eine Datei, die immer richtig ist.

Der Test ist schnell durchgeführt. Wenn ein Absatz problemlos in der README stehen könnte, entfernen Sie ihn aus DESIGN.md. Übrig bleiben sollte der Teil, den Sie in einem Code-Review ausdrücklich ansprechen würden, der Teil, der mit „Das haben wir bereits ausprobiert“ beginnt.

Woran erkennen Sie, dass die Datei verwendet wird?

Dafür gibt es keinen Linter. Es gibt jedoch eine Prüfung, die Sie in einer Minute durchführen können.

Geben Sie dem Agenten eine Aufgabe, die direkt auf eine Invariante trifft: „Fügen Sie einen Hintergrundjob hinzu, der veraltete Zeilen als abgelaufen markiert.“ Eine Datei, die tatsächlich verwendet wird, zeigt sich in der Antwort, noch bevor Code entsteht: Der Agent sollte angeben, dass der Job über queue.enqueue() schreibt, weil ein direkter Schreibzugriff das Audit-Log umgehen würde. Wenn er eine Datenbankverbindung öffnet und schreibt, trifft eine von zwei Möglichkeiten zu: Die Datei wird überhaupt nicht gelesen, oder die Invariante ist so unpräzise formuliert, dass darüber diskutiert werden kann.

Beobachten Sie außerdem die Token-Anzahl, da diese Datei bei jeder Anfrage geladen wird. Wenn die Context-Nutzung nach dem Hinzufügen von DESIGN.md steigt, die Antworten aber nicht besser werden, enthält die Datei möglicherweise Prosa, die dem Agenten bereits bekannt war. Token-Zähler in Claude Code lesen zeigt, wohin dieses Budget fließt.

Das ist besonders wichtig, wenn der Agent auf einem Server und nicht auf Ihrem Laptop läuft. Ein Agent in einer langlebigen Sitzung, wie bei der Einrichtung in einem Claude-Code-Arbeitsbereich auf einem VPS mit tmux, hat keine Erinnerung an das Gespräch vom Vortag. Das Repository ist der Speicher. Alles, was Sie im Chat erklärt und nie committed haben, ist in der nächsten Sitzung verloren. DESIGN.md enthält diese Erklärung, damit sie erhalten bleibt.

Beginnen Sie mit den Entscheidungen, über die diskutiert wird

Die erste Version ist in zwanzig Minuten erstellt. Öffnen Sie die letzten Pull Requests, in denen ein Reviewer „nein, das machen wir hier anders“ geschrieben hat. Jeder dieser Kommentare beschreibt eine Invariante, die nie dokumentiert wurde. Jeder Kommentar markiert außerdem eine Stelle, an der ein Agent denselben Fehler schneller und häufiger als ein Mensch machen wird. Ergänzen Sie die Datei, wenn sie Sie im Stich lässt, nicht nach einem festen Zeitplan. Wenn Sie noch herausarbeiten, wie Agenten in einen normalen Entwicklungsworkflow passen, ist der Leitfaden zum Erlernen von AI-Agenten aus dem Jahr 2026 ein sinnvoller nächster Schritt.

FAQ

Ist DESIGN.md ein offizieller Standard?

Nicht in derselben Weise wie AGENTS.md. AGENTS.md hat mit agents.md eine zentrale Anlaufstelle, wird von über 60,000 Open-Source-Projekten verwendet und steht unter der Betreuung der Agentic AI Foundation, die Teil der Linux Foundation ist. Für DESIGN.md gibt es eine veröffentlichte Spezifikation, aber keine neutrale betreuende Organisation. Google hat am April 21, 2026 einen Entwurf der Spezifikation als Open Source veröffentlicht. Er liegt im Repository google-labs-code/design.md unter der Apache-2.0-Lizenz. Im October 2026 ist die Spezifikation in der Version alpha und wird weiterhin aktiv entwickelt. Sie beschreibt eine visuelle Identität: Farben, Typografie, Layout und Komponenten. DESIGN.md wird außerdem von ersten Anbietern übernommen: Elf Unternehmen und Projekte, darunter Vercel, Nuxt, Atlassian und Resend, veröffentlichen eine solche Datei. Eine Community-Sammlung enthielt am October 27, 2026 weitere 84 Dateien, die aus öffentlichen Websites extrahiert wurden. Für eine Backend-Datei mit Invarianten und verworfenen Alternativen sollten Sie DESIGN.md als Konvention betrachten, die Sie jetzt übernehmen und frei erweitern können, weil keine Spezifikation diese Abschnittsnamen abdeckt.

Sollte DESIGN.md einfach ein Abschnitt von AGENTS.md sein?

Für ein kleines Repository: ja. Eine Datei, die der Agent sicher liest, ist besser als zwei Dateien, von denen eine ignoriert wird. Teilen Sie die Dateien auf, sobald AGENTS.md nicht mehr schnell überblickt werden kann oder wenn Sie feststellen, dass sich die beiden Teile unterschiedlich schnell ändern. AGENTS.md ändert sich, wenn sich der Build ändert. DESIGN.md ändert sich, wenn sich eine Entscheidung ändert. Das kommt seltener vor und hat größere Auswirkungen. Fügen Sie beim Aufteilen eine Zeile zu AGENTS.md hinzu, die den Agent anweist, DESIGN.md vor dem Bearbeiten des Codes zu lesen, weil nicht jedes Tool jede Markdown-Datei im Root lädt.

Wie unterscheidet sich DESIGN.md von einem Architecture Decision Record?

Ein ADR (Architecture Decision Record) ist eine datierte Dokumentation einer einzelnen Entscheidung. In einem gesunden Projekt sammeln sich davon Dutzende in einem Verzeichnis an. Das ist eine Historie. Das Laden einer Historie ist aufwendig, weil ein Agent alle Einträge lesen müsste, um festzustellen, welche noch gelten. DESIGN.md beschreibt den aktuellen Stand und ist dafür vorgesehen, bei jeder Aufgabe vollständig gelesen zu werden. Behalten Sie beides, wenn Sie bereits ADRs schreiben. Das ADR beschreibt, was entschieden wurde und wann. DESIGN.md beschreibt, was heute gilt. Auf diese Datei verweisen Sie den Agent.

Wie lang sollte DESIGN.md sein?

Kurz genug, um sie in jeder Runde ohne Bedenken zu laden. Die veröffentlichten Beispiele sind lang, weil sie eine vollständige visuelle Sprache festlegen: Die Nuxt-Datei umfasst im October 2026 ungefähr 2,000 Wörter, die Vercel-Datei ungefähr 6,000. Ein Backend-Dienst benötigt normalerweise deutlich weniger. Beginnen Sie mit einer Seite und erweitern Sie die Datei nur, wenn ein Agent etwas falsch macht, das ein einziger Satz verhindert hätte. Die Länge ist nicht entscheidend. Jede Zeile sollte etwas beschreiben, das der Agent sonst falsch machen würde.