Das Problem mit den meisten CLAUDE.md-Dateien

Die meisten CLAUDE.md-Dateien, die ich sehe, haben das gleiche Problem: Sie sind zu lang und zu generisch. Eine seitenweise Anleitung, was guter Code ist. Generische Hinweise auf Best Practices, die das Modell sowieso kennt. Dinge, die in jeder README stehen könnten.

Das führt dazu, dass der Agent die Instructions nicht ernst nimmt — weil sie keine Information tragen, die er nicht schon hätte. Eine CLAUDE.md ist dann sinnvoll, wenn sie das enthält, was spezifisch für dieses Projekt ist und nirgendwo sonst steht.

Was in die Projekt-CLAUDE.md gehört

  • Projekt-spezifische Constraints: Warum bestimmte Entscheidungen so getroffen wurden. Eigenheiten die nicht offensichtlich sind.
  • Kritische Sicherheitsregeln: Was niemals passieren darf. Deploy-Regeln, Branch-Protection-Logik, Secrets-Handling.
  • Architektur-Shortcuts: Welche Patterns hier Standard sind. Wo neue Dateien hingehören. Naming-Conventions die vom Standard abweichen.
  • Tool-Kommandos: Welches CLI für was. Nicht npm sondern bun. Nicht python sondern uv run.

Was in die globale CLAUDE.md gehört

Persönliche Präferenzen, die für alle Projekte gelten. Antwort-Stil-Vorgaben. Skill-Referenzen. Tool-Präferenzen (ripgrep statt grep, fd statt find). Dinge, die du dir nicht in jedem Projekt neu erklären willst.

Die globale Datei läuft in jeden Kontext rein — entsprechend vorsichtig mit der Größe. Kurze, dichte Information trägt besser als ausführliche Erklärungen.

AGENTS.md, copilot-instructions.md und Co.

Diese Dateien sind Äquivalente für andere Tools — Cursor, GitHub Copilot, OpenCode. Die Strategie ist dieselbe: projekt-spezifische Information die nirgendwo sonst steht. Nichts generisches.

Ein nützliches Pattern: eine zentrale Instructions-Datei und die anderen Dateien mit@dateiname darauf referenzieren. So pflegt man nur eine Quelle.

Was raus sollte

Alles, was das Modell schon weiß. "Schreibe sauberen Code." "Nutze sprechende Variablennamen." "Beachte Sicherheit." Diese Hinweise blähen die Datei auf ohne Information zu addieren. Kürzer ist fast immer besser.