After 6 months of Claude Code, I don't think the context window is the problem.
I keep seeing the same workflow.
Someone dumps their entire codebase into Claude, adds a massive CLAUDE.md, layers on some "skills," and hopes the model "remembers" what to do.
Then three prompts later, Claude rewrites a function that was explicitly rejected in a PR discussion from two months ago. Or it builds a feature that directly contradicts a product constraint buried in a Slack thread. Or it "optimizes" code that was intentionally left simple because of a customer support pattern no one documented.
So we make the CLAUDE.md bigger. We add more rules. We stuff more tokens into the window.
And the document becomes another thing nobody wants to maintain.
Here's what I think is actually happening.
We keep asking AI to remember knowledge that was never captured in the first place.
Think about what a developer (or Claude) needs to know before writing one line of code:
- Why does this feature exist? What customer problem triggered it?
- What implementations were tried and rejected? Why?
- What architecture decisions constrain the solution?
- What did the last PR discussion actually conclude?
- What are the invisible product rules that never made it into a ticket?
None of that lives in the repository. Some of it lives in Slack. Some in Linear. Some in the head of the engineer who just left. Most of it is simply gone.
So we compensate by making the context window bigger, as if the problem is how much the AI can read, not what it has available to read.
Maybe the real gap isn't retrieval. Maybe it's that the knowledge was never written down in a form a machine (or a new human) could actually use.
I've been watching our team spend 40 minutes understanding an issue before writing 5 minutes of code. The code isn't the bottleneck. The archaeology is.
Curious if anyone else has reached the same conclusion, or if I'm just building CLAUDE.md wrong.
the 40 minutes of archaeology before 5 minutes of code line is exactly it. what's worked for me isn't one CLAUDE md that keeps growing, it's splitting it. a short house style file for conventions that rarely change, plus a separate doc per feature written at the moment a real decision gets made (why this approach and not the obvious one, what got tried and rejected, what the tradeoff was), living next to the code. the trick is writing that second kind of doc as part of actually building the feature, not after, because the reasoning is fully in your head for maybe an hour and gone by next week. a bigger single file just means more tokens spent re-deriving context that was never captured cleanly in the first place
Your observation about spending 40 minutes on archaeology before 5 minutes of coding is exactly right. The naive fix is a bigger CLAUDE.md, but that just becomes another document nobody maintains. The harder question youre asking is structural: how do you capture decision context at the moment its created, in a way the AI can reference later. Have you found any practice that consistently works for preserving that context before it disappears?