Skip to main content
What this unit solvesCLAUDE.md is the standing instruction injected automatically at the start of every session — the “common sense” you give the agent. Too long and it eats context; too vague and it has no constraining force. This unit unpacks when it is loaded, how the override layers work, the optimal length, and how to modularize it. It also clarifies the division of labor between the instruction-oriented CLAUDE.md and the fact-oriented auto-memory, and closes with a cross-tool comparison of project-level instruction file names.

​
Learning objectives

  • State the four placement locations for CLAUDE.md (managed / user / project / local) and their loading priority order.
  • Use the “cross-task leverage” filter to judge which content belongs in CLAUDE.md and which does not.
  • Use @path import syntax and .claude/rules/ path scoping to modularize rules and avoid a single monolithic file.
  • Distinguish CLAUDE.md (instruction-oriented) from auto-memory (fact-oriented), and identify the risks of memory poisoning and how to handle it.
  • Map the project-level instruction file names of OpenAI Codex, Google Antigravity, GitHub Copilot, and Cursor to their Claude Code equivalents.

​
1. What CLAUDE.md is and when it is loaded

CLAUDE.md is a plain-text Markdown file stored on disk. Claude Code reads it at the start of every session and injects it into the conversation context as a user message. Once loaded, it occupies token budget in the context window alongside everything you say. Two key facts to internalize first:
  • It is context, not enforced configuration. Claude will “try to comply,” but there is no hard guarantee when conflicts arise or rules are missed. For hard guarantees, see Section 8 on the difference between hooks and context.
  • It is a standing message injected in full every session, unlike a Skill which is loaded on demand (see 04-4 Skills). Every line you write costs tokens every time.
/init is the fastest starting pointRun /init in a new project directory and Claude Code will automatically scan your codebase and generate a starter CLAUDE.md covering build commands, test workflows, and project conventions. It reads what can be mechanically inferred; you then add what it cannot infer but needs to know every session.

​
2. Placement locations and override layers

Claude Code searches for and loads CLAUDE.md in the following order at startup (as of 2026-06, per the official memory documentation [1]):
Loading order is not “overriding”Multiple files are concatenated into context, not the later one overwriting the earlier. They are joined in order from root toward the working directory, with local files read last. When CLAUDE.md and CLAUDE.local.md are in the same layer, the local file is appended after. This means a CLAUDE.md placed in a parent directory will be read by any session started in any of its subdirectories.
The managed policy is published by the organization and cannot be disabled by individuals. Personal and project-level CLAUDE.md files can use claudeMdExcludes to exclude specific files (settable at any configuration layer; arrays are merged across layers). This is useful in large monorepos for preventing another team’s CLAUDE.md from polluting yours. The managed policy CLAUDE.md cannot be excluded [1].

​
3. What to write and what not to: the cross-task leverage principle

The filter comes down to one sentence: if a rule will still be useful next session, write it in; if it is only useful once, do not. Applying this standard quickly eliminates 80% of candidates. Content that belongs in CLAUDE.md:
  • Role and language: second-person voice, response language, terminology glossary.
  • Coding style: indentation, naming, quote style, module-splitting conventions.
  • Build and test commands: make test, uv run pytest, pnpm lint, and the like.
  • Project structure and boundaries: “API handlers live in src/api/handlers/”, “do not touch dist/”.
  • Prohibitions: “do not modify existing files in migrations/”, “never commit any .env”.
  • Common workflows: “after fixing a bug, run make lint before committing”.
Content that does not belong:
  • One-off task details (“merge PR #1234 into main for me”).
  • Frequently changing version numbers and package lists (these go stale and belong in lockfiles).
  • Secrets (API keys, passwords, tokens). CLAUDE.md goes into version control; secrets belong in .env guarded by .gitignore.
  • Verbose background (more than a page of project history or design philosophy). Background should be passed in conversation context, not left standing.
  • Content that belongs on another axis: multi-step procedures, cross-file refactor SOPs, release workflows — split these into Skills (see 04-4 Skills).
Write imperatives, not descriptionsCLAUDE.md is “what to comply with,” not a project introduction. For the same content, the imperative version is several times more effective than the descriptive version.Do not write: “Our tests use the pytest framework, running on Python 3.11+, primarily using fixtures and parametrize…” (description)Write instead: “Run tests with uv run pytest; for a single test file use uv run pytest path/to/test_x.py -k name” (imperative)Imperatives make it much easier for the model to extract “what to do.”

​
4. Length and token budget

Anthropic’s official guidance on CLAUDE.md length is 200 lines or fewer per file [1]. This is not a hard limit, but there are two reasons for it:
  1. Adherence degrades. The longer the file, the lower the fraction of rules the model remembers and follows across multiple turns. Shorter is more consistent.
  2. Every session burns tokens. Once CLAUDE.md is loaded it is not removed from context (unless you manually /compact and re-trigger loading). The longer it is, the same cost is paid on every interaction.
If a rule is only needed in a specific subdirectory or file extension, move it to .claude/rules/<topic>.md and constrain it with paths frontmatter (see 04-2 rules). That way it is not fully loaded in every session — only when Claude touches matching files.
Real cost: the difference between 200 and 800 linesAssume CLAUDE.md is about 200 lines averaging 25 tokens per line. A single session starts with 5,000 tokens of static overhead. The same content inflated to 800 lines costs 20,000 tokens. In a 200k context window, the 800-line version permanently consumes roughly 7.5% more of the available conversation space. With Claude Opus 4.5 input costs, the 800-line version can cost hundreds of dollars more per year — before counting the correction cost from degraded adherence.

​
Structured segmentation

Group sections under explicit Markdown headings and avoid large blocks of prose. The model scans structure; concentrating related rules under a single ## heading is more stable than scattering them across three paragraphs.
Block comments are strippedThe official implementation strips <!-- ... --> HTML block comments before loading CLAUDE.md into context [1]. This means comments intended for human maintainers (e.g., “this section came from the 2026-04 linting discussion”) do not consume tokens. Comments inside code blocks are not stripped. Comments remain visible when you open CLAUDE.md with the Read tool; only the copy injected into the model is stripped.

​
5. Modularization: avoiding the monolithic file

Two orthogonal tools let you split the file.

​
5.1 Importing with @path

Inside CLAUDE.md you can import other files using @path/to/import syntax [1]:
Rules:
  • Relative paths are resolved against the file that contains the @, not the current working directory.
  • Imports can be recursive up to 4 levels deep.
  • Imported files are also loaded in full at session startup, so @ imports are for organizational structure, not for saving tokens. To save tokens, use the path-scoped mechanism in .claude/rules/.
  • The first time an external import is used, Claude Code shows a trust confirmation dialog. Clicking “reject” disables imports for that project [1].
Sharing personal preferences across worktreesIf you use multiple git worktrees, put cross-worktree personal preferences in ~/.claude/my-project-instructions.md and reference it with @~/.claude/my-project-instructions.md in each worktree’s CLAUDE.md, eliminating duplicate edits.

​
5.2 Splitting into .claude/rules/

When a rule is only needed for specific file extensions or subdirectories, move the entire rule to .claude/rules/<topic>.md and use paths frontmatter to limit its reach (see 04-2 rules). Files in .claude/rules/ without paths are equivalent to CLAUDE.md — they are loaded in full at session startup. Once paths is specified, they are only loaded when Claude touches files matching the glob.
All 320 lines are injected in full at every session startup.

​
6. Auto-memory: fact-oriented memory

CLAUDE.md is the instructions you write for Claude. Auto-memory is the fact notes Claude writes for its future self [1]. The two work together: Storage location: ~/.claude/projects/<project>/memory/, containing a MEMORY.md index file and multiple topic files (debugging.md, api-conventions.md, etc.) [1]. This is machine-local — it does not sync across machines or to the cloud, but it is shared across worktrees within the same repo. Requirements: Claude Code v2.1.59 or later [1]. On by default; disable with /memory or by setting autoMemoryEnabled: false in settings.json, or with the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. To change the default storage location, use autoMemoryDirectory in settings.json (accepts an absolute path or ~/ prefix; setting this at the project or local layer requires passing the workspace trust dialog first) [1].
Auto-memory cuts both waysClaude decides whether to write based on “will this be useful in a future conversation?” What it writes may not be what you want (for example, recording an experimental approach you mentioned in passing as a persistent preference). The /memory command lets you browse, open, edit, and delete memory files. Treat it like your own notes: review it periodically.

​
7. Memory poisoning: the supply-chain risk of auto-memory

When external content enters the agent and is written into auto-memory, it influences behavior when loaded in the next session. This is memory poisoning. For the concrete attack surface see 03-3 Security, Privacy, and Supply-Chain Risk. The relevant mitigations for this unit are:
  • After workflows that process untrusted content, clear or rotate the contents of ~/.claude/projects/<project>/memory/.
  • Review auto-memory periodically: run /memory to open the folder and at minimum scan MEMORY.md and each topic file.
  • Secrets do not belong in auto-memory: Claude may write API keys or tokens you pasted into a conversation. MEMORY.md is a plain-text local file with no encryption; it travels with your backup or sync.

​
8. Division of labor with hooks: CLAUDE.md says “please comply”; hooks enforce

CLAUDE.md is context that the model references while generating responses. For prohibitions like “do not commit .env”, the model may miss this in a long-chain task. Hooks provide the hard guarantee (see 04-6 Hooks):
  • CLAUDE.md: “do not commit .env files” — the model will usually remember, but occasionally misses.
  • Hook (PreToolUse on Bash): when Bash(git commit *) is triggered, a shell check for .env in staged files exits with code 2 and blocks — every time, without exception.
The criterion: use CLAUDE.md when you need the model to “remember”; use a hook when you need it “blocked regardless.”

​
9. Tool comparison: project-level instruction files across tools

AGENTS.md has become the cross-tool shared project rules file natively supported by multiple tools. It is maintained by the Agentic AI Foundation under the Linux Foundation and as of 2026-06 had been adopted by 60,000+ open-source projects (adoption figures and governance claims sourced from [4], not Anthropic official documentation). Claude Code reads CLAUDE.md natively, but @AGENTS.md can be imported to bring it in [1].
Official position: Claude reads CLAUDE.md, not AGENTS.mdThe Anthropic official memory documentation states: “Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplication.” Source: Claude Code memory documentation, AGENTS.md section (official) (as of 2026-06) [1].The minimal approach from the official docs: first line of CLAUDE.md is @AGENTS.md, followed by Claude-specific instructions. If no Claude-specific content is needed, ln -s AGENTS.md CLAUDE.md also works. Creating symlinks on Windows requires administrator privileges or Developer Mode, so Anthropic recommends using @AGENTS.md import on Windows instead.
Naming clarificationThe primary column uses current official naming. Claude Code’s standing instruction file is CLAUDE.md (not AGENTS.md); if a project already has AGENTS.md, use @AGENTS.md import to have Claude read it too. Google Antigravity reads both GEMINI.md and AGENTS.md; priority ordering is inconsistent across sources — see 02-6 Other Tools Comparison for details. Cursor is a third-party IDE (Anysphere); this Playbook only includes a brief column for it.

​
10. Hands-on exercise

1

Prune

Apply the “cross-task leverage” filter to every rule in your current CLAUDE.md (if you have one). Delete anything only useful for a one-off task. Compare line counts before and after.
2

Split

If your Python or frontend coding style exceeds 30 lines, extract it to .claude/rules/<lang>-style.md and add a paths frontmatter constraint.
3

Local layer

Move any settings that are only needed on your local machine (sandbox URLs, test data locations) to CLAUDE.local.md and add it to .gitignore.
4

Verify

Start claude in the same working directory and run /memory to confirm all files that should be loaded appear in the list.
5

Trust dialog

The first time you use @path to import an external file, a trust confirmation will appear. Decide your strategy in advance: full project trust, or per-file approval.

​
11. Common pitfalls

Anti-pattern list
  • Copying someone else’s CLAUDE.md: their conventions reflect their workflow. Copying blindly introduces constraints you do not need and potentially security risks (see 03-3 Security, Privacy, and Supply-Chain Risk). Start from the skeleton and rewrite for your own workflow.
  • Growing CLAUDE.md indefinitely until layers contradict each other: the model picks one when rules conflict, and you may not know which. Review layered files regularly and delete stale rules.
  • Writing “must enforce” rules as imperatives in CLAUDE.md: rules that require hook enforcement written only in CLAUDE.md will occasionally be missed. For deterministic guarantees, see 04-6 Hooks.
  • Putting .env content in CLAUDE.md: it goes into version control, which means the secrets are no longer secret. Secrets belong in .env guarded by .gitignore.
  • Copying a single file name across all tools: Claude does not read AGENTS.md (unless you @ import it), and GitHub Copilot does not read CLAUDE.md. For cross-tool setups, use AGENTS.md as the shared foundation and attach tool-specific settings separately.

​
Self-check

The bar for passing this unit
  1. Can you state in under a minute the four placement locations for CLAUDE.md, their loading order, and which layer can be disabled and which cannot?
  2. For every rule in your own CLAUDE.md, can you state “what breaks if this is deleted”? Keep the ones you can answer; delete the ones you cannot.
  3. Can you articulate the criterion for “does this go in CLAUDE.md, .claude/rules/, a Skill, or a Hook”?
  4. Do you know where auto-memory is stored, how to inspect it, and how to clear it?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
  • [1] Anthropic, “How Claude remembers your project,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/memory (as of 2026-06)
  • [2] Anthropic, “Extend Claude with skills,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/skills (as of 2026-06; includes Skill and instruction mechanism integration)
  • [3] Cursor, “Rules,” cursor.com, 2026. [Online]. Available: https://cursor.com/docs/context/rules (as of 2026-06; .mdc and globs frontmatter mechanism)
  • [4] Agentic AI Foundation (Linux Foundation), “AGENTS.md, a simple, open format for guiding coding agents,” 2026. [Online]. Available: https://agents.md/ (as of 2026-06; 60,000+ open-source projects; full list of supporting tools on that page)