Wo gehören die Anweisungen in Claude Code hin: CLAUDE.md, Pfadregeln oder Hooks

Die meisten Teams, die Claude Code verwenden, halten mittlerweile eine CLAUDE.md-Datei bereit, doch nur wenige können sagen, ob diese tatsächlich etwas bewirkt. Ein häufiges Muster ist eine Datei, die auf mehrere hundert Zeilen angewachsen ist, wobei das Modell manche Anweisungen befolgt und andere stillschweigend ignoriert. Die Lösung liegt selten in einem besseren Vorlageformat; vielmehr geht es darum, zu verstehen, was die Datei eigentlich ist, und jede Anweisung an das entsprechende Verarbeitungsmechanismus weiterzuleiten. Dieser Leitfaden behandelt sieben praktische Ansätze – von der Kürzung der Datei über Regelungen nach Pfad bis hin zum Verschieben strenger Anforderungen in Hooks sowie der Überprüfung, was Claude tatsächlich geladen hat.

Falls Sie mit einer leeren Datei beginnen, behandelt das praktische Handbuch zur Erstellung einer effektiven CLAUDE.md-Datei Inhalt und Struktur. Der Fokus hier ist anders: Welche Anweisungen gehören überhaupt in die CLAUDE.md-Datei und wohin soll der Rest?

CLAUDE.md ist Kontext, keine Konfiguration

Jedes andere Problem hat seine Wurzeln in diesem Missverständnis. Claude Code fügt die Datei als Nachricht in das Gespräch ein; sie wird nicht in den Systemprompt integriert, und nichts im Laufzeitumfeld stellt ihre Einhaltung sicher. Das Modell liest sie und versucht, sich daran zu halten. Darüber hinaus gibt es keine Garantien, und die Chancen sinken weiter, wenn die Formulierung unklar ist oder zwei Anweisungen in entgegengesetzte Richtungen drängen.

Ein nützliches mentales Modell ist ein Übergabememo für einen kompetenten Teamkollegen, der es beim Morgenkaffee überfliegt und anschließend wieder an die eigentliche Arbeit geht. Was diesen Prozess überlebt, sind Inhalte, die kurz, präzise und konsistent sind. Das macht Länge, Präzision und interne Konsistenz zu den einzigen wirklichen Hebeln, die man hat – nicht Stilfragen.

Halten Sie die Quelldatei unter 200 Zeilen

Die aktuelle Empfehlung ist, bei etwa 200 Zeilen zu bleiben. Darüber hinaus verbraucht die Datei mehr Platz im Kontextfenster, und die Einhaltung wird schlechter statt besser.

Das ist gegenintuitiv: Je mehr Anweisungen es gibt, desto weniger werden tatsächlich befolgt. Jede Zeile konkurriert um dieselbe begrenzte Aufmerksamkeit wie alle anderen Zeilen sowie das Gespräch selbst. Betrachten Sie ein Team, dessen Datei 340 Zeilen enthielt. Wenn diese auf etwa 120 reduziert wurden, befolgte Claude die Anweisungen zuverlässiger. Keine der gelöschten Zeilen war falsch; sie waren lediglich Störgeräusche, die sich über die wichtigen Anweisungen legten.

Es gibt außerdem eine harte Obergrenze, gegen die man jedoch nicht designen sollte: Laut den Dokumenten zum Zeitpunkt der Erstellung werden Dateien, die größer als 4 MiB sind, vollständig übersprungen. Die Zuverlässigkeit leidet bereits lange bevor eine Datei dieser Größe erreicht wird.

Löschen Sie, was Claude aus dem Repository herausfinden kann

Die effektivste Bearbeitungsregel ist einfach: Entfernen Sie alles, was Claude durch das Lesen der Codebasis herausfinden könnte. Dies entspricht den Anpassungen, die die eigene /doctor-Überprüfung von Claude Code vorschlägt – sie entfernen Ordnerrahmen, Abhängigkeitslisten und hochlevelige Architekturbeschreibungen, während sie Fallstricke, Begründungen sowie Konventionen, die von den Standardeinstellungen der Tools abweichen, beibehalten. Mit anderen Worten: Es wird die übliche Inhaltsstruktur dieser Dateien umgekehrt.

Dinge, die entfernt werden sollten:

• Die Ordnerrahmenstruktur, da Claude die Verzeichnisse selbst auflisten kann.
• Die Abhängigkeitsliste, die bereits in package.json aufgeführt ist.
• Eine erzählerische Übersicht der Architektur, die der Code genauer wiedergibt.

Dinge, die beibehalten werden sollten:

• Code, der wie ein Fehler aussieht, aber absichtlich ist.
• Der Grund, warum der offensichtliche Ansatz abgelehnt wurde.

