Die Prioritätsreihenfolge auf einen Blick
Lesen Sie vom engsten zum weitesten Geltungsbereich. Eine Regel in einer spezifischeren Datei gewinnt gegenüber einer allgemeineren, und eine Regel, die der Nutzer während der Session eingibt, gewinnt gegenüber jeder Datei.
- Eingaben des Nutzers in der Session: gewinnen immer, auch wenn sie einer Datei widersprechen.
- `SKILL.md`: nur aktiv, wenn diese Fähigkeit aufgerufen wird, und auf diese beschränkt.
- `CLAUDE.md` / toolspezifische Datei: das Verhalten dieses Tools in diesem Repository.
- `AGENTS.md`: die Projektregeln für jeden beliebigen Agenten.
- `DESIGN.md`: der visuelle Vertrag, auf den die oben genannten Dateien verweisen, anstatt mit ihnen zu konkurrieren.
DESIGN.md steht bewusst leicht außerhalb des Stacks. Die anderen drei Dateien sagen einem Agenten, wie er *arbeiten* soll; diese hier sagt ihm, wie das Ergebnis *aussehen* soll. Sie stehen selten im Konflikt, weshalb ein Projekt sie einführen kann, ohne andere Vereinbarungen neu verhandeln zu müssen.
AGENTS.md: die toolübergreifende Projektdatei
Dies ist die Datei, die zuerst geschrieben werden sollte. Sie wird von einer wachsenden Zahl an Agenten gelesen, gehört keinem spezifischen Anbieter und enthält die Dinge, die unabhängig vom Ausführenden gelten: wie gebaut wird, wie getestet wird, was nicht angefasst werden darf und welchen Konventionen die Codebasis tatsächlich folgt.
Die anbieterspezifischen Äquivalente nehmen zu: Copilot liest .github/copilot-instructions.md (und in VS Code auch AGENTS.md), die Gemini CLI liest eine GEMINI.md-Hierarchie, Cursor nutzt sein Rules-Verzeichnis. Das folgende Muster – eine kanonische AGENTS.md plus eine schlanke, toolspezifische Datei, die diese importiert oder referenziert – ist der Weg, all diese Tools zu unterstützen, ohne fünf divergierende Regelwerke pflegen zu müssen.
Die entscheidende Disziplin ist hier die Kostenfrage. Da die Datei bei jeder Anfrage geladen wird, wird jede Zeile dauerhaft „bezahlt“. Eine Regel verdient nur dann einen Platz direkt in der Datei, wenn sie das Standardverhalten ändert, breit anwendbar ist und Fehler bei ihrer Missachtung teuer wären. Befehlskataloge, API-Schemas und Setup-Prozeduren gehören in ein separates Dokument mit einem einzeiligen Verweis.
# AGENTS.md
## Build and verify
- `pnpm dev` on :4000. Never run `pnpm build` — it corrupts the shared dev cache.
- Verify with `tsc --noEmit`, not a build.
## Conventions
- Server work goes in `src/server/` as server actions, not API routes.
- Never hardcode theme colors; use the semantic tokens in DESIGN.md.
## Before you act
- Changing the payment flow: read `docs/PRICING.md` first.CLAUDE.md: ein Import plus Anhang
Der häufigste Fehler besteht darin, CLAUDE.md und AGENTS.md als zwei vollständige Kopien zu pflegen. Sie driften schleichend auseinander, und dieser Drift wird sichtbar, wenn ein Agent selbstbewusst einer Regel folgt, die Sie bereits vor zwei Monaten gelöscht haben.
# CLAUDE.md
@AGENTS.md
## Claude Code only
- Use the local browser tool for hydration checks; the remote one stalls RSC.
- Slash commands live in `.claude/commands/`.Die Import-Falle
Die @file-Expansion ist nicht universell. Claude expandiert relative Pfade innerhalb des Projekts; einige andere Tools geben die Zeile als literalen Text weiter, und absolute Pfade bewirken oft stillschweigend gar nichts. Überprüfen Sie, was Ihr Agent tatsächlich lädt, bevor Sie sich auf einen Import verlassen.
SKILL.md: eine Fähigkeit, kein Regelwerk
Die Unterscheidung, die Skills effektiv macht: AGENTS.md ist *immer* im Kontext, während ein Skill nur geladen wird, *wenn er relevant ist*. Dieser Unterschied ist eine Budget-Entscheidung. Eine 400-Zeilen-Checkliste für Code-Reviews in AGENTS.md kostet bei jeder Anfrage, selbst wenn nur ein Tippfehler korrigiert wird. Dieselbe Checkliste als Skill kostet nichts, bis das Review tatsächlich beginnt.
Der entscheidende Faktor ist also nicht die Wichtigkeit, sondern die Häufigkeit. Regeln, die für fast jede Anfrage gelten, gehören in die Datei, die immer geladen wird. Verfahren, die für eine bestimmte Art von Aufgabe gelten (Deployment, Review, Generierung einer Migration), gehören in einen Skill.
| AGENTS.md | SKILL.md | DESIGN.md | |
|---|---|---|---|
| Geladen | Jede Anfrage | Bei Aufruf | Beim Schreiben der UI |
| Scope | Gesamtes Projekt | Ein Aufgabentyp | Alles Visuelle |
| Gut geeignet | Build-Befehle, Constraints | Deployment-Schritte, Review-Checkliste | Tokens, Typografie-Skala, Motive |
| Nicht geeignet | Ein 300-zeiliges Verfahren | Eine Regel, die bei jeder Anfrage benötigt wird | Alles Nicht-Visuelle |
| Kosten einer falschen Zeile | Dauerhaft bezahlt | Bei Aufruf bezahlt | Falsche Pixel |
DESIGN.md: die Datei, die niemand schreibt
Hier liegt die Lücke. AGENTS.md bietet keinen natürlichen Platz für eine Farbskala. In CLAUDE.md geht es um das Tool-Verhalten. Ein Skill wird aufgerufen, ist aber nicht omnipräsent. Somit landet der visuelle Vertrag nirgendwo, und ein Agent ohne visuellen Vertrag greift auf Standardwerte zurück – und das ist der Grund, warum KI-generierte Websites alle gleich aussehen.
Eine DESIGN.md schließt diese Lücke. Sie enthält mindestens semantische Farb-Tokens für Light- und Dark-Mode, die Schriftkombination und -skala, das Spacing- und Radius-System sowie die Do's und Don'ts, die verhindern, dass ein Agent ein neues Pattern erfindet, wenn er auf einen unbekannten Fall stößt.
# DESIGN.md
## Color (semantic, light + dark)
--background / --foreground / --card / --primary / --muted-foreground …
## Type
Headings: Fraunces 600, -0.02em. Body: Inter 400, 1.6.
Scale: 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem.
## Motifs
Hairline rules between sections. Radius scales with element size.
## Don't
No gradient text. No shadow on flat surfaces. Never hardcode a hex.Der Grund, warum diese Datei dort funktioniert, wo ein Prompt versagt, ist wenig glamourös: Sie wird zu Beginn jeder Session neu gelesen. Anweisungen innerhalb einer Konversation degradieren, wenn der Kontext wächst. Eine Datei tut dies nicht.
Die anderen drei Dateien sagen einem Agenten, wie er zu arbeiten hat. Nur eine sagt ihm, wie das Ergebnis aussehen soll – und das ist meistens diejenige, die nicht existiert.
Werden alle vier benötigt?
Nein, und mit allen vieren gleichzeitig zu starten, ist der falsche Weg. In ungefährer Reihenfolge des Nutzens:
- Zuerst `AGENTS.md`. Höchster Wert pro Zeile, funktioniert toolübergreifend, geringer Aufwand beim Schreiben.
- Danach `DESIGN.md`, falls eine UI ausgeliefert wird. Dies ist die größte Qualitätssteigerung bei geringstem Aufwand, da nichts anderes dies abdeckt.
- `CLAUDE.md` als einzeiliger Import, ergänzt um Details nur dann, wenn tatsächlich toolspezifische Regeln vorliegen.
- Skills zuletzt, sobald auffällt, dass dasselbe lange Verfahren wiederholt erklärt werden muss.
Eine DESIGN.md erhalten, ohne eine schreiben zu müssen
Jedes Identity Forge Kit lässt sich in eine vollständige DESIGN.md serialisieren (semantische Tokens in Light und Dark, eine echte Schriftkombination, Motive sowie Do's & Don'ts), die jeder Coding-Agent lesen kann. Kostenlose Kits erfordern kein Konto.
Wie viele Projekte nutzen diese Dateien tatsächlich?
Die Dateien werden meist danach verglichen, wofür sie *da* sind. Es lohnt sich zu wissen, wie sie in der Praxis verwendet werden, denn die Lücke zwischen Konvention und Praxis ist der Ort, an dem die meisten Missverständnisse entstehen.
Wir haben 299 öffentliche DESIGN.md-Dateien im Root-Verzeichnis von GitHub-Repositories analysiert und ausgewertet. Die erste Erkenntnis ordnet den gesamten Vergleich neu ein: Nur 24 % von ihnen beschreiben überhaupt das visuelle Design. Die anderen 76 % sind Software-Architekturdokumente: wie ein System aufgebaut ist, nicht wie ein Produkt aussieht.
DESIGN.md ist eine Namenskollision
Der Name existiert bereits Jahre vor der Konvention für Designsysteme. Wenn Sie eine solche Datei zu einem bestehenden Repository hinzufügen, sollten Sie damit rechnen, dass einige Leser und Tools ein Architekturdokument erwarten. Es empfiehlt sich, in einer einzeiligen Kopfzeile festzulegen, um welche Art es sich handelt.
Innerhalb der 72 Dateien, die tatsächlich ein visuelles System beschreiben, wird die oben diskutierte Aufteilung der Verantwortlichkeiten nicht eingehalten. 86 % verwenden keine semantischen Farbrollennamen, sodass die Datei auf keine Komponente angewendet werden kann, die sie nicht explizit beschreibt – genau das ist jedoch ihre Aufgabe. 76 % enthalten keine Verbote, dabei sind Verbote die Form von Anweisungen, denen Coding-Agents am zuverlässigsten folgen. 69 % lassen den Dark Mode weg, sodass ein komplettes Theme erfunden werden muss.
Die praktische Interpretation: Die meisten Projekte, die eine DESIGN.md hinzufügen, schreiben ein Dokument statt eines Kontrakts. Der Unterschied besteht darin, ob ein Agent einen Wert daraus auflösen kann, ohne raten zu müssen.
Wenn ich nur eine Datei schreibe, welche sollte es sein?
AGENTS.md. Sie wird vom breitesten Set an Tools gelesen, ist nicht an einen Anbieter gebunden und enthält die Regeln, die verhindern, dass ein Agent den Build zerstört. Wenn ein User Interface ausgeliefert wird, folgt DESIGN.md dicht darauf, da nichts anderes diesen Bereich abdeckt.
Ersetzt AGENTS.md die Datei CLAUDE.md?
weitgehend. Behalten Sie CLAUDE.md als @AGENTS.md plus tatsächlich Claude-spezifische Regeln bei. Löschen Sie den Rest komplett, falls keine vorhanden sind. Ein leerer Anhang ist kostengünstiger als ein Duplikat.
Werden diese Dateien tatsächlich gelesen oder ist das Cargo-Kult?
Sie werden gelesen, aber sie sind nicht magisch. Das beobachtbare Fehlerbild ist die Länge: Eine 600-zeilige Anweisungsdatei konkurriert mit sich selbst, und spezifische Regeln werden unter allgemeinen begraben. Kurze Dateien werden zuverlässiger befolgt als ausführliche.
Kann DESIGN.md einfach innerhalb von AGENTS.md existieren?
Das ist möglich und für kleine Projekte völlig ausreichend. Eine Trennung ist sinnvoll, sobald das visuelle System eine echte Tiefe erreicht, da Token-Tabellen lang sind und in einem anderen Zyklus als Build-Befehle geändert werden und weil eine separate Datei von Tools konsumiert werden kann, die überhaupt keine Agent-Anweisungen lesen.
Was passiert, wenn zwei Dateien kollidieren?
Der engere Scope sollte gewinnen, aber verlassen Sie sich nicht darauf, dass das Modell dies sauber schlichtet. Konflikte sollten beseitigt statt priorisiert werden: Wenn zwei Dateien widersprüchlich sind, ist eine von ihnen veraltet.