Claude Code and CLAUDE.md
Why Claude Code ignores your CLAUDE.md.
CLAUDE.md is context, not enforcement. Claude Code reads it and weighs it against the task, its own instructions, and everything else in the window. Rules get skipped when the file is long, when they sit far from the code they govern, or when nothing checks the edit against them.
- Length
- Every extra rule dilutes the others
- Distance
- A rule far from the task reads as optional
- Chat corrections
- Said once, never written down
- Enforcement
- Nothing checks the edit against the rule
A rule helps only if it is in front of the agent when it touches the file the rule is about.
The file is context, not a contract.
Claude Code treats CLAUDE.md as guidance it may or may not apply to the task in hand. The longer the file, the more each rule competes with the others, and adherence tends to drop as instructions pile up. Vague rules go first, but specific ones can be missed too.
Before adding another line in capitals, make the rules that matter easier to follow and harder to miss.
- Keep CLAUDE.md short: only what Claude would get wrong without it
- Move area-specific rules next to the code, in nested CLAUDE.md files or path-scoped rules
- Turn every never-do-this rule into a test, a lint rule, or a hook that fails
- Prune the file when a rule stops earning its place
What a notes file can’t do.
Even a well-kept CLAUDE.md is text. It cannot tell which files a rule applies to beyond its folder, check an edit against it, or record what the agent actually did. A correction made in chat disappears with the session unless someone writes it back into the file by hand.
That is why the same rule gets broken again after it was already explained: the explanation never reached the place where the next edit happens.
Where Kaplira fits.
Kaplira records decisions and known errors from each governed run and links them to the files they affect. When an agent is about to touch those files, it gets the ones that apply and is asked to acknowledge them. On the governed path, planned edits are checked against the task’s scope when a pre-edit gate applies, and a receipt records what changed.
It does not force the model to obey either. It puts the right rule in front of the agent at the right file and keeps a record of what happened. Your CLAUDE.md can stay.
Continue exploring
Repeated mistakes
Why a fix doesn’t stick between sessions, and how to attach the lesson to the file.
02.md file sprawl
What to keep in your agent’s notes, what to cut, and what to stop writing by hand.
03Regression prevention
Carry known errors, guardrails, and required tests into the runs that follow.
04Agent governance
The boundaries, evidence, and review that keep autonomous changes accountable.
Governance is easier to judge on a real run.
The desktop app is free, no signup is required, and the run record stays on your machine by default. Tell me which part of your review actually needs proof — that is what decides what gets built next.
Governance applies to integrated workflows that use the project contract. It does not replace your executor’s sandbox, access controls, tests, or human review, and it does not guarantee correct code. Read the run evidence and security boundaries to see what the record proves.