Matt Pocock recently put out a video called "Never Run claude /init" about managing your CLAUDE.md files to avoid context rot. The core argument: claude /init generates verbose boilerplate that eats into your context window, and you should be intentional about what goes in there instead. I agree with the premise, but I wanted to push the idea further. How much of what we put in these files is actually for the machine, and how much is just… for us?
The Problem
Claude Code injects your CLAUDE.md files into every conversation as system prompt context. You've got a project-level CLAUDE.md, a global one at ~/.claude/CLAUDE.md, and if you're running a persistent memory system like I do, those files get loaded too. Every character in those files is context that Claude processes before it even starts thinking about your actual request.
Context windows are big now, sure. But they're not infinite, and there's real evidence that models perform better when the signal-to-noise ratio in their context is high. Every decorative markdown header, every prose explanation of something the model can infer, every redundant framing sentence—that's noise competing with signal.
The Hypothesis
Most of the formatting in CLAUDE.md and related instruction files exists for human readability. Markdown headers, bold text, bullet list prose, verbose table formatting, "when to read" hints—these all help a human scan and understand the file. But Claude doesn't need any of that. Claude can parse compact notation just as well as a formatted table, and it can infer when a file is relevant without being told.
So what if we stripped all the human-readable decoration and kept only the machine-readable signal?
What I Did
I went through my CLAUDE.md files and my persistent memory system files and compressed them using a few simple rules:
- Strip markdown decoration: Headers (
##), bold (**), italic (*), horizontal rules (---). These are visual aids Claude doesn't need. - Collapse prose to notation: Instead of a sentence explaining something, use compact key-value pairs or pipe-delimited lists.
- Remove redundant framing: Sentences like "This section contains…" or "The following table shows…"—Claude can see what it contains.
- Deduplicate cross-file context: If the same information appears in multiple files, keep it in one canonical place.
- Compress table formatting: Markdown tables with alignment rows and padding are verbose for what they communicate.
Before & After: Directory Index Table
Here's a real example. My project CLAUDE.md had a directory index formatted as a markdown table:
## Directories
| Directory | What | When to read |
|-------------|-----------------------------|---------------------------------------|
| src/ | Application source code | Working on application logic |
| infra/ | Terraform and Ansible files | Modifying infrastructure |
| docs/ | Architecture documentation | Understanding system design |
| scripts/ | Deployment and utility scripts | Running or editing deploy workflows |After compression:
Dirs: src/=application source | infra/=terraform+ansible | docs/=architecture docs | scripts/=deploy+utility scriptsOne line. Same information. Claude has no trouble parsing pipe-delimited key-value pairs. The "When to read" column was entirely redundant—Claude can infer when to read a directory from its name and description.
Before & After: Memory System Instructions
My global CLAUDE.md had detailed instructions for a persistent memory system:
## Memory System
Persistent memory lives at `/path/to/memory/`.
**Session start**: Read `memory/_index.md` to re-establish context
when doing substantive work in this repo.
**During work** — Write to memory when something significant happens:
- A discovery or non-obvious finding → append to `memory/discoveries.md`
- A new skill applied or learned → update `memory/skills.md`After compression:
Memory: /path/to/memory/
session-start: read _index.md for substantive work
during-work (write on significant events only, signal not noise):
discovery → append memory/discoveries.md
skill learned → update memory/skills.mdSame behavior. Less than half the characters.
The Results
File Before After Reduction
─────────────────────────────────────────────────────
_index.md 3,560 2,036 43%
discoveries.md 11,260 5,609 50%
interests.md 4,315 2,561 41%
skills.md 16,176 5,353 67%
career-timeline.md 17,882 5,027 72%
~/.claude/CLAUDE.md 2,350 1,495 36%Total compressed memory system: 60,264 characters—roughly 60-70% reduction across the board.
The project CLAUDE.md actually compressed even more aggressively at 74%, because the table format was extremely verbose relative to what it communicated. The global CLAUDE.md compressed less (36%) because it was already fairly concise—mostly procedural instructions without much decoration.
Token savings track closely to character savings here since the content is mostly natural language. If you're working with a memory system or large instruction set, that's a meaningful chunk of context budget freed up for actual work.
The Tradeoff
These files are harder for humans to read now. There's no getting around that. Compact notation is fast to parse programmatically but slower to scan with your eyes.
But here's the thing: how often do you actually read these files yourself? In my workflow, Claude reads them at session start and Claude updates them at session end. I review them occasionally to audit for context rot (which you should be doing regardless), but day-to-day, they're machine-to-machine communication. Optimizing them for machine readability is just… correct.
If you're in a workflow where you're frequently hand-editing your CLAUDE.md, more aggressive compression might not be worth it. But if Claude is the primary reader and writer, compress away.
How to Apply This Yourself
- Audit first. Before compressing, audit your CLAUDE.md for context rot. Remove anything outdated or no longer relevant. This alone might save you 20-30%.
- Identify decoration. Look for markdown headers, bold/italic, horizontal rules, table alignment rows, and "when to read" hints. These are the low-hanging fruit.
- Collapse prose to notation. Any sentence that can be expressed as a key-value pair or pipe-delimited list should be. If you're writing "The following directory contains project artifacts for…" just write
projects/=project artifacts. - Deduplicate. If the same context appears in your global CLAUDE.md, project CLAUDE.md, and a memory file, pick one canonical location and remove the rest.
- Test it. After compressing, run a few sessions and verify Claude still behaves correctly. If it misinterprets a compressed instruction, expand just that part back out. Some instructions genuinely need prose for disambiguation.
- Keep auditing. Compression doesn't prevent context rot. Set a cadence—weekly or biweekly—to review your instruction files for stale content.
The Bigger Picture
This is a small optimization in isolation. But if you're serious about using Claude Code as a daily tool, these small optimizations compound. A leaner system prompt means more room for conversation context, which means Claude maintains coherence longer in extended sessions. It means your instructions are processed faster and with less noise.
And honestly, thinking about what your AI tools actually need versus what you're giving them out of habit is just good engineering practice. We don't put comments in machine code. We don't add pretty-printing to wire protocols. CLAUDE.md is a machine-readable instruction set that happens to be stored in a human-readable format. Treating it that way is a mindset shift worth making.
Need help optimizing your AI-assisted engineering workflow?
I help teams build production-grade systems with AI tooling, from code audits to infrastructure automation. Get a free assessment to see where your workflow can improve.