--- title: "CLAUDE.md" description: "Claude Code reads AGENTS.md on its own, so most repositories no longer need a CLAUDE.md. When one still helps, and how to write it so it doesn't hide AGENTS.md" url: "https://agentsurface.dev/docs/context-files/claude-md" lastVerified: 2026-09-25 lastModified: 2026-09-25T08:23:18.000Z --- ## Summary [#summary] From v2.1.277 (18 September 2026), Claude Code reads `AGENTS.md` as project instructions on its own. A repository with a good `AGENTS.md` doesn't need a `CLAUDE.md`, an import, or a setting. Write `AGENTS.md` for every coding agent and stop there unless Claude Code needs something no other tool should see. * **Default: no `CLAUDE.md`.** Claude Code reads `AGENTS.md` when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the working directory or above it * **A `CLAUDE.md` hides `AGENTS.md`.** If any of those three files exists, Claude Code reads it instead and skips `AGENTS.md`, unless the file imports it with `@AGENTS.md` * **If you add one, start it with `@AGENTS.md`** and put only Claude-only instructions below the import * **Enforced rules go in settings.** Tool allow and deny rules and the default permission mode belong in `.claude/settings.json`. Instruction files are context Claude weighs, not configuration it enforces * **Old workarounds can go**: a `CLAUDE.md` that only imports `AGENTS.md`, a `CLAUDE.md` symlink, or a `SessionStart` hook that prints `AGENTS.md` *** ## Which files Claude Code reads [#which-files-claude-code-reads] With the default setting: | In the repository | What Claude Code reads | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `AGENTS.md` only | `AGENTS.md` | | `AGENTS.md`, plus a `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` on the path | The `CLAUDE.md` files only | | `AGENTS.md`, plus a `CLAUDE.md` that imports it with `@AGENTS.md` | Both: `AGENTS.md` through the import, then the rest of `CLAUDE.md` | | `CLAUDE.md` only | `CLAUDE.md` | The details that change outcomes: * **What doesn't count.** A user's `~/.claude/CLAUDE.md`, an organization's managed `CLAUDE.md`, and `.claude/rules/` files don't stop `AGENTS.md` loading. They load alongside it. * **Nested files.** Every `AGENTS.md` and `.claude/AGENTS.md` from the working directory upward loads at session start. A subdirectory's `AGENTS.md` loads when Claude reads a file in that directory, as long as the directory has no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` of its own. `@path` imports inside `AGENTS.md` are expanded. * **What isn't read.** `AGENTS.local.md`, `AGENTS.override.md`, and anything under `.agents/`. * **`CLAUDE.local.md` counts.** A developer who adds one for personal notes in an `AGENTS.md`-only repository stops Claude Code reading `AGENTS.md` for themselves, with no warning. Start the local file with `@AGENTS.md`, or set **Project instructions** to `claude-md-and-agents-md`. * **The setting is per person.** **Project instructions** (in `/config`) takes `claude-md-or-agents-md` (the default), `claude-md-and-agents-md`, `claude-md`, or `managed-only`. It can be set in user or managed settings, but Claude Code ignores it in a project's settings files, so a repository can't choose it for contributors. Write the repository for the default. * **Checking what loaded.** `/memory` lists the instruction files Claude read. See [Claude Code's memory docs](https://code.claude.com/docs/en/memory#agents-md) for the full rules. ## Sessions that still need a CLAUDE.md [#sessions-that-still-need-a-claudemd] In these sessions Claude Code reads `CLAUDE.md` files only: * Claude Code before v2.1.277 * Before v2.1.281 (23 September 2026), some sessions such as Amazon Bedrock or with telemetry disabled * The built-in `agents-md` plugin disabled in `/plugin` * Sometimes, the first session after upgrading from v2.1.276 or earlier If contributors or automation run in any of these, keep a `CLAUDE.md` that contains `@AGENTS.md`. On newer versions the import never loads `AGENTS.md` twice. ## When to add a CLAUDE.md [#when-to-add-a-claudemd] Only when Claude Code needs instructions that other agents shouldn't get: * Claude Code skills, subagents or slash commands this repository expects Claude to use * Hooks or MCP servers the repository configures for Claude Code that change how Claude should work * Workflow notes that only make sense in Claude Code Keep out of it: * **Anything true for every agent.** Commands, conventions, boundaries and layout belong in `AGENTS.md`. * **Tool rules and permission mode.** Put them in `.claude/settings.json`, where Claude Code enforces them (see below). * **Hard stops.** A rule that must hold whatever Claude decides needs a `PreToolUse` hook, not a sentence. * **Model choice and memory configuration.** Those are decisions about building agents, not context for working in this repository. ## Writing one [#writing-one] Put the import on the first line and only Claude-only lines under it: ```markdown @AGENTS.md ## Claude Code - Run /security-review on changes under src/auth/ and src/crypto/ - The PostToolUse hook in .claude/settings.json formats files after each edit; don't run the formatter by hand ``` In most repositories that need a `CLAUDE.md`, that's the whole file. Claude reads `AGENTS.md` first, then the lines below it. A sentence such as "See AGENTS.md" doesn't load the file. Claude only sees it if it decides to open it, so always use the `@AGENTS.md` import. A symlink (`ln -s AGENTS.md CLAUDE.md`) also avoids duplication, but it leaves no room for Claude-only lines, Claude's edit tools refuse to write through it, and a Windows clone without `core.symlinks` checks it out as a one-line text file. Use the import. ## Tool rules belong in settings [#tool-rules-belong-in-settings] Instruction files are context. Claude Code doesn't enforce a sentence saying "never deploy". Permission rules in `.claude/settings.json` are enforced for everyone who works in the repository: ```json { "permissions": { "allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"], "ask": ["Bash(pnpm db:migrate)"], "deny": ["Bash(vercel deploy *)", "Read(./.env)"], "defaultMode": "plan" } } ``` `deny` and `ask` rules apply straight away; `allow` rules in a project file apply once each contributor trusts the folder. A project file can't set `auto` or `bypassPermissions` as the default mode. Those only take effect from user or managed settings. See [Claude Code permissions](https://code.claude.com/docs/en/permissions) for the rule syntax. ## Moving off an older setup [#moving-off-an-older-setup] | What the repository has | What to do | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | A `CLAUDE.md` containing only `@AGENTS.md` | Delete it, unless some sessions can't read `AGENTS.md` (see above) | | A `CLAUDE.md` that says "see AGENTS.md" in words | Delete it, or replace the sentence with `@AGENTS.md` | | A `CLAUDE.md` that restates `AGENTS.md` | Move anything missing into `AGENTS.md`, then delete the file or cut it to Claude-only lines under the import | | A `CLAUDE.md` symlinked to `AGENTS.md` | Harmless. Delete it when convenient | | A `SessionStart` hook that prints `AGENTS.md` | Remove it. It now adds a second copy to the context | | Tool rules or a permission mode written in `CLAUDE.md` | Move them to `permissions` in `.claude/settings.json` | ## Monorepos [#monorepos] Each package keeps its own `AGENTS.md`, and Claude Code picks it up when it reads a file in that package. A package-level `CLAUDE.md` hides that package's `AGENTS.md` just as a root one does, so if a package needs one, start it with `@AGENTS.md`. See [Monorepos](/docs/context-files/monorepos) for how other tools resolve nested files. ## Auto memory and rules [#auto-memory-and-rules] Claude Code also keeps **auto memory**, notes Claude writes itself from your corrections, and reads `.claude/rules/`, topic files that can be scoped to paths with `paths` frontmatter. Both load alongside `AGENTS.md`. Neither needs a mention in `CLAUDE.md` unless a contributor has to know the repository relies on one. See [Claude Code's memory docs](https://code.claude.com/docs/en/memory) for how both work. ## See also [#see-also] * [AGENTS.md](/docs/context-files/agents-md) - the file every agent reads * [Cursor and Copilot](/docs/context-files/cursor-and-copilot) - other tools' overlays * [Claude Code memory docs](https://code.claude.com/docs/en/memory#agents-md) - instruction file resolution, the Project instructions setting, auto memory and `.claude/rules/` * [Claude Code permissions](https://code.claude.com/docs/en/permissions) - permission rules and modes * `/templates/discovery/CLAUDE.md` - optional starter overlay