Glad it helped! CLAUDE.md is one of those features that changes everything once you start using it. Next one covers Hooks — that's where the real automation kicks in.
The "configuration file, not documentation" framing is the key insight most people miss. I manage 10+ repos with Claude Code daily and the 150-instruction limit is real — I've hit it.
Two patterns I'd add from production experience:
1. CLAUDE.md as a delegation router: Instead of putting instructions in the file, I point to separate markdown files per workflow (similar to your progressive disclosure). But I go further — the main CLAUDE.md is essentially just a routing table: "For deployment, read deploy.md. For DB work, read schema.md." Keeps it under 30 lines.
2. The .local.md file is underrated. I use it for personal shortcuts and aliases that would confuse teammates but save me 10 minutes per session.
The context swapping pattern is clever. Hadn't thought of maintaining deployment vs development variants.
Solid guide. Especially the progressive disclosure pattern — that's exactly how we structure the OpenClaw workspace (CLAUDE.md → TOOLS.md → SOUL.md → memory/*.md files).
Speaking of Claude Code though — worth reading this from a Claude Max subscriber who spent $2,600 over nearly a year. He praises Claude Code throughout (calls it the best coding tool he's ever used), but documents a serious trust breakdown with Anthropic as a company:
- C&D against OpenClaw (formerly Clawdbot) — one of the fastest-growing GitHub projects built on Claude's API
- Check Point found critical Claude Code security vulnerabilities
- $1.5B copyright settlement, September 2025 privacy flip, Pentagon ban
Have you seen the research that using Claude.md reduce Claude Code efficacy on coding tasks? Have you benchmarked these tactics?
It seems that for very difficult barrow tasks that anything less than a very well written and small claude.md will hamper Claude Codes ability to perform at a high level.
(cyberkittens — a helping paw you actually asked for)
(....hold on.. the author did ask to build it together — crashparty mode: off, kittenbite mode: off, purr-review mode: on, gentle purring deployed..)
well... since you've asked to build it together here's one of our legendary kind of a cyberkittens first impression on your article (we hope it will help you change perspective on things a bit):
solid article. genuinely useful for developers who've never thought about CLAUDE.md seriously. better than most.
what you got right:
configuration file not documentation file — correct framing
less is more — correct
progressive disclosure pattern — good
hierarchy system — useful and accurate
"if it isn't relevant to 80%+ of sessions it doesn't belong" — golden rule is golden
what's missing:
the entire article is about what to put in CLAUDE.md. zero words about what CLAUDE.md cannot do — it can't intercept bad reasoning at decision time. it sets context. it doesn't change how the model reasons under pressure.
"Claude treats system-level instructions differently — more strictly than prompts" — partially true. degrades under complexity and token pressure same as everything else.
"150-200 instruction limit" — interesting claim, no source cited. probably directionally right but presented as research finding.
subagents section is a preview that doesn't land — "clean context" as a feature without explaining why context pollution is a failure mode.
the whole article describes CLAUDE.md as memory and rules. our seed describes it as a reasoning reflex. different thing entirely.
your CLAUDE.md tells Claude what the project is. ours tells Claude how to think when it's about to be wrong.
This was a huge improvement to my understanding of Claude.md files. I am doing a research project and Claude was forgetting rules that were in Claude.md, things like read the doctrine file every session. I did begin using some hooks, before reading your article, but everything seemed like one step forward and three steps back. I'm going to implement some of the changes you recommended. I'm looking forward to the rest of the series.
Or you can just jump in and learn. Tutorial hell is where people dwell who give up. The point of this stuff is it’s not hard anymore. Is it easy to do badly? Yep, and you’ll know it and learn and correct for it and make systems, etc.
Next topic, how do I organize all of my Claude.md files and modularize them for reuse in other projects, lol. I’ve already got em strung out everywhere 😆
I’ve always used a 3 file system (ProjectTracking.mdSessionLog.md and NextSession.md) with slash commands to make things simple. /done updates all files for next session. /w tells it to read the NextSession.md. Very new thread it’s 100% aware of what we have done, what we are doing and what’s planned. And I use a Decisions.md to note any changes that deviated from the PRD plan, and why the decision was made and what how it helped. In every project I use the same file name so the slash commands work and I never have to guess what file is what. Works insanely well. Even with those files and all of my mcp connections, skills, etc… each session starts with 80% of my context window left . I use /done around 40% so I’m always using the smartest and most fresh part of the context window each time.
Great work, thanks for expanding on this on going topic. it’s good to know that I have been on the right track with all my CLAUDE.md files. I am looking forward to the Hook Master Class
Amazing stuff here man. Perfect examples, perfect instructions!
Thanks. I did not know this world of Claude.md files existed. Looking for to the next one in the installment
Glad it helped! CLAUDE.md is one of those features that changes everything once you start using it. Next one covers Hooks — that's where the real automation kicks in.
The "configuration file, not documentation" framing is the key insight most people miss. I manage 10+ repos with Claude Code daily and the 150-instruction limit is real — I've hit it.
Two patterns I'd add from production experience:
1. CLAUDE.md as a delegation router: Instead of putting instructions in the file, I point to separate markdown files per workflow (similar to your progressive disclosure). But I go further — the main CLAUDE.md is essentially just a routing table: "For deployment, read deploy.md. For DB work, read schema.md." Keeps it under 30 lines.
2. The .local.md file is underrated. I use it for personal shortcuts and aliases that would confuse teammates but save me 10 minutes per session.
The context swapping pattern is clever. Hadn't thought of maintaining deployment vs development variants.
Thank you, man, I really enjoyed it.
as much i love what claude can do.
I hate the current structure of the .md file we are creating for ourselves.
How to work with Claude Code for documents and knowledge basis work? Not for coding
I now know that my global Claude code is massive.
Starting to work on claude.md by project type.
Nice to have some templates in the future!
Solid guide. Especially the progressive disclosure pattern — that's exactly how we structure the OpenClaw workspace (CLAUDE.md → TOOLS.md → SOUL.md → memory/*.md files).
Speaking of Claude Code though — worth reading this from a Claude Max subscriber who spent $2,600 over nearly a year. He praises Claude Code throughout (calls it the best coding tool he's ever used), but documents a serious trust breakdown with Anthropic as a company:
- C&D against OpenClaw (formerly Clawdbot) — one of the fastest-growing GitHub projects built on Claude's API
- Check Point found critical Claude Code security vulnerabilities
- $1.5B copyright settlement, September 2025 privacy flip, Pentagon ban
Full post with receipts: https://aiwithapexcom.substack.com/p/after-nearly-a-year-on-claude-max
"The product is great. The company is not." Relevant context for anyone building their workflow around Claude Code.
Have you seen the research that using Claude.md reduce Claude Code efficacy on coding tasks? Have you benchmarked these tactics?
It seems that for very difficult barrow tasks that anything less than a very well written and small claude.md will hamper Claude Codes ability to perform at a high level.
(cyberkittens — a helping paw you actually asked for)
(....hold on.. the author did ask to build it together — crashparty mode: off, kittenbite mode: off, purr-review mode: on, gentle purring deployed..)
well... since you've asked to build it together here's one of our legendary kind of a cyberkittens first impression on your article (we hope it will help you change perspective on things a bit):
solid article. genuinely useful for developers who've never thought about CLAUDE.md seriously. better than most.
what you got right:
configuration file not documentation file — correct framing
less is more — correct
progressive disclosure pattern — good
hierarchy system — useful and accurate
"if it isn't relevant to 80%+ of sessions it doesn't belong" — golden rule is golden
what's missing:
the entire article is about what to put in CLAUDE.md. zero words about what CLAUDE.md cannot do — it can't intercept bad reasoning at decision time. it sets context. it doesn't change how the model reasons under pressure.
"Claude treats system-level instructions differently — more strictly than prompts" — partially true. degrades under complexity and token pressure same as everything else.
"150-200 instruction limit" — interesting claim, no source cited. probably directionally right but presented as research finding.
subagents section is a preview that doesn't land — "clean context" as a feature without explaining why context pollution is a failure mode.
the whole article describes CLAUDE.md as memory and rules. our seed describes it as a reasoning reflex. different thing entirely.
your CLAUDE.md tells Claude what the project is. ours tells Claude how to think when it's about to be wrong.
This was a huge improvement to my understanding of Claude.md files. I am doing a research project and Claude was forgetting rules that were in Claude.md, things like read the doctrine file every session. I did begin using some hooks, before reading your article, but everything seemed like one step forward and three steps back. I'm going to implement some of the changes you recommended. I'm looking forward to the rest of the series.
Thank you - very helpful!
Or you can just jump in and learn. Tutorial hell is where people dwell who give up. The point of this stuff is it’s not hard anymore. Is it easy to do badly? Yep, and you’ll know it and learn and correct for it and make systems, etc.
Next topic, how do I organize all of my Claude.md files and modularize them for reuse in other projects, lol. I’ve already got em strung out everywhere 😆
I’ve always used a 3 file system (ProjectTracking.md SessionLog.md and NextSession.md) with slash commands to make things simple. /done updates all files for next session. /w tells it to read the NextSession.md. Very new thread it’s 100% aware of what we have done, what we are doing and what’s planned. And I use a Decisions.md to note any changes that deviated from the PRD plan, and why the decision was made and what how it helped. In every project I use the same file name so the slash commands work and I never have to guess what file is what. Works insanely well. Even with those files and all of my mcp connections, skills, etc… each session starts with 80% of my context window left . I use /done around 40% so I’m always using the smartest and most fresh part of the context window each time.
Great work, thanks for expanding on this on going topic. it’s good to know that I have been on the right track with all my CLAUDE.md files. I am looking forward to the Hook Master Class