Keep CLAUDE.md and AGENTS.md from lying to your agent

TL;DR

• The failure mode isn’t a bad file — it’s an aging one. Anthropic’s own docs say Claude treats CLAUDE.md as “context, not enforced configuration.” Nothing checks whether a rule still matches the code underneath it.
• The community diagnosis is specific. A 97-comment r/cursor thread opens with: “We wrote ours at launch. Six months later half the rules in it are wrong… It trusts the file more than the code.”
• The fix is a system, not a rewrite. Date every rule with a one-line reason, prune on a schedule, move enforceable rules to lint and hooks, and add a “Verify, Don’t Trust” rule — a 168-upvote post’s exact wording is below, ready to paste.
• Claude Code now automates part of it. /checkup (the alias for the expanded /doctor, shipped in v2.1.205) can dedupe and split CLAUDE.md — but it can’t decide whether a rule is still true. That judgment call is still yours.

If you haven’t decided which file format to use, or which one Claude Code actually reads, that’s a separate question — see CLAUDE.md vs AGENTS.md vs Skills. If you’re starting from a blank file, the annotated Karpathy CLAUDE.md is the best template we’ve found. This post assumes you already have a file, and asks how to keep it from becoming a liability.

The failure mode: the agent trusts the file over the code

Start with the shape of the problem, because it’s not the one people expect. A missing CLAUDE.md means the agent has less context — it falls back to reading your code, which is usually fine. A stale CLAUDE.md is worse: it actively tells the agent something false, and the agent has no way to know that.

The clearest description of this came from a Reddit thread that hit 97 comments on a modest 10 upvotes — a comment-to-upvote ratio that signals real, sustained discussion rather than a viral one-liner. The original poster:

The reply that names the mechanism most precisely came a few comments down:

“Worse than the rot itself is when the agent starts ‘fixing’ new code back toward the deprecated pattern, because it trusts the file over the codebase.” — u/ultrathink-art

That’s the sharp edge. A stale rule doesn’t just get ignored — it gets enforced. One team on the same thread watched it happen for real:

“A library we’d deprecated last year was still listed as the preferred option and the agent cheerfully rebuilt half a module around it before we noticed.” — u/JimmyBenHsu

Notice what makes this dangerous: the output looked fine. Tests may have passed. The diff may have looked reasonable to a reviewer skimming it. As the original poster summed it up, an agent generating code against standards that don’t exist anymore “looks fine on the surface, which is worse than it being obviously broken.” A crashed build gets fixed the same day. A confidently-wrong one ships.

Why files rot, but code doesn’t

The mechanism is a straightforward asymmetry. Code has a feedback loop: change something wrong and tests fail, types break, CI turns red. CLAUDE.md has none of that. It’s prose. Delete the function it describes, and the sentence describing it sits there, confidently wrong, until a human happens to reread it.

Anthropic’s own docs put CLAUDE.md squarely on the no-feedback-loop side of that table: “Claude treats [CLAUDE.md and auto memory] as context, not enforced configuration.” Nothing in the mechanism checks a rule against reality. The file is exactly as fresh as the last person who opened it and meant it.

How common is the underlying problem? One data point from the same thread, offered with its own hedge attached: “I saw a stat recently that out of 10k public repos only about 5% even have these config files at all. I believe it.” That’s a secondhand number from a Redditor, not a cited study — treat the 5% as color, not fact. The point that survives the hedge: most repos still don’t have an instructions file at all, so the minority that do can’t afford to let theirs become a liability instead of an asset.

The maintenance system

Nobody on either thread proposed abandoning instructions files entirely. The fixes that got upvoted converge on four habits, and they compose — you don’t have to pick just one.

The next four sections take them one at a time.

1. Dated rules with a one-line why

The single most concrete fix in the r/cursor thread came from the same commenter who named the “fixes code back toward a dead pattern” failure above:

The date and the reason do different jobs. The date tells a reviewer when to be suspicious — a rule from fourteen months ago deserves more scrutiny than one from last week. The reason tells them whether to be suspicious: if you can’t restate why a rule exists, you’ve found a rule that’s ready to delete, regardless of its age.

In practice, the format is one line per rule:

- Use /v2/export for bulk downloads, not /v1 — [2026-04-11, why: v1 is
  rate-limited to 10 req/min and was deprecated after the March incident]
- Data fetching: SWR only, not React Query — [2025-11-02, why: standardized
  before Suspense support existed; revisit if this blocks a Suspense migration]

The second example does something specific: it names its own expiration condition. “Revisit if this blocks a Suspense migration” tells a future reviewer exactly what to check before deciding whether the rule still holds, instead of asking them to reconstruct the original tradeoff from scratch eight months later.

2. The monthly prune

