Warum KI .md-Regeln ignoriert: Laden, Geltungsbereich und Ergebnisse prüfen

Sie fragen Claude Code, ob es CLAUDE.md gelesen hat. Es bejaht die Frage, überspringt aber trotzdem die vorgeschriebenen Tests. Unterscheiden Sie in diesem Fall zwischen Anweisungen, die das Modell nicht erreicht haben, und geladenen Anweisungen, die nicht befolgt wurden. Die Antwort „Ich habe es gelesen“ belegt keines von beidem.

Bei Cursors .cursor/rules, GitHub Copilots .github/copilot-instructions.md und der AGENTS.md von Codex CLI ist es nicht anders: Woher Dateien geladen werden und wann sie gelten, unterscheidet sich je nach Werkzeug. Dass eine Datei geladen wird und dass das Modell ihre Anweisungen befolgt, sind getrennte Fragen.

Kurz gesagt gehen Sie in drei Stufen vor. Prüfen Sie zuerst, ob die Datei geladen wird. Regeln, die geladen, aber nicht befolgt werden, formulieren Sie in Sätze um, deren Einhaltung sich nachträglich prüfen lässt. Was trotzdem ausnahmslos jedes Mal ausgeführt werden muss, verlagern Sie in Hooks oder CI. Auch die offizielle Dokumentation von Claude Code beschreibt CLAUDE.md als „Kontext, keine erzwungene Konfiguration“ und empfiehlt Hooks, wenn ein Vorgang unabhängig von Claudes Urteil gestoppt werden soll.

Dieser Artikel stellt fünf Prüfpunkte vor, darunter das Laden, die Wiederherstellung nach der Verdichtung und widersprüchliche Anweisungen, und zeigt anschließend eine Diagnosefolge und Beispiele für umformulierte Regeln.

1. Warum KI Regeln ignoriert: fünf Prüfpunkte

1. Die Datei ist zu lang, Regeln gehen unter

Die Dokumentation von Claude Code empfiehlt, CLAUDE.md auf weniger als 200 Zeilen pro Datei zu halten, und begründet dies damit, dass lange Dateien mehr Kontext verbrauchen und die Einhaltung verringern. 200 Zeilen sind keine Abbruchstelle beim Laden: CLAUDE.md-Dateien bis 4 MiB werden vollständig geladen (größere Dateien werden übersprungen). Bei langen Dateien bricht das Lesen also nicht an einer bestimmten Stelle ab; vielmehr werden sie gelesen, die einzelnen Regeln aber schlechter befolgt.

2. Automatische Verdichtung in langen Sitzungen

Claude Codes /compact verdichtet das Gespräch, doch die CLAUDE.md im Projektstamm wird danach erneut vom Datenträger geladen und in den Kontext eingefügt. CLAUDE.md-Dateien in Unterverzeichnissen und pfadbezogene Regeln werden dagegen beim Lesen der betreffenden Dateien erneut geladen. Laut Dokumentation wurde eine nach der Verdichtung verschwundene Anweisung entweder (1) nur im Gespräch mitgeteilt, oder sie steht (2) in einer CLAUDE.md eines Unterverzeichnisses, die noch nicht erneut geladen wurde, bzw. (3) in einer pfadbezogenen Regel, deren Zieldateien noch nicht gelesen wurden. Soll etwas, das Sie im Gespräch beschlossen haben, erhalten bleiben, ergänzen Sie es in CLAUDE.md.

3. Widersprüchliche Anweisungen und Geltungsbereiche

Stehen „vor dem Commit testen“ und „diesmal die Tests auslassen“ nebeneinander, entscheidet das Modell, welche Anweisung gilt. Laut der Dokumentation von Claude Code gilt bei zwei widersprüchlichen Regeln: Claude wählt unter Umständen willkürlich eine davon aus. Vergleichen Sie projektweite, persönliche und verzeichnisbezogene Anweisungen regelmäßig, beseitigen Sie Widersprüche und schreiben Sie bei erlaubten Ausnahmen dazu, „wer sie wie anordnen darf“. Wollen Sie einen Vorgang selbst verhindern, nutzen Sie statt CLAUDE.md die Berechtigungseinstellungen oder Hooks.

4. Vage oder widersprüchliche Regeln

Bei subjektiven oder abstrakten Anweisungen wie „höflich schreiben“ oder „angemessen behandeln“ ergänzt die KI ihre eigene Auslegung, die von Ihren Erwartungen abweichen kann. Formulieren Sie Anforderungen so, dass sich ihre Einhaltung prüfen lässt, etwa „höchstens drei Zeilen schreiben“ oder „bei Nutzung der Slack-API chat.postMessage verwenden“ (Beispiele für Umformulierungen in Abschnitt 3).

5. Aufgeblähte oder verstreute Regeldateien

Ein gewöhnlicher Link von CLAUDE.md auf SPEC.md lädt beim Start nicht zwangsläufig die gesamte verlinkte Datei. Claude Code löst Importe mit @path beim Start auf, doch deren Inhalt verbraucht ebenfalls Kontext. Dateien zur besseren Ordnung aufzuteilen ist etwas anderes, als sie erst bei Bedarf zu laden. Widersprechen sich doppelte Regeln, klären Sie die maßgebliche Fassung und den Geltungsbereich.

Die bisher beschriebenen Spezifikationen von Claude Code folgen der offiziellen Dokumentation zum Gedächtnis von Claude Code (Stand: 21. September 2026).

2. So prüfen Sie, ob Regeln befolgt werden

Erfassen Sie zunächst den aktuellen Zustand. Stellen Sie der KI folgende Fragen und prüfen Sie ihre Antworten:

Die Antwort „gelesen“ oder „verstanden“ ist weder ein Beleg für das Laden noch für die Anwendung. Belege sind die Ladeanzeige und die Ergebnisse nach der Ausführung.

Vier Schritte zur Eingrenzung der Ursache

1. Den Einstiegspunkt prüfen. Sehen Sie in Claude Code unter „Memory files“ in /context nach, ob die betreffenden CLAUDE.md-Dateien und Regeln aufgeführt sind. Fehlen sie, prüfen Sie Ablageort und Ausschlusseinstellungen (claudeMdExcludes). Lassen Sie AGENTS.md direkt laden, erscheint diese AGENTS.md nicht in der Liste. Achten Sie bei Standardeinstellungen darauf, ob beim Start die Zeile no CLAUDE.md found; AGENTS.md loaded: … erscheint (eine aus CLAUDE.md importierte AGENTS.md wird in der Liste angezeigt).
2. Die Bedingungen der Regel auslösen. Lassen Sie den Agenten bei pfadbezogenen Regeln eine passende Datei lesen. Hat er diese seit der Verdichtung noch nicht gelesen, wurde die Regel noch nicht erneut geladen. Wollen Sie festhalten, wann was geladen wurde, können Sie das Laden von CLAUDE.md-Dateien und Regeln mit dem Hook InstructionsLoaded protokollieren (bei direkt geladener AGENTS.md wird er nicht ausgelöst).
3. Eine kleine, harmlose Aufgabe ausprobieren. Lassen Sie eine entbehrliche Beispieldatei bearbeiten, etwa mit den Regeln „vor der Änderung die Zieldatei nennen“ und „danach Testbefehl und Exit-Code melden“. Verwenden Sie weder das Löschen von Produktionsdaten noch eine Veröffentlichung als Test. Wenn Sie mit einer geheimen Testphrase prüfen, schreiben Sie diese nur in die Anweisungsdatei und nicht in Ihre Frage.
4. Das Ergebnis unabhängig überprüfen. Suchen Sie im Diff nach unerwarteten Änderungen, bestätigen Sie die tatsächliche Ausführung gemeldeter Tests und prüfen Sie den Umfang der Kontrollen. Notieren Sie Einstellungen, Werkzeugversion und Zieldateien des Tests und wiederholen Sie ihn, sobald sich eines davon ändert.

