Claude Ignores Your CLAUDE.md? Lock It Down

Rules written, rules ignored

You wrote the perfect CLAUDE.md: architecture overview, coding standards, helpful context, examples of good patterns. The agent thanked you, then installed three packages, refactored auth, and pushed to main.

Not malice — triage. Agents weight instructions by enforceability and brevity: short checkable rules survive into step 20 of a session; long prose decays by step 4. Your 200-line essay became background texture the model skimmed once and forgot.

Claude ignores claude md files for structural reasons, not attitude. Fix the structure and compliance follows.

Ignored rules vs locked rules

Three details make long files fail mechanically:

1. Attention decays with session length. The file loads at step 0; by step 15 the working context is code, diffs, and errors. Only rules short enough to persist as compressed memory survive — four clauses fit, forty paragraphs don't.
2. Vague rules can't trigger self-correction. "Write clean code" gives the agent nothing to check itself against mid-task. "Routes ≤40 lines" fires a mental grep on every file write. Checkable rules self-enforce; vague ones need external policing that never arrives.
3. No teeth means no learning. Sessions that violate unenforced rules succeed anyway — the agent learns rules are decorative. One blocked push (hook refuses, CI reds) teaches more than a hundred polite paragraphs. Consequences compile; suggestions evaporate.

The AGENTS.md-vs-conventions post wrote the four clauses. This one makes them stick.

Claude ignores claude md lockdown

Same file, three upgrades: shorten, symlink, enforce.

Step 1 — Cut the file to four clauses under one page.

## NEVER (violations fail review automatically)

- No npm install without written human approval.
- No DROP/RENAME/TRUNCATE, no DELETE without WHERE.
- No secrets committed. No direct pushes to main.
## SHAPES

- Routes: validate → auth → ONE call → JSON. ≤40 lines.
- Providers: same exports, every engine, plain objects.
## DONE

- node --check + lint clean + curled endpoint + health 200, pasted in transcript.

Everything else (architecture tours, examples, philosophy) moves to docs/ where humans read it. The agent file holds only what constrains — short enough to persist all session, checkable enough to self-fire. Length was the bug; deletion is the fix.

Step 2 — Symlink every tool to the one file.

# one source of truth, every doorway:
ln -s AGENTS.md CLAUDE.md          # Claude-native path
ln -s AGENTS.md .cursorrules       # Cursor path (or rules dir include)
ln -s AGENTS.md .opencode.json 2>/dev/null || true  # where supported
# verify: each tool reports the same four clauses on "what are your rules?"

Five rule files disagree by March; one file with four symlinks agrees forever. Ask each tool to recite its rules after linking — mismatch means the symlink missed and sessions run ungoverned. Verify quarterly; vendors rename paths without telling you.

Step 3 — Add teeth: hooks that fail violations.

Add a pre-push check that does three things: it searches for live secret patterns, it flags route files over about 40 lines, and it refuses migrations containing drops.

Three checks, thirty seconds, enforced compliance: secrets blocked, fat routes flagged, drops refused. The agent learns within two sessions that violations fail loudly — behavior change through consequences, not comprehension. Teeth don't require understanding; they require existence.

That's the design earning its keep — rules that hold on every device, every model.

Essay file vs lock file, one month

The other column, filled in: short files feel incomplete to thorough humans (where's the context? the examples? the why?) — that's what docs/ is for. And teeth need tending (grep patterns rot, hooks need new verbs yearly).

BoringPush splits the audience deliberately: humans get the library, agents get the law. Each format serves its reader; neither serves both.

FAQ

Why does claude ignores claude md happen even with short files?

Usually placement or multiplicity: the file sits where the tool doesn't look (wrong filename, nested wrong), or five competing files disagree and the agent follows the loudest. Diagnose by asking the tool to recite its loaded rules verbatim — absence means path problem, contradiction means multiplicity problem. Fix paths first, then prune to one file.

Should rules live in version control with the code?

Yes — rules versioned beside code stay synchronized (new provider → new shape clause in the same PR). Unversioned rules (dashboard settings, personal configs) drift from the repo they govern within weeks.

Law lives where the governed live: in git, reviewed like code, blamed like code. Colocation is compliance infrastructure.

How often should the lock file change?

Rarely and deliberately: new clauses arrive from the bug ledger (recurring incident → new never), never from speculation. Quarterly prune removes clauses that stopped earning (no violations in 90 days means either mastery or irrelevance — investigate which).

Stable law compounds trust; churning law teaches contempt. Amend on evidence, never on vibes.

Do different models need different rule phrasings?

Marginally: some models obey "NEVER" absolutely, others need "forbidden — review fails automatically" spelled out. Keep one file, tune the verbs yearly against observed violations per model.

The structure (forbidden/shapes/done) is universal; the emphasis words drift with model generations. One file, seasonal verb tuning, same teeth.

Can over-strict rules hurt agent usefulness?

Yes — rules that forbid legitimate paths (no new files ever, no refactors at all) turn agents into typists needing permission per keystroke. Strictness belongs on irreversible actions (drops, secrets, pushes, installs); everything else gets shapes, not bans.

Forbid the catastrophic, shape the routine, free the trivial. Calibrated law, not maximum law.

What if my team won't read or maintain the file?

Then the file dies and violations resume — rules need one owner the way code needs reviewers. Assign the qubit: whoever reviews agent PRs owns the lock file, amended from the ledger monthly.

Ownerless law is decoration with extra steps. Name the owner in the file itself; accountability starts at authorship.

Keep reading

• AGENTS.md Is a Wish List Until You Add Teeth — the four clauses, defended
• OpenCode SaaS Starter: Stop the Every-Session Redesign — the structural half of the split
• Stop AI Hallucinating Packages (It Almost Installed Malware) — Clause 1 (deps) in full depth