Anthropic’s own memory docs recommend reviewing CLAUDE.md “periodically to remove outdated or conflicting instructions,” without naming a cadence. The community filled in the number: monthly, run against the dated rules from the section above — if a reason no longer holds, delete the rule; don’t wait for someone to trip over it first.

A prune session is short if the file is dated. These are the signs a rule has already gone stale before you even open the file:

One Redditor automated the review itself rather than relying on remembering to run it:

“Make a skill called /update-docs… tell the agent to consider the code changes, read CLAUDE.md and all the other bits of markdown… and update the stale parts. Invoke this skill before you invoke the commit and push sequence… My CLAUDE.md files never rot since I made that skill.” — u/florinandrei

Another team took a more radical first step — shrink, then enforce — which is exactly where the next habit picks up:

“We deleted maybe two thirds of it and pushed the conventions we actually cared about into code: CI greps for patterns we don’t want, a custom eslint config that flags reintroduction of stuff we deprecated… Updating a doc is a chore nobody remembers, but breaking CI is impossible to ignore.” — u/JimmyBenHsu

3. Move enforceable rules out of prose

This habit shrinks how much there is to prune in the first place. If a rule can be checked by a machine, prose is the wrong home for it — not because prose is imprecise, but because prose has no failure mode. A broken lint rule turns CI red. A broken CLAUDE.md rule sits there unenforced, waiting for the next prune to notice it.

Two commenters on the r/cursor thread converged on the same line independently:

“This is why I like treating AGENTS.md like docs with tests, not a magic instruction file. If a rule can be enforced by lint, type checks, or a small script, it should live there. The agent file should mostly point at the source of truth.” — u/CODE_HEIST

“AGENTS.md is not the place for hard rules and conventions… Custom linting rules work great. Use git hooks to run those rules on changed code before committing and your agent will have no choice but to follow.” — u/Sontemo

Anthropic’s own docs draw the identical line from the mechanism side: CLAUDE.md and auto memory are “context, not enforced configuration… To block an action regardless of what Claude decides, use a PreToolUse hook instead.” A hook runs as a real shell command at a fixed point in the session and applies no matter what the model decides. A sentence in CLAUDE.md is a request the model is free to misjudge, forget, or outrun as the codebase changes underneath it.

A commenter on the companion r/ClaudeCode thread made the same connection from a different angle, replying under the “Verify, Don’t Trust” rule below:

“You can also build out a hook that enforces this behavior so that you aren’t just taking the AI’s word for it.” — u/Weary_Caregiver_8428

The dividing line in practice: “don’t leave unused imports” is a sentence Claude might forget under context pressure. "no-unused-vars": "error" in an ESLint config, plus a pre-commit hook, is not a sentence anyone has to remember — it fails the commit. Move every rule you can turn into the second kind, and the file that remains is smaller, which makes the monthly prune faster too.

4. Verify, Don’t Trust

The most-upvoted CLAUDE.md addition either thread produced wasn’t about pruning at all — it was a standing rule that stops Claude from trusting its own stale memory of anything, instructions file included. A post titled “The single best thing I’ve put in CLAUDE.md” (168 upvotes at the time of writing) shared it in full:

## Verify, Don't Trust

When producing an analysis or summarization of something gleaned from a
resource (web page, MCP call, user-provided document), do not trust a
memory or retained summary of that resource. Always retrieve the resource
afresh and compare it to the summary or analysis you are preparing. When
comparing, do so in an adversarial way: you are fact-checking work that
you suspect at the start contains errors and hallucinations.

Quoted verbatim from u/MisterHarvest’s post on r/ClaudeCode. As written, it’s about resources Claude reads mid-session — a web page, an MCP call, a document. Extend the logic one step and it covers the instructions file too: CLAUDE.md is a retained summary, written once, of how your codebase used to behave. A rule you haven’t re-checked against the actual code is precisely the kind of memory this rule warns against — you’re the one holding the stale summary this time, not the model.

One reply captured why the rule resonated:

“Fable doesn’t need it but often the others do. They blindly trust the whatever.md from 2 weeks ago that’s out of date.” — u/teramoc (18 upvotes)

Another commenter made the rule more mechanical rather than repeating it — worth adopting if the plain version doesn’t change behavior on its own:

“The part that made it stick was forcing a diff step: tell it to quote the original line next to its claim. Otherwise it still paraphrases from memory and calls that verified.” — u/Fresh-Resolution182

That’s the upgrade worth making: don’t just ask Claude to verify, ask it to show the verification — quote the current line of code or docs next to the claim it’s making about it.

Copy-paste starter block

Everything above, combined into one block you can paste into CLAUDE.md or AGENTS.md today. Adjust the cadence if monthly doesn’t fit your team; keep the shape.

