DESIGN.md: Warum Ihr Coding-Agent Entscheidungen bewahrt

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

DESIGN.md ist eine Markdown-Datei im Root-Verzeichnis Ihres Repositorys. Sie erklärt einem KI-Coding-Agent, warum der Code so aufgebaut ist. AGENTS.md beantwortet eine andere Frage: wie hier gearbeitet wird. Dazu gehören der Build-Befehl, der Test-Befehl, die auszuführende Lint-Prüfung und die Pfade, die nicht geändert werden dürfen. 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. Aus einem von Hand geschriebenen Cache wird Redis (ein In-Memory-Datenspeicher), weil ein Cache in den meisten Codebeispielen, die das Modell gelesen hat, so umgesetzt ist. AGENTS.md verhindert das nicht, weil make test in beiden Fällen erfüllt ist. Die verletzte Regel wurde nirgends schriftlich festgehalten, wo der Agent sie hätte lesen können.

Wenn Sie die erste Datei noch nicht erstellt haben, beginnen Sie dort. AGENTS.md und die daneben liegende HUMAN.md behandelt das Format und die Orte, an denen die einzelnen Tools nach dieser Datei suchen. Das folgende Kapitel baut darauf auf.

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 nur solche Dateien. Die Aufnahmeregel besteht aus einer Zeile. Genau das ist der Zweck 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 August 2026 sind dort sieben Dateien aufgeführt: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel und VoltAgent. Jede Datei befindet sich unter einer stabilen öffentlichen URL. Sie können eine davon daher 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 beschreiben ein Designsystem. Sie legen fest, wie ein Produkt aussehen soll: Farben, Typografie, Abstände und Animationen. Achten Sie beim Lesen nicht nur auf den Inhalt. Entscheidend ist die Struktur des Textes, nicht das jeweilige Thema.

Die Datei von Nuxt umfasst etwa 2,100 Wörter. Der größte Teil besteht aus einer Regel mit der zugehörigen Begründung:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Die Datei von Vercel ist länger. Im August 2026 umfasst sie etwa 6,500 Wörter und geht noch einen Schritt weiter. Eine ihrer Überschriften lautet Reject generated-design reflexes. Darunter steht eine Liste mit den Lösungen, 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. Sie wird veröffentlicht, damit das Modell diese Standardwerte nicht mehr erzeugt. Jede DESIGN.md, die sich zu versionieren lohnt, ist für eine bestimmte Domäne genau diese Liste.

Warum veröffentlichen Unternehmen ihre eigene DESIGN.md?

Die Community war zuerst da. awesome-design-md enthält 73 Dateien, die aus öffentlichen Websites rekonstruiert wurden. Jede Datei folgt demselben Format mit neun Abschnitten. Ein Agent kann auf eine dieser Dateien verwiesen werden und daraus eine ähnliche Gestaltung erzeugen. Diese Dateien sind nützlich, aber weiterhin Annahmen. Niemand in den jeweiligen Unternehmen hat sie geprüft.

Eine Datei aus erster Hand ist etwas anderes. Sie ist die Quelle und nicht die Interpretation des Ergebnisses. Wenn Vercel seine Typografieskala ändert, ändert sich auch vercel.com/design.md. Eine im März extrahierte Kopie vermittelt Ihrem Agenten weiterhin die alte Skala. In Ihrem Repository gibt es keinen Hinweis darauf, dass diese Kopie veraltet ist.

Sieben Herausgeber sind eine kleine Zahl, und das Repository weist selbst darauf hin: Der Standard ist neu, und die offizielle Nutzung 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 Beobachtungsliste und nicht als neutrale Bestandsaufnahme verstanden werden. Beobachtenswert ist sie trotzdem, und zwar wegen der Unternehmen, die diese sieben bilden. Es sind die Unternehmen, deren Frontend-Code andere Entwickler am häufigsten kopieren. Ihre Dateien werden zum Praxisbeispiel dafür, was eine DESIGN.md ist. Vergleichen Sie die Entwicklung von AGENTS.md: agents.md wird inzwischen von mehr als 60,000 Open-Source-Projekten verwendet, und die Verantwortung liegt bei der Agentic AI Foundation unter dem Dach der Linux Foundation. Konventionen für agentenlesbare Dateien etablieren sich schnell. Sie entstehen dabei vor allem bei den führenden Unternehmen.

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

