Was gehört in eine CLAUDE.md?
Vier Dinge: lauffähige Befehle (Dev, Test, Lint, Build), die Projektstruktur, ein echtes Code-Snippet als Style-Vorbild und Grenzen in drei Stufen (immer erlaubt, erst fragen, niemals). Unter 60 Zeilen, und jede Zeile muss das Agent-Verhalten ändern.
Die CLAUDE.md (bei anderen Tools AGENTS.md) ist die wichtigste Einzeldatei für die Qualität deines Coding-Agenten. Sie wird in jeder Session automatisch geladen und beantwortet die Fragen, die der Agent sonst rät oder dir jedes Mal neu stellt.
Die vier Sektionen
1. Befehle: Dev-Server, Tests (auch: wie führe ich einen einzelnen Test aus), Lint, Build. Copy-paste-lauffähig, mit allen Flags. Keine Platzhalter wie <dein-test-hier>.
2. Projektstruktur: Nur die Ordner, die zählen, mit je einem Satz Zweck. Kein vollständiger Verzeichnisbaum.
3. Code-Style: Ein echtes Snippet aus dem Repo als kanonisches Beispiel. Ein Vorbild schlägt drei Absätze Regel-Prosa.
4. Grenzen in drei Stufen:
- Immer erlaubt: Tests laufen lassen, in
src/editieren - Erst fragen: neue Dependencies, Schema-Migrationen, CI-Änderungen
- Niemals: Secrets committen,
node_modules/editieren, Force-Push
Die zwei harten Regeln
Unter 60 Zeilen. Die Datei kostet in jeder Session Kontextfenster. Sie ist kein Wiki, sie ist eine Betriebsanweisung.
Jede Zeile muss Verhalten ändern. Der Test: Kann die Zeile gestrichen werden, ohne dass der Agent anders arbeitet? Dann streichen. Die CLAUDE.md ist Verhaltenssteuerung, keine Team-Dokumentation.
Die Faustprobe
Starte eine frische Agent-Session und gib eine kleine Aufgabe. Muss der Agent nach Befehlen, Konventionen oder dem Stack fragen? Dann fehlt genau das in der Datei. Übrigens kann der Agent die erste Version selbst schreiben: „Analyze this codebase and generate a CLAUDE.md", mit der Auflage, nur Gefundenes zu dokumentieren und nichts zu erfinden.