CLAUDE.md Design Patterns: Scopes, Size Templates, Anti-Bloat

The more you use Claude Code day to day, the more expensive it becomes to restate the same project rules and commands in every chat. CLAUDE.md is the durable place for those instructions.

📑Table of Contents

1. What CLAUDE.md Is For (User / Project / Local)
2. Choose a Scale Template and Run the Day-One Checklist
3. Monorepo Hierarchy Pattern
4. Keep It Short: Size Guidance and Prune Criteria
5. Skills vs Always-On Rules
6. Antipatterns and Size Heuristics
7. FAQ
8. Summary — What to Do Today

Anthropic’s Memory docs describe it as persistent project guidance loaded across sessions—not as model retraining.

Common failure mode

The failure mode is also familiar:

• dump everything into one file
• watch it bloat and lose instruction adherence
• in monorepos, pay context cost for unrelated rules on every session

---

What this guide covers

This article rebuilds practical design patterns from official scopes and best practices, then covers monorepo hierarchy, skills vs always-on rules, prune criteria, and a day-one checklist.

---

What CLAUDE.md Is For (User / Project / Local)

Treat CLAUDE.md as persistent context that reduces repeated prompting. Official Memory documentation splits placement by sharing boundary:

Scope table and sharing boundary

Scope	Typical path	Shared with	Use for
Managed policy	OS-managed paths	Organization	Company standards and compliance
User	~/.claude/CLAUDE.md	You only	Personal defaults across projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team via git	Stack, conventions, shared workflow
Local	./CLAUDE.local.md	You (usually gitignored)	Private URLs and test fixtures

Source: Anthropic Claude Code Memory (as of July 2026)

---

Load order and monorepo asymmetry

• Parents above the working directory load at startup
• Child-directory CLAUDE.md files are added on demand when work touches files under that subtree

That asymmetry is why monorepos should stay thin at the root and local at the package.

---

Context vs enforcement

Critical boundary: CLAUDE.md is context, not enforced configuration.

• Writing “never do X” does not hard-block the tool
• For non-skippable control, use mechanisms such as PreToolUse hooks

---

Choose a Scale Template and Run the Day-One Checklist

Copy-pasting one mega template into every repo creates either over-engineering or under-specification.

Minimum set by scale

• Personal scripts: overview, stack, run/test commands only.
• Mid-size web apps: directory ownership, dependency direction, hard don’ts, main commands.
• Monorepos: root holds cross-cutting policy and pointers; package-local files hold local rules.

---

Day-one checklist (~15 minutes)

• ✓ Project overview (1–2 lines)
• ✓ Tech stack
• ✓ Directory ownership (mid-size+)
• ✓ Dependency / package boundaries when relevant
• ✓ Only verifiable coding rules (indent, naming, forbidden APIs)
• ✓ Explicit don’ts
• ✓ build / test / run commands
• ✓ Hierarchy decision for monorepos

---

Verify after placement

Then open a fresh session and verify the rules actually apply. Placement and hierarchy mistakes are a common reason “we wrote it, but nothing changed.”

For how CLAUDE.md fits the broader harness (model, inner loop, external config), see What the Claude Code harness is.

---

Monorepo Hierarchy Pattern

Failure modes of a root mega-file

A single root mega-file usually fails in three ways:

1. Session-wide context cost
2. Relevance dilution
3. Merge pain across teams

Independent guidance recommends:

• a thin root (cross-cutting policy, branch protection, pointers)
• package-local rules
• package-scoped commands such as pnpm --filter @app/api test

See the Claude Fast subdirectory guide.

---

Split signal

A practical split signal: when the root starts accumulating “if you are working in packages/api…” conditionals, split.

---

Official alignment

Official behavior matches the pattern:

• Parent full-load, child on-demand
• Oversized topic procedures can move into path-scoped .claude/rules/ or skills
• Unrelated ancestor files can be filtered with claudeMdExcludes where appropriate

---

Keep It Short: Size Guidance and Prune Criteria

Token cost vs adherence

Because CLAUDE.md is loaded early every session, length trades directly against token cost and adherence.

Anthropic Engineering’s best practices say (Claude Code best practices):

• Keep only non-inferable, broadly useful rules
• Prune with: “Would removing this cause Claude to make mistakes?” If no, delete it

Memory docs target under 200 lines per file, moving long procedures to rules/skills.

---

Verifiable instructions and imports

Prefer verifiable instructions (run npm test before commit, 2-space indent) over vague wishes (write clean code).

@path imports help organize files, but imported content still expands at launch—so imports are not a free context win.

---

Progressive disclosure and ignore risk

HumanLayer emphasizes progressive disclosure and the ignore risk of oversized, low-relevance instruction lists.

It also includes a sub-60-line root example as a practical anchor (Writing a good CLAUDE.md).

---

Skills vs Always-On Rules

Role split by mechanism

Mechanism	Loading	Best for
CLAUDE.md	Mostly always-on	Rules that must be true on every edit
Skill	On-demand by task type	Multi-step review/generation playbooks
Hook	Non-skippable	Safety stops that must not be optional

Source: Hamid Shoja on dev.to, Anthropic Memory (July 2026)

Source

---

Single source of truth and doc verification

A durable hygiene rule: every fact lives in exactly one file; everything else links.

• When a mode-specific procedure grows past a few lines, move it to a skill (or a linked doc)
• Leave a short pointer in CLAUDE.md
• Verify docs like code—broken example paths create expensive debug loops

For skill authoring detail, see How to write Claude Code Skills. For repository-driven setup of hooks/skills, see the Claude Code Setup plugin.

---

Antipatterns and Size Heuristics

Antipattern	Symptom	Fix
Everything file	300+ line single doc	Hierarchy + rules/skills
Append-only history	Contradictory rules coexist	Scheduled prune
Huge code pastes	Samples dominate the file	Minimal example + file:line refs
Wish list	Unverifiable abstractions	Replace with testable rules
Secrets in-repo	Keys/passwords in markdown	Env var names only

Use the official under-200-line guidance as a warning threshold and bias shorter. Over-specified CLAUDE.md files are a documented failure mode: large instruction sets get partially ignored.

---

FAQ

Q1. If I ban an action in CLAUDE.md, is it hard-blocked?

No. CLAUDE.md is context. Use hooks (for example PreToolUse) for enforcement (Memory docs).

---

Q2. When root and package files both exist, which wins?

They are composed, not simply overridden. Closer files tend to load later, but conflict priority is not a guaranteed precedence system—remove contradictions.

---

Q3. Is AGENTS.md enough by itself?

Claude Code’s primary file is CLAUDE.md. Share existing AGENTS.md via @AGENTS.md import or a symlink from CLAUDE.md.

---

Q4. What length is a danger signal?

Official guidance is under 200 lines per file. Past that, expect weaker adherence and split/prune.

---

Summary — What to Do Today

CLAUDE.md is not a dump of everything the model might need. It is the minimum shared premise for every session.

1. Decide User / Project / Local placement
2. Write a minimal version under 200 lines with verifiable rules and don’ts
3. For monorepos, keep the root thin and localize packages
4. Verify in a fresh session
5. Move growing task playbooks to skills/rules; prune weekly

If you also need execution isolation decisions, pair this with Choosing sandboxes for Claude Code and Codex.

Related articles:

• 13580
• 13621
• 13623