DESIGN.md: Warum AGENTS.md nicht genügt

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 wird hier gearbeitet? Dazu gehören der Build-Befehl, der Testbefehl, der auszuführende Linter und die Pfade, die nicht geändert werden dürfen. DESIGN.md dokumentiert bereits festgelegte 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 selbstsicher 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 funktioniert. Die verletzte Regel wurde nirgends festgehalten, wo der Agent sie hätte lesen können.

Wenn Sie die erste Datei noch nicht geschrieben haben, beginnen Sie damit. AGENTS.md und die danebenliegende HUMAN.md beschreibt das Format und wo die einzelnen Tools nach der Datei 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. Seine Aufnahmeregel besteht aus einer Zeile. Genau darum geht es bei 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 darin sieben Einträge aufgeführt: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel und VoltAgent. Jede Datei ist unter einer stabilen öffentlichen URL erreichbar. Sie können daher sofort eine davon im Terminal lesen.

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

Beide Dateien sind Design-System-Dokumente. Sie beschreiben, 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 Thema.

Die Nuxt-Datei umfasst ungefähr 2,100 Wörter. Der größte Teil besteht aus einer Regel mit einer 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 Vercel-Datei ist länger. Im August 2026 umfasst sie ungefähr 6,500 Wörter. Außerdem geht sie 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 Einstellungen nicht mehr verwendet. Jede DESIGN.md, die sich zu versionieren lohnt, ist eine solche Liste für einen bestimmten Bereich.

Warum veröffentlichen Unternehmen ein eigenes DESIGN.md?

Die Community war zuerst. awesome-design-md enthält 73 Dateien, die aus öffentlichen Websites rekonstruiert wurden. Jede Datei folgt demselben 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. Sie bleiben jedoch 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 Typografie-Skalierung ändert, ändert sich vercel.com/design.md mit. Eine im März erfasste 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. 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 Tracker und nicht als neutrale Bestandsaufnahme. Beobachtenswert ist sie trotzdem, und zwar wegen der sieben Unternehmen. Es sind die Unternehmen, deren Frontend-Code andere Entwickler am häufigsten kopieren. Ihre Dateien werden zum ausgearbeiteten Beispiel dafür, was ein DESIGN.md ist. Vergleichen Sie, welchen Weg AGENTS.md genommen hat: agents.md wird inzwischen in über 60.000 Open-Source-Projekten verwendet. Die Betreuung liegt bei der Agentic AI Foundation unter dem Dach der Linux Foundation. Konventionen für agentenlesbare Dateien etablieren sich schnell. Sie entstehen dabei zunehmend von oben nach unten.

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

Die meiste Software auf einem VPS hat keine visuelle Sprache, die festgelegt werden müsste. Die Datei ist trotzdem sinnvoll, weil es bei diesem Mechanismus nicht um Farben geht. Es geht darum, die Einschränkungen zu dokumentieren, 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, das von der Compliance-Exportfunktion gelesen wird.“ Eine Invariante mit der zugehörigen 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, 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 innerhalb des Prozesses schneller. Außerdem muss dadurch kein zusätzlicher Daemon dauerhaft ausgeführt werden. Überdenken Sie diese Entscheidung, sobald ein zweiter Anwendungsserver vorhanden ist.“ Ohne diesen Absatz fügt ein Agent Redis hinzu, wenn er den Cache beschleunigen soll. Das wäre korrekt, weil Sie die Einschränkung nie dokumentiert haben. Dieser Abschnitt rechtfertigt die gesamte Datei.

Grenzen. Die Stellen, an denen eine kleine Änderung große Auswirkungen haben kann. 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 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, sollten Sie auch das als Grenze dokumentieren. Die Datei sollte festlegen, welcher abgerufene Text den Code beeinflussen darf und welcher nur an Sie zurückgegeben werden darf.