Jede Konvention, die der Dokumentation des Frameworks widerspricht.

Befehle, die niemand von selbst finden würde.

Eine gute Prüfung: Wenn ein kompetenter Ingenieur mit dem Repository geöffnet innerhalb von zehn Minuten etwas lernen kann, sollte es weggelassen werden. Wenn er es nur durch das Zerstören von etwas herausfinden würde, sollte es aufgeschrieben werden.

Hinweise für Menschen zu null Token-Kosten hinterlassen

Blockebene HTML-Kommentare werden entfernt, bevor der Inhalt der Datei Claudes Kontext erreicht. Dadurch können Sie die Datei für die Personen, die sie warten, annotieren, ohne den Budget des Modells zu verbrauchen – zum Beispiel um festzuhalten, warum ein Abschnitt verschoben wurde:

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Ihre Teamkollegen sehen die Historie; das Modell zahlt nie dafür.

@imports ordnen die Datei, speichern aber keinen Kontext

Wenn ein CLAUDE.md zu lang wird, ist die erste Reaktion, es in mehrere Dokumente aufzuteilen und diese einzubinden:

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

Das sieht aus wie träge Ladung, ist aber nicht der Fall. Die importierten Dateien werden bei Start zusammen mit dem CLAUDE.md, das auf sie verweist, ausgepackt und im Kontext geladen. Auch wenn 340 Zeilen in vier Dateien aufgeteilt werden, werden dennoch dieselben 340 Zeilen geladen.

Importe haben durchaus legitime Anwendungsbereiche. Sie helfen bei der Organisation und ermöglichen es, eine einzige, kanonische Anleitungssammlung zwischen verschiedenen Tools zu teilen. Wenn ein Repository bereits ein AGENTS.md enthält, vermeidet eine einzige @AGENTS.md-Zeile im CLAUDE.md das Aufrechterhalten von zwei unterschiedlichen Kopien. Erwarten Sie jedoch nicht, dass sie die Nutzung des Kontexts verringern. Für Anweisungen, die nur gelegentlich geladen werden sollen, sind path-basierte Regeln erforderlich.

Bedingte Regeln mit .claude/rules und Pfaden einschränken

Dateien in .claude/rules/ können im Frontmatter ein paths-Feld deklarieren. Dies ist die Funktion, die das bietet, was die Nutzer von Imports erwarten: Eine globale Regel bleibt außerhalb des Kontexts, bis Claude eine entsprechende Datei liest oder bearbeitet. Das Frontmatter einer API-Regeldatei könnte wie folgt aussehen:

---
paths:
  - "src/api/**/*.ts"
---

Unter dem Frontmatter enthält der Regelkörper die Konventionen, die nur auf diesen Teil des Baums zutreffen, wie beispielsweise Eingabenvalidierung, das gemeinsame Fehlerformat sowie die Bereiche, in denen SQL erlaubt ist:

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

Dadurch entfällt für die Frontend-Arbeit die Kostenbelastung durch API-Konventionen, und für die API-Arbeit entfällt die Kostenbelastung durch Testskonventionen.

In der Praxis ist dies die Lösung für ein übermäßig gewachsenes CLAUDE.md. Teilen Sie den Inhalt nach Themen auf, ordnen Sie jedes Thema den zugehörigen Verzeichnissen zu und reservieren Sie die Wurzeldatei für Anleitungen, die für das gesamte Projekt gelten. Eine Regeldatei ohne Feld paths wird in jeder Sitzung geladen, daher sollten Sie dies als bewusste Entscheidung und nicht als Standard betrachten.

Globs unterstützen die Erweiterung mit Klammern, sodass eine Regel mehrere Endungen sowie ein separates Testmuster abdecken kann:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Unverzichtbare Schritte gehören in Hooks

Ausdrücke wie „Lint vor jedem Commit“, „Pushen Sie nicht direkt in main“ oder „Formatieren Sie jede Datei nach der Bearbeitung“ sind in CLAUDE.md üblich. In den meisten Fällen werden sie befolgt, die Ausnahmen werden bemerkt, und Teams entscheiden dann, dass dem Modell nicht vertraut werden kann.

Doch das ist das dokumentierte Verhalten: CLAUDE.md beeinflusst, was Claude tut, ohne dies zu garantieren. Für einen Schritt, der zu einem festgelegten Zeitpunkt im Lebenszyklus der Sitzung stattfinden muss, führt ein Hook zu diesem Zeitpunkt einen Shell-Befehl aus – unabhängig von der Beurteilung des Modells. Ein PreToolUse-Hook kann sogar einen Toolaufruf vollständig ablehnen, etwas, was weder fettgedruckter noch großgeschriebener Markdown erreichen kann.

Eine praktische Methode, um jede Art von Anweisung zuzuweisen:

• Eine Konvention, der Claude im Allgemeinen folgen sollte, wird in CLAUDE.md festgelegt.
• Eine Regel für einen bestimmten Bereich des Codebases wird in .claude/rules/ zusammen mit paths abgelegt.
• Eine Anforderung mit keiner Toleranz für Ausnahmen wird zu einem Hook.
• Ein wiederholbarer mehrschrittiger Ablauf wird zu einer Fähigkeit.

Die Verlegung einiger „immer“ geltender Regeln in Hooks bringt einen doppelten Vorteil: Die Anforderungen werden nun tatsächlich durchgesetzt, und die Datei enthält nicht länger Zeilen, die niemals erfolgreich sein können, wodurch mehr Aufmerksamkeit den Anweisungen gewidmet werden kann, die es tatsächlich schaffen.

Überprüfen, was tatsächlich geladen wurde

Führen Sie /context aus und prüfen Sie den Abschnitt „Memory Files“, der genau zeigt, was von der laufenden Sitzung geladen wurde. /memory ergänzt dies, indem es die Dateien auf Benutzer- und Projektebene auflistet und es Ihnen ermöglicht, sie zu öffnen. Gemeinsam verwandeln sie die Frage „Ignoriert Claude das?“ von einer Vermutung in etwas, das man überprüfen kann. Es ist überraschend einfach, Zeit damit zu verbringen, die Formulierungen einer Datei zu überarbeiten, die überhaupt nicht geladen wird.

Widersprüche in zusammengefügten Dateien

Nichts wird überschrieben; alles wird zusammengefügt. Aus dem Arbeitsverzeichnis heraus arbeitet sich Claude Code zum Root des Dateisystems vor und sammelt unterwegs jede CLAUDE.md-Datei ein, um sie anschließend vom Root nach unten zu ordnen. Auf jedem Niveau, auf dem auch eine CLAUDE.local.md-Datei vorhanden ist, folgt diese ihrer Schwesterdatei CLAUDE.md. In einem Monorepo können zwei Dateien leicht entgegengesetzte Anweisungen geben. In solchen Fällen wählt Claude einfach eine aus, und es wird Sie nicht vor dem Konflikt gewarnt.

Vorfahren-Dateien, die Sie nicht angefordert haben

Falls eine CLAUDE.md-Datei in einem übergeordneten Verzeichnis in Ihre Sitzungen eindringt, überspringt die Einstellung claudeMdExcludes in Ihren lokalen Einstellungen die entsprechenden Dateien mithilfe von Glob-Regeln.

Was bei der Komprimierung erhalten bleibt

Die Projektwurzel-Datei CLAUDE.md wird nach dem Aufruf von /compact erneut vom Datenträger gelesen und eingefügt, sodass ihre Anweisungen bestehen bleiben. Alles, was nur im Gespräch erwähnt wurde, geht verloren. Wenn Sie nach jeder Komprimierung immer wieder dieselbe Korrektur vornehmen, ist das ein deutliches Zeichen dafür, dass diese in die Datei aufgenommen werden sollte.

Ein Ausgangsplan

Falls Sie die Einrichtung von Grund auf erstellen würden, sähe ein realistisches Ziel wie folgt aus:

• Eine Wurzel-Datei CLAUDE.md mit etwa 120 Zeilen, die nur das enthält, was überall gilt.
• Bedingte Anleitungen in .claude/rules/ mit Platzhaltern für Pfade.
• Jede unverhandelbare „immer“-Anforderung als Hook umgesetzt.
• Nichts, was jemand durch das Lesen des Repositoriums in zehn Minuten erfahren könnte.
• Eine schnelle /context-Überprüfung nach jeder Änderung.

Die vollständige Referenz, einschließlich Funktionen wie der automatischen Speicherung, die eine eigene Behandlung verdienen, findet sich in der Dokumentation zu Claude Code Memory. Verhalten und Grenzen entwickeln sich weiter, daher prüfen Sie diese, wenn etwas nicht mit dem übereinstimmt, was Sie erwarten.

Hauptpunkte

• Schreiben Sie CLAUDE.md für einen Kollegen, der es liest, und nicht für eine Maschine, die es ausführt: kurz, präzise und frei von Widersprüchen.
• Kürzere Dateien werden zuverlässiger befolgt; entfernen Sie alles, was die Codebasis bereits an Claude mitteilt.
• Imports ordnen den Inhalt neu, laden ihn aber vollständig; nur regelbasierte Einschränkungen nach Pfad können das Laden verzögern.
• Alles, was jedes Mal ausgeführt werden muss, benötigt einen Hook, da der Kontext nur das Verhalten beeinflussen kann.
• Betrachten Sie /context als Ihre Quelle der Wahrheit, bevor Sie Formulierungen anpassen.