---
title: "CLAUDE.md (Claude Code): paths and format · DotsAgent"
description: "Where CLAUDE.md lives, its format and frontmatter, how global and nested copies merge, and which tools read it. Checked 2026-10-01."
url: https://dotsagent.io/instructions/files/claude-md
---

CLAUDE.md

# 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`

`CLAUDE.md`

```
@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

| Tool | Support |
| --- | --- |
| [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) | Reads a root CLAUDE.md as agent instructions, as an alternative to AGENTS.md. |

## 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.

Generate an AGENTS.md and matching rule files for five tools from one form. [Open the AGENTS.md generator →](https://dotsagent.io/instructions)

## Other instruction files

[AGENTS.md](https://dotsagent.io/instructions/files/agents-md)

[GEMINI.md](https://dotsagent.io/instructions/files/gemini-md)

[.cursor/rules/*.mdc](https://dotsagent.io/instructions/files/cursor-rules)

[.github/copilot-instructions.md](https://dotsagent.io/instructions/files/github-copilot-instructions)

[.devin/rules/*.md](https://dotsagent.io/instructions/files/windsurf-rules)

[.clinerules/](https://dotsagent.io/instructions/files/cline-rules)

[~/.openclaw/workspace/AGENTS.md](https://dotsagent.io/instructions/files/openclaw-workspace)

## Sources

1. [code.claude.com](https://code.claude.com/docs/en/memory)/docs/en/memory

Independent reference for people who build AI agents. Not affiliated with any vendor named here.

© 2026 DotsAgent · Facts checked October 1, 2026