Wurde beispielsweise „vor dem Commit testen“ geladen, aber nicht ausgeführt, löst das Verschieben der Datei das Problem nicht. Zu korrigieren sind die Formulierung der Regel (siehe die Beispiele im nächsten Abschnitt) und der Prüfmechanismus. Verbindliche CI-Prüfungen als Merge-Bedingung liefern Belege unabhängig vom Bericht der KI.

Fehlt die betreffende CLAUDE.md in der Ladeanzeige, korrigieren Sie zuerst Startverzeichnis und Einstellungen, bevor Sie Formulierungen stärker hervorheben. Bleiben Verstöße trotz bestätigten Ladens bestehen, prüfen Sie die Genauigkeit der Anweisungen und den Kontrollablauf. So schreiben Sie nicht jeden Fehler pauschal einem „Vergessen“ der KI zu.

3. Erste Verbesserungen in fünf Minuten

1. Ständige Regeln von Details für den Bedarfsfall trennen

Nehmen Sie Claude Codes offizielle Empfehlung von weniger als 200 Zeilen als Ausgangspunkt, aber reduzieren Sie Doppelungen und unnötige Erklärungen, statt nur eine Zeilenzahl anzustreben. Zum Beispiel:

• Unverzichtbare Regeln (10–20 Zeilen) → an den Anfang der CLAUDE.md
• Ausführliche Dienstspezifikationen → eigene SPEC-xxx.md-Dateien
• Verlauf und Hintergrund → ins Verzeichnis docs/

Vermerken Sie nach dem Auslagern in der Einstiegsdatei, was vor welcher Aufgabe zu lesen ist. Importieren Sie alle Einzelheiten für jede Sitzung, reduziert die Aufteilung den Startkontext nicht. Pfadbezogene Regeln oder Skills eignen sich für Anweisungen, die nur unter bestimmten Bedingungen benötigt werden.

2. Regeln in Sätze umformulieren, deren Einhaltung sich prüfen lässt

Bei Regeln, die geladen, aber nicht befolgt werden, prüfen Sie zuerst, ob darin steht, was als Einhaltung gilt. Auch die offizielle Dokumentation von Claude Code empfiehlt, Anweisungen so konkret zu schreiben, dass sie überprüfbar sind, und nennt als Beispiel „vor dem Commit npm test ausführen“ statt „Änderungen testen“. Geht man einen Schritt weiter und beschreibt auch das Verhalten bei Fehlern und die Bedingungen für Ausnahmen, sieht das so aus:

Mit den umformulierten Sätzen lässt sich anhand von Diff, Befehlsverlauf und Exit-Codes entscheiden, ob eine Regel befolgt wurde. Sind sie einmal prüfbar formuliert, dienen sie später unverändert als Prüfbedingungen, wenn Sie sie in Hooks oder CI verlagern (Abschnitt 4).

3. Prioritäten kennzeichnen

Wichtigkeitsmarkierungen helfen Menschen und KI, die Absicht zu verstehen. Die Markierungen selbst erzwingen keine Ausführung. Definieren Sie sie beispielsweise so:

• CRITICAL: Ein Verstoß könnte einen Produktionsvorfall auslösen
• MUST: immer erforderlich
• SHOULD: normalerweise erwartet
• NICE TO HAVE: optional, wenn Zeit bleibt

„CRITICAL: Destruktive Abfragen der Produktionsdatenbank erfordern vorherige Freigabe“ benennt den Vorgang und die Freigabebedingung. Um unerlaubte Vorgänge tatsächlich zu blockieren, sind zusätzlich Berechtigungseinstellungen oder Prüfungen vor der Ausführung nötig.

