Die Prioritätenfolge auf einen Blick
Lesen Sie vom engsten Scope nach außen. 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 Repo.
- `AGENTS.md` – die Projektregeln für jeden Agenten.
- `DESIGN.md` – der visuelle Vertrag, auf den die oben genannten Dateien verweisen, statt 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 Anzahl an Agenten gelesen, gehört keinem bestimmten Anbieter und enthält die Dinge, die unabhängig davon gelten, wer die Arbeit ausführt: wie gebaut wird, wie getestet wird, was nicht angefasst werden darf und welchen Konventionen die Codebasis tatsächlich folgt.
Die entscheidende Disziplin ist hier die Kostenfrage. Da sie 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 teuer zu stehen kämen. 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
Ein häufiger Fehler ist es, CLAUDE.md und AGENTS.md als zwei vollständige Kopien zu pflegen. Sie entwickeln schleichend einen Drift, der dann dadurch sichtbar wird, dass 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, und ein Skill wird geladen, *wenn er relevant ist*. Dieser Unterschied ist eine Budget-Entscheidung. Eine 400-zeilige Code-Review-Checkliste in AGENTS.md wird bei jeder Anfrage bezahlt, selbst wenn nur ein Tippfehler korrigiert wird. Dieselbe Checkliste als Skill kostet nichts, bis die Review tatsächlich beginnt.
Der Test ist also nicht die Wichtigkeit, sondern die Häufigkeit. Regeln, die für fast jede Anfrage gelten, gehören in die dauerhaft geladene Datei. Prozeduren, 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 | Bei jeder Anfrage | Bei Aufruf | Beim Schreiben von UI |
| Scope | Gesamtes Projekt | Ein Aufgabentyp | Alles Visuelle |
| Geeignet | Build-Befehle, Constraints | Deploy-Schritte, Review-Checkliste | Tokens, Typografie-Skala, Motive |
| Ungeeignet | 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, er ist nicht omnipräsent. Somit bleibt der visuelle Vertrag unberücksichtigt – und ein Agent ohne visuellen Vertrag greift auf Standardwerte zurück, weshalb KI-generierte Websites oft 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 neue Muster 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 unspektakulär: Sie wird zu Beginn jeder Session neu gelesen. Anweisungen innerhalb einer Konversation verlieren an Wirkung, je mehr der Kontext wächst. Eine Datei hingegen 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 nicht ratsam. In grober Reihenfolge des Nutzens:
- Zuerst `AGENTS.md`. Höchster Wert pro Zeile, funktioniert toolübergreifend, geringer Schreibaufwand.
- Danach `DESIGN.md`, falls UI ausgeliefert wird. Dies ist die größte Qualitätssteigerung bei geringstem Aufwand, da nichts anderes diesen Bereich abdeckt.
- `CLAUDE.md` als einzeiliger Import, ergänzt nur dann um weitere Details, wenn tatsächlich toolspezifische Regeln vorliegen.
- Skills zuletzt, sobald bemerkt wird, dass dasselbe lange Verfahren wiederholt erklärt werden muss.
Eine DESIGN.md erhalten, ohne eine schreiben zu müssen
Jedes Identity Forge Kit wird in eine vollständige DESIGN.md serialisiert – inklusive semantischer Design-Tokens für Light- und Dark-Mode, einer konkreten Font-Pairing-Strategie, Motiven sowie Do's & Don'ts –, die von jedem Coding-Agent gelesen werden 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 eingesetzt 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 – also 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 einige Tools – ein Architekturdokument erwarten. Es empfiehlt sich, im Header in einer Zeile festzulegen, um welche Art von Dokument es sich handelt.
Von den 72 Dateien, die tatsächlich ein visuelles System beschreiben, wird die oben diskutierte Aufteilung der Verantwortlichkeiten nicht eingehalten. 86 % verwenden keine semantischen Farbrollen-Namen, sodass die Datei auf keine Komponente angewendet werden kann, die sie nicht explizit beschreibt – und genau das ist eigentlich 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 Schlussfolgerung: Die meisten Projekte, die eine DESIGN.md hinzufügen, schreiben ein Dokument statt eines Vertrags. Der Unterschied besteht darin, ob ein Agent einen Wert daraus ableiten kann, ohne raten zu müssen.
Wenn ich nur eine Datei schreibe, welche sollte es sein?
AGENTS.md. Sie wird von der breitesten Palette 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 sonst nichts 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 Sie keine spezifischen Regeln haben – 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-Zeilen-Anweisungsdatei konkurriert mit sich selbst, und spezifische Regeln werden unter allgemeinen begraben. Kurze Dateien werden zuverlässiger befolgt als ausführliche.
Kann DESIGN.md nicht einfach innerhalb von AGENTS.md stehen?
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 aktualisiert werden als Build-Befehle – 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 eher beseitigt als priorisiert werden: Wenn zwei Dateien widersprüchliche Angaben machen, ist eine von ihnen veraltet.