Für die meiste Software auf einem VPS gibt es keine visuelle Sprache, die festgelegt werden muss. 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 könnte.

Invarianten. Jeweils ein Satz, der festhält, was nach jeder Änderung weiterhin gelten muss. „Jeder Schreibvorgang läuft über queue.enqueue(). Ein direkter Datenbankschreibvorgang umgeht das Audit-Log, das die Compliance-Exporte auslesen.“ Eine Invariante mit zugehöriger Begründung bleibt auch bei einer Aufgabe verständlich, die Sie nicht vorhergesehen haben. Eine Invariante ohne Begründung wirkt wie eine Präferenz, und Präferenzen werden bei Optimierungen entfernt.

Verworfene Alternativen. Die naheliegende Option und der Grund, warum sie verworfen wurde. „Wir verwenden Redis nicht für das Caching. Der Dienst läuft auf einem einzelnen VPS. Daher ist eine Map innerhalb des Prozesses schneller, und es muss ein Daemon weniger ausgeführt werden. Prü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 wäre richtig, weil Sie die Einschränkung nicht beschrieben haben. Dieser Abschnitt rechtfertigt die gesamte Datei.

Grenzen. Stellen, an denen eine kleine Änderung weitreichende Auswirkungen hat. Das Datenbankschema. Das öffentliche Routenpräfix, gegen das Kunden bereits Skripte ausführen. Die Konfigurationsdatei, die ein Deployment vor dem Start der Anwendung einliest. Der Cron-Eintrag, der voraussetzt, dass nur eine Instanz davon läuft. Nennen Sie diese Stellen und beschreiben Sie, welche Folgen eine Änderung jeweils hat. Wenn der Agent außerdem das offene Web erreichen kann, beispielsweise über eine selbst gehostete SearXNG-Instanz, die als Search-Backend angebunden 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 zitiert zurückgegeben werden darf.

Terminologie. Wenn der Code tenant verwendet und das Team customer sagt, dokumentieren Sie die Zuordnung. Ein Agent, der hier falsch schließt, erzeugt Code, der sich gut liest, aber das falsche Konzept abbildet. Das ist die am schwersten erkenn­bare Fehlerart im Review.

Eine DESIGN.md, die Sie heute erstellen 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 Rest 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 einheitlichen Verhalten aus. Fügen Sie in AGENTS.md einen Verweis 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. All das steht bereits in der README. Nichts davon erklärt, warum etwas auf diese Weise umgesetzt ist.

Das kostet Sie doppelt. Die ersten Kosten entstehen beim Kontext. Eine Datei, die der Agent zu Beginn jeder Aufgabe liest, wird bei jeder Aufgabe erneut verarbeitet. Ein doppelter Installationsabschnitt ist bei einem begrenzten Kontextfenster reiner Overhead. Die Größe dieses Fensters sinnvoll zu planen, ist eine eigene Fähigkeit. Sie wird in dem Verwalten des Kontextfensters in Claude Code behandelt. Die Kurzfassung: Alles, was automatisch geladen wird, sollte der wertvollste Text im Repository sein.

Die zweiten Kosten sind schwerwiegender. Zwei Kopien derselben Aussage driften auseinander. In der README steht, 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 laut sagen würden, der Teil, der mit „Das haben wir bereits ausprobiert“ beginnt.

Woran erkennen Sie, dass die Datei wirksam ist?

Dafür gibt es keinen Linter. Es gibt jedoch einen Check, den Sie innerhalb einer Minute ausführen können.

Geben Sie dem Agenten eine Aufgabe, die direkt auf eine Invariante zuläuft: „Fügen Sie einen Hintergrundjob hinzu, der veraltete Zeilen als abgelaufen markiert.“ Eine funktionierende Datei zeigt sich in der Antwort, noch bevor Code geändert wird: Der Agent sollte darauf hinweisen, 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 ungenau formuliert, dass sie sich auslegen lässt.

Achten Sie auch auf die Token-Anzahl, da diese Datei bei jeder Anfrage geladen wird. Wenn die Kontextauslastung steigt, nachdem Sie DESIGN.md hinzugefügt haben, und die Antworten nicht besser werden, enthält die Datei Text, den der Agent bereits kannte. Token-Zähler in Claude Code lesen zeigt, wofür dieses Budget verwendet wird.

Das ist besonders wichtig, wenn der Agent auf einem Server und nicht auf Ihrem Laptop läuft. Ein Agent in einer langfristig laufenden Sitzung, wie bei der Einrichtung in einem Claude-Code-Arbeitsbereich auf einem VPS mit tmux, hat kein Gedächtnis an die Unterhaltung vom Vortag. Das Repository ist der Speicher. Alles, was Sie im Chat erklärt und nie committet haben, ist in der nächsten Sitzung verschwunden. 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 fertig. Ö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. Außerdem zeigt jeder Kommentar eine Stelle, an der ein Agent denselben Fehler machen wird – schneller und häufiger als ein Mensch. Ergänzen Sie die Datei, wenn sie Sie im Stich lässt, nicht nach einem festen Zeitplan. Wenn Sie noch herausarbeiten, an welcher Stelle Agents in einen normalen Entwicklungsworkflow passen, ist der Leitfaden zum Lernen von AI Agents für 2026 ein sinnvoller nächster Schritt.

FAQ

Ist DESIGN.md ein offizieller Standard?

Nicht in dem Sinn, wie es bei AGENTS.md der Fall ist. AGENTS.md hat mit agents.md eine zentrale Anlaufstelle, wird von mehr als 60,000 Open-Source-Projekten verwendet und steht unter der Betreuung der Agentic AI Foundation, die Teil der Linux Foundation ist. DESIGN.md hat im August 2026 keine zuständige Organisation und keine veröffentlichte Spezifikation. Es wird jedoch von den ursprünglichen Anbietern übernommen: Sieben Unternehmen, darunter Vercel, Nuxt, Atlassian und Resend, veröffentlichen eine solche Datei unter einer öffentlichen URL. Eine Community-Sammlung enthält außerdem 73 weitere Dateien, die aus öffentlichen Websites rekonstruiert wurden. Betrachten Sie DESIGN.md als Konvention, die Sie jetzt übernehmen und frei erweitern können, da nichts Ihre Abschnittsnamen validiert.

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. Trennen Sie die Dateien, wenn AGENTS.md nicht mehr schnell erfassbar ist oder wenn sich zeigt, 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 geschieht seltener und hat größere Auswirkungen. Fügen Sie nach der Trennung eine Zeile in AGENTS.md ein, die den Agenten anweist, vor Änderungen am Code DESIGN.md zu lesen. Nicht jedes Tool lädt jede Markdown-Datei im Root-Verzeichnis.

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

Ein ADR (Architecture Decision Record) dokumentiert eine einzelne Entscheidung mit Datum. In einem gepflegten Projekt sammeln sich davon Dutzende in einem Verzeichnis. Das ist eine Historie. Das Laden dieser Historie ist aufwendig, weil ein Agent alle Einträge lesen müsste, um festzustellen, welche davon noch gültig sind. DESIGN.md beschreibt den aktuellen Stand und ist dafür vorgesehen, bei jeder Aufgabe vollständig gelesen zu werden. Verwenden Sie weiterhin ADRs, wenn Sie diese bereits schreiben. Das ADR beschreibt, was wann entschieden wurde. DESIGN.md beschreibt, was heute gilt. Auf diese Datei verweisen Sie den Agenten.

Wie lang sollte ein DESIGN.md sein?

Kurz genug, um es bei jeder Interaktion ohne Bedenken zu laden. Die veröffentlichten Beispiele sind lang, weil sie eine vollständige visuelle Sprache festlegen: Die Nuxt-Datei umfasst im August 2026 etwa 2,100 Wörter, die Vercel-Datei etwa 6,500 Wörter. Ein Backend-Dienst benötigt normalerweise deutlich weniger. Beginnen Sie mit einer Seite. 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 andernfalls falsch machen würde.