Vokabular. Wenn der Code tenant sagt und das Team customer sagt, dokumentieren Sie die Zuordnung. Ein Agent, der hier falsch rät, erzeugt Code, der sich korrekt liest, aber das falsche Konzept abbildet. Das ist die schwerste Fehlerart, die bei einem Review erkannt werden kann.

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 die beiden Abschnitte aus, die Sie heute 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 sinnvoll. Eine Datei mit vierzig geratenen Zeilen 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 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. 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 durch den Kontext. Eine Datei, die der Agent zu Beginn jeder Aufgabe liest, wird bei jeder Aufgabe erneut eingerechnet. Ein duplizierter Installationsabschnitt ist innerhalb eines festen Kontextfensters reiner Mehraufwand. Die Planung dieses Fensters ist eine eigene Fähigkeit, die unter das Kontextfenster in Claude Code verwalten behandelt wird. Die Kurzfassung: Alles, was automatisch geladen wird, sollte der wertvollste Text im Repository sein.

Die zweiten Kosten sind gravierender. Zwei Kopien derselben Aussage entwickeln sich auseinander. Die README sagt, dass der Dienst auf Port 8080 lauscht, während DESIGN.md weiterhin 3000 nennt. Der Agent kann nicht erkennen, 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 konsultiert wie eine Datei, die immer korrekt 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 mündlich ansprechen 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 jedoch innerhalb einer Minute eine Prüfung durchführen.

Geben Sie dem Agenten eine Aufgabe, die direkt auf eine Invariante führt. „Fügen Sie einen Hintergrundjob hinzu, der veraltete Zeilen als abgelaufen markiert.“ Eine funktionierende Datei zeigt sich bereits in der Antwort, bevor Code geschrieben wird: Der Agent sollte Ihnen sagen, dass der Job über queue.enqueue() schreibt, weil ein direkter Schreibzugriff das Audit-Log umgehen würde. Wenn er eine Datenbankverbindung öffnet und direkt 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.

Behalten Sie auch die Token-Anzahl im Blick, 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 Prosa, die 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 statt auf Ihrem Laptop läuft. Ein Agent in einer langlebigen Sitzung, wie bei der Einrichtung eines Claude-Code-Arbeitsbereichs 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 ist der Ort, an dem diese Erklärung abgelegt wird, 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 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, und nicht nach einem festen Zeitplan. Wenn Sie noch herausarbeiten, wie sich Agents in einen normalen Entwicklungsworkflow einfügen, ist der Leitfaden zum Erlernen von AI Agents für 2026 ein sinnvoller nächster Schritt.

FAQ

Ist DESIGN.md ein offizieller Standard?

Nicht in dem Sinne, wie es bei AGENTS.md der Fall ist. AGENTS.md hat unter agents.md eine zentrale Anlaufstelle, wird von mehr als 60,000 Open-Source-Projekten verwendet und steht unter der Schirmherrschaft der Agentic AI Foundation, die Teil der Linux Foundation ist. Für DESIGN.md gibt es im August 2026 weder eine zuständige Organisation noch eine veröffentlichte Spezifikation. Was es gibt, ist die Einführung 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 Sammlung aus der Community 73 weitere Dateien, die aus öffentlichen Websites rekonstruiert wurden. Behandeln Sie DESIGN.md als Konvention, die Sie jetzt übernehmen und frei erweitern können, weil niemand 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, sobald AGENTS.md nicht mehr schnell erfassbar ist oder sich die beiden Teile mit unterschiedlicher Geschwindigkeit ändern. AGENTS.md ändert sich, wenn sich der Build ändert. DESIGN.md ändert sich, wenn sich eine Entscheidung ändert. Das kommt seltener vor und ist inhaltlich gewichtiger. Wenn Sie die Dateien trennen, ergänzen Sie in AGENTS.md eine Zeile, die den Agent anweist, vor Änderungen am Code DESIGN.md zu lesen. Nicht jedes Tool lädt jede Markdown-Datei im Stammverzeichnis.

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

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

Wie lang sollte DESIGN.md sein?

Kurz genug, um sie bei jeder Interaktion ohne Bedenken zu laden. Die veröffentlichten Beispiele sind lang, weil sie eine vollständige visuelle Sprache festlegen: Die Datei von Nuxt umfasst im August 2026 etwa 2,100 Wörter, die von Vercel etwa 6,500. Ein Backend-Dienst benötigt in der Regel deutlich weniger. Beginnen Sie mit einer Seite. Erweitern Sie die Datei nur, wenn ein Agent etwas falsch macht, das sich mit einem einzigen Satz hätte verhindern lassen. Die Länge ist nicht entscheidend. Jede Zeile sollte eine Vorgabe enthalten, die der Agent sonst falsch umsetzen würde.