Warum Claude Code CLAUDE.md ignoriert und was tatsächlich wirkt
CLAUDE.md ist eine Anfrage, keine verbindliche Vorgabe: Claude Code liest die Datei als Kontext und versucht, ihr zu folgen, eine Garantie gibt es laut Anthropic jedoch nicht. In der Praxis waren viele scheinbar ignorierte Regeln gar nicht oder für einen anderen Kontext dokumentiert.
Veröffentlicht am 9. Oktober • Zuerst erschienen auf singhlabs.dev • KI-unterstützt
Die kurze Antwort: CLAUDE.md ist eine Bitte, kein Schloss. Claude Code lädt die Datei als Kontext und versucht, ihr zu folgen, und Anthropics Dokumentation sagt unmissverständlich, dass es dafür keine Garantie gibt. Als ich meine eigene Historie durchsah, stellte ich fest, dass die meisten Regeln, denen ich Claude vorgeworfen hätte, sie ignoriert zu haben, nie aufgeschrieben waren oder für etwas anderes galten. Die wenigen, die wirklich halten müssen, brauchen einen Hook, keinen besseren Satz.
Sucht man nach "claude code ignores claude.md", landet man auf Seite eins bei GitHub Issues. Regeln in Großbuchstaben. MANDATORY. NEVER. Im Repository anthropics/claude-code tragen 124 Issues CLAUDE.md und "ignore" im Titel. Acht sind offen. 68 wurden als "not planned" geschlossen.
Viele Beschwerden, keine Antworten. Also öffnete ich meine eigene Akte: meine Claude-Code-Historie seit Juli, die CLAUDE.md jedes Projekts und die dahinterliegenden Git-Logs.
Eine Regel in CLAUDE.md ist eine Bitte. Wenn sie niemals gebrochen werden darf, braucht sie einen Hook, keinen lauteren Satz.
Schließe die langweilige Ursache aus, bevor man dem Modell die Schuld gibt. Die Dokumentation sagt, dass Claude CLAUDE.md "als Kontext behandelt, nicht als erzwungene Konfiguration", und dass sie als User-Nachricht nach dem System-Prompt ankommt. Zuerst sollte man also bestätigen, dass sie überhaupt angekommen ist:
Führe /context aus und schaue unter Memory files. Steht die Datei nicht in der Liste, wurde sie nicht gesehen.
Eine CLAUDE.md in einem Unterordner wird beim Start nicht aufgelistet. Sie lädt erst, wenn Claude eine Datei in diesem Ordner liest.
Beim Laden gibt es ebenfalls Bugs. #99032, letzte Woche gemeldet: Die VS-Code-Erweiterung überspringt einen @import, der außerhalb des Projekts zeigt, während das Terminal ihn lädt.
Geladen und trotzdem ignoriert? Dann ist es eines der folgenden vier Probleme.
Dieser hier ist peinlich. toldya liest, was du an Claude Code geschrieben hast, und findet die Korrekturen, die du immer wieder wiederholst. Meine waren:
$ npx toldya --all --dry toldya · 175 Sitzungen (2. Jul – 9. Okt) · 3804 deiner Nachrichten · 328 Korrekturen Du sagst deiner KI immer wieder: 1. 20× keep it simple (20 Sitzungen) 2. 8× dont assume (7 Sitzungen) 3. 8× I don't like it (7 Sitzungen) Enter fullscreen mode Exit fullscreen mode toldya markiert auch eine Wiederholung, die bereits in deiner CLAUDE.md oder AGENTS.md steht, mit dem Hinweis ← already in your rules, still repeated. Ich habe es in allen 12 meiner Projekte ausgeführt, die eine dieser Dateien haben. Es fand nichts.
"Keep it simple" stand in keiner der CLAUDE.md-Dateien der Projekte, in denen ich es ständig eintippte. Claude hat diese Regel nicht ignoriert. Ich hatte ihm nie eine gegeben.
Eine Korrektur, die ich beim Schreiben dieses Textes gefunden habe. Wenn man eine Sitzung fortsetzt, kopiert Claude Code die früheren Nachrichten in die neue Datei, und toldya 0.3.2 zählte jede Kopie mit: Es meldete 44. Der Fix erschien in 0.3.3, mit dem auch der obige Lauf erstellt wurde. Immer noch meine Spitzenposition.
Außer dass ich es irgendwie doch getan hatte. Seit dem 26. Juli läuft bei mir ponytail, ein Plugin, dessen Session-Start-Hook etwa 900 Wörter nach dem Motto "baue das Einfachste, das funktioniert" in jede Sitzung lädt. Dieser Text steht in 187 meiner 195 Transkripte.
Also nahm ich toldyas beiden Einfachheits-Wiederholungen ("keep it simple", "dont complex this"), warf die Kopien heraus und behielt die Nachrichten, die ich getippt hatte, während dieser Text bereits geladen war. Es waren 24. Ich habe alle gelesen:
17 betrafen, wie es geredet oder geschrieben hat, nicht was es gebaut hat. "Sorry, I didn't understand what you did. Keep it simple and explainable."
5 betrafen den Ansatz, eher das Terrain des Plugins.
Ponytail sagt in seinem eigenen Text, dass es "governs what you build, not how you talk". Es war bei jedem Mal geladen. Es war nur nicht die Regel, nach der ich ständig gefragt habe.
Also stand in der CLAUDE.md meines neuen Datenprojekts in dieser Woche vom ersten Moment an die richtige Regel: "Explain simply." Innerhalb eines Tages habe ich fünf weitere Male um eine einfache Erklärung gebeten. "I need to understand in very simple way how to use that app."
"Explain simply" ist ein Wunsch. Nichts daran lässt sich prüfen. Die Dokumentation macht denselben Punkt mit besseren Beispielen: "Use 2-space indentation" statt "Format code properly". Eine prüfbare Version meiner Regel würde das Konkrete nennen: ein Zeilenlimit, ein Beispiel zuerst, kein Begriff ohne Definition. Ich habe das noch nicht getestet, also verspreche ich es nicht.
Der harte Fall. Ein anderes Repository von mir beginnt seine CLAUDE.md mit einer Logging-Regel unter einer Überschrift, die unverhandelbar sagt: Jede Änderung erhält einen CHANGELOG-Eintrag, mit Zeitstempel aus date -u, "nie geraten oder erfunden". Konkret. Prüfbar. Zeile 40 einer 222-Zeilen-Datei zum Zeitpunkt der Einführung; die Datei hat inzwischen 311 Zeilen.
$ git log --format = "%ad %s" --date = short -S "Timestamps are UTC and real" -- CLAUDE.md 2026-08-16 Repo audit, project rules, and the documents needed to run this $ git log --reverse --format = "%ad %s" --date = short -i -E --grep = "(correct|fix).*timestamp" 2026-08-17 Correct a changelog timestamp I invented 2026-08-24 Correct a changelog timestamp that was written before date -u was read 2026-08-29 Fix a guessed timestamp, and write down how to stop guessing them 2026-09-09 Correct a guessed timestamp, for the third time $ wc -l CLAUDE.md 311 CLAUDE.md Enter fullscreen mode Exit fullscreen mode Vier geratene Zeitstempel in den 24 Tagen nach Einführung der Regel, jeder in seinem eigenen Commit entdeckt und behoben. Claude hat diese Fixes geschrieben, und jeder einzelne nennt die Regel, die er gerade gebrochen hatte. Mit dem dritten Fix wurde die Regel schärfer: erst die Uhr in einem eigenen Befehl ablesen, dann schreiben.
Elf Tage später wurde sie wieder gebrochen. Der vierte Fix trägt den Titel "for the third time". Sogar die Entschuldigung hatte den Überblick verloren.
Das sind vier entdeckte Fehler in etwa 150 Commits, die das Log betrafen, also hielt die Regel meistens. Meistens reicht bei Einrückungen. Bei einem Zeitstempel, dessen einzige Aufgabe es ist, korrekt zu sein, ist das wertlos. Seit dem 9. September gab es 44 weitere Log-Commits und keinen Fix, was bedeutet, dass entweder die schärfere Formulierung griff oder niemand nachgeprüft hat. Die Historie kann das nicht entscheiden.
Meine vier Fälle decken sich mit Anthropics Memory-Dokumentation, den Best Practices und dem Issue-Tracker:
Der Ort, an dem sie steht. CLAUDE.md kommt nach dem System-Prompt als User-Nachricht an. Wenn sie mit Claude Codes eigenen Vorgaben kollidiert, kann die eingebaute gewinnen. In #27032 schlug der Plan-Modus einen Plans-Ordner im Home-Verzeichnis vor, und das Modell folgte dem statt einer CLAUDE.md-Regel, die Pläne im Repository halten wollte. Die Dokumentation führt das unter den zu prüfenden Punkten.
Die Länge. Ziel sind unter 200 Zeilen; längere Dateien "reduce adherence". Die Best-Practices-Seite ist deutlicher: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" Meine Logging-Regel lebte in einer Datei, die von 222 auf 311 Zeilen wuchs. Was jede Zeile kostet, steht im Length-Post.
Konflikte. Wenn sich zwei Anweisungen widersprechen, "Claude may pick one arbitrarily". Prüfe deine User-Datei gegen deine Projektdatei und alle verschachtelten Dateien.
Das Schreien. Die Dokumentation schlägt "IMPORTANT" für die eine Zeile vor, die immer wieder übersprungen wird, und warnt, dass wenn man viele hervorhebt, keine heraussticht. #33603 zeigt, was danach passiert: eine Regel, die nach jedem Verstoß wiederholt und verschärft wurde, und dann in jedem der nächsten drei Sessions gebrochen wurde.
Das Modell. #99704 zählte eine "reply in Korean"-Regel über eine lange Sitzung mit: keine englischen Antworten bei claude-opus-5, 33 Prozent Englisch bei claude-opus-5-5, gleiche CLI. Eine Regel, die letzten Monat hielt, beweist nichts für dieses Modell.
Das Timing. Wenn etwas an einem festen Punkt passieren muss, vor jedem Commit oder nach jeder Bearbeitung, sagt die Dokumentation, soll man es als Hook schreiben.
Die Best-Practices-Seite bringt es auf einen Punkt: CLAUDE.md-Anweisungen sind "advisory", während Hooks "deterministic and guarantee the action happens" sind. Ein PreToolUse-Hook sieht den Tool-Aufruf, bevor er ausgeführt wird, und kann ihn verweigern.
Hier ist slopguards Bash-Guard, ausgeführt aus seinem Plugin-Ordner, gefüttert mit dem Aufruf, den Claude tätigen würde, um a.env zu committen:
$ echo '{"tool_name":"Bash","tool_input":{"command":"git add.env && git commit -m wip"}}' \ | node scripts/guard-bash.mjs \ | node -p "JSON.parse(require('fs').readFileSync(0)).hookSpecificOutput.permissionDecisionReason" SLOPGUARD blocked this command — [ SG-1] credential file staged for commit. fix: Add it to.gitignore. Anything committed is in the history permanently, even after a later delete. Rule text lives in AGENTS.md. Enter fullscreen mode Exit fullscreen mode Die Satz-Version dieser Regel ist #2142, offen seit Juni 2025: Claude Code "repeatedly ignores CLAUDE.md security guidelines and exposes API keys to version control". Ein Hook gibt ihr diese Chance gar nicht erst.
Ein Hook erzwingt nur das, was ein Skript prüfen kann. In #99642 waren Hooks, die die Form prüften (eine Tabelle existiert, die Logs wurden gelesen), zufrieden gestellt, während die Arbeit, für die sie standen, übersprungen wurde.
Ein Hook, der nur Text hinzufügt, bleibt eine Bitte. Ponytails Hook gibt seine Regeln beim Sitzungsstart aus, und der Hooks-Guide sagt, dass diese Ausgabe einfach in Claudes Kontext einfließt. Gleiche Chancen wie bei CLAUDE.md. #99642s Reminder-Hook injizierte seine Anweisung bei jedem Turn, und das Modell hat nie darauf reagiert.
Der Test lautet also: Könnte ein Skript Ja oder Nein sagen? Eine.env-Datei in einem Commit: Ja, als Hook lösen. Ein Log-Zeitstempel, der nicht zur Uhr passt: Ja, und genau das hätte der Hook meiner Logging-Regel sein sollen. Ich habe ihn noch nicht geschrieben. "Explain simply": Nein. Die bleibt ein Satz, so konkret, wie ich ihn machen kann, und wird gezählt.
Eine Regel, die du nie nachprüfst, ist eine Regel, auf die du nur hoffst. toldya macht das Zählen, auf deinem Rechner, und sendet nichts:
$ npx toldya --dry # nur der Bericht, es wird nichts geaendert Enter fullscreen mode Exit fullscreen mode Fuehrt man das Kommando ohne --dry aus, fragt es bei jeder Wiederholung nach: y schreibt sie in CLAUDE.md, n ueberspringt sie, e erlaubt es, den Wortlaut vorher anzupassen. Eine Woche laeuft man es erneut. Jede hinzugefuegte Regel erhaelt eine Zeile wie "Keep it simple." said 20× before · 0× since. Wenn "since" nicht nahe null liegt, ist die Regel ein Wunsch, oder sie braucht einen Hook.
Ehrliche Einordnung: Einen echten "since"-Wert kann ich noch nicht zeigen, weil ich meine Wiederholungen nie ueber toldya hinzugefuegt habe. Diese Zeile stammt aus einem Testlauf eine Minute nach dem Hinzufuegen einer Regel, ihre Null bedeutet also nichts. Die Ponytail-Zaehlung oben ist dieselbe Pruefung, aber von Hand durchgefuehrt, mit toldyas Matcher.
So bauen wir. Bei den Agents, die wir fuer Unternehmen entwickeln, ist ein must-never eine Pruefung im Code, keine Zeile im Prompt. Den Prompt bekommt der Stil. Den Code bekommen die Regeln, die sich nicht beugen.
Quellen: jedes Terminal-Beispiel ist ein echter Lauf auf meinem Rechner am 9. Oktober 2026; der toldya-Bericht (0.3.3) ist auf seine ersten drei Zeilen gekuerzt. Die Kopien wurden durch Abgleich von Zeitstempel und Text jeder Nachricht gefunden, die 24 Nachrichten wurden von Hand gelesen und sortiert. Das git log stammt aus einem meiner eigenen Repositories. Der slopguard-Lauf uebergibt dem Hook-Skript das JSON, das ein Toolaufruf sendet. Dokumentation: Claude Codes Memory, Best Practices und Hooks-Guide. Issues findest du unter anthropics/claude-code, abgerufen am selben Tag ueber die GitHub API; die 124 ist eine Suche nach CLAUDE.md und "ignore" in Issue-Titeln.
Einordnung: Memory und Context, Schicht 2 des Agent Ops Stack.
Weiterlesen: How long should CLAUDE.md be? I priced every line. · The best CLAUDE.md rules are hiding in your chat history.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Posted on Oct 9 • Originally published at singhlabs.dev • AI-assisted
Short answer: CLAUDE.md is a request, not a lock. Claude Code loads it as context and tries to follow it, and Anthropic's docs say plainly there's no guarantee. When I went through my own history, most of the rules I'd have blamed Claude for ignoring were never written down, or were written for something else. The few that truly must hold need a hook, not a better sentence.
Search "claude code ignores claude.md" and page one is GitHub issues. Rules in capitals. MANDATORY. NEVER. On anthropics/claude-code, 124 issues have CLAUDE.md and "ignore" in the title. Eight are open. 68 were closed as not planned.
Plenty of complaints, no answers. So I opened my own case file: my Claude Code history since July, every project's CLAUDE.md, and the git logs behind them.
A rule in CLAUDE.md is a request. If it must never break, it needs a hook, not a louder sentence.
Rule out the boring cause before blaming the model. The docs say Claude treats CLAUDE.md "as context, not enforced configuration", and that it arrives as a user message after the system prompt. So first, confirm it arrived:
Run /context and look under Memory files. Not listed means not seen.
A CLAUDE.md in a subfolder isn't listed at launch. It loads when Claude reads a file in that folder.
Loading has bugs too. #99032, filed last week: the VS Code extension skips an @import that points outside the project, while the terminal loads it.
Loaded and still ignored? Then it's one of the next four.
This one's embarrassing. toldya reads what you've typed to Claude Code and finds the corrections you keep repeating. Mine:
$ npx toldya --all --dry toldya · 175 sessions (2 Jul – 9 Oct) · 3804 of your messages · 328 corrections You keep telling your AI: 1. 20× keep it simple (20 sessions) 2. 8× dont assume (7 sessions) 3. 8× I don't like it (7 sessions) Enter fullscreen mode Exit fullscreen mode toldya also flags a repeat that's already in your CLAUDE.md or AGENTS.md, with ← already in your rules, still repeated. I ran it in all 12 of my projects that have one of those files. It flagged nothing.
"Keep it simple" wasn't in the CLAUDE.md of any project where I kept typing it. Claude wasn't ignoring that rule. I'd never given it one.
One correction, found while writing this. When you resume a session, Claude Code copies the earlier messages into the new file, and toldya 0.3.2 counted every copy: it said 44. The fix shipped in 0.3.3, which made the run above. Still my top line.
Except I sort of had. Since 26 July I've run ponytail, a plugin whose session-start hook loads about 900 words of "build the simplest thing that works" into every session. Its text is in 187 of my 195 transcripts.
So I took toldya's two simplicity repeats ("keep it simple", "dont complex this"), dropped the copies, and kept the messages I typed with that text already loaded. There were 24. I read all of them:
17 were about how it talked or wrote, not what it built. "Sorry, I didn't understand what you did. Keep it simple and explainable."
5 were about the approach, closer to the plugin's turf.
Ponytail says, in its own text, that it "governs what you build, not how you talk." It was loaded every time. It just wasn't the rule I kept asking for.
So when I started a new data project this week, its CLAUDE.md had the right rule from the first hour: "Explain simply." Within a day I'd asked for a simple explanation five more times. "I need to understand in very simple way how to use that app."
"Explain simply" is a wish. Nothing in it can be checked. The docs make the same point with better examples: "Use 2-space indentation", not "Format code properly". A checkable version of mine would name the thing: a line limit, an example first, no term left undefined. I haven't tested that yet, so I'm not promising it.
The hard case. Another repo of mine opens its CLAUDE.md with a logging rule, under a heading that says non-negotiable: every change gets a CHANGELOG entry, timestamped from date -u, "never guessed or invented". Specific. Checkable. Line 40 of a 222-line file when it went in; the file is 311 lines now.
$ git log --format = "%ad %s" --date = short -S "Timestamps are UTC and real" -- CLAUDE.md 2026-08-16 Repo audit, project rules, and the documents needed to run this $ git log --reverse --format = "%ad %s" --date = short -i -E --grep = "(correct|fix).*timestamp" 2026-08-17 Correct a changelog timestamp I invented 2026-08-24 Correct a changelog timestamp that was written before date -u was read 2026-08-29 Fix a guessed timestamp, and write down how to stop guessing them 2026-09-09 Correct a guessed timestamp, for the third time $ wc -l CLAUDE.md 311 CLAUDE.md Enter fullscreen mode Exit fullscreen mode Four guessed timestamps in the 24 days after the rule went in, each caught and fixed in its own commit. Claude wrote those fixes, and every one names the rule it had just broken. With the third fix the rule got sharper: read the clock in its own command, then write.
Eleven days later it broke again. The fourth fix is titled "for the third time". Even the apology lost count.
That's four caught misses in about 150 commits that touched the log, so the rule mostly held. Mostly is fine for indentation. It's useless for a timestamp whose only job is to be right. Since 9 Sep there have been 44 more log commits and no fix, which means either the sharper wording landed or nobody checked. The history can't say which.
My four cases line up with Anthropic's memory docs, its best practices, and the issue tracker:
Where it sits. CLAUDE.md arrives after the system prompt, as a user message. When it clashes with Claude Code's own guidance, the built-in can win. In #27032, plan mode suggested a plans folder in the home directory, and the model followed it over a CLAUDE.md rule to keep plans in the repo. The docs list this among the things to check.
Length. Target under 200 lines; longer files "reduce adherence". The best-practices page is blunter: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" My logging rule lived in a file that grew from 222 lines to 311. What each line costs is in the length post.
Conflicts. If two instructions contradict each other, "Claude may pick one arbitrarily". Check your user file against your project file and any nested ones.
Shouting. The docs suggest "IMPORTANT" on the one line that keeps getting skipped, and warn that if you emphasise many, none stands out. #33603 is what happens next: a rule restated and strengthened after each violation, then broken in each of the next three sessions.
The model. #99704 counted a "reply in Korean" rule over one long session: no English replies on claude-opus-5, 33% English on claude-opus-5-5, same CLI. A rule that held last month proves nothing about this model.
Timing. If something must happen at a fixed point, before every commit or after every edit, the docs say to write it as a hook.
The best-practices page puts it in one line: CLAUDE.md instructions are "advisory", while hooks "are deterministic and guarantee the action happens". A PreToolUse hook sees the tool call before it runs, and can refuse it.
Here's slopguard 's Bash guard, run from its plugin folder, fed the call Claude would make to commit a.env:
$ echo '{"tool_name":"Bash","tool_input":{"command":"git add.env && git commit -m wip"}}' \ | node scripts/guard-bash.mjs \ | node -p "JSON.parse(require('fs').readFileSync(0)).hookSpecificOutput.permissionDecisionReason" SLOPGUARD blocked this command — [ SG-1] credential file staged for commit. fix: Add it to.gitignore. Anything committed is in the history permanently, even after a later delete. Rule text lives in AGENTS.md. Enter fullscreen mode Exit fullscreen mode The sentence version of that rule is #2142, open since June 2025: Claude Code "repeatedly ignores CLAUDE.md security guidelines and exposes API keys to version control". A hook doesn't give it the chance.
A hook only enforces what a script can check. In #99642, hooks that checked the form (a table exists, the logs were read) were satisfied while the work they stood for was skipped.
A hook that only adds text is still a request. Ponytail's hook prints its rules at session start, and the hooks guide says that output just joins Claude's context. Same odds as CLAUDE.md. #99642's reminder hook injected its instruction on every turn, and the model never acted on it.
So the test is: could a script say yes or no? A.env in a commit: yes, hook it. A log timestamp that doesn't match the clock: yes, and that's the hook my logging rule should have been. I haven't written it yet. "Explain simply": no. That one stays a sentence, as concrete as I can make it, and gets counted.
A rule you never re-check is a rule you're hoping about. toldya does the counting, on your machine, sending nothing:
$ npx toldya --dry # the report only, changes nothing Enter fullscreen mode Exit fullscreen mode Run it without --dry and it asks about each repeat: y writes it into CLAUDE.md, n skips it, e lets you reword it first. A week later, run it again. Each rule it added gets a line like "Keep it simple." said 20× before · 0× since. If "since" isn't near zero, the rule is a wish, or it needs a hook.
Honest status: I can't show you a real "since" yet, because I never added my repeats through toldya. That line is from a test run a minute after adding one, so its zero means nothing. The ponytail count above is the same check done by hand, with toldya's matcher.
This is how we build. In the agents we build for businesses, a must-never is a check in code, not a line in a prompt. The prompt gets the style. The code gets the rules that can't bend.
Sources: every terminal block is a real run on my machine on 9 Oct 2026; the toldya report (0.3.3) is trimmed to its first three lines. Copies were found by matching each message's timestamp and text, and the 24 messages were read and sorted by hand. The git log is from one of my own repos. The slopguard run feeds its hook script the JSON a tool call sends. Docs: Claude Code's memory, best practices and hooks guide. Issues are on anthropics/claude-code, read through the GitHub API the same day; the 124 is a search for CLAUDE.md and "ignore" in issue titles.
Where this fits: memory and context, layer 2 of the Agent Ops Stack.
Read next: How long should CLAUDE.md be? I priced every line. · The best CLAUDE.md rules are hiding in your chat history.