The conditional loading point is what most people miss. I went through a similar evolution with my agent's instruction file - started as one growing http://CLAUDE.md that hit 800+ lines before I realized the problem wasn't length but specificity.
What worked for me was a different split than pure file paths: behavioral rules in the base file (what the agent always needs), domain workflows as skills (loaded on demand), and a self-extending memory layer the agent manages itself.
The base file stayed under 200 lines. Skills handle the rest. Token cost dropped and consistency went up because the agent only loads what's relevant.
Read your full breakdown. The lean-core-plus-reference-docs pattern is interesting — you're solving the same loading problem I'm solving with path-gated rules, but yours relies on agent judgment to decide what's relevant while mine triggers automatically on file patterns. Different trade-off: yours is more flexible, mine is deterministic. For a single-project agent that's probably the right call. I run three contexts in one environment, so I need the automatic routing.
On conflicts: no, because the tiers are additive. Core rules are context-agnostic — writing style, session mechanics, how to interpret requests. Context rules add domain knowledge the core doesn't touch. Different layers, not competing opinions. The only overlap risk would be between contexts, and path-gating prevents that — a file matches one context or the other, never both.
The self-extending pattern is the thing I don't have and keep thinking about. My commands and skills are all human-authored. Your agent flagging its own gaps and creating skills is a genuinely different philosophy — more autonomous evolution, less oversight. I'd probably want a lighter version: agent flags the gap, I approve the addition. But the continuous auto-learning on corrections is smart. Right now I batch that into session-close updates, which means a correction has to survive an entire session before it sticks.
Your "principle beats rule" stance is a good counterpoint to my hooks approach. I'd push back slightly — principles drift in long sessions, especially with context-specific constraints the model hasn't seen enough to internalize. That's where mechanical enforcement earns its keep. But for single-context work where you're iterating daily, principles are probably sufficient.
Side note: as an elder millennial I really dig the 8-bit cover art throughout your Substack :)
The conditional loading point is what most people miss. I went through a similar evolution with my agent's instruction file - started as one growing http://CLAUDE.md that hit 800+ lines before I realized the problem wasn't length but specificity.
What worked for me was a different split than pure file paths: behavioral rules in the base file (what the agent always needs), domain workflows as skills (loaded on demand), and a self-extending memory layer the agent manages itself.
The base file stayed under 200 lines. Skills handle the rest. Token cost dropped and consistency went up because the agent only loads what's relevant.
Full breakdown after 1000+ sessions of iterating on this: https://thoughts.jock.pl/p/how-i-structure-claude-md-after-1000-sessions
Curious - do your 27 files ever conflict with each other when multiple load at once?
Read your full breakdown. The lean-core-plus-reference-docs pattern is interesting — you're solving the same loading problem I'm solving with path-gated rules, but yours relies on agent judgment to decide what's relevant while mine triggers automatically on file patterns. Different trade-off: yours is more flexible, mine is deterministic. For a single-project agent that's probably the right call. I run three contexts in one environment, so I need the automatic routing.
On conflicts: no, because the tiers are additive. Core rules are context-agnostic — writing style, session mechanics, how to interpret requests. Context rules add domain knowledge the core doesn't touch. Different layers, not competing opinions. The only overlap risk would be between contexts, and path-gating prevents that — a file matches one context or the other, never both.
The self-extending pattern is the thing I don't have and keep thinking about. My commands and skills are all human-authored. Your agent flagging its own gaps and creating skills is a genuinely different philosophy — more autonomous evolution, less oversight. I'd probably want a lighter version: agent flags the gap, I approve the addition. But the continuous auto-learning on corrections is smart. Right now I batch that into session-close updates, which means a correction has to survive an entire session before it sticks.
Your "principle beats rule" stance is a good counterpoint to my hooks approach. I'd push back slightly — principles drift in long sessions, especially with context-specific constraints the model hasn't seen enough to internalize. That's where mechanical enforcement earns its keep. But for single-context work where you're iterating daily, principles are probably sufficient.
Side note: as an elder millennial I really dig the 8-bit cover art throughout your Substack :)
Thanks for thoughtful comment!
I am also millenial(91!) and I love pixel-art :D