CLAUDE.md and AGENTS.md files: how to write and share them

CLAUDE.md is a Markdown file of instructions that Claude Code loads at the start of every session, so it knows your build commands, conventions and project rules without you repeating them. AGENTS.md is the open, tool-neutral version of the same idea, and Claude Code can now read it too, so one well-kept file can serve Claude Code, Codex, Cursor and most other coding agents.

For the rest of Claude Code, see our practical guide to using Claude Code. Product details come from Anthropic's Claude Code memory docs and the AGENTS.md site as of October 12, 2026.

CLAUDE.md vs AGENTS.md at a glance

What CLAUDE.md is

Each Claude Code session begins with a fresh context window. CLAUDE.md files carry what Claude should know from one session to the next: you write them in plain Markdown, and Claude reads them at the start of every session. There's no required format, but the docs recommend grouping instructions under headers and bullets rather than dense paragraphs.

Claude Code also keeps a second, separate memory. Auto memory is notes Claude writes for itself about your corrections and preferences, stored per repository in ~/.claude/projects/<project>/memory/. The first 200 lines or 25KB of its MEMORY.md index load into every session. When you say "remember that the API tests need a local Redis," Claude saves that to auto memory. To put something in CLAUDE.md instead, ask Claude to "add this to CLAUDE.md," or open the file with /memory.

Where CLAUDE.md files live

The project file is what most teams mean by "the CLAUDE.md." The managed file is for organization-wide rules that IT or DevOps deploys with MDM, Group Policy, Ansible or similar tools, and individual settings can't exclude it. Admins can also put the same kind of text in the claudeMd key of managed settings instead of shipping a file.

How CLAUDE.md files load

• At launch, Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Start Claude in foo/bar/ and it reads both foo/CLAUDE.md and foo/bar/CLAUDE.md.

• Files add up instead of overriding each other. Content runs from the filesystem root down to your working directory, so the file closest to where you started is read last. In each directory, CLAUDE.local.md comes after CLAUDE.md.

• Across scopes, the order is managed, user, project, then local, so a project instruction appears in context after a user instruction.

• Subdirectory files load on demand, when Claude reads, writes or edits a file in that subdirectory.

• After /compact, Claude re-reads the project-root CLAUDE.md from disk. Nested files and path-scoped rules load again the next time Claude touches a matching file.

Run /context and check the Memory files list to see what loaded at launch. In a monorepo where other teams' files get picked up, add a claudeMdExcludes list of paths or globs to .claude/settings.local.json so the exclusion stays on your machine:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Import other files with @path

A CLAUDE.md can pull in other files with @path/to/file, anywhere in the text:

• Relative paths resolve from the file that contains the import, not from your working directory.

• Imported files can import others, up to four hops deep.

• A path inside backticks stays literal, so you can mention a file without loading it.

• The first time a project imports a file from outside the working directory, Claude Code shows an approval dialog. Decline and those imports stay off.

• Imports keep a long file organized, but they don't save context, because imported files also load at launch.

Scope rules to part of the codebase

For instructions that only matter for some files, add Markdown files to .claude/rules/. A rule without frontmatter loads at launch, like .claude/CLAUDE.md. A rule with a paths field loads only when Claude reads, writes or edits a matching file:

paths is the only frontmatter field Claude Code reads from a rule. Personal rules that apply to every project go in ~/.claude/rules/.

Generate a starting file with /init

Run /init and Claude analyzes your codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. It also reads Cursor rules (.cursor/rules/ or .cursorrules) and .github/copilot-instructions.md and folds in the relevant parts.

Set CLAUDE_CODE_NEW_INIT=1 before running /init for an interactive version. It asks which artifacts to set up (CLAUDE.md files, skills and hooks), explores the codebase with a subagent, asks follow-up questions, and shows you a proposal before it writes any files. With the variable set, /init also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.

Treat the output as a draft. The docs suggest refining it with what Claude wouldn't discover on its own.

What AGENTS.md is

The AGENTS.md site describes it as "a simple, open format for guiding coding agents" and says more than 60,000 open-source projects use it. The site calls it a README for agents: a predictable place for build steps, test commands and conventions that would clutter a README written for humans. It came out of work across the AI tools ecosystem, including OpenAI Codex, Amp, Google's Jules and Cursor, and the Agentic AI Foundation under the Linux Foundation now stewards it.

There are no required fields. It's plain Markdown with whatever headings you like. In a monorepo, you put another AGENTS.md in each package; the site says agents read the nearest file in the directory tree, the closest one wins, and an explicit chat prompt from the user overrides everything.

Which tools read AGENTS.md

The AGENTS.md site lists compatible agents including OpenAI's Codex, Cursor, Google's Jules and Gemini CLI, GitHub Copilot's coding agent, Devin, Windsurf, Zed, Warp, VS Code, Aider, goose, opencode, Junie, Amp and RooCode. A few need a setting, and the site's FAQ shows two:

• Aider: add read: AGENTS.md to .aider.conf.yml.

• Gemini CLI: set { "context": { "fileName": "AGENTS.md" } } in .gemini/settings.json.

Claude Code's own docs say it reads AGENTS.md directly from v2.1.277. If you're still choosing between the two most common agents, Codex vs Claude Code compares them, including how each handles instruction files.

How Claude Code reads AGENTS.md

By default, Claude Code reads AGENTS.md only when there's no CLAUDE.md in your working directory or above it:

Some caveats apply:

• CLAUDE.local.md counts. Adding a personal CLAUDE.local.md to a repo that relies on AGENTS.md stops Claude from reading AGENTS.md for you. Your ~/.claude/CLAUDE.md, the managed CLAUDE.md and .claude/rules/ files don't count, and they keep loading alongside AGENTS.md.

• Some file names are ignored. Claude Code doesn't read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory.

• Some sessions can't read it. Older versions, sessions where someone disabled the built-in plugin that reads AGENTS.md with /plugin, and in some cases the first session after an upgrade read CLAUDE.md only.

To change the default, type /config and set Project instructions to one of four values:

The same setting can live in ~/.claude/settings.json, a --settings file or managed settings. Claude Code ignores it in project and local settings files.

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Older versions only recognize the plugin's previous ID, agents-md@builtin, which current versions also accept, so use that one if older installs read the same settings file. To confirm Claude read your AGENTS.md, run /memory and look for its path.

Keep one source of truth for both

If your team uses more than one coding agent, write the shared instructions once, in AGENTS.md, and point Claude Code at it. There are three ways to do that.

Option 1: AGENTS.md alone

With no CLAUDE.md anywhere on the path, current versions of Claude Code read AGENTS.md by default. It's the least setup. It also breaks quietly when someone adds a CLAUDE.local.md or runs an older version, and Claude Code's InstructionsLoaded hooks don't fire for an AGENTS.md read this way.

Option 2: a thin CLAUDE.md that imports AGENTS.md

Put @AGENTS.md at the top of a CLAUDE.md next to it, and add anything only Claude Code needs below:

Claude reads the imported file first, then the rest. This is the setup we'd pick for most teams. It works in sessions that can't read AGENTS.md directly, a teammate's CLAUDE.local.md doesn't break it, and the docs say keeping the import never makes Claude read AGENTS.md twice, whatever Project instructions is set to. Everyone on other agents keeps reading AGENTS.md as before.

Option 3: a symlink

If you don't need Claude-specific content, ln -s AGENTS.md CLAUDE.md also works. The docs list two catches. Claude's Edit and Write tools refuse to write through a symlink, so Claude edits AGENTS.md instead. And on Windows, creating a symlink needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md. If anyone on the team uses Windows, use the import.

Whichever you choose, run /context in your next session and confirm CLAUDE.md appears under Memory files.

Clean up older workarounds

• If a CLAUDE.md tells Claude in words to read AGENTS.md, Claude sees AGENTS.md only if it decides to open it. Replace that sentence with an @AGENTS.md import.

• Remove any SessionStart hook that prints AGENTS.md. Once Claude reads AGENTS.md directly, the hook adds a second copy to the context.

If you're moving to Claude Code from Codex, Gemini CLI or Cursor, /import brings that tool's configuration over, appending a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md. A copy can drift from the original, so for a file other agents still read, the import line from Option 2 is easier to keep in sync.

Best practices: what to put in CLAUDE.md and AGENTS.md

Keep the file to facts Claude needs in every session. Anthropic's best practices page lists what earns a line:

• Bash commands Claude can't guess, such as how to run a single test file

• Code style rules that differ from the defaults

• Testing instructions and preferred test runners

• Repository etiquette, such as branch naming and PR conventions

• Architectural decisions specific to your project

• Developer environment quirks, such as required environment variables

• Common gotchas and behavior that isn't obvious from the code

Write each instruction so someone could check it. The docs' own examples: "Use 2-space indentation" instead of "Format code properly," "Run npm test before committing" instead of "Test your changes," and "API handlers live in src/api/handlers/" instead of "Keep files organized."

The docs also say when to add a line: when Claude makes the same mistake a second time, when a code review catches something Claude should have known about the codebase, when you type the same correction you typed last session, or when a new teammate would need the same context.

If you'd rather start from written rules than a blank page, cubic's code review standards group review rules by language and framework, and the page says you can paste them into AGENTS.md so your coding agent follows them too. Each rule in the code review agents library also has its own page, with a version to copy into AGENTS.md or CLAUDE.md. For an API like the one in the example below, Require API Auth, Validation, and Tenant Scoping flags endpoints that skip auth, accept unvalidated request bodies or leak internal errors.