## Maintenance

Rule format: <rule> — [YYYY-MM-DD, why: <one-line reason>]
Example: Don't use the /v1 export endpoint — [2026-03-02, why: rate-limited
to 10 req/min, agent kept looping retries against it]

Monthly prune (run on the 1st):
- Read every dated rule. If the "why" no longer holds, delete the rule.
- Grep the codebase for anything this file says to avoid. If the pattern
  is already gone, the rule describing it can go too.
- Anything enforceable by a lint rule, a type, or a git hook: move it
  there and delete it here. Prose rules drift silently; enforced rules
  fail loudly.
- Anything nobody has been corrected on in 3+ months: delete it. A rule
  still worth keeping is one someone would have needed by now.
- Re-run /init (or /checkup) and diff its suggestions against what's
  actually committed.

## Verify, Don't Trust

When producing an analysis or summarization of something gleaned from a
resource (web page, MCP call, user-provided document, or this file), do
not trust a memory or retained summary of that resource. Always retrieve
the resource afresh and compare it to the summary or analysis you are
preparing. When comparing, do so in an adversarial way: you are
fact-checking work that you suspect at the start contains errors and
hallucinations. Quote the current line next to any claim you make about
it.

Two changes from the sourced version, both deliberate and worth flagging since the rest of this post insists on quoting verbatim: “or this file” was added to the resource list, and Fresh-Resolution182’s quote-the-line technique was folded in as the closing sentence. The core paragraph is still u/MisterHarvest’s wording — those two additions are this post’s synthesis of the thread, not part of the original.

Automate it: /checkup

Anthropic shipped part of this into the tool itself. Claude Code v2.1.205 (July 8, 2026) folded a fuller diagnostic into /doctor: “/doctor is now a full setup checkup that can diagnose and fix issues; /checkup is its alias.” Boris Cherny, Claude Code’s creator, announced what running it actually does. Trimmed to the parts relevant to instruction files:

• Dedupes your local CLAUDE.md against the version checked into git.
• Can break up an overgrown root CLAUDE.md into nested CLAUDE.md files plus skills.
• Cleans up unused skills, MCP servers, and plugins to save context.

Per Cherny’s announcement, it also updates Claude Code itself, turns off slow hooks, and pre-approves frequently-denied read-only commands — general tool upkeep more than instructions-file hygiene specifically — and “confirms with you before making any changes.” The full walkthrough lives in a dedicated post: how /checkup works, end to end.

What it doesn’t do is the interesting boundary. Deduplication finds an identical line living in two places. Drift is a line that isn’t a duplicate of anything — it’s wrong, and nothing about matching text tells /checkup that. It’s a good janitor: it can shrink and de-duplicate a bloated file faster than you’d do it by hand. It can’t tell you whether a rule’s stated reason still holds. That’s still the dated-rule-and-prune system above, not the tool.

Community signal

Not everyone agrees the whole premise is worth this much process. The sharpest pushback on the r/cursor thread came from a commenter running agents across a 1-million-line codebase:

That’s a real critique, and it agrees with everything above more than it first looks like it does. A file with nothing speculative in it — no rules the codebase could already teach a competent reader — is a file with almost nothing left to rot. The maintenance system in this post and the “write less of it” camp pull in the same direction: keep only what the agent genuinely can’t infer, date it, and prune what stops being true. They disagree only on how much such a file should contain in the first place — the debate our formats-and-evals piece covers directly.

The verdict

Frequently asked questions

Glossary

Sources

Primary

• code.claude.com/docs/en/memory — “context, not enforced configuration,” the periodic-review guidance, the under-200-line size guidance, PreToolUse hooks.
• Claude Code CHANGELOG, v2.1.205 (July 8, 2026) — “/doctor is now a full setup checkup… /checkup is its alias.”
• @bcherny on X, July 8 2026 — Boris Cherny’s itemized /checkup announcement; cited here, embedded in our dedicated /checkup post.

Community

• r/cursor — “Anyone else find their CLAUDE.md / AGENTS.md files end up lying to the agent after a few months?” — u/WEEZIEDEEZIE, 97 comments.
• r/ClaudeCode — “The single best thing I’ve put in CLAUDE.md” — u/MisterHarvest, 168 upvotes at time of writing.

Related on MCP.Directory

• CLAUDE.md vs AGENTS.md vs Skills (2026) — which format to use, and what the evals say.
• Karpathy’s CLAUDE.md, Annotated — how to write a strong file from a blank page.
• Stop Claude Code From Over-Engineering — the output-verbosity side of the same discipline.
• /checkup, end to end — the automation this post references.
• Claude Code hooks — the enforced-configuration layer this post argues for.
• /clients/claude-code — client reference.