CLAUDE.md: where it goes, how it loads, and how it works with AGENTS.md
Where do I put CLAUDE.md, and does Claude Code read AGENTS.md?
Put team instructions in ./CLAUDE.md (or ./.claude/CLAUDE.md), personal ones in ~/.claude/CLAUDE.md, and private project notes in ./CLAUDE.local.md. Claude Code loads every CLAUDE.md from your working directory up to the root at launch, and subdirectory files on demand. It reads AGENTS.md when there is no CLAUDE.md; with both, import it with @AGENTS.md.
Compare: rules and instruction files in every AI coding agent →
Where CLAUDE.md files live
- Project (shared via git): ./CLAUDE.md or ./.claude/CLAUDE.md.
- User (all your projects): ~/.claude/CLAUDE.md.
- Local (just you, this project): ./CLAUDE.local.md; add it to .gitignore.
- Managed (whole organization): /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux.
How they load
- Files from the working directory and every directory above it load at launch and are concatenated, not overridden; the closest file is read last.
- CLAUDE.md files in subdirectories load when Claude reads or edits a file there.
- Run /init to generate a starting CLAUDE.md from your codebase.
- Keep each file under about 200 lines; longer files cost context and are followed less reliably.
Imports and AGENTS.md
Use @path/to/file to import other files, up to four hops deep. If the repo has an AGENTS.md and no CLAUDE.md, Claude Code reads AGENTS.md. If it has both, only CLAUDE.md loads unless it imports AGENTS.md:
CLAUDE.md
@AGENTS.md ## Claude-specific - Use plan mode for changes touching more than three files.
Scope rules to files with .claude/rules
Markdown files in .claude/rules/ load automatically. Add a paths field to load a rule only when Claude works on matching files.
.claude/rules/api.md
--- paths: - "src/api/**/*.ts" --- - Every endpoint validates its input. - Use the standard error response format.
Sources
More Claude Code guides
- How to allow Claude Code to run all commands: permission modes, allow rules and skip permissions
- Claude Code permissions: allow, ask and deny rules, rule syntax and allowed tools
- Claude Code telemetry and data retention: what is sent and how to turn it off
- Claude Code hooks: all events, exit codes, PreToolUse and PermissionRequest JSON, examples
- Claude Code subagents: create one, limit its tools, and call it
- Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes)
- Claude Code custom slash commands and skills (SKILL.md)
- Claude Code settings.json: file locations, precedence, and key settings
- Claude Code plugins and marketplaces: install, create, and share
- Claude Code headless mode: claude -p, --output-format json, --bare and CI flags
- Claude Code statusline: custom status bar in settings.json with context %, cost and git branch
- Claude Code /model: switch models, aliases (opus, sonnet, haiku, opusplan), ANTHROPIC_MODEL and effort
- Claude Code /cost and /usage: check token spend, usage limits and reduce costs
- Claude Code VS Code extension: install, shortcuts, settings and /ide (works in Cursor too)
- MCP 2026-07-28 Migration Guide: Stateless Protocol, No Sessions, server/discover, MRTR, and SDK v2 Upgrade
- Subagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot (2026)
- Allow all commands in any AI coding agent: Cursor, Claude Code, Codex, Gemini CLI, Copilot CLI and 7 more (2026)
- How to deploy a remote MCP server (Streamable HTTP): Cloudflare Workers, Vercel, Railway and more (2026)
- Claude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict mode
Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →