How to Keep Your CLAUDE.md From Going Stale
A static file describing a moving codebase will quietly degrade every session
Writing a good CLAUDE.md is the easy part. Keeping it true is the part nobody warns you about.
You set it up once — the stack, the conventions, the commands, the reasons behind your architecture — and for a week it's the best thing in your workflow. Then the codebase moves. You rename a module, drop a dependency, change how you handle migrations. The file doesn't move with it. A month later Claude Code is confidently following three rules that stopped being true, and you can't figure out why it keeps reintroducing a pattern you deleted.
That's context drift, and in a fast-moving repo it's not an edge case. It's the default.
Why does CLAUDE.md go stale?
Because it's a static description of something that changes every day, and nothing forces the two to stay in sync. Your code is under version control, reviewed, tested. Your CLAUDE.md is a document you edited once and mostly forgot — it drifts the moment the first commit lands that contradicts it.
The reason drift matters more than it sounds is where the file goes. CLAUDE.md is loaded automatically at the start of every session and sits in the context window for every prompt after it. That window is finite: Claude Code runs on a 200,000-token context by default (1M on the newer Opus models, per Anthropic's own docs). Everything in your CLAUDE.md competes for that budget against the actual code Claude needs to reason about. So a stale file isn't just inaccurate — it's inaccurate and occupying space that real work needs.
In a slow repo you might get away with it. In one where the architecture is still moving, the file falls behind faster than you'd expect, and every session inherits the gap.
Why stale context is worse than no context
Because a missing instruction makes the agent guess, but a wrong instruction makes it confidently do the wrong thing. Those are not the same failure. Absence of context produces a generic answer you can catch. Bad context produces a specific, plausible, wrong one — the agent dutifully applies a rule that no longer holds, and the output looks intentional.
There's now real measurement behind this. Chroma's Context Rot study, published in July 2025, evaluated 18 frontier models — including GPT-4.1, Claude 4, Gemini 2.5, and Qwen3 — and found that model reliability drops as input grows, with degradation showing up at every input length they tested, not just near the window limit. The takeaway for a context file: more text is not free, and older text you've stopped verifying is actively working against you. A bloated, half-true CLAUDE.md doesn't just waste tokens; it measurably lowers the quality of what comes back.
This is a different problem from context rot inside a single long session — that's degradation as one conversation grows. Stale CLAUDE.md is degradation across sessions, baked into the file before you type anything. Both produce the same symptom: a confident wrong answer with nothing flagging that the information aged.
How do you keep it current?
Treat maintenance as a first-class part of the workflow, not documentation you'll get to later. Three habits do most of the work.
Prune to a budget, not to taste
There's a ceiling on how many instructions a model reliably follows — practitioners who've stress-tested it put it around 150–200 distinct directives, and Claude Code's own system prompt already consumes roughly 50 of those slots before you've written a line. That leaves you something like 100–150 usable instructions before Claude starts quietly dropping some. Pruning isn't tidiness under that math — it's staying under a hard limit. If a rule no longer earns its slot, delete it. A lean file also keeps the salient instructions salient. (More on the token side of this in optimizing context in Claude Code.)
Update on events, not from memory
You will never remember to refresh CLAUDE.md on a schedule. Tie updates to the moments that make it stale instead: when you rename a thing, change a convention, or merge a PR that alters how the project works, update the file in the same change. If it's part of the diff, it stays honest. If it's a separate chore, it never happens.
Automate the writes
Claude Code's hooks and slash commands let you append or rewrite rules programmatically at specific points — a commit, a PR, a test run — so the file updates from real events instead of your recollection. Anthropic's own Claude Code best-practices guide frames CLAUDE.md as a living tuning parameter you refine continuously, not a one-time setup. The more of that refinement you can trigger automatically, the less drift accumulates between the code and the file.
What doesn't belong in CLAUDE.md in the first place
A lot of what bloats these files — and rots the fastest — was never project context to begin with. Open a few well-worn CLAUDE.md files and you'll find who the developer is, which client the work is for, the team's house style, preferred tone in comments, standing dos and don'ts that have nothing to do with this repo. That's personal and organizational context, and it's living in the wrong place.
Two things go wrong when it lives in the repo file. It gets duplicated — the same "who I am and how I work" block copy-pasted into every project's CLAUDE.md, going stale in each one at a different rate. And it crowds out the project-specific rules that actually need the token budget.
The industry is already separating these concerns on the project side. AGENTS.md — the tool-agnostic convention formalized in August 2025 by OpenAI, Google, Cursor, Factory, and Sourcegraph, adopted across 20,000+ repositories and now stewarded under the Linux Foundation — exists precisely to standardize project instructions into a portable format any agent can read. That's the right move for project context. But it sharpens the point about the other half: your identity, your client, your standards aren't project context at all. They're stable and cross-repo, and they belong in a layer that every tool can load — not pasted into a file per repository.
Pull that layer out, and the CLAUDE.md you're left with is smaller, genuinely project-specific, and rots far slower — because the parts that changed with you rather than the code aren't in it anymore. Personal context is the name for that layer: who you are, who you're working for, how you work, held once and served to Claude Code and every other tool, instead of maintained by hand in each repo.
Keeping your CLAUDE.md fresh is half discipline, half knowing what should never have been in it.
See what belongs in your portable context layer →
