CLAUDE.md (Claude Code): where it lives and how tools read it

CLAUDE.md is the memory file Claude Code loads at launch from your home directory, the project and every parent folder. Path-scoped rules in .claude/rules/ add guidance that loads only when matching files are read.

Where it lives

• Project: ./CLAUDE.md or ./.claude/CLAUDE.md, committed and shared with the team.
• Local: ./CLAUDE.local.md, for personal notes kept out of git.
• User: ~/.claude/CLAUDE.md, applied to every project.
• Rules: ./.claude/rules/**/*.md and ~/.claude/rules/**/*.md, optionally scoped with paths frontmatter.
• Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, C:\Program Files\ClaudeCode\CLAUDE.md on Windows, or the claudeMd key in managed-settings.json.

Format

Markdown. Files in .claude/rules/ may start with YAML frontmatter whose paths key lists globs. Pull in other files with @path/to/file, up to 4 hops deep; no hard size limit is documented, but Anthropic advises staying under 200 lines per file.

Frontmatter keys: paths

@AGENTS.md

# Claude Code notes

- Run `pnpm test` after every change under src/.
- Use the `gh` CLI for issues and pull requests.
- Ask before adding a dependency.

## API

- Error format is described in @docs/api-errors.md.
- One handler file per route in src/api/.

Precedence and merging

Nothing is overridden: every discovered file is concatenated. Managed policy loads first, then files from the filesystem root down to the launch directory, so closer files are read last; within one directory CLAUDE.local.md follows CLAUDE.md. Files in subdirectories load on demand when Claude reads files there, and managed policy can't be excluded with claudeMdExcludes.

Tools that read it

Tips

• If you keep a CLAUDE.md, start it with @AGENTS.md; otherwise Claude Code ignores AGENTS.md under the default setting.
• Move area-specific guidance into .claude/rules/ with paths frontmatter so it loads only for those files.
• Imports organise the file but still cost context, because the imported text is loaded too.
• Run /doctor to audit CLAUDE.md, CLAUDE.local.md, AGENTS.md, rules and skills in one pass.

Other instruction files