CLAUDE.md best practices: locations, imports and examples

CLAUDE.md best practices, per Anthropic’s docs: run /init for a first draft, keep each file under about 200 lines, include only what Claude can’t work out from the code (commands, conventions that differ from defaults, gotchas), and move rules that must always hold into hooks or permissions.

/init

Applies to: Claude Code 2.1.287 (changelog), docs as of October 2, 2026; AGENTS.md, size-limit and tool-compatibility answers re-checked against the docs on October 10, 2026. Last checked: October 10, 2026.

On this page

What is CLAUDE.md?

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. Anthropic’s memory docs describe it as one of two ways knowledge carries across sessions; the other is auto memory, notes Claude writes for itself.

The docs are explicit that Claude treats both as context, not enforced configuration. CLAUDE.md content is delivered as a user message after the system prompt, and “there’s no guarantee of strict compliance, especially for vague or conflicting instructions” (troubleshooting).

Where do CLAUDE.md files go?

The locations table, in load order from broadest to most specific:

How the hierarchy loads

• Claude Code walks up from your working directory and loads every CLAUDE.md and CLAUDE.local.md it finds. Running in foo/bar/ loads foo/CLAUDE.md and foo/bar/CLAUDE.md.
• Files are concatenated, not overridden. Content runs from the filesystem root down, so instructions nearest your working directory come last, and CLAUDE.local.md comes after CLAUDE.md at each level.
• CLAUDE.md files in subdirectories below the working directory load on demand, when Claude reads files there.
• Block-level HTML comments are stripped before the content reaches Claude, so you can leave notes for human maintainers without spending tokens.
• A managed policy CLAUDE.md can’t be excluded by individual settings. Admins can also put the text in the claudeMd key of managed-settings.json.

Source: How CLAUDE.md files load.

For monorepos, claudeMdExcludes skips other teams’ files. The docs suggest putting it in .claude/settings.local.json:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

How do I create one with /init?

1. Open Claude Code in the project and run /init. Claude analyzes the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
2. Review the draft and remove anything inaccurate. Anthropic’s help center article says to then commit it.
3. Run /context and confirm the file is listed under Memory files.
4. Add instructions Claude wouldn’t discover on its own as you work.

Setting CLAUDE_CODE_NEW_INIT=1 enables an interactive multi-phase /init that can also set up skills and hooks and asks follow-up questions before writing files. /init reads Cursor rules (.cursor/rules/, .cursorrules) and Copilot rules (.github/copilot-instructions.md) and folds the relevant parts into the new file (set up a project CLAUDE.md).

How do I edit it with /memory?

/memory lists your CLAUDE.md, CLAUDE.local.md and other memory locations across user and project scopes, including entries for files that don’t exist yet. Selecting one opens it in your editor and creates it if needed. The same menu toggles auto memory and opens the auto memory folder (/memory).

If you ask Claude to “remember” something, it goes to auto memory. To put it in CLAUDE.md, the docs say to ask directly (“add this to CLAUDE.md”) or edit the file through /memory.

What should go in CLAUDE.md?

Anthropic’s best practices page gives this split:

The test it gives for every line: “Would removing this cause Claude to make mistakes?” If not, cut it. The page warns that bloated CLAUDE.md files cause Claude to ignore your actual instructions.

The memory docs list when to add a line (when to add to CLAUDE.md):

• Claude makes the same mistake a second time
• A code review catches something Claude should have known about this codebase
• You type the same correction into chat that you typed last session
• A new teammate would need the same context to be productive

Example from the docs

There is no required format. This is Anthropic’s own example:

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

Write instructions Claude can verify

The memory docs ask for instructions “concrete enough to verify” (write effective instructions):

The same section’s other rules:

• Size: target under 200 lines per file. Longer files consume more context and reduce adherence.
• Structure: group related instructions under Markdown headers and bullets.
• Consistency: if two rules contradict each other, Claude may pick one arbitrarily, so review CLAUDE.md files, nested files and .claude/rules/ periodically.

The best practices page adds that emphasis such as “IMPORTANT” or “YOU MUST” can improve adherence, and that you can put compaction instructions in CLAUDE.md, for example "When compacting, always preserve the full list of modified files and any test commands".

How do imports with @ work?

A CLAUDE.md can pull in other files with @path/to/import. Relative paths resolve from the file that contains the import, absolute paths and ~ work, and imports can nest up to four hops deep (import additional files):

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

Things to know:

• Imported files load at launch, so splitting a file into imports helps organization but doesn’t reduce context.
• Paths inside backticks or code blocks are not imported.
• The first time a project imports a file from outside the working directory, Claude Code shows an approval dialog. Imports in your own ~/.claude/CLAUDE.md load without it.
• To share personal instructions across git worktrees, import a file from your home directory, since a gitignored CLAUDE.local.md exists only in the worktree where you created it:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Using an existing AGENTS.md

Since v2.1.277, Claude Code can read AGENTS.md itself. By default it reads your AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it; if one exists, Claude reads the CLAUDE.md files only. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don’t count for that check and keep loading alongside AGENTS.md (AGENTS.md).

To change the default, type /config and set Project instructions to claude-md-and-agents-md (both files, each directory’s CLAUDE.md first), claude-md (CLAUDE.md only) or managed-only (choose which instruction files load).

When a project keeps both files, or a session can’t read AGENTS.md directly, the docs still suggest a CLAUDE.md that imports it, with any Claude-specific lines below:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works; on Windows the docs recommend the import, because symlinks need Administrator rights or Developer Mode. If you earlier added a SessionStart hook that prints AGENTS.md, the docs say to remove it, since it now adds a second copy to the context (remove an earlier workaround).

When should an instruction leave CLAUDE.md?

Anthropic’s post Steering Claude Code lists signs that an instruction belongs elsewhere:

Path-scoped rules

Files in .claude/rules/ load like CLAUDE.md. Add paths frontmatter and a rule loads only when Claude reads a matching file (path-specific rules):

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Personal rules for every project go in ~/.claude/rules/. Hooks are covered in our Claude Code hooks guide, and published skills are listed in the skills directory; the Skill Creator skill helps build new ones.

Things Anthropic says to keep out

• Secrets. Anthropic’s CLAUDE.md blog post says not to include API keys, credentials, database connection strings or detailed security vulnerability information, and to treat the file as documentation that could be shared publicly.
• Stale or aspirational rules. The help center article lists changelogs, anything obvious from the file tree, and “aspirational rules the team does not actually follow” as things to leave out, and suggests a quarterly skim because outdated instructions are worse than none.
• Content Claude can derive. The /doctor checkup (v2.1.206 and later) proposes trims for a checked-in CLAUDE.md, cutting directory layouts, dependency lists and architecture overviews while keeping pitfalls, rationale and non-default conventions (my CLAUDE.md is too large).

More configuration guides are in Skills & config.