CLAUDE.md: what it is, where each file goes, and what to put in it

CLAUDE.md is a markdown file of instructions that Claude Code reads at the start of every session: your build commands, conventions and rules. There are four levels (an organization's managed file, your user file, the project file and a private local file), and Claude Code loads every one it finds into context. Keep each file under about 200 lines, and move rules that only matter for part of the code into path-scoped rules.

What is CLAUDE.md?

Every Claude Code session starts with an empty context window. CLAUDE.md is how you carry knowledge from one session to the next: a plain markdown file of instructions "for a project, your personal workflow, or your entire organization" that Claude reads at the start of every session.

Typical content: how to build and test, code style, architecture decisions, preferred libraries, review checklists, and the things a new teammate gets wrong in week one. Run /init in a project and Claude Code drafts a first version from what it finds in the codebase.

The four CLAUDE.md levels

How Claude Code loads CLAUDE.md files

• Upward at launch. Claude Code reads CLAUDE.md and CLAUDE.local.md in your working directory and every directory above it. Started in foo/bar/, it reads foo/bar/CLAUDE.md and foo/CLAUDE.md.
• Concatenated, not overridden. All files go into context, ordered from the filesystem root down to where you launched, so the closest file is read last; within a directory, CLAUDE.local.md comes after CLAUDE.md.
• Subdirectories on demand. A CLAUDE.md deeper in the tree loads only once Claude reads, writes or edits a file in that subdirectory.
• Comments are free. Block-level HTML comments (<!-- notes for humans -->) are stripped before the content reaches Claude.

In a large monorepo where other teams' files get picked up, claudeMdExcludes skips them.

@imports: keep the main file small

A CLAUDE.md can pull in other files with @path/to/file, relative to the file that contains the import, up to four hops deep:

```markdown Cogwheel support agent: project instructions

• Build: npm run build · Tests: npm test (run before every commit)
• Refunds over $100 must go through the approval hook, never around it.
• API conventions: @docs/api-conventions.md
• My machine-specific notes: @~/.claude/cogwheel-notes.md ```

Imported files load at launch with the file that references them, so imports organize content without saving context. To save context, use path-scoped rules.

Path-scoped rules in .claude/rules/

Put topic files in .claude/rules/ (testing.md, api-design.md). A rule without frontmatter loads like CLAUDE.md, every session. A rule with a paths glob loads only when Claude reads or edits a matching file:

```markdown

paths: - "services/billing/*/.ts"

• Amounts are integer cents, never floats.
• Every refund call logs the booking ID and the reason. ```

This is the right home for instructions that matter for one part of the code: they cost nothing until Claude touches those files.

What to put in CLAUDE.md, and what to leave out

The docs give clear targets:

• Size: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."
• Specific beats vague: "Use 2-space indentation" works; "format code nicely" does not.
• Consistent: if two instructions contradict each other, Claude may pick one arbitrarily, so review the files together now and then.

Leave out what Claude can read from the code itself, long reference documents (import them or link them), and anything that must be enforced. CLAUDE.md is context, not configuration: to block an action regardless of what Claude decides, use a PreToolUse hook or permission rules.

CLAUDE.md vs auto memory vs skills

Open /memory in a session to see and edit what is loaded and to toggle auto memory, which lives in ~/.claude/projects/<project>/memory/.

CLAUDE.md on the Claude Certified Architect exam

Domain 3 (Claude Code Configuration & Workflows) is 20% of the CCAR-F exam. Task 3.1 covers the CLAUDE.md hierarchy (user, project, directory levels), what belongs where (team standards in the project file, not in a personal one), and splitting with imports and .claude/rules/; task 3.3 covers path-specific rules; task 3.2 asks when a skill beats CLAUDE.md. One update since the guide: the levels now also include the managed policy file and CLAUDE.local.md, and path rules load when Claude reads a matching file, not only when it edits one.

The classic trap: a team convention that only one developer follows because it sits in their ~/.claude/CLAUDE.md instead of the project file in git.

Related: plan mode, GitHub Actions, and all articles.

Sources: How Claude remembers your project (CLAUDE.md levels, loading, imports, rules, auto memory); Claude Code overview; Claude Certified Architect Foundations exam guide v1.0, task statements 3.1 to 3.3.

FAQ

What is CLAUDE.md?

A markdown file that gives Claude Code persistent instructions for a project, your personal workflow or your organization. Claude reads it at the start of every session.

Where should CLAUDE.md go?

./CLAUDE.md or ./.claude/CLAUDE.md for the team's project instructions, ~/.claude/CLAUDE.md for your personal preferences across projects, ./CLAUDE.local.md for private project notes (gitignored), and a managed policy file for organization-wide rules.

How long should a CLAUDE.md file be?

The docs target under 200 lines per file. Longer files take more context and reduce adherence; move narrow instructions into path-scoped rules in .claude/rules/.

Is CLAUDE.md enforced?

No. Claude treats CLAUDE.md as context, not enforced configuration. To block an action whatever Claude decides, use a PreToolUse hook or permission rules.

Does Claude Code read AGENTS.md?

Yes. If a repository uses AGENTS.md, Claude Code can read it in place of, or alongside, CLAUDE.md.