I am an AI Architect, and a lot of my work is getting AI agents ready for production. Context cost is part of the agent harness: whatever you load before the first prompt is paid for again on every prompt after it. This post is about one file in my own setup that I had stopped treating as part of that harness.
If you use Claude Code every day, your CLAUDE.md might be costing you way more than your prompts—both in hard token costs and in response quality.
I learned this the hard way earlier this year. I noticed my token usage was spiking, but the quality of the agent’s responses was actually going down. Claude was getting more context, yet returning worse answers. I decided to audit my setup, and the findings were eye-opening.
The Culprit: CLAUDE.md Turned Project Diary
Over months of development, my CLAUDE.md file had slowly accumulated project history. Every completed task, build error debugged, deployment checklist, and test outcome was logged there. It grew to nearly 46KB.
Here is the problem: Claude Code reads CLAUDE.md at the start of every session and automatically propagates it to all subagents.
That means every single prompt, command execution, or subagent invocation was carrying 46KB of history as overhead. I was paying for hundreds of thousands of redundant tokens daily, only to dilute the context and get confused, hallucinated responses.
Two Types of Costs in Claude Code
When optimizing agent workflows, it is helpful to divide token expenses into two main buckets:
- Per-use costs: One-off actions like executing shell commands, calling custom skills, or spawning subagents. You can control these by choosing when to delegate.
- Per-prompt costs: Constant overhead sent with every single message in a thread. This includes active memory, context hooks, and system files like
CLAUDE.md.
I had spent hours optimizing my commands and skills (per-use costs) while completely ignoring the silent token drain happening on every prompt.
The Fix: Housekeep Your Settings
To solve this, I pruned my CLAUDE.md from 46KB to under 1,000 words. I removed all logs, histories, and completed task archives, leaving only essential instructions (commands, styling guidelines, test runs). All historical notes were moved to a separate status file that Claude only reads when explicitly told to.
Now, I stick to a simple rule: CLAUDE.md is for instructions, not history.
What to remove from CLAUDE.md
Completed tasks, changelogs, old architecture specs, meeting notes, build logs, and environment variables.
What to keep in CLAUDE.md
Development commands (build, run, lint), core architectural guidelines, coding conventions, and high-priority rules.
Check Your Files Today
If you have been running Claude Code on the same workspace for a few weeks or months, take a look at your files. Open your CLAUDE.md and check its size. You might be surprised at how much you’re spending on memory overhead, and how much better your responses get when you clean it up.
Housekeep your Claude Code workspace today and keep your agent fast, cheap, and focused.