Warum KI-Agenten deine .md-Regeln ignorieren — und wie du CLAUDE.md, Cursor Rules & AGENTS.md wirklich zum Greifen bringst

Du fragst Claude Code: „Hast du CLAUDE.md gelesen?" Die Antwort kommt fröhlich: „Ja, gelesen." Ein paar Turns später ist von den Regeln in dieser Datei nichts mehr übrig — projektspezifische Befehle, Commit-Message-Konventionen, Deploy-Schritte. Alles ist klammheimlich verdunstet.

Das ist kein reines Claude-Code-Problem. Derselbe Drift zeigt sich auch bei Cursors .cursor/rules, GitHub Copilots .github/copilot-instructions.md und Codex CLIs AGENTS.md, sobald du sie lange genug einsetzt.

Dieser Artikel legt die fünf Grundursachen offen, warum KI-Agenten deine .md-Regeldateien ignorieren, und führt dich anschließend durch schnelle Umschreibtechniken sowie langfristige Systematisierung mit Hooks und Sub-Agents — alles mit konkreten Beispielen.

1. Warum KI deine Regeln ignoriert — 5 Grundursachen

1. Strukturelle Limits des Kontextfensters

Ein LLM verteilt seine Aufmerksamkeit nicht gleichmäßig über alle Tokens im Input. Anweisungen, die in der Mitte eines langen Dokuments vergraben sind, gehen verloren — der gut dokumentierte „Lost in the Middle"-Effekt. Sobald deine CLAUDE.md die 200-Zeilen-Marke knackt, verschwindet alles in der Mitte praktisch.

2. Auto-Compact in langen Sessions

Claude Code besitzt ein /compact-Feature, das den Verlauf komprimiert. Wenn es automatisch zuschlägt, überleben Anweisungen auf System-Prompt-Ebene, aber die operativen Details aus CLAUDE.md werden weggekürzt oder ganz verworfen. Genau deshalb häufen sich Regelverletzungen in der zweiten Hälfte langer Sessions.

3. Direkte User-Anweisungen haben Vorrang

Für eine KI wiegt „was der User gerade gesagt hat" schwerer als „eine Regel, die sie vor 300 Turns gelesen hat". Sobald ein User „mach einfach" oder „committe ruhig" sagt, wird deine „immer vor dem Commit bestätigen lassen"-Regel aus CLAUDE.md überrollt.

4. Vage oder widersprüchliche Regeln

Subjektive Vorgaben wie „schreibe höflich" oder „handle das angemessen" überlassen der KI die Interpretation, was selten zu dem passt, was du wolltest. Schreibe sie als prüfbare Constraints um: „Antworten unter 3 Zeilen halten", „für die Slack API chat.postMessage verwenden" und so weiter.

5. Aufgeblähte, verstreute Regeldateien

CLAUDE.md plus SPEC.md plus README.md plus ein Stapel weiterer .md-Dateien — sobald sie verteilt und einzeln lang sind, liest die KI sie nicht mit gleicher Gewichtung. Wenn dieselbe Regel in mehreren Dateien mit subtilen Unterschieden steht, wählt die KI tendenziell die sicherste Variante.

2. So diagnostizierst du, ob deine Regeln tatsächlich befolgt werden

Verschaffe dir zuerst einen Überblick über den Ist-Zustand. Stell der KI folgende Fragen und beobachte ihre Antwort:

Die KI sagt „ich habe es gelesen" oder „verstanden" — das sagt dir gar nichts. Ob sie die Regeln wirklich anwendet, ist eine separate Frage — beurteile nach dem tatsächlichen Verhalten, nicht nach den Behauptungen.

3. Schnelle Fixes, die du in 5 Minuten umsetzt

1. Komprimiere deine Regeldatei auf unter 150 Zeilen

In der Praxis befolgt Claude Code eine CLAUDE.md von etwa 100 bis 150 Zeilen zuverlässig. Darüber hinaus solltest du sie aufteilen:

