Eine CLAUDE.md, die befolgt wird

Frage zuerst, ob CLAUDE.md überhaupt das richtige Werkzeug ist

Bevor du eine Regel schreibst, frage dich, ob sie überhaupt in die CLAUDE.md gehört. Manche Regeln sind Orientierungshilfen, 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 die CLAUDE.md schreibst, hoffst du, dass Claude sie liest und respektiert. Meistens wird es das tun. Aber „meistens“ ist bei etwas so Gefährlichem nicht gut genug. Eine solche harte Regel 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 es. Das ist echte Durchsetzung, keine höfliche Bitte. Verschiebe deine harten Regeln in Hooks und lass CLAUDE.md die weicheren Konventionen übernehmen.

Die vier Speicherorte

CLAUDE.md ist nicht nur eine einzige Datei, die in deinem Projekt liegt. Es gibt vier Orte, an denen sie liegen kann, und Claude lädt sie beim Start alle zusammen. Nichts wird verworfen, und sie stapeln sich.

Hier ist, wofür jede einzelne gedacht ist:

• Verwaltete Richtlinie — die Datei auf Organisationsebene, die dein Platform-Team kontrolliert. Du kannst sie nicht ausschließen, also ist die Organisationsrichtlinie immer im Spiel.
• Benutzer — deine persönlichen Einstellungen, die dich über jedes Projekt auf deinem Rechner hinweg begleiten.
• Projekt — die mit deinem Team geteilte Datei, die ins Repo eingecheckt wird.
• Lokal — von Git ignoriert. Deine persönlichen Notizen nur für dieses eine Repository.

Diese letzte, lokal, wird leicht übersehen, ist aber wirklich praktisch. Angenommen, du refaktorierst in deinem eigenen Branch und möchtest, dass Claude während deiner Arbeit bestimmte Architekturentscheidungen im Kopf behält. Das gehört nicht in die geteilte Projektdatei, wo es dein ganzes Team betreffen würde. Es kommt in die lokale Datei, wo es nur dir für dieses Repo gehört.

Eine große Datei mit Imports aufteilen

Wenn deine Projektdatei anfängt, lang zu werden, kannst du sie mit der Pfad-zu-Datei-Import-Syntax in Teile zerlegen. Statt einer Textwand verweist du auf andere Dateien:

@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md

Das ist großartig zum Organisieren. Aber wisse genau, was es dir bringt, denn es ist leicht, sich eine falsche Vorstellung zu machen. 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 im Voraus geladen. Sie reduzieren nicht die Menge an Kontext, die Claude lesen muss. Nutze Imports zum Organisieren, nicht um die Last zu verringern.

Formulierung entscheidet, ob Regeln haften bleiben

Sobald du entschieden hast, dass eine Regel in die CLAUDE.md gehört, hängt es davon ab, wie du sie formulierst, ob Claude ihr tatsächlich folgt. Die meisten Regeln scheitern, weil sie vage sind. Hier ist, wie du das beheben kannst.

Sei konkret 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.“
• Konkret: „Lege neue API-Routen in src/api/handlers ab, eine pro Datei.“

Die zweite ist eindeutig. Du kannst dir das Ergebnis ansehen und sofort erkennen, 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, sag auch, was stattdessen zu tun ist. Sonst lässt du die Tür offen.

• Lässt sie offen: „Verwende keine Default-Exporte.“ Okay, aber was dann?
• Schließt sie: „Verwende benannte Exporte, keine Default-Exporte.“

Die zweite Version nennt die Alternative, sodass nichts mehr falsch interpretiert werden kann.

Betonung ist ein Budget

Wörter wie „IMPORTANT“ und „YOU MUST“ erhöhen tatsächlich die Priorität einer Regel. Aber nur relativ zu allem, was leiser um sie herum steht. Wenn jede Regel schreit, fällt nichts mehr auf, und die Betonung bedeutet nichts mehr. Behandle Betonung also wie ein Budget. Gib es für die zwei oder drei Regeln aus, die wirklich schaden, wenn sie gebrochen werden, und lass den Rest auf normaler Lautstärke.

Halte die Datei in ständiger Überarbeitung

Deine CLAUDE.md-Datei ist nie fertig. Behandle sie wie lebenden Code, der ständig bearbeitet wird.

Wenn Claude etwas Falsches tut, seufze nicht einfach und behebe es manuell. Behandle es als Bug-Report gegen deine CLAUDE.md-Datei. Du kannst Claude sogar direkt sagen: „füge das zur CLAUDE.md-Datei hinzu“, und es wird die Regel für dich schreiben. So wird die Datei jedes Mal besser, wenn etwas schiefgeht.

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:

1. Verschiebe harte Regeln in Hooks, wo sie tatsächlich durchgesetzt werden.
2. Organisiere lange Dateien mit Imports (denk nur daran, dass sie den Kontext nicht reduzieren).
3. Mache jede Regel konkret und überprüfbar, und nenne die Alternative.
4. Gib dein Betonungsbudget für die wenigen Regeln aus, die am meisten zählen.
5. Überarbeite die Datei weiter, wann immer Claude etwas falsch macht.

Die ganze Idee ist einfach. Je schlanker die Datei, desto mehr davon befolgt Claude.