Claude Code

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.

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

Claude Code: How Claude remembers your project

More on Claude Code

Claude Code standards supportAdd MCP servers to Claude Code

Other guides

Cursor: allow all terminal commandsClaude Code: allow commands without promptsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call it

Get the weekly agent stack update

New official MCP servers, spec changes and harness releases, checked against the source. One email a week, no fluff.

Reviewed Oct 6, 2026. Settings change often; the linked vendor docs are the source of truth.