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.
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
This is gold. I've been using Claude for client automation workflows but never structured my CLAUDE.md files properly. Just the hooks section alone is a game-changer for building context-aware agents.
The part about subagents is exactly what I need for my B2B lead gen automation - breaking complex workflows into smaller, focused agents with clear contexts.
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.
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.
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
I started using subfolders in Claude. Adding agents and commands. Using hooks to make sure dangerous terminal commands can’t be used.
This is gold. I've been using Claude for client automation workflows but never structured my CLAUDE.md files properly. Just the hooks section alone is a game-changer for building context-aware agents.
The part about subagents is exactly what I need for my B2B lead gen automation - breaking complex workflows into smaller, focused agents with clear contexts.
Thanks for the detailed walkthrough!
Love it, thanks for sharing. What’s your view on the update-claude-md plugin?
good read
In thr noise around claude code this is best read. Great work
https://open.substack.com/pub/cataklaus/p/apple-earnings-were-a-non-event?r=2k77a7&utm_medium=ios&shareImageVariant=overlay
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.
This looks like a comprehensive guide for mastering Claude. Thanks for sharing.