What to Put in Your CLAUDE.md File in 2026: The Hierarchy Most Guides Miss

Your CLAUDE.md should contain project purpose and tech stack (2-4 sentences), exact build/test/lint commands, explicitly off-limits file paths, and @-pointers to detailed documentation — not inline style guides, linting rules, or personal preferences. Keep it under 200 lines. Everything else belongs in .claude/rules/ for scoped guidelines, hooks for deterministic actions, CLAUDE.local.md for personal preferences, or sub-docs pointed to by @-imports.

The most common advice about CLAUDE.md is "add your conventions so Claude remembers them." That framing produces 500-line files that degrade rather than improve performance. Claude doesn't read monolithic memory files like a human reads a spec — it loads and samples. Past roughly 300 lines, signal dilutes into noise, the model starts quietly skipping sections, and teams believe their context is comprehensive when the agent is already pattern-matching around it. Digital Applied, 2026 The highest-leverage CLAUDE.md files are mostly pointers, not content. The hierarchy is what most teams miss entirely.

The Four-Layer Hierarchy You're Probably Using Wrong

Claude Code loads CLAUDE.md from a precedence hierarchy, not just your project root. Anthropic — How Claude Remembers Your Project Understanding the layers changes what you put where:

Most guides treat the project layer as the only layer and ignore the rest. The right design:

• Managed layer → security policies, compliance reminders, org-wide coding standards deployed by IT
• User layer → your personal cross-project preferences (verbosity level, preferred explanations, shortcuts)
• Project layer → project-specific architecture decisions and build commands, shared with the team via git
• Subdirectory layer → module-specific conventions loaded only when Claude touches that directory

The subdirectory layer is the most underused. If you're writing 400 lines in your root CLAUDE.md to cover all your packages, you've picked the wrong layer. Move package-specific rules to packages/api/CLAUDE.md and packages/web/CLAUDE.md. The context window stays clean and scoped to whatever Claude is actually touching. Medium — Complete Guide to CLAUDE.md

What Belongs in a Root CLAUDE.md

After pruning, a production CLAUDE.md should have five categories of content and nothing else:

1. Project WHY and WHAT (2–4 sentences)

The model can read your code, but it cannot infer your product's strategic constraints. Why does this service exist? What are the non-obvious architectural decisions that govern every change?

``markdown # Project Overview Multi-tenant SaaS billing service for Acme Corp. Handles Stripe webhooks, usage-based metering, and invoice generation for 3,000 enterprise customers. All billing mutations must be idempotent — see @docs/idempotency.md for the pattern. ``

2. Exact build, test, and lint commands

Don't make Claude guess. Wrong commands waste tool-call rounds and sometimes break things.

``markdown # Commands - Build: pnpm build - Test: pnpm test (unit) | pnpm test:integration (needs Docker) - Lint: pnpm lint - Type check: pnpm tsc --noEmit ``

3. Explicitly off-limits paths

Claude Code's --worktree flag isolates changes to a branch, but the model also needs to know which files are human-only:

``markdown # Off-Limits Files - NEVER modify: prisma/migrations/ (hand-authored; use migration tooling) - NEVER modify: .env* files - NEVER modify: infra/terraform/ without explicit instruction ``

4. @-pointers to detailed docs

This is the most important pattern and the one most files get wrong. Anthropic's best practices guide is explicit: include the project overview inline, but for detailed conventions, use @-pointers to let Claude fetch them just-in-time. Anthropic's own context engineering research describes the principle: "CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow Claude to navigate its environment and retrieve files just-in-time, effectively bypassing the issues of stale indexing." The pointer tells Claude where to go when it needs the information; don't duplicate content upfront.

``markdown # Reference Docs - Authentication flow: @docs/auth-flow.md - API conventions: @docs/api-design.md - Error handling patterns: @docs/error-handling.md - Database schema: @prisma/schema.prisma ``

5. Compaction behavior instructions (optional but high-value)

When Claude Code hits context limits, it compacts the conversation. You can specify what to preserve:

``markdown # Compaction When compacting: always preserve the full list of files modified, open TODO items, and any test commands run with their outcomes. ``

What Doesn't Belong (and Where It Should Go)

Wrong content in CLAUDE.md doesn't just waste lines — it competes with correct content for attention. HumanLayer — Writing a Good CLAUDE.md

Linting rules → hooks

"Always run ESLint before committing" is the canonical example of an instruction that belongs in a hook, not CLAUDE.md. CLAUDE.md instructions are advisory — the model can and sometimes does skip them. Hooks are deterministic: they run on every trigger with zero exceptions. Anthropic best practices If it must happen every time, wire a hook. If it's a preference, CLAUDE.md is fine.

Scoped guidelines → `.claude/rules/`

Rules that only apply to specific file types belong in .claude/rules/ with path-scoped frontmatter, not in the root file:

``markdown --- paths: - "src/api/**.ts" --- # API Handler Conventions - Validate request bodies with Zod schemas - Return HTTP 422 for validation failures, not 400 - Log all auth failures with structuredLog('auth.failure', ...) ``

This rule loads only when Claude touches an API file. A developer working in the React frontend never sees it. Scoping at this level also makes rules easier to maintain — the team owns security conventions for src/api/ without those conventions polluting the experience in src/components/. Dometrain — Creating the Perfect CLAUDE.md

Personal preferences → `CLAUDE.local.md`

Your preference for verbose explanations, or your habit of requesting diffs before accepting edits, doesn't belong in the shared project file. Claude Code auto-gitignores CLAUDE.local.md, making it the correct location for personal preferences that would be noise for teammates. Builder.io — How to Write a Good CLAUDE.md

The Orchestrator Pattern: Pointers Beat Content at Scale

The teams reporting the best results at scale use what practitioners call the orchestrator pattern: the root file is almost entirely pointers, and actual content lives in linked sub-docs. BuildCamp — The Ultimate Guide to CLAUDE.md

The @-import syntax makes this concrete:

```markdown # Project Context @README.md

# Development Guide @docs/development.md

# Architecture Decisions @docs/adr/0001-database-choice.md @docs/adr/0012-auth-strategy.md ```

Claude reads the linked files when it needs them, not upfront. This keeps the context window clean for the actual task rather than loading every convention into memory at session start. A BuildCamp analysis of high-performing configurations found that orchestrator-style files "consistently outperform the monolithic version, even at identical total line counts" — the model handles small linked context far better than large blocks of inline text.

The linked structure also stays accurate longer. A doc file with a heading like @docs/api-design.md is maintained by whoever owns API conventions. The root CLAUDE.md just points to it. When conventions change, you update the doc, not the CLAUDE.md. Monolithic files decay fast because no one owns cleanup.

Where to Configure What: A Decision Matrix

This table synthesizes across all five Claude Code configuration surfaces. No single official doc consolidates this view:

The key column is advisory vs deterministic. CLAUDE.md is advisory — it informs Claude's behavior but doesn't guarantee it. If a rule must always run, it belongs in a hook. Piling enforcement rules into CLAUDE.md and then complaining that "Claude ignored my instructions" is the most common failure mode on community threads. HN thread 46098838

Runnable Example: A Minimal but Complete CLAUDE.md

```markdown # Acme Billing Service

TypeScript/Node.js billing microservice for enterprise SaaS. Handles Stripe webhooks, usage-based metering, and invoice generation. All billing mutations must be idempotent.

Commands - Build: pnpm build - Test (unit): pnpm test - Test (integration): pnpm test:integration (requires Docker) - Lint: pnpm lint - Type check: pnpm tsc --noEmit

Off-Limits - Never modify prisma/migrations/ directly — use migration tooling - Never modify .env* files

Reference Docs - Authentication: @docs/auth-flow.md - Error handling: @docs/error-handling.md - Billing mutations: @docs/idempotency.md

Compaction Preserve: all modified file paths, open TODOs, last test run results. ```

22 lines. Covers all five categories. Linting runs via a hook in .claude/settings.json. API conventions live in .claude/rules/api.md scoped to src/api/**.ts. Personal preferences are in CLAUDE.local.md. The root file is a stable pointer map that rarely changes and is easy for the whole team to maintain.

Knowledge Check

Which location is correct for a rule that should only apply when Claude modifies TypeScript files in src/api/?

A) Root CLAUDE.md B) ~/.claude/CLAUDE.md C) .claude/rules/api.md with paths: ["src/api/**.ts"] frontmatter D) .claude/settings.json hooks

Correct answer: C. Path-scoped rules in `.claude/rules/` load conditionally based on the files Claude is touching, keeping context clean for unrelated work.

A well-structured CLAUDE.md is the foundation — but it's one layer of a full Claude Code harness that also covers subagents, MCP server wiring, and worktree isolation. If you're evaluating whether to build a multi-agent pipeline or choosing between tools for your team, the AI coding agents buyers guide gives the full decision matrix. For the model-specific setup for Opus 4.7 — including effort levels, task budgets, and the Detailed Plan Pattern — the Opus 4.7 production guide covers the specifics.

Ready to build a production-grade Claude Code setup end to end? [[course/claude-code-production-workflows]] covers CLAUDE.md architecture, hook design, .claude/rules/ scoping, subagent orchestration, and MCP server wiring across structured hands-on modules.