How to Build a CLAUDE.md Template Your Whole Business Can Use

A CLAUDE.md file with 500 lines of rules gets read at the start of every session and followed less than half the time. The same project, trimmed to 150 lines and paired with three enforced hooks, runs closer to 100 percent compliance. That gap is the one most teams walk straight into when they treat CLAUDE.md as a wiki for their AI.

Why teams write one in the first place is reasonable. Claude opens fresh on every session, with no memory of the previous conversation, the team's naming conventions, the glossary, or the rules that took six months of trial and error to nail down. A persistent context file fixes that. The trouble is almost never the idea. The trouble is what gets put in it.

Why CLAUDE.md Usually Gets Ignored

Anthropic's official documentation calls CLAUDE.md advisory context. In practice that means somewhere between 60 and 80 percent compliance on a good day, depending on how full the context window is at the moment Claude tries to remember the rule. HumanLayer's writeup on the topic puts the failure mode plainly: most files are too long, too vague, and full of advice Claude would have followed on its own.

A second mechanism amplifies the problem. Datadog's 2026 State of AI Engineering report found that 69 percent of all input tokens in production traces are spent on system prompts, instructions, policies, and tool descriptions repeated on every call. Every line in CLAUDE.md ships on every call. As the context fills with code and conversation, the model biases toward what sits at the very beginning and the very end and quietly drops attention from the middle. The 300 line ceiling cited in Blink's template guidance is not arbitrary. It is the rough edge where reliability starts to fall off a cliff.

The third reason is more boring. Most CLAUDE.md files are written once, never edited, and never measured. They accumulate aspirational rules like 'be concise' or 'think carefully' that Claude already does, and lose the specific business rules ('the V2 dashboard is the one in production', 'never call this client by first name in writing') that actually move the output.

The 150 Line Editorial Budget

Treat the file like an editor's brief, not a knowledge base. Every line earns its slot. The four sections that consistently justify themselves:

Voice and tone rules. Things Claude will get wrong without explicit instruction. 'Write in present tense. Use you not the user. Cap paragraphs at three sentences. Lead with the most surprising number, not the setup.' Short, imperative, and verifiable.

Glossary. Internal product names, customer segments, abbreviations. What MQL means in your funnel. What the V2 dashboard refers to. Which client gets called by their first name and which does not. This is the section that pays back every time a new team member or a new Claude session starts.

Do not list. Five to ten short rules of what never to do. 'Never publish without a Friday review.' 'Never use em dashes in customer copy.' 'Never assume pricing, always check /docs/pricing.md.' Negative rules are easier to enforce in advisory text than positive ones, because Claude is checking a single condition rather than producing the right thing from scratch.

Source of truth links. Pointers to where the real data lives. Pricing in one file. ICP definitions in Airtable. Brand voice in a separate skill. The file's job is not to contain the answers; it is to send Claude to the right place to find them.

What does not earn its place is anything Claude already does correctly. Restating model behavior, padding with 'always think before you act', or duplicating what a sensible directory structure already shows. Anthropic's own best practices page recommends running /init first to scaffold from the actual codebase, then trimming hard.

Where CLAUDE.md Stops and Hooks Start

The rules a team genuinely cannot afford to have followed only 70 percent of the time do not belong in CLAUDE.md at all. They belong in hooks.

A hook is code that runs before or after a Claude action, outside the model's reasoning chain. A March 2026 analysis by Christopher Montes measured prompt-based rules at 70 to 90 percent compliance and hooks at 100 percent. The phrasing that stuck: rules in prompts are requests, rules in code are laws.

A workable split for a business team looks like this. CLAUDE.md handles style, glossary, naming conventions, voice rules, and the do not list. These are rules where occasional drift is acceptable and easy to spot in review. Hooks handle anything destructive, expensive, or compliance-critical. Blocking pushes to main. Requiring a human review step before sending a customer email. Running a linter or typecheck before commit. Refusing to call certain APIs in certain environments. The kind of rule that, if Claude ignores it 30 percent of the time, ends the experiment.

This separation is what keeps CLAUDE.md short. Once the genuinely critical rules move to hooks, the file no longer carries the weight of being right every time. It becomes what it should have been: an editorial brief.

The Open Standard Question

A team adopting Claude in 2026 also has to make a call about AGENTS.md. AGENTS.md is an open, tool-agnostic instruction standard developed by Sourcegraph, OpenAI, Google, Cursor, and Factory, and is now stewarded by the Linux Foundation. Adoption sits past 60,000 repositories, including projects like n8n and LangFlow.

Claude Code does not read AGENTS.md by default. The cleanest pattern for a multi-tool team is AGENTS.md as the shared source of truth (read by Cursor, Codex, Copilot, Gemini) with a short CLAUDE.md that imports it for Claude-specific layering like hooks and skill references. If the only AI in the workflow is Claude, this complexity is unnecessary and CLAUDE.md alone is enough. The decision should be driven by which tools the team actually uses, not by which standard is currently winning the GitHub star race.

A Starting Template That Holds Up

The version most agencies running production workloads on Claude converge on, after the third or fourth rewrite, breaks down like this. 10 to 30 lines at the top for project purpose, stack, and key directories. 20 to 40 lines for voice and tone rules. 20 to 40 lines for the glossary and naming. 10 to 20 lines for the do not list. 10 to 30 lines for source of truth links. 5 to 10 lines for how to handle unknowns: when to ask, when to web search, when to stop and flag.

Total: 75 to 170 lines. The 200 line mark is a soft ceiling, not a target. Files closer to 100 lines often outperform 200 line files because the signal-to-noise ratio stays high. The first test for any new line is whether Claude would have made the mistake without it. If the answer is no, the line is noise dressed up as instruction.

One more discipline matters more than the structure: edit the file when the team learns something. A CLAUDE.md that ships in month one and is never touched again is the same as no CLAUDE.md by month six. The compounding value is in the editing, not in the writing.

The Practical Reframe

The instinct to write down everything a team knows is correct. The instinct to put it all in CLAUDE.md is not. A working CLAUDE.md is an editorial document with a hard budget, paired with hooks that enforce the rules that cannot move. Teams that treat it that way get the persistent context they wanted. Teams that treat it as a wiki end up with the same blank-session problem they thought they had solved, plus the cost of having written the wiki.