I have been running Claude Code as my daily driver for over a year, and for most of that time my CLAUDE.md was working against me. Not dramatically. Just a steady tax of repeated corrections, forgotten rules, and sessions that got slower and dumber as the day went on.
Here are the mistakes I kept making, and what actually fixed each one.
Mistake 1: Repeating instructions in chat instead of writing them down
For months I typed the same corrections into chat. "Use pnpm, not npm." "Don't touch the migrations folder." "British spelling in docs." Every session, again.
The obvious cost is my time. The less obvious cost is tokens. Every instruction repeated in chat is context spent in that session, and it vanishes when the session ends. An instruction in CLAUDE.md loads once, automatically, in every session, forever.
My rule now: if I have typed the same correction twice, it goes in CLAUDE.md before I type it a third time. This one habit removed most of my daily friction.
Mistake 2: Believing CLAUDE.md instructions are enforcement
They are not. An instruction in CLAUDE.md is a request. The model reads it, usually honours it, and occasionally does not, especially deep into a long session when earlier context has faded.
I learned this when "never commit directly to main" failed on exactly the day it mattered. The fix was realising that Claude Code has two different tools for two different jobs:
- CLAUDE.md is for preferences and conventions, things where 95 per cent compliance is fine.
- Hooks are for rules, things where 95 per cent is a failure. A PreToolUse hook that inspects the command and exits non-zero blocks the action deterministically. The model cannot forget a hook, because the hook is not the model.
Now anything I would describe as "must never happen" is a hook. Anything I would describe as "prefer this" stays in CLAUDE.md. Sorting my rules into those two buckets took twenty minutes and eliminated a whole class of incidents.
Mistake 3: Letting it read whole files when a slice would do
By default I would say "look at the auth module" and watch it pull in thousands of lines, most of them irrelevant. Every one of those lines occupies context that could hold something useful.
What fixed it: being specific in prompts ("read the validateSession function in auth/session.ts, lines around the token check") and adding a line to CLAUDE.md asking for targeted reads over whole-file reads. Grep first, read the matching region, only expand when needed. Sessions stay sharp noticeably longer.
Mistake 4: One giant session for everything
I used to keep a single session alive all day. Refactor in the morning, debug after lunch, write docs at the end. By the afternoon the model was dragging 100k plus tokens of morning context into every response, and quality dropped in ways that were easy to blame on the model rather than on me.
Fresh sessions per domain beat one long drag every time. Context from the refactor does not just waste space during the docs work, it actively biases it. When I switch task type, I start clean and let CLAUDE.md carry the durable rules across.
Mistake 5: Compacting mid-task
Compaction summarises the conversation so work can continue, and summaries are lossy. Compact in the middle of a delicate change and the details that get dropped are precisely the ones you needed.
The fix is timing. I compact at boundaries: a task finished, a test suite green, a decision recorded. Before compacting I make sure the current state is written somewhere on disk, a notes file or the plan doc, so the resumed session can recover specifics from files rather than from a summary.
Mistake 6: Leaving every MCP server switched on
This one surprised me. Every enabled MCP server injects its full tool definitions into the context on every request, whether or not you use it. I had accumulated a dozen servers and was paying thousands of tokens per request for tools I touched once a month.
Audit yours. Disable anything you have not used in a fortnight. Re-enabling takes seconds when you actually need it, and the reclaimed context goes to your actual code.
Mistake 7: Exploring in the main thread
When I did not know where something lived, I would have the main session search, open files, follow dead ends. All of that exploration, including the dead ends, stayed in context for the rest of the session.
Subagents fixed this. Delegate the exploration ("find where rate limiting is applied and report the file paths and the key function"), and only the answer comes back to the main thread. The wrong turns are discarded with the subagent. The main session stays focused on the actual change.
The pattern underneath all of these
Every mistake above is the same mistake wearing different clothes: treating context as free. It is not. It is the scarcest resource in the whole setup, and almost everything that felt like a model problem turned out to be a context problem I had created myself.
Durable rules in CLAUDE.md. Hard rules in hooks. Targeted reads. Fresh sessions per domain. Compact at boundaries. Trim the MCP list. Delegate exploration.
None of it is clever. All of it compounds.
What is in your CLAUDE.md that you find yourself repeating in chat anyway? I am curious whether others hit the instruction-versus-enforcement wall the same way I did.
Top comments (0)