April 5, 2026
The hidden cost of manually maintaining project context for Claude Code
CLAUDE.md files start useful and end up a maintenance burden. They go stale, eat tokens, and need constant updates. Here's what that actually costs you.
You start a new project and write a clean CLAUDE.md. Forty lines. Covers the architecture, the key conventions, a few gotchas. Claude Code reads it, understands the repo, and you’re productive immediately.
Three months later, that file is 400 lines. It has sections that contradict each other. A whole block about a database schema that got replaced in January. Instructions for a build command that changed last week. You keep meaning to update it, but every time you open it you close it again because you don’t have time to audit the whole thing right now.
This is context debt. And it compounds silently.
Every session, Claude reads that entire file. Every token spent processing outdated instructions is a token not spent on your actual problem. Worse, stale context actively misleads. If CLAUDE.md still describes the old API structure, Claude will confidently use it. Not because it’s wrong about your intent, but because you told it that’s how things work.
The underlying cause isn’t laziness or poor discipline. It’s that CLAUDE.md is a static document trying to describe a moving target. Your codebase evolves constantly. Decisions get made, reversed, refined. New patterns emerge. Files get renamed, deleted, reorganized. Keeping a human-written summary in sync with all of that is a second job nobody signed up for.
The more you invest in the file, the more you need to maintain it. Teams with thorough, well-organized CLAUDE.md files often have the worst drift, because thoroughness creates more surface area to go stale.
What actually works is generating context from what already happened, not writing it by hand. When you make a meaningful commit, KeepGoing captures what changed and why, directly from git. When you start a new session, it surfaces a briefing built from recent activity: what files were touched, what decisions were recorded, what’s next. The briefing reflects the current state of the repo because it was derived from the current state of the repo, not from something you wrote weeks ago.
The MCP server (npx @keepgoingdev/mcp-server) exposes this as a tool Claude can call at the start of any session. Instead of a static file Claude reads and hopes is accurate, it’s a live query against what actually happened. You stop writing context and start capturing it.
If you’re maintaining a long-running project with Claude Code, audit your CLAUDE.md right now. Count the lines. Find one section that’s no longer accurate. That section exists in every file like it. The question is how much of Claude’s attention it’s consuming before you get to the work that actually matters.