4. Regeln im Chat erneut hervorheben

Ergänzen Sie zu Sitzungsbeginn: „Nenne vor Arbeitsbeginn die drei wichtigsten Regeln.“ Die Nennung ruft die Regeln in Erinnerung; ob sie befolgt wurden, zeigen die Ergebnisse nach der Arbeit.

5. Abschlussbedingungen in den Plan aufnehmen

Nehmen Sie „Regeln prüfen“ in die Aufgabenverwaltung Ihres KI-Agenten auf und machen Sie die Abschlussbedingungen jedes Schritts sichtbar. Verlangen Sie statt „getestet“ den Befehl, den Exit-Code und den ungeprüften Umfang. Ist das Feld für Belege leer, obwohl ein Häkchen gesetzt ist, gilt der Schritt nicht als abgeschlossen.

4. Dauerhafte Absicherung: Hooks, Reviews und Skills

Überführen Sie auswertbare Bedingungen in Skripte und steuern Sie Ausführungsrechte über Einstellungen. Hooks, CI, KI-Reviews und Skills erfüllen unterschiedliche Zwecke. Wer alles „automatische Durchsetzung“ nennt, verdeckt die Bereiche, die nicht geprüft werden.

1. Prüfungen mit Claude Code Hooks durchsetzen

Die Hooks-Funktion von Claude Code kann Skripte vor oder nach bestimmten Werkzeugaufrufen ausführen. Damit lässt sich ein Mechanismus einrichten, bei dem das System einen Vorgang stoppt, selbst wenn die KI die Regel vergisst.

Ein PreToolUse-Hook kann beispielsweise:

• Gefährliche Befehle (rm -rf, git push --force) vor der Ausführung des Werkzeugs Bash erkennen und ablehnen
• Berechtigungen oder den Sperrstatus einer Zieldatei vor dem Aufruf von Edit prüfen
• Vor einem Commit projektspezifische Tests ausführen und ihn bei Fehlern blockieren

Soll ein PreToolUse-Hook einen Vorgang blockieren, muss er den Exit-Code 2 oder das passende Ablehnungs-JSON zurückgeben. Liefert ein fehlgeschlagener Test nur 1 und gewöhnlichen Text, gilt das als nicht blockierender Fehler; der Vorgang läuft weiter. PostToolUse läuft erst danach und macht bereits abgeschlossene Vorgänge nicht rückgängig.

Ein Hook kann nur blockieren, was sein Skript beim konfigurierten Ereignis auswertet. Die alleinige Überwachung von Edit erfasst keine Schreibvorgänge über eine Shell. Auch eine einfache Suche nach gefährlichen Zeichenfolgen ist nicht lückenlos. Kombinieren Sie Hooks mit Berechtigungen, Sandbox und CI und testen Sie erlaubte ebenso wie abzulehnende Eingaben.

2. Zuständigkeiten mit Subagenten trennen

Nutzen Sie Subagenten-Funktionen im Claude Agent SDK oder in Cursor, um einen eigenen Agenten für Regelprüfungen einzurichten. Ein Prüfagent kann im Code des Hauptagenten aus anderer Perspektive Auslassungen erkennen. Beide können jedoch denselben Fehler machen oder dasselbe Problem übersehen.

Geben Sie dem Prüfer die maßgeblichen Regeln, den Diff und die erwarteten Nachweise (Testnamen oder Exit-Codes). Gleichen Sie die gemeldeten Befunde mit den tatsächlichen Dateien oder Testergebnissen ab und behandeln Sie Bereiche außerhalb des Prüfauftrags als ungeprüft.

3. Wiederkehrende Abläufe über Skills aufrufen

