Claude Code: `CLAUDE.md` location, format and template

Where Claude Code reads project instructions, whether it reads AGENTS.md, and what the format allows. From the official documentation, checked Oct 7, 2026. See also Claude Code: pricing, popularity and alternatives.

Project files

CLAUDE.md or .claude/CLAUDE.md in the project (commit it)
CLAUDE.local.md for personal notes (add it to .gitignore)
.claude/rules/*.md for topic rules; a paths list in front matter limits a rule to matching files
CLAUDE.md files in parent folders load at start; ones in subfolders load when Claude works on files there

Global (all projects)

~/.claude/CLAUDE.md and ~/.claude/rules/*.md

AGENTS.md

✓ Yes, from v2.1.277, but by default only when the project has no CLAUDE.md (change it in /config → Project instructions). The portable pattern: a CLAUDE.md that contains @AGENTS.md.

Format and limits

Import other files with @path/to/file (relative to the importing file, up to 4 levels deep).
The docs suggest keeping each CLAUDE.md under about 200 lines.
/init writes a starter CLAUDE.md from your codebase; /memory opens the loaded files and /context lists them.
HTML comments are stripped before the file reaches the model, so you can leave notes for humans.
Permissions live separately, in .claude/settings.json (shared) and .claude/settings.local.json (personal).

Sources: code.claude.com/docs/en/memory · code.claude.com/docs/en/settings

Templates

CLAUDE.md that reuses AGENTS.mdCLAUDE.md

@AGENTS.md

## Claude Code
- For changes that touch several files, outline the plan first and wait for a go-ahead.
- After editing, run the test command from AGENTS.md and fix failures before you stop.

Claude Code rule for one part of the code.claude/rules/api.md

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

# API rules
- Every endpoint validates its input and returns typed errors.
- Add or update the matching test in `tests/api/`.

Claude Code permissions (from the official docs).claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Written by AgentGid as a starting point; swap in your own commands and folders.

Claude Code: CLAUDE.md location, format and template