• Nicht verhandelbare Regeln (10 bis 20 Zeilen) — ganz oben in CLAUDE.md
• Service-spezifische Specs — in SPEC-xxx.md auslagern
• Historie und Hintergrund — in ein docs/-Verzeichnis verschieben

Beschränke CLAUDE.md auf „Dinge, deren Vergessen katastrophal wäre". Details können in verlinkten Dateien leben.

2. Setze explizite Prioritätsmarker

Verwende laute Prioritäts-Keywords, um die Aufmerksamkeit der KI zu erzwingen:

• CRITICAL — Verstoß führt zu einem Production Incident
• MUST — immer zu befolgen
• SHOULD — standardmäßig zu befolgen
• NICE TO HAVE — nur, wenn Platz ist

Eine Zeile wie „CRITICAL: destruktive Queries gegen die Production-DB erfordern explizite Freigabe" lässt sich selbst in einer langen Datei kaum übersehen.

3. Im Chat selbst nochmals betonen

Wirf zu Beginn einer Session einen Einzeiler ein wie „Bevor du loslegst, deklariere die drei wichtigsten Regeln aus CLAUDE.md." Das zieht diese Regeln in den jüngsten Kontext und sorgt dafür, dass sie für den Rest der Session haften bleiben.

4. Gefährliche Operationen in TodoWrite protokollieren

Nutze das TodoWrite-Tool eines KI-Agenten (oder das äquivalente Task-Tracking-Feature in deinem Tool), um „Regelcheck" als expliziten Schritt aufzunehmen. Sichtbarkeit macht „ich habe es vergessen" deutlich seltener.

4. Langfristige Systematisierung — Hooks, Sub-Agents, Slash Commands

Prosa-Regeln kommen irgendwann an ihre Grenzen. Der Wechsel von „die KI bitten, Regeln zu befolgen" zu „die Umgebung erzwingt sie" ist sehr viel verlässlicher.

1. Mit Claude Code Hooks mechanisch erzwingen

Mit dem Hooks-Feature in Claude Code lassen sich beliebige Skripte vor oder nach bestimmten Tool-Aufrufen ausführen. So baust du ein Setup, in dem das System die KI stoppt, selbst wenn die KI selbst die Regel vergisst.

Beispiel mit einem PreToolUse-Hook:

• Gefährliche Befehle (rm -rf, git push --force) vor dem Bash-Lauf erkennen und blockieren
• Vor dem Bearbeiten einer Datei mit Edit Berechtigungen oder Lock-Status prüfen
• Vor dem Commit projekteigene Tests laufen lassen und bei Fehlschlag abbrechen

Höflich in Prosa bitten hat keine Chance gegen mechanische Durchsetzung über Hooks.

2. Verantwortlichkeiten mit Sub-Agents trennen

Nutze die Sub-Agent-Fähigkeiten im Claude Agent SDK oder in Cursor, um einen dedizierten „Regel-Audit-Agent" aufzubauen. Ein zweistufiger Flow, in dem der Haupt-Agent Code schreibt und der Audit-Agent ihn prüft, fängt Regelverletzungen auch dann ab, wenn der Haupt-Agent sie übersieht.

Der Sub-Agent braucht nur einen kurzen audit-fokussierten Prompt, dadurch bleibt seine Regel-Erkennungsrate hoch. Genau das ist der Schlüssel.

3. Routinen als Custom Slash Commands kodifizieren

Wiederkehrende Workflows wie „vor jedem Commit diese 3 Checks laufen lassen" eignen sich perfekt als Slash Command (/precommit usw.). Tippt der User /precommit, fährt die KI eine fixe Sequenz ab. Es muss nicht jedes Mal die Regeldatei neu gelesen werden.

4. Verstöße per automatisiertem Skript erkennen