In Claude Code können Sie wiederkehrende Abläufe in .claude/skills/precommit/SKILL.md ablegen und über Ihren eigenen Befehl /precommit aufrufen. Dies ist ein selbst anzulegendes Beispiel, kein eingebauter Befehl. Dateien im älteren Verzeichnis .claude/commands/ funktionieren weiterhin, werden in der aktuellen Dokumentation aber den Skills zugeordnet. Einen Ablauf aufzurufen ist nicht dasselbe, wie alle Prüfungen zu bestehen. Sehen Sie sich daher am Ende die Prüfergebnisse an.

Ablageorte und Aufruf beschreibt die offizielle Skills-Dokumentation. Halten Sie im Skill sowohl den Ablauf als auch seine Bestehenskriterien fest und verlangen Sie Nachweise für die ausgeführten Schritte.

4. Verstöße mit automatisierten Skripten erkennen

Suchen Sie in CI oder einem Pre-Commit-Hook mit grep nach verbotenen Mustern, etwa:

• console.log im Produktionscode
• Fest einprogrammierte API-Schlüssel
• Fehlende Copyright-Kommentare am Dateianfang

Skripte prüfen weder nicht implementierte Regeln noch Dateien außerhalb ihres Umfangs. Testen Sie gültige Beispiele, Verstöße und Abruffehler und zeigen Sie die Zahl geprüfter und übersprungener Einträge an. Sind etwa zwei von zehn Dateien nicht lesbar, bedeutet ein Erfolg bei den übrigen acht nicht „alle Dateien bestanden“.

5. Empfehlungen für die einzelnen Werkzeuge

Die werkzeugspezifischen Bedingungen erläutern die Cursor-Regeldokumentation, die Anleitung zu individuellen GitHub-Copilot-Anweisungen und OpenAIs AGENTS.md-Leitfaden. Pfadbezogene Copilot-Anweisungen verwenden *.instructions.md; welche Copilot-Funktionen sie lesen, ist von Funktion zu Funktion verschieden. Die 32-KiB-Grenze von Codex ist die standardmäßige gemeinsame Byte-Grenze, keine Zeichen- oder Zeilenzahl.

Das gemeinsame Prinzip lautet: „kurz, konkret und klar priorisiert“. Dateinamen und Ablageorte unterscheiden sich, die Grundsätze für verständliche Regeln bleiben gleich.

6. Drei Fehler beim Entwerfen von Regeln

1. „Bitte Best Practices befolgen“

Die Bitte allein definiert keine „Best Practices“. Benennen Sie die im Projekt verwendeten Methoden und ihre Prüfung. Ersetzen Sie „angemessen testen“ durch die erforderlichen Testbefehle und den Arbeitsschritt, der bei Fehlern stoppen muss (Umformulierungsbeispiele in Abschnitt 3).

2. Dieselbe Regel in mehreren Dateien duplizieren

Stehen dieselben Commit-Konventionen in CLAUDE.md, SPEC.md und README.md, können Aktualisierungen die Fassungen auseinanderlaufen lassen. Bestimmen Sie eine maßgebliche Fassung und verlinken Sie sie aus den anderen Dateien.

3. Überall „unbedingt erforderlich“ schreiben

Wer alle Bedingungen gleich stark hervorhebt, erschwert die Vermittlung von Prioritäten. Reservieren Sie „CRITICAL“ für Bedingungen mit wirklich schwerwiegenden Folgen und verwenden Sie sonst gewöhnliche Formulierungen. Denn zu viele Hervorhebungen verlieren ihre Wirkung.

Zusammenfassung

Werden Regeln nicht befolgt, untersuchen Sie in dieser Reihenfolge: Ladebedingungen → Geltungsbereich → widersprüchliche Anweisungen → Ausführungsergebnisse. Da die CLAUDE.md im Projektstamm auch nach der Verdichtung erneut eingefügt wird, stammt eine danach verschwundene Anweisung entweder allein aus dem Gespräch oder aus einer noch nicht erneut geladenen CLAUDE.md eines Unterverzeichnisses bzw. einer pfadbezogenen Regel.

