Fair point — headers do carry semantic meaning for section navigation, especially in longer files. My experience was that removing them didn't change behavior noticeably, but I was working with fairly flat files. If your CLAUDE.md has deep nesting where heading hierarchy actually matters for context, keeping them makes sense. The table compression is probably the higher-ROI change for most people regardless.
I've found that maintaining minimal structural cues (typically a single repeating heading) in Claude.md helps it better index information. And anecdotally a lot less GREP'ing, web searching and wasted tokens.
I also include a short instruction a the top of my file. Requiring context to be written as single line rationales with up to 1 additional line for links/refs/pointers. While explicitly forbidding "tutorial-like" explanations and blocks/pages of code.
The single repeating heading as an index anchor is a smart middle ground — keeps structure without the full markdown overhead. The "single line rationale, no tutorial explanations" constraint is interesting, that's essentially forcing the same signal-over-noise discipline at the instruction level rather than just the formatting level. I might steal that.
It looks like Claude tokenizer handles markdown pretty efficiently, like a ## header is like 1-2 tokens. So I think the actual token savings are smaller than the byte-level numbers suggest. Where this actually matters is if maybe if you're on Haiku with big codebases where system prompt and context fight for space. On Opus? Probably not worth making your files unreadable for humans?
Good callout on the tokenizer — I was measuring character reduction, not actual token savings, so the real gains are smaller than the headline numbers suggest. You're right that this matters most at the edges: Haiku, large codebases, or heavy memory systems where the context budget is genuinely tight. On Opus with a simple project CLAUDE.md it's probably not worth the readability hit.
>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.
That's not a problem. You can have the full version for you, and "compress" programmatically the claude-bound version before claude reads it.
This is the cleaner solution honestly. Keep the human-readable version as source of truth, generate the compressed version as a build step. I've been doing it manually but automating that transform is the obvious next evolution. Might be worth a follow-up post.
Curious if others have experimented with this — I found the memory system files compressed more aggressively than the project CLAUDE.md because they had more prose decoration. Anyone tried a middle ground where you keep human-readable formatting in the project file but compress the memory files only?
> Strip markdown decoration: Headers (##), bold (*), italic (*), horizontal rules (---). These are visual aids Claude doesn't need.
In my experience, LLMs do understand header levels in markdown. So removing these is detrimental.
---
> Compress table formatting: Markdown tables with alignment rows and padding are verbose for what they communicate.
This is a good idea imo.
Fair point — headers do carry semantic meaning for section navigation, especially in longer files. My experience was that removing them didn't change behavior noticeably, but I was working with fairly flat files. If your CLAUDE.md has deep nesting where heading hierarchy actually matters for context, keeping them makes sense. The table compression is probably the higher-ROI change for most people regardless.
I've found that maintaining minimal structural cues (typically a single repeating heading) in Claude.md helps it better index information. And anecdotally a lot less GREP'ing, web searching and wasted tokens.
I also include a short instruction a the top of my file. Requiring context to be written as single line rationales with up to 1 additional line for links/refs/pointers. While explicitly forbidding "tutorial-like" explanations and blocks/pages of code.
The single repeating heading as an index anchor is a smart middle ground — keeps structure without the full markdown overhead. The "single line rationale, no tutorial explanations" constraint is interesting, that's essentially forcing the same signal-over-noise discipline at the instruction level rather than just the formatting level. I might steal that.
It looks like Claude tokenizer handles markdown pretty efficiently, like a ## header is like 1-2 tokens. So I think the actual token savings are smaller than the byte-level numbers suggest. Where this actually matters is if maybe if you're on Haiku with big codebases where system prompt and context fight for space. On Opus? Probably not worth making your files unreadable for humans?
Good callout on the tokenizer — I was measuring character reduction, not actual token savings, so the real gains are smaller than the headline numbers suggest. You're right that this matters most at the edges: Haiku, large codebases, or heavy memory systems where the context budget is genuinely tight. On Opus with a simple project CLAUDE.md it's probably not worth the readability hit.
>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.
That's not a problem. You can have the full version for you, and "compress" programmatically the claude-bound version before claude reads it.
This is the cleaner solution honestly. Keep the human-readable version as source of truth, generate the compressed version as a build step. I've been doing it manually but automating that transform is the obvious next evolution. Might be worth a follow-up post.
Curious if others have experimented with this — I found the memory system files compressed more aggressively than the project CLAUDE.md because they had more prose decoration. Anyone tried a middle ground where you keep human-readable formatting in the project file but compress the memory files only?
[dead]