Eine CLAUDE.md, die befolgt wird
Hier ist eine Falle, die fast jeden erwischt: Deine CLAUDE.md-Datei wächst immer weiter. Du stößt auf ein Problem, du fügst eine Regel hinzu. Du stößt auf ein weiteres, du fügst eine weitere Regel hinzu. Nach kurzer Zeit hast du eine riesige Datei, und Claude fängt an, Teile davon zu ignorieren. Das ist kein Bug in Claude. So funktioniert die Datei.
Der entscheidende Punkt ist zu verstehen, dass CLAUDE.md keine erzwungene Konfiguration ist. Es ist eine Anleitung. Jede Zeile konkurriert mit jeder anderen Zeile um Claudes Aufmerksamkeit. Je länger die Datei wird, desto mehr konkurriert sie mit sich selbst, und desto unzuverlässiger befolgt Claude eine einzelne Regel. Das Ziel ist also nicht, alles aufzuschreiben. Das Ziel ist, die Datei knapp zu halten. Je schlanker die Datei, desto mehr davon befolgt Claude tatsächlich.
Frage zuerst, ob CLAUDE.md überhaupt das richtige Werkzeug ist
Bevor du eine Regel schreibst, frage dich, ob sie überhaupt in CLAUDE.md gehört. Manche Regeln sind Anleitungen, und manche Regeln sind harte Grenzen, die niemals überschritten werden dürfen. Das sind zwei unterschiedliche Aufgaben.
Nimm eine Regel wie „niemals auf main pushen“. Wenn du das in CLAUDE.md schreibst, hoffst du, dass Claude sie liest und respektiert. Meistens wird das auch klappen. Aber „meistens“ reicht nicht für etwas so Gefährliches. Eine harte Regel wie diese gehört stattdessen in einen Pre-Tool-Use-Hook.
Der Unterschied ist wichtig. Ein Hook ist Code, der ausgeführt wird, bevor Claude eine Aktion durchführt, und er kann die Aktion tatsächlich blockieren. Selbst wenn Claude also versucht, auf main zu pushen, stoppt der Hook das. Das ist echte Durchsetzung, keine höfliche Bitte. Verschiebe deine harten Regeln in Hooks und lass CLAUDE.md die weicheren Konventionen übernehmen.
Die vier Orte
CLAUDE.md ist nicht nur eine einzelne Datei, die in deinem Projekt liegt. Es gibt vier Orte, an denen sie existieren kann, und Claude lädt sie beim Start alle zusammen. Nichts fällt weg, und sie stapeln sich.
Hier ist, wofür jeder einzelne gedacht ist:
- Verwaltete Richtlinie — die Datei auf Organisationsebene, die dein Plattform-Team kontrolliert. Du kannst sie nicht ausschließen, daher ist die Organisationsrichtlinie immer aktiv.
- Benutzer — deine persönlichen Einstellungen, die dich über alle Projekte auf deinem Rechner hinweg begleiten.
- Projekt — die Datei, die mit deinem Team geteilt und ins Repository eingecheckt wird.
- Lokal — von git ignoriert. Deine persönlichen Notizen nur für dieses eine Repository.
Die letzte, lokal, wird leicht übersehen, ist aber wirklich praktisch. Angenommen, du refactorst gerade für dich allein in deinem eigenen Branch und möchtest, dass Claude während der Arbeit bestimmte Architekturentscheidungen im Hinterkopf behält. Das gehört nicht in die geteilte Projektdatei, wo es dein ganzes Team betreffen würde. Es gehört in lokal, wo es nur dir gehört, für dieses Repo.
Eine große Datei mit Imports aufteilen
Wenn deine Projektdatei lang wird, kannst du sie mit der Pfad-zu-Datei-Import-Syntax in Teile aufteilen. Statt einer Textwand verweist du auf andere Dateien:
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.mdDas ist großartig zum Organisieren. Aber wisse genau, was es dir bringt, denn man bekommt leicht den falschen Eindruck. Wenn Claude startet, erweitert es diese importierten Dateien inline, genau dort, wo du sie referenziert hast. Imports helfen dir also, Ordnung zu halten, aber alles wird trotzdem vorab geladen. Sie verringern nicht die Menge an Kontext, die Claude lesen muss. Verwende Imports zum Organisieren, nicht um die Last zu verkleinern.
Formulierung ist, was Regeln haften lässt
Sobald du entschieden hast, dass eine Regel in CLAUDE.md gehört, hängt es davon ab, wie du sie formulierst, ob Claude sie tatsächlich befolgt. Die meisten Regeln scheitern, weil sie vage sind. So behebst du das.
Sei spezifisch und überprüfbar
Schreibe nicht „befolge Best Practices“. Weißt du überhaupt genau, was das bedeutet? Wenn du nicht überprüfen kannst, ob sie befolgt wurde, kann Claude das auch nicht. Vergleiche diese beiden:
- Vage: „Befolge Best Practices für API-Routen.“
- Spezifisch: „Lege neue API-Routen in
src/api/handlersab, eine pro Datei.“
Die zweite ist eindeutig. Du kannst dir das Ergebnis ansehen und sofort sagen, ob es richtig gemacht wurde. Das ist die Messlatte, die jede Regel erreichen sollte.
Nenne die Alternative, verbiete nicht nur etwas
Wenn du Claude sagst, etwas nicht zu tun, sage auch, was stattdessen zu tun ist. Sonst lässt du die Tür offen.
- Lässt sie offen: „Verwende keine Default-Exports.“ Okay, aber was dann?
- Schließt sie: „Verwende benannte Exports, keine Default-Exports.“
Die zweite Version nennt die Alternative, sodass nichts zur Fehlinterpretation übrig bleibt.
Formuliere es schlicht, statt zu schreien
Wörter wie „WICHTIG“ und „DU MUSST“ retten selten eine Regel, die Claude ständig übersieht. Aktuelle Modelle befolgen eine schlicht formulierte Zeile, und zu viel Betonung sorgt meistens dafür, dass Claude die Regel überanwendet. Wenn eine Regel nicht flexibel sein darf, mach sie zu einem Hook. Wenn sie untergeht, mach die Datei kürzer.
Halte die Datei in Bearbeitung
Deine CLAUDE.md-Datei ist nie fertig. Behandle sie wie lebenden Code, der ständig überarbeitet wird.
Wenn Claude etwas falsch macht, seufze nicht einfach und korrigiere es von Hand. Behandle es als Bug-Report gegen deine CLAUDE.md-Datei. Du kannst Claude sogar direkt sagen: „füge das der CLAUDE.md-Datei hinzu“, und es schreibt die Regel für dich. So wird die Datei jedes Mal besser, wenn etwas schiefgeht.
Das Fazit
Behandle deine CLAUDE.md wie Produktionscode. Wenn du eine Zeile nicht rechtfertigen kannst, lösche sie. So hältst du die Datei schlank und befolgbar:
- Verschiebe harte Regeln in Hooks, wo sie tatsächlich durchgesetzt werden.
- Organisiere lange Dateien mit Imports (denk nur daran, dass sie den Kontext nicht verringern).
- Mache jede Regel spezifisch und überprüfbar, und nenne die Alternative.
- Formuliere Regeln schlicht, statt Betonung hinzuzufügen.
- Überarbeite die Datei weiterhin, wann immer Claude etwas falsch macht.
Die ganze Idee ist einfach. Je schlanker die Datei, desto mehr davon befolgt Claude.