What to leave out, and where it goes instead

For each line, the best practices page suggests asking: "Would removing this cause Claude to make mistakes?" If not, cut it. It also warns that bloated CLAUDE.md files cause Claude to ignore your actual instructions. Leave out:

• Anything Claude can figure out by reading the code, including file-by-file descriptions of the codebase

• Standard language conventions Claude already knows

• Detailed API documentation (link to it instead)

• Information that changes often

• Long explanations and tutorials

• Self-evident practices like "write clean code"

Some instructions are real but belong somewhere else:

A copyable CLAUDE.md and AGENTS.md example

This is a shared AGENTS.md for a TypeScript monorepo, with the thin CLAUDE.md from Option 2 next to it. Swap in your own commands, paths and rules.

@AGENTS.md

<!-- Shared rules live in AGENTS.md. Only Claude Code specifics go here. -->

@AGENTS.md

<!-- Shared rules live in AGENTS.md. Only Claude Code specifics go here. -->

@AGENTS.md

<!-- Shared rules live in AGENTS.md. Only Claude Code specifics go here. -->

Block-level HTML comments in a CLAUDE.md, like the one above, are stripped before the content reaches Claude, so notes for maintainers cost no context. Add the .claude/rules/ file from earlier for API-only rules, and the setup is complete.

Keep it short and current

• Aim for under 200 lines per CLAUDE.md. The docs say longer files use more context and reduce adherence. Claude Code loads a file of up to 4 MiB in full and skips a larger one, and it shows a warning at startup and in /status when a file runs past the recommended length.

• For a checked-in CLAUDE.md, /doctor proposes cuts for content Claude can derive from the codebase, such as directory layouts, dependency lists and architecture overviews, and keeps pitfalls, rationale and conventions that differ from tool defaults.

• /doctor prompt-audit (v2.1.283 or later) checks your CLAUDE.md, CLAUDE.local.md and AGENTS.md files, plus the rules, skills and commands under .claude/, for outdated or conflicting instructions. Nothing changes until you ask Claude to apply the proposed edits.

• If Claude keeps skipping one instruction, the docs suggest adding "IMPORTANT" to that line alone. Emphasize many lines and none of them stands out.

• If two instructions contradict each other, Claude may pick either one. Review nested files and rules together, not one at a time.

Instructions are context, not enforcement

Anthropic's docs say Claude treats CLAUDE.md as context, not enforced configuration. Its content arrives as a user message after the system prompt, and there's no guarantee of strict compliance, especially for vague or conflicting instructions. For a step that must always run, use a hook. For a hard block, use permission rules.

That leaves the question of whether the code that comes out follows your rules. According to cubic's AI coding statistics, Claude Code wrote 78.1% of the AI-written code cubic reviewed in the latest week, more than any other coding agent, and Bug Bench ranks the models used inside it by bug rate. The share covers reviewed code, not the whole market, but it means a lot of code is being written against these files. Checking it is a review job, and cubic's AI code review reads CLAUDE.md and AGENTS.md as context when it reviews pull requests. For rules you want flagged on every PR, how to enforce coding standards on AI-written code shows how to turn them into review checks.

FAQ

What is a CLAUDE.md file for?

It gives Claude Code persistent instructions, so every session starts out knowing your build commands, conventions and project-specific rules. Claude Code loads it at the start of each session from the project, your home directory and any managed location. Without one, Claude has to re-explore the codebase each time and sometimes guesses.

Is AGENTS.md the same as CLAUDE.md?

They do the same job, but AGENTS.md is an open format that many agents read, while CLAUDE.md is Claude Code's own file with extras like local files, managed policy files and path-scoped rules. Current versions of Claude Code read AGENTS.md too, by default only when there's no CLAUDE.md. To use both, import AGENTS.md from a CLAUDE.md with @AGENTS.md.

How long is too long for a CLAUDE.md?

Anthropic's docs recommend keeping each CLAUDE.md under 200 lines, because longer files use more context and reduce adherence. Claude Code warns at startup and in /status when a file passes the recommended length, and it skips any file over 4 MiB. Move rules for one part of the codebase into .claude/rules/ and procedures into skills.

Is CLAUDE.md really useful?

Yes, for facts Claude can't infer from the code: how to run one test, an environment quirk, a convention that differs from the default. It gets less useful as it grows, since the docs warn that bloated files cause Claude to ignore the instructions that matter. Keep it short, and treat it as guidance rather than a guarantee.

Why not use CLAUDE.md?

The usual reason is that the repo already has an AGENTS.md for other agents. Claude Code reads that file when no CLAUDE.md exists, so you only need a CLAUDE.md for Claude-specific notes, ideally one that imports AGENTS.md so the two never drift apart.