• Nicht geladen: Ablageort, Ausschlusseinstellungen und die Ladebedingungen von AGENTS.md korrigieren
• Geladen, aber nicht befolgt: die Regel in einen Satz umformulieren, dessen Einhaltung sich nachträglich prüfen lässt
• Muss ausnahmslos jedes Mal ausgeführt werden: mit Hooks oder CI prüfen und erlaubte Vorgänge über Berechtigungseinstellungen festlegen

Abschlussnachweise liefern Ausführungsergebnisse und Artefakte, nicht die Antwort „Ich habe es gelesen“.

FAQ

F1. Wie lang sollte CLAUDE.md idealerweise sein?

Die offizielle Empfehlung lautet weniger als 200 Zeilen pro Datei; laut Dokumentation verbrauchen längere Dateien mehr Kontext und verringern die Einhaltung. Über 200 Zeilen bricht das Laden nicht mittendrin ab (bis 4 MiB wird die gesamte Datei geladen). Behalten Sie nur Regeln, die ständig benötigt werden, und verschieben Sie Regeln, die nur für bestimmte Dateien gelten, in pfadbezogene Regeln. Auch per @path importierte Dateien werden beim Start geladen, sodass der Kontextverbrauch nicht sinkt.

F2. Sollte ich in Cursor .cursorrules oder .cursor/rules/*.mdc verwenden?

Verwenden Sie bei einer neuen Einrichtung .cursor/rules/*.mdc. Halten Sie eine Regel pro Datei fest und bestimmen Sie mit Glob-Mustern ihren Geltungsbereich. Die ältere .cursorrules ist eine einzelne Datei, die unübersichtlich werden kann.

F3. Werden längere Regeln strenger durchgesetzt?

Länge allein macht Regeln nicht strenger. Auch die offizielle Dokumentation erklärt, dass lange Dateien die Einhaltung verringern. Wenn Sie etwas ergänzen, dann prüfbare Bedingungen und konkrete Beispiele; streichen Sie Doppelungen und Widersprüche.

F4. Was gilt, wenn mehrere KI-Werkzeuge wie Claude Code und Cursor am selben Projekt arbeiten?

Führen Sie die maßgebliche Fassung der gemeinsamen Regeln in AGENTS.md zusammen und trennen Sie werkzeugspezifische Einstellungen nach den Einstiegspunkten der einzelnen Werkzeuge. Codex und Cursor unterstützen AGENTS.md. Auch Claude Code lädt ab v2.1.277 AGENTS.md direkt, wenn es im Arbeitsverzeichnis und darüber weder CLAUDE.md noch .claude/CLAUDE.md noch CLAUDE.local.md gibt. Existiert eine davon, wird standardmäßig nur diese geladen; schon eine persönliche CLAUDE.local.md genügt, damit AGENTS.md nicht mehr gelesen wird. In Projekten, die auch CLAUDE.md verwenden, importieren Sie AGENTS.md mit der Zeile @AGENTS.md in CLAUDE.md (alternativ können Sie unter /config die Option Project instructions auf claude-md-and-agents-md setzen, damit beide geladen werden). In Sitzungen über externe Anbieter wie Amazon Bedrock oder mit deaktivierter Telemetrie, in der ersten Sitzung direkt nach Installation oder Update sowie in Umgebungen, in denen Hooks etwa per disableAllHooks abgeschaltet sind, funktioniert das direkte Laden nicht; verwenden Sie dort den Import. Über welchen Weg die Datei geladen wird, erkennen Sie mit Schritt 1 in Abschnitt 2.

F5. Kann die Datei ungelesen sein, obwohl die KI „gelesen“ meldet?

Die Antwort beweist weder, dass die Datei gelesen wurde, noch dass sie ungelesen blieb. Prüfen Sie mit den Diagnoseschritten in Abschnitt 2 die Ladeanzeige und vergleichen Sie sie mit Diffs, Testergebnissen und Ausführungsverlauf.