CLAUDE.md

Every line of CLAUDE.md loads on every session and shapes the main thread for everything you do — including the trivial queries where the rule doesn’t apply. A bloated CLAUDE.md is the most common reason a project burns through Opus quota faster than it should.

This section is about keeping it tight: what earns its place, what doesn’t, where the file lives at each scope, and how to handle it when the file genuinely needs to grow.

The test for any rule

Before adding any rule to CLAUDE.md, ask: would I want this loaded during a one-line git status query?

If yes, the rule belongs there. It applies to every read, every edit, every question — so the per-session cost of loading it is paid back by the value it adds across all of them.

If no, the rule belongs somewhere else. Either:

• A Skill — if the rule applies to a recognisable class of task and you want it available on demand
• A subagent description — if the rule shapes a repeatable specialist task
• The prompt — if the rule only applies to this specific dialogue

Most “I want Claude to do X” rules fail this test. They’re task-specific, and they bloat the system prompt with instructions that are irrelevant 90% of the time.

What belongs in CLAUDE.md

Three categories of rule reliably justify their place in CLAUDE.md:

Stack rules — what the project is built on. Claude touches the stack on every read or edit, so stack rules apply to every session by definition. “Next.js 14 App Router, TypeScript strict” is the kind of thing that shapes every line of code Claude writes.

Security rules — what must never happen. Worth enforcing on the tiniest change. “Never log full transaction data, PII, or API keys” applies whether you’re shipping a feature or fixing a typo.

Convention rules — naming, structure, file organisation. Belong here when they’re consistent across the codebase. “Components in components/, named PascalCase” applies everywhere; “tests live next to the component they test” applies everywhere.

The common thread: these rules shape how Claude does things, regardless of what it’s doing.

What doesn’t belong

Three categories of rule that look tempting but cost more than they pay:

Methodology rules — how to think, not how to act. “Apply adversarial self-review before finalising” is good practice, but only relevant when finalising. Loading it on every session means paying token cost during reads, edits, and trivial queries where it doesn’t apply. Demote to a Skill triggered on draft completion.

Style rules — how to format output. “Prefer tables over bullets” only applies when generating prose. Demote to a Skill or include it in the prompt when you actually need it.

One-off corrections — rules added in response to a specific mistake. “Don’t use the deprecated useEffect pattern” is a useful note, but if it’s a one-time issue, fixing it in the code is better than enshrining it in the system prompt forever.

The common thread: these rules shape Claude’s behaviour for some tasks, not all. They belong in mechanisms that load on demand.

Quick test

If a person could reasonably argue against this rule and the rule should still hold, it’s settings.json. If you’d want a thoughtful collaborator to be able to point out an exception, it’s CLAUDE.md. If the rule only applies to certain tasks, it’s a Skill.

The three scopes — concrete examples

CLAUDE.md has three scopes. Each has a different role and a different shape.

Root-level — ~/.claude/CLAUDE.md

Truly global preferences. Things you want Claude to do on every project, every machine, every session. Keep this minimal.

# Global behaviour
- Lead with the answer; no preamble before substantive replies.
- When uncertain, flag the uncertainty explicitly. Do not paper over gaps.
- Match register to context: technical for code, assertive for strategy.

That’s the right shape. Three to five rules, each one a genuine cross-project preference. If you find yourself adding stack rules or framework conventions here, stop — those belong at project level. If you find yourself adding methodology like “always apply adversarial review”, stop — that’s a Skill.

The root file is the easiest to bloat because it feels low-stakes (“just a few preferences”). It isn’t. Rules here load on every session across every project, and the cost compounds.

When you first run Claude Code, the file at ~/.claude/CLAUDE.md is seeded with four empty H2 headings: About me, Preferences, Tooling defaults, and Conventions. They’re a starting point Claude Code gives you, not a constraint. The same minimal-rules principle still applies — three to five total preferences, distributed across whichever headings actually have content. The example above uses one custom heading because that author had only three behavioural rules; the four-heading shape works when the rules span more than one category.

If you keep the defaults, the rule of thumb for each is:

