# CLAUDE.md

@AGENTS.md

<!--
  The line above is the whole point of this file, and it is easy to get wrong.

  Claude Code does not read AGENTS.md. Anthropic's memory documentation says
  so directly, and the Claude Code changelog has never mentioned the file
  across its entire release history. So a repo whose real instructions live
  in AGENTS.md needs this file to bridge the gap.

  It must be a bare @-import. `@AGENTS.md` expands the file into context at
  launch. A markdown link — [AGENTS.md](./AGENTS.md) — does not: it is inert
  text, and Claude has to decide to go and read the file itself.

  This is not hypothetical. Both MUI and Adobe React Spectrum ship a
  CLAUDE.md that points at AGENTS.md with a markdown link. As written, Claude
  Code loads four lines of prose instead of their real instructions.

  Imports resolve up to 4 hops deep. Backticks around `@AGENTS.md` would keep
  it literal, so do not quote it.

  Also worth knowing: CLAUDE.md files do not override each other the way
  AGENTS.md files do. Every discovered file — managed policy, ~/.claude/,
  repo root, subdirectory — is concatenated into context. If two of them
  contradict, Claude may pick either one. Do not design a monorepo around a
  package-level file overriding a root rule; that works under AGENTS.md
  semantics and silently does not work here.
-->

## Claude-specific notes

<!--
  Anything here that is genuinely Claude-only. If it applies to every agent,
  it belongs in AGENTS.md instead. Keep this section short or delete it.
-->

- Use plan mode before changes under `<src/critical-path/>`.
- Path-scoped rules live in `.claude/rules/` with `paths:` frontmatter.
- Long reference material lives in `.claude/skills/`, not here — a skill's
  body costs nothing until it is used, where everything in this file is
  loaded on every turn.