Lass grep-basierte Erkennung verbotener Muster in CI oder als Pre-Commit-Hook laufen. Beispiele:

• Vergessenes console.log im Production-Code
• Hartkodierte API-Schlüssel
• Fehlende Copyright-Header

Verlasse dich nicht auf die KI — lass Maschinen das finden. Das ist deine letzte Verteidigungslinie.

5. Best Practices nach Tool

Die universelle Regel lautet „kurz, konkret, priorisiert". Dateinamen und Pfade unterscheiden sich pro Tool, die Schreibprinzipien sind dieselben.

6. Drei Anti-Patterns beim Regeldesign

1. „Bitte halte dich an Best Practices."

Wessen Best Practices? Die KI fällt auf den Durchschnitt ihrer Trainingsdaten zurück, was bedeutet: du bekommst den kleinsten gemeinsamen Nenner. Projektspezifische Eigenheiten landen nie darin. Schreibe stattdessen konkrete Do's und Don'ts.

2. Dieselbe Regel in mehreren Dateien dupliziert

Wenn deine „Commit-Konventionen" in CLAUDE.md, SPEC.md und README.md leben, driften die drei Kopien subtil auseinander und verwirren die KI. Wähle eine einzige Source of Truth und verlinke von überall sonst dorthin.

3. Überall „ABSOLUT MUSS" draufstempeln

Wenn alles „absolut" ist, verliert die KI die Fähigkeit zu priorisieren. Reserviere „CRITICAL" für das wirklich Katastrophale; alles andere darf in normaler Prosa stehen. Betonung leidet unter Inflation — halte sie knapp.

Fazit

Wenn KI-Agenten deine .md-Regeln ignorieren, liegt das fast immer an strukturellen Beschränkungen und Problemen im Regeldesign, nicht an Faulheit der KI. Die meisten Fälle löst du mit Quick Fixes — auf unter 150 Zeilen komprimieren, Prioritätsmarker einfügen, im Chat noch einmal hervorheben. Für die wirklich kritischen Regeln, die danach übrig bleiben, wechsle zur mechanischen Durchsetzung: Hooks, Sub-Agents, Slash Commands und automatisierte Erkennungsskripte.

„Wenn die Regeln nicht befolgt werden, baue ein System, das sie erzwingt" — das ist der neue Common Sense im Betrieb von KI-Agenten.

FAQ

F1. Was ist die ideale Länge für CLAUDE.md?

In der Praxis 100 bis 150 Zeilen. Über 200 hinaus in SPEC-xxx.md oder Ähnliches aufteilen. Eine Zusammenfassung „Top 5 kritische Regeln" ganz oben ist eine gute Versicherung gegen das Vergessen.

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

Für neue Setups .cursor/rules/*.mdc. Eine Regel pro Datei, mit Glob-Patterns, um den Geltungsbereich jeder Regel einzugrenzen. Die alte Single-File-.cursorrules bläht sich mit der Zeit zwangsläufig auf.

F3. Machen längere Regeln die KI strenger?

Im Gegenteil. Je länger die Datei, desto stärker wird die Mitte verwässert. Kurze, essenzielle Regeln, prominent (oben) platziert, werden mit höherer Quote befolgt.

F4. Was, wenn ich mehrere KI-Tools (Claude Code + Cursor) im selben Projekt nutze?

Die pragmatische Antwort: dieselbe Zusammenfassung in die Konfigurationsdatei jedes Tools legen und die Details in einer gemeinsamen SPEC.md zentralisieren. Eine vollständig vereinheitlichte Lösung gibt es noch nicht (Stand Mai 2026).

F5. Wenn die KI sagt „ich habe es gelesen", liest sie es dann wirklich nicht?

Die Behauptung „ich habe es gelesen" und das tatsächliche Laufzeitverhalten sind zwei verschiedene Dinge. Verifiziere die Erkennung auf Ausführungsebene mit den Diagnoseverfahren aus Abschnitt 2.