The day CLAUDE.md hit 1,300 lines, I thought I was being thorough.
Everything was in there. Every project quirk, every API convention, every behavior I didn't want the AI to get wrong — all of it, stuffed in. The logic felt obvious: more information means better performance. Complete is better than incomplete.
The result was an AI that gave me increasingly vague answers. It knew everything and executed nothing precisely. Like an employee who memorized every document in the company filing system but couldn't decide what to do next because the signal was buried in noise.
I cut CLAUDE.md to 300 lines. Things got better.
It took me a long time to really understand why.
The Wrong Mental Model
Most people — including me, six months ago — treat CLAUDE.md as an instruction manual.
The instruction manual logic goes: the more detail, the better. If you want the AI to know something, write it in. This intuition is sensible because that's how we think about documentation — more complete documentation produces better-informed readers.
The problem is that AI attention isn't unlimited. Every conversation loads the full text of CLAUDE.md. The longer that file is, the less attention any single rule receives. In a 1,300-line document, the five rules you consider most important compete for weight against the detail on line 1,200, and the gap is smaller than you'd expect.
The right mental model is: CLAUDE.md is a corporate charter, not an employee handbook.
The charter hangs on the office wall. Everyone can see it. But it only contains the fundamental things — the company's purpose, the non-negotiable principles, the highest-level decision constraints. Procedures, workflows, situational SOPs live somewhere else.
The charter is short because it only needs to be short.
Anthropic's Six-Layer Framework
Late last year, Anthropic published a post describing the agent architecture they built into Claude Code. Around the same time, Tw93 put together a detailed usage handbook. When I read both, I had a strange feeling — the system I'd spent six months building through trial and error, they'd described in a single framework.
The six layers work like this:
Layer 1: CLAUDE.md Always loaded, never called explicitly. It's the highest-level ruleset. It should be short, and every line should address something the AI gets wrong without any prompt.
Layer 2: Rules (path-specific) Rules that load automatically based on the current working directory. Different subdirectories, different rule sets. This prevents you from cramming every context's requirements into the root-level CLAUDE.md.
Layer 3: Skills On-demand SOPs. The AI reads them when needed and they don't consume attention otherwise. A skill might be "how to handle a database migration" or "how to file a PR." It expands fully when invoked and waits silently when not.
Layer 4: Hooks Deterministic control that doesn't depend on model judgment. Hooks execute automatically at specific events — before a commit, before a command, after a tool call. They don't ask the AI's opinion. They just run.
Layer 5: Agents Workers operating in isolated contexts. An agent is separate from the main conversation — it has its own task, its own workspace, its own context window. The main agent delegates to it and receives a report back.
Layer 6: Verifiers Post-execution checks that outputs match expectations. You assign a task, the verifier confirms the result meets spec.
These six layers aren't a stack. They're a separation of responsibilities. Each layer does its own job and nothing else.
The Company Governance Analogy
The framework clicked for me through a specific analogy: this is organizational governance.
Managing AI agents is the same problem as managing an organization.
CLAUDE.md = corporate charter. On the wall, always visible, containing the inviolable fundamentals. You don't write every operating procedure into the charter. You write the things that can't be negotiated.
Skill = SOP manual. Kept in a drawer, pulled out when relevant. There's a SOP for handling complaints, a SOP for shipping new features. You don't distribute it every morning to every employee. You hand it to the person who needs it in the moment they need it.
Agent = employee dispatched to work independently. You give them a task, define their scope of authority, and send them off. They have their own office (an isolated context). Communication with headquarters is a formal handoff, not constant surveillance.
Hook = compliance department. They don't ask your opinion. They run automatically. You try to push code, compliance runs a check, and the push only goes through if it passes. Their existence doesn't depend on anyone remembering to call them. They're just there.
The most valuable part of this analogy: Skill and Agent are peers, not a hierarchy.
Skill is not "lightweight Agent." Agent is not "advanced Skill." They solve different problems.
Skill solves: "I need the AI to reference a detailed procedure during a task, but I don't need context isolation." The task runs in the main conversation. Skill is the reference document it reads on demand.
Agent solves: "I need this task completely isolated — not polluting the main context, running in its own context window, reporting results when done."
Simple tasks: use a Skill. Tasks that need isolation: use an Agent. The deciding factor isn't complexity. It's whether the task needs its own workspace.
Building from Postmortems
My current system has 53 agents, 142 skills, and 34 hooks.
None of those numbers were planned upfront. Most of them grew from failures.
Incident one: I let the main agent investigate a bug directly. It read a lot of code, spent ten minutes, generated a thorough analysis, and never opened a browser. I opened the browser in thirty seconds and saw the problem immediately. The AI spent ten minutes without finding what a thirty-second visual check revealed.
This told me: bug investigation is a task that needs isolated execution with a fixed procedure. It should be an Agent paired with a Skill (the debug SOP). The main agent's job is to hand off the task, not investigate it.
CLAUDE.md now has one rule: any bug investigation must spawn the bug-fixer agent, no exceptions. That rule exists because without it, the AI does the wrong thing. Not sometimes. Reliably.
Incident two: A feature change landed directly on the main branch — no feature branch, no PR, no staging validation, straight to production. The AI didn't do anything technically wrong. I had never told it not to do this. The absence of a rule was the instruction.
This incident produced a Hook: before any commit, automatically check whether the current branch is main. If yes, intercept. This hook doesn't depend on the AI remembering a rule. It doesn't depend on some line in CLAUDE.md getting enough attention. It just runs.
CLAUDE.md Only Captures What AI Gets Wrong
This is the principle I eventually realized matters most.
CLAUDE.md is not a knowledge base. Your API documentation doesn't belong there. Your architecture overview doesn't belong there. That information is important, but it belongs in Skills, loaded on demand.
CLAUDE.md contains exactly one category of content: behaviors you've observed the AI performing that you don't want, when given no specific instruction to the contrary.
Not "things the AI might get wrong." Things the AI has actually already gotten wrong.
Every rule in CLAUDE.md has a specific failure behind it. It's not preventive guidance. It's after-the-fact correction. This is also why it should be short — the patterns of repeated, consistent error are limited in number, but every one of them must be there.
This Is a Systems Design Problem, Not a Prompt Engineering Problem
Most content about making AI perform better is about prompting. Change the phrasing. Add chain-of-thought. Open with a role definition. These techniques work at the conversation level.
But when you're managing not a single conversation but months of continuous work across multiple projects and dozens of agents, the problem changes. It becomes a systems design problem: how do you keep rules in effect when no one is watching? How do you make sure an AI working independently doesn't exceed its authorized scope? How do you ensure that five hundred small decisions don't accumulate into something that drifts from your intent?
The answers to those questions aren't in prompts. They're in architecture.
The character limit on CLAUDE.md is architecture. The on-demand loading of Skills is architecture. The deterministic execution of Hooks is architecture. The context isolation of Agents is architecture.
The way I evaluate CLAUDE.md now: if I read it a month from now, every line should remind me of a specific failure. If there's a line I can't connect to a concrete incident, it probably shouldn't be there.
References
- Anthropic: Equipping agents for the real world with agent skills
- Tw93: My Claude Usage Handbook
- Claude Code: Skills Documentation
Building something similar, or just starting to organize your own AI workflow? Let's talk.