Skip to content

CLAUDE.md

Summary

A plain Markdown file loaded by Claude Code (Anthropic's CLI coding agent) at the start of every session. Provides persistent project-level instructions: build commands, coding standards, architectural decisions, and team workflows. Also accepted by GitHub Copilot coding agent as a simpler alternative to AGENTS.md.

Tool

  • Primary: Anthropic Claude Code (claude CLI)
  • Also accepted by: GitHub Copilot coding agent (reads CLAUDE.md at repository root as an alternative to AGENTS.md)

Support level

supported — v0.1 Core target.

Canonical path(s)

  • ./CLAUDE.md — project root, team-shared via source control
  • ./.claude/CLAUDE.md — equivalent alternative location within the .claude/ directory

Alternate / legacy path(s)

Additional non-repo-committed locations (not generated by agent-policy):

Location Scope Repo-safe
./CLAUDE.local.md Personal project preferences, not checked into git No (auto-added to .gitignore)
~/.claude/CLAUDE.md Personal preferences for all projects No (machine-local)
macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Org-managed policy, deployed by IT No
Linux/WSL: /etc/claude-code/CLAUDE.md Org-managed policy No
Windows: C:\Program Files\ClaudeCode\CLAUDE.md Org-managed policy No

File format

Plain Markdown. No required structure or frontmatter for the root CLAUDE.md. Free-form prose and markdown headings/bullets. Vendor recommends:

  • Target under 200 lines per file. Files longer than 200 lines consume more context and reduce adherence. The 200-line limit applies only to auto memory's MEMORY.md; however the same guidance applies to CLAUDE.md for best results.
  • Use markdown headers and bullets to group related instructions. Structured sections are easier for the model to scan than dense paragraphs.
  • Write instructions specific enough to verify: "Use 2-space indentation" not "Format code properly".

Frontmatter

None for CLAUDE.md itself.

Files placed under .claude/rules/ may use YAML frontmatter with a paths field for path-scoped activation:

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules

- All endpoints must include input validation.

Rules without a paths field are loaded unconditionally. Path-scoped rules only activate when Claude reads files matching the pattern (not on every tool use).

The paths field supports multiple patterns as a YAML array, and brace expansion within patterns:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

This is relevant for Phase 4 if agent-policy ever targets .claude/rules/ path-scoped outputs.

Discovery / scope behavior

Claude Code discovers CLAUDE.md files at multiple scopes (per vendor docs):

  1. Managed policy (highest precedence, cannot be excluded): OS-specific system path.
  2. User scope: ~/.claude/CLAUDE.md — personal, applies to all projects.
  3. Project scope: Walking up from the CWD toward the filesystem root, Claude loads CLAUDE.md and CLAUDE.local.md from each directory. All are loaded in full at session start.
  4. Subdirectory scope: CLAUDE.md files in subdirectories below the CWD are loaded on demand when Claude reads files in those directories — not loaded at session start.
  5. More-specific locations take precedence over broader ones when instructions conflict.

.claude/rules/ directory: An alternative organization for larger projects. All .md files in .claude/rules/ (including subdirectories) are discovered and loaded. Each file can be scoped via paths frontmatter. Rules without a paths field are loaded at launch with the same priority as .claude/CLAUDE.md.

User-level rules at ~/.claude/rules/ work the same way but apply to every project on the machine. They are loaded before project rules, which means project rules have higher priority — project-level instructions override user-level ones on conflict.

@import syntax: A CLAUDE.md file can import additional files:

See @README for project overview and @package.json for available npm commands.

# Additional instructions

- Git workflow: @docs/git-instructions.md

Relative paths resolve from the file containing the import. Max import depth: 5 hops. The first time Claude encounters external imports in a project it shows an approval dialog.

claudeMdExcludes: In monorepos, specific CLAUDE.md files can be excluded via the claudeMdExcludes setting in .claude/settings.local.json. Managed policy files cannot be excluded.

Repo-safe

  • CLAUDE.md and .claude/: Yes — designed to be committed and shared with the team.
  • CLAUDE.local.md: No — automatically added to .gitignore; for personal, machine-local preferences.

Renderer notes

  • Output path: CLAUDE.md at repository root.
  • Single file output (v0.1).
  • No header or frontmatter required.
  • Suggested section structure (conventional, aligns with what /init generates):
  • Build and test commands
  • Coding standards
  • Architecture decisions
  • Common workflows
  • Keep under 200 lines for best adherence.

Known limitations / gotchas

  • Context, not enforcement: Claude reads the file and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions. More specific instructions produce better results.
  • Conflicting instructions across files: If multiple CLAUDE.md files (project + user + subdirectory) give contradictory guidance, Claude may pick one arbitrarily. Review all loaded files periodically.
  • Survives /compact: After /compact, Claude re-reads CLAUDE.md fresh from disk — instructions given conversationally (not written to CLAUDE.md) will be lost.
  • GitHub Copilot support is alternative, not primary: Copilot reads CLAUDE.md only as an alternative when AGENTS.md is absent. Prefer AGENTS.md for multi-tool repos.

Official references

Minimal example

# CLAUDE.md

## Build and test

- Install: `cargo build`
- Test: `cargo test --all-targets`
- Lint: `cargo clippy --all-targets -- -D warnings`
- Format check: `cargo fmt --check`

## Coding standards

- MSRV is 1.75. Do not use APIs stabilized after 1.75.
- All errors must use the `Error` and `Result` types in `src/error.rs`.
- Do not use `unwrap()` or `expect()` in library code (`src/lib.rs` and its submodules).

## Architecture

- Business logic lives in the library crate (`src/lib.rs`), not in `src/main.rs`.
- The CLI is a thin wrapper that parses args and calls library functions.

Internal mapping notes

  • Target ID: claude-md
  • Output path constant: "CLAUDE.md"
  • Template: templates/CLAUDE.md.j2
  • OutputTargets.claude_md: bool