DESIGN.md: Die Ergänzung zu AGENTS.md

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

DESIGN.md ist eine Markdown-Datei im Repository-Stammverzeichnis. 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, der erfolgreiche Lint-Lauf und die Pfade, die unverändert bleiben müssen. DESIGN.md dokumentiert die bereits getroffenen Entscheidungen und was fehlschlägt, 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, ist standardmäßig überzeugt von seinen Entscheidungen. Es findet ein Muster, das es nicht erkennt, und verbessert dieses Muster. 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 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 lesen konnte.

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

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

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. Diese Zeile ist der eigentliche Zweck der 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 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 Dateien sind Dokumente zu Designsystemen. Sie beschreiben, wie ein Produkt aussehen soll: Farben, Typografie, Abstände und Animationen. Sehen Sie über das Thema hinweg. Der nützliche Teil ist die Struktur der Formulierungen, nicht der Inhalt.

Die Nuxt-Datei umfasst etwa 2.100 Wörter. Der größte Teil besteht aus einer Regel mit einer angefügten 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 Vercel-Datei ist länger. Im August 2026 umfasst sie etwa 6.500 Wörter und geht einen Schritt weiter. Eine ihrer Überschriften lautet Reject generated-design reflexes. Darunter steht eine Liste der Elemente, 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. Es handelt sich um eine schriftliche Liste der Standardeinstellungen, die ein selbstsicheres Modell verwendet. Sie wird veröffentlicht, damit das Modell diese Standardeinstellungen nicht mehr verwendet. Jede DESIGN.md, deren Aufnahme sich lohnt, ist eine solche Liste für einen bestimmten Bereich.

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 verwendet dasselbe Format mit neun Abschnitten. Dadurch kann ein Agent auf eine Datei verwiesen werden und eine Benutzeroberfläche erzeugen, die diesem Erscheinungsbild nahekommt. Diese Dateien sind nützlich, bleiben aber Vermutungen. Niemand aus den jeweiligen Unternehmen hat sie geprüft.

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

Sieben Herausgeber sind eine kleine Zahl, und das Repository weist selbst darauf hin: 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. Betrachten Sie die Liste daher als Übersicht und nicht als neutrale Erhebung. Sie ist trotzdem wegen der sieben Unternehmen beobachtenswert. Es handelt sich um 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 den Weg von AGENTS.md: agents.md wird inzwischen in mehr als 60,000 Open-Source-Projekten verwendet. Die Verantwortung liegt bei der Agentic AI Foundation unter dem Dach der Linux Foundation. Konventionen für agentenlesbare Dateien etablieren sich schnell. Sie gehen dabei von den führenden Projekten aus.

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, 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 sicherer Editor sonst unbemerkt verletzen würde.

Invarianten. Jeweils ein Satz, der festlegt, was nach jeder Änderung weiterhin gelten muss. „Jeder Schreibvorgang läuft über queue.enqueue(). Ein direkter Datenbankschreibvorgang umgeht das Audit-Log, und der Compliance-Export liest das Audit-Log.“ Eine Invariante mit ihrer Begründung bleibt auch bei einer nicht vorhergesehenen Aufgabe erhalten. 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, 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, und es gibt einen Daemon weniger, 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 ihm die Einschränkung nicht mitgeteilt haben. Dieser Abschnitt rechtfertigt die gesamte Datei.

Grenzen. Die Stellen, an denen eine kleine Änderung große 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 liest. Der Cron-Eintrag, der voraussetzt, dass nur eine Instanz davon läuft. Benennen Sie diese Stellen und sagen Sie, welche Kosten eine Änderung an jeder einzelnen verursacht.

Terminologie. Wenn der Code tenant verwendet und das Team customer sagt, halten Sie die Zuordnung schriftlich fest. Ein Agent, der hier falsch rä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 die übrigen Abschnitte als Überschriften stehen. Eine Datei mit vier ehrlichen Zeilen ist ausreichend. Eine Datei mit vierzig geratenen Zeilen ist es nicht.

Einige Tools laden jede Markdown-Datei im Repository-Stammverzeichnis. Andere laden nur die Datei, die ihnen angegeben wird. Gehen Sie daher nicht von einem bestimmten 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 der Projektfunktion, 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 doppelt. Der erste Kostenpunkt ist der Kontext. Eine Datei, die der Agent zu Beginn jeder Aufgabe liest, wird bei jeder Aufgabe erneut berücksichtigt. Ein duplizierter Installationsabschnitt belastet ein fest begrenztes Kontextfenster ohne Nutzen. Die Verwaltung 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 den wertvollsten Text im Repository enthalten.

Der zweite Kostenpunkt ist schwerwiegender. Zwei Kopien derselben Aussage entwickeln sich auseinander. Die README sagt, dass der Dienst auf 8080 lauscht, DESIGN.md nennt weiterhin 3000, und der Agent kann nicht feststellen, welche Angabe Vorrang hat. Daher wählt er eine davon und schreibt den Code entsprechend. Eine Datei, die manchmal falsch ist, wird mit demselben Vertrauen 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 funktioniert?

Dafür gibt es keinen Linter. Sie können innerhalb einer Minute eine Prüfung durchführen.

Geben Sie dem Agenten eine Aufgabe, die direkt gegen eine Invariante verstößt. „Fügen Sie einen Hintergrundjob hinzu, der veraltete Zeilen als abgelaufen markiert.“ Eine funktionierende Datei zeigt sich in der Antwort, noch bevor Code erscheint: Der Agent sollte Ihnen sagen, dass der Job über queue.enqueue() schreibt, weil ein direkter Schreibvorgang das Auditprotokoll 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 man darüber diskutieren kann.

Achten Sie außerdem auf die Tokenanzahl, da diese Datei bei jedem Durchlauf geladen wird. Wenn die Kontextnutzung steigt, nachdem Sie DESIGN.md hinzugefügt haben, und die Antworten nicht besser werden, enthält die Datei Text, den der Agent bereits kannte. Lesen der Tokenzähler in Claude Code zeigt, wohin dieses Budget fließt.

Das ist besonders wichtig, wenn der Agent auf einem Server und nicht auf Ihrem Laptop ausgeführt wird. Ein Agent in einer langlebigen Sitzung, wie bei der Einrichtung in einem Claude-Code-Arbeitsbereich auf einem VPS mit tmux, hat kein Gedächtnis für 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. In DESIGN.md gehört diese Erklärung hin, damit sie erhalten bleibt.

Beginnen Sie mit den Entscheidungen, über die Sie diskutieren

Die erste Version dauert zwanzig Minuten. Ö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 ist 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, wo Agenten in einen normalen Entwicklungsworkflow passen, ist der Leitfaden 2026 zum Erlernen von AI-Agenten ein sinnvoller nächster Schritt.

FAQ

Ist DESIGN.md ein offizieller Standard?

Nicht in dem Maß wie AGENTS.md. AGENTS.md hat unter agents.md eine eigene Website, wird von über 60,000 Open-Source-Projekten verwendet und steht unter der Aufsicht der Agentic AI Foundation, die Teil der Linux Foundation ist. DESIGN.md hatte im August 2026 keine zuständige Organisation und keine veröffentlichte Spezifikation. Es gibt jedoch Übernahme durch die ursprünglichen Anbieter: Sieben Unternehmen, darunter Vercel, Nuxt, Atlassian und Resend, veröffentlichen eine solche Datei unter einer öffentlichen URL. Außerdem enthält eine Community-Sammlung 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 keine Instanz 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. Teilen Sie die Dateien auf, wenn AGENTS.md nicht mehr schnell überblickt werden kann oder wenn sich die beiden Hälften unterschiedlich häufig ä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. Wenn Sie die Dateien aufteilen, fügen Sie AGENTS.md eine Zeile hinzu, die den Agent anweist, DESIGN.md vor dem Bearbeiten von Code zu lesen, da nicht jedes Tool jede Markdown-Datei im Root-Verzeichnis lädt.

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

Ein ADR (Architecture Decision Record) ist eine datierte Aufzeichnung einer einzelnen Entscheidung. In einem gut gepflegten Projekt sammeln sich Dutzende davon in einem Verzeichnis. Das ist eine Historie. Das Laden einer Historie ist aufwendig, da ein Agent alle Einträge lesen müsste, um festzustellen, welche noch gültig sind. DESIGN.md beschreibt den aktuellen Stand und ist so geschrieben, dass es bei jeder Aufgabe vollständig gelesen wird. Wenn Sie bereits ADRs schreiben, behalten Sie beide Formate bei. Das ADR beschreibt, was wann entschieden wurde. DESIGN.md beschreibt, was heute gilt. Auf diese Datei verweisen Sie den Agent.

Wie lang sollte eine DESIGN.md sein?

Kurz genug, um sie bei jeder Verarbeitung ohne Bedenken zu laden. Die veröffentlichten Beispiele sind lang, weil sie eine vollständige visuelle Sprache beschreiben: Die Nuxt-Datei umfasst im August 2026 etwa 2,100 Wörter und die Vercel-Datei etwa 6,500 Wörter. Ein Backend-Service 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 das Maß. Jede Zeile sollte etwas beschreiben, das der Agent sonst falsch machen würde.