• About me — who you are and the kinds of work you do. Context Claude should hold across every session, two or three lines at most.
• Preferences — how you want Claude to communicate. Response shape, level of detail, tone, what to skip.
• Tooling defaults — default stack and CLI choices that span projects. pnpm over npm, gh over the GitHub web UI. Project-specific tooling belongs in the project’s CLAUDE.md, not here.
• Conventions — workflow patterns that span projects. Commit message style, PR description shape, how you like changes summarised.

Delete any heading you don’t have content for — empty headings are noise. If something doesn’t fit any of the four, add a new heading rather than forcing it.

Project-level — <repo>/CLAUDE.md

Stack and security rules for this specific codebase. Committed to the repo. The typical shape for a web project:

# Stack
- Next.js 14 (App Router), TypeScript strict, Tailwind.
- Anthropic SDK for chat routes; never expose API key client-side.
- Mock data in `lib/mock/`; real connectors are Phase 2.

# Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test single: `pnpm test [path]`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

# Security
- Flag security issues with `// WARNING:` comments inline.
- Refuse to implement known-insecure patterns; suggest the secure alternative.
- Never log request bodies, PII, or API keys.

# Conventions
- Components in `components/`, named PascalCase, default exports.
- Types in `types/`, no `any` in production code.
- Server actions over API routes where possible.

# Out of scope
- `lib/generated/` — auto-generated from the schema. Don't edit.
- `migrations/*` — written by hand and reviewed in PR. Don't modify existing migrations.
- `docs/decisions/` — append-only ADR log; new entries only, never edit prior ones.

Stack, commands, security, conventions, out of scope. Each rule (and the commands reference) should usefully shape behaviour even on trivial queries — not just feature builds.

The Out of scope section deserves a moment. It’s the cleanest way to prevent Claude from rewriting generated files, modifying append-only logs, or “helpfully” refactoring code that’s manually maintained. A short list of paths Claude should treat as read-only saves a class of mistakes that no other rule reliably catches.

For the Playbook’s standard projects, the stack section is largely fixed (Next.js, TypeScript, Tailwind, Supabase). The security section follows the rules in Security Rules. The conventions section is where most projects will grow — adding rules as patterns settle, removing rules when they become redundant or stale.

Local-only — <repo>/CLAUDE.local.md

Personal overrides for this specific project that shouldn’t be committed. Gitignored. Use sparingly — most projects don’t need one.

# Personal overrides for this project
- Use my fork of the design system at ~/code/forks/design-system for now.
- Skip the linter pre-commit hook; I run it manually.
- When proposing UI changes, surface them in plain text first; I dislike
  the rendered preview pattern.

The shape is “things that would be wrong to commit” — temporary forks, personal workflow preferences, local environment quirks. If a rule would be useful for anyone working on this project, it goes in the committed CLAUDE.md instead.

Most builds never grow a CLAUDE.local.md. Don’t create one preemptively; add it the first time you actually have a personal override worth pinning.

The @import system

A CLAUDE.md file can pull in other markdown files using @path syntax:

# Project Overview
Next.js 14 App Router, deployed to Vercel, Supabase backend.

# Architecture
@docs/architecture.md
@docs/api-conventions.md

# Coding Standards
- TypeScript strict mode
- No default exports except `page.tsx` and `layout.tsx`
- @docs/testing-standards.md

Imports are recursive up to five levels deep, accept relative or absolute paths (including @~/.claude/personal-style.md to pull from your home directory), and load into context at session start.

They’re an organisational tool. They let your CLAUDE.md stay scannable while detailed specs live in dedicated files. A 30-line CLAUDE.md with three @imports is easier to maintain than a 200-line monolith — and easier for you to read when you come back to the project months later.

The Command Centre’s CLAUDE.md is a worked example of the minimal-index pattern in active use — a short header file that points at a handful of context files via @import, rather than carrying the rules itself.

The caveat that catches people out

@imports don’t reduce context usage. Every imported file is loaded at session start, the same as inlining its contents. If your CLAUDE.md is too long because it has too much to say, splitting it via @import makes it more readable but doesn’t make Claude pay more attention or burn fewer tokens.

When CLAUDE.md is genuinely over budget, the answer is one of two things — neither of which is @import:

• Delete redundant or stale rules. This is almost always the right answer. Most bloated CLAUDE.md files have rules that no longer apply, rules that say the same thing twice, or rules that never belonged there in the first place.
• Move task-specific rules to Skills. If a rule only applies to feature development but not bug fixes, it doesn’t belong in the system prompt. A Skill triggered on relevant tasks loads only when needed.

If neither applies and the rules are all genuinely cross-cutting, see path-scoped rules below.

Path-scoped rules

.claude/rules/*.md is the mechanism for rules that apply to part of the codebase, not all of it. Frontmatter scopes each file to specific paths:

---
paths:
  - "src/api/**"
  - "src/services/**"
---
Always use dependency injection. Never import concrete implementations
directly.

This rule loads into context only when Claude is working on a file matching one of the globs. It’s the only memory mechanism that’s genuinely lazy — CLAUDE.md and @imports always load; path-scoped rules only load when relevant.

When to reach for them:

• Monorepos — when frontend, backend, and infrastructure each have distinct conventions that shouldn’t bleed across.
• Mixed-stack projects — when one part of the codebase uses one pattern and another part uses a different one.
• Genuinely large CLAUDE.md — when you’ve already deleted the deletable and demoted the demote-able, and what’s left is real but cross-cutting.

For most solo Playbook projects, path-scoped rules are overkill. The codebase is small enough that everything cross-cuts and CLAUDE.md stays tight without them. Reach for them when the simpler approach genuinely isn’t doing the job — not preemptively.

File size limits

A few hard numbers from the Anthropic docs:

• Single memory file: target under 200 lines.
• Hard limit: 40,000 characters per memory file. Beyond this, files may not be fully read.
• Total memory across all loaded files: keep tight. Every line consumes context budget the actual work doesn’t get.

If a CLAUDE.md is creeping past 200 lines, the fix is almost always delete, not split. Splitting via @import reorganises but doesn’t reduce. Path-scoped rules genuinely reduce. Deleting redundant or stale instructions does the most good.

Anti-patterns

Five patterns that show up in real CLAUDE.md files and reliably cost more than they pay.

Shouting in ALL CAPS. “NEVER USE any IN PRODUCTION CODE” is no more enforceable than “Never use any in production code”, and it makes the file harder to scan. The model doesn’t pay extra attention to capital letters; you just look angry.

Redundant rules. “Use TypeScript strict mode” stated three times across different sections doesn’t reinforce the rule. It bloats the file and makes it harder to find the rule that does need updating when you come back later.

Stale instructions. Rules referencing patterns the project no longer uses, libraries it’s removed, or decisions that have since reversed. These aren’t just useless — they actively mislead, because Claude reads them as current. Treat CLAUDE.md like code: prune it when the codebase changes.

Methodology as system prompt. “Apply first-principles thinking”, “Always consider the alternatives”, “Reason step by step before answering”. These belong in prompts when you want them, not in the system prompt where they shape every trivial query.

Personal preferences in the project file. “I prefer concise responses.” “Don’t use emojis.” Project-level CLAUDE.md is committed and team-shared — your preferences belong in ~/.claude/CLAUDE.md (if cross-project) or CLAUDE.local.md (if just for this project). Putting them in the committed file imposes them on everyone else who works on the codebase.

Maintaining CLAUDE.md over time

CLAUDE.md drifts. New rules accumulate as the project evolves; old rules go stale as patterns shift. Treat it as a living document, not a write-once spec.

A few habits worth forming:

• Update at decision points. When you make a non-obvious architectural choice, the rule that captures it goes in CLAUDE.md (and the rationale goes in memory.md). Don’t let the rule live only in your head.
• Review at session start. When you come back to a project after time away, reread CLAUDE.md before starting. If a rule is wrong, fix it before working — drift left in place becomes drift Claude inherits.
• Prune before adding. When you’re about to add a rule, scan for one to remove. Keeps the file tight.
• Review monthly. A short pass through CLAUDE.md once a month catches the stale, the redundant, and the rules that never belonged. Cheap maintenance; high payoff.