How to write a CLAUDE.md or AGENTS.md file that coding agents actually follow

Every major coding agent now reads a plain Markdown file of project instructions at the start of a session. Claude Code calls its file CLAUDE.md. OpenAI's Codex, Cursor, GitHub Copilot and more than 20 other tools read AGENTS.md. As of September 2026, Claude Code reads AGENTS.md too. A good file saves you from repeating the same corrections every session. A bad one gets ignored, or quietly makes the agent worse. This guide covers where each tool looks for its file, what to put in it, how long it should be, and how to check the agent is actually following it. Everything here comes from each vendor's current documentation.

Last verified: October 8, 2026. Documented against Claude Code v2.1.293 (npm latest) and the Codex, Cursor and GitHub documentation as published that day.

Prerequisites

• A git repository you want an agent to work in.
• At least one agent installed: Claude Code (v2.1.277 or later to read AGENTS.md directly; v2.1.281 or later on Amazon Bedrock or with telemetry off), the Codex CLI or IDE extension, Cursor, or GitHub Copilot.
• Five minutes to list the commands you run most often: install, build, test, lint, and a single test file.

Step 1: Decide which file is canonical

AGENTS.md is the cross-tool standard. OpenAI released it in August 2025. On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF) with three founding projects: AGENTS.md from OpenAI, Anthropic's Model Context Protocol, and Block's goose. The agents.md site now says the format "is stewarded by the Agentic AI Foundation under the Linux Foundation." In the same announcement, the Linux Foundation said more than 60,000 open-source projects and agent frameworks had adopted it. That figure comes from the Foundation, not from an independent count.

The format has no required fields. It's ordinary Markdown with whatever headings you like.

Here's what each tool reads, according to its own documentation:

The recommendation: if more than one agent touches your repository, make AGENTS.md the single source of truth. Then add a two-line CLAUDE.md that imports it (Step 4). If only Claude Code will ever read the file, write a CLAUDE.md directly, because it supports features AGENTS.md doesn't (Step 5).

Step 2: Generate a first draft, then cut it down

Don't start from a blank page:

• Claude Code: run /init. Claude analyzes the codebase and writes a starting CLAUDE.md with build commands, test instructions and conventions. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Set CLAUDE_CODE_NEW_INIT=1 for an interactive multi-phase version. That version can also pull in an existing AGENTS.md, .cursorrules, .windsurfrules or .clinerules.
• Migrating from Cursor or Copilot: Anthropic says /init already reads .cursor/rules/, .cursorrules and .github/copilot-instructions.md.

Then cut. Anthropic's docs say the /doctor checkup proposes trims that remove "content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews." It keeps "pitfalls, rationale, and conventions that differ from tool defaults." That's the best one-line summary of what belongs in these files.

Step 3: Write it (template)

This template follows the sections the agents.md site recommends: project overview, build and test commands, code style, testing, and security. It adds the "don't" list most teams discover they need. Replace everything in angle brackets.

# AGENTS.md

## Project
<One or two sentences: what this repo is and the main language/framework.>

## Commands
- Install: `pnpm install`
- Build: `pnpm build`
- Test everything: `pnpm test`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Lint and typecheck (run before finishing): `pnpm lint && pnpm typecheck`

## Conventions that differ from defaults
- Use 2-space indentation; single quotes; no semicolons.
- API handlers live in `src/api/handlers/`; one handler per file.
- Use the `Result` type from `src/lib/result.ts`; don't throw in request handlers.

## Testing
- Add or update a test for every behavior change.
- Tests that hit the network are tagged `@integration` and are skipped in CI; don't add new ones without asking.

## Don't
- Don't edit files under `generated/` (they are rebuilt by `pnpm codegen`).
- Don't add dependencies without saying why in your summary.
- Don't change `.github/workflows/` unless the task is about CI.

## Security
- Never print or commit values from `.env*` files.
- Database migrations go through `pnpm migrate:new`; never edit applied migrations.

## When you finish
- Run lint, typecheck and the affected tests; report the commands and results.

What to include

• Exact commands, including how to run a single test. This is the highest-value content in the file.
• Conventions that differ from what the agent would do by default. If your team does what the language's style guide says, you don't need to repeat it.
• Pitfalls with a reason. "Don't edit generated/ because codegen overwrites it" works better than a bare rule, because the agent can apply the reason to cases you didn't list.
• Boundaries: directories to leave alone, approvals needed, secrets handling.

What to leave out

• Things the agent can read for itself: directory listings, dependency lists, long architecture overviews.
• Vague advice like "write clean code" or "be careful." Anthropic's docs give concrete pairs: "Use 2-space indentation" instead of "Format code properly", and "Run npm test before committing" instead of "Test your changes."
• Multi-step procedures that only matter sometimes. In Claude Code those belong in a skill or a path-scoped rule.
• Secrets, tokens and internal URLs you wouldn't put in a README. These files are committed, and the agent reads them every session.

Step 4: Make Claude Code read the shared file

By default, Claude Code reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. Your personal ~/.claude/CLAUDE.md and an organization's managed CLAUDE.md don't count. That has a non-obvious consequence: adding a personal CLAUDE.local.md silently stops Claude reading your AGENTS.md.

You have three options:

Option A (most robust): import it. Create a CLAUDE.md next to AGENTS.md:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Claude reads the imported file first, then anything Claude-specific below it. Anthropic says keeping the import "never makes Claude read AGENTS.md twice". It also covers sessions where native AGENTS.md support is unavailable, such as versions before 2.1.277.

Option B: a symlink. Run ln -s AGENTS.md CLAUDE.md. Anthropic advises against this if anyone clones the repository on Windows, where git may check the symlink out as a one-line text file.

Option C: change the setting. Type /config and set Project instructions to claude-md-and-agents-md to load both files. Or put it in ~/.claude/settings.json (project and local settings files are ignored for this key):

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

Use agents-md@builtin as the key if anyone runs a version older than 2.1.285. Under the hood, AGENTS.md loading is a built-in mod (cc-plugin-agents-md), Claude Code's new in-process extension type. We explain mods in our explainer on Claude Code mods.

Some Claude Code-only details:

• Claude Code doesn't read AGENTS.local.md, AGENTS.override.md or anything under .agents/.
• Those last two names do mean something to Codex. In each directory it looks for AGENTS.override.md first, then AGENTS.md.

Step 5: Use the hierarchy instead of one giant file

Every tool supports layering in some form.

Claude Code

• Load order: managed policy, then user (~/.claude/CLAUDE.md), then project, then local. Files from the filesystem root down to your working directory are concatenated, not overridden, and the one closest to where you launched is read last.
• Subdirectories: a CLAUDE.md in a subdirectory loads on demand, when Claude reads or edits a file there.
• Imports: @path imports resolve relative to the importing file and nest up to four hops. Imports in code spans and fenced code blocks are ignored.
• Path-scoped rules: files in .claude/rules/ with paths: frontmatter, such as "src/api/**/*.ts", only load when Claude touches matching files. This is the main way to cut context use.
• Maintainer notes: block-level HTML comments (<!-- note -->) are stripped before the content reaches Claude.

Codex

• Codex reads one global file from ~/.codex/ (or CODEX_HOME).
• It then walks from the project root down to your working directory, taking at most one file per directory, and concatenates them so closer files come later.
• It stops adding files once their combined size reaches project_doc_max_bytes, which defaults to 32 KiB.
• Extra filenames can be added with project_doc_fallback_filenames in ~/.codex/config.toml.

Cursor and Copilot

• Both apply the nearest AGENTS.md in the directory tree.
• The agents.md site states the general rule: the closest file wins, and an explicit instruction in chat overrides everything.

How long should it be?

These are the numbers the vendors actually publish:

Last verified: October 8, 2026.

Imports don't save anything. Anthropic notes that @path imports "help you organize a long file but don't reduce its context cost, because imported files also load at launch." Only on-demand mechanisms save context: path-scoped rules, subdirectory files and skills.

Anti-patterns

1. Contradictions across files. Anthropic warns that "if two instructions contradict each other, Claude may pick one arbitrarily." A user rule and a project rule don't override each other. Both are in context.
2. A CLAUDE.md that says "read AGENTS.md" in words. Claude only sees AGENTS.md if it decides to open it. Use the @AGENTS.md import instead.
3. A SessionStart hook that prints AGENTS.md. Now that Claude Code reads the file natively, this adds a second copy to context. Remove it.
4. Using instructions for rules that must never be broken. Claude Code's docs are explicit: CLAUDE.md content arrives "as a user message after the system prompt", and "there's no guarantee of strict compliance." For must-happen behavior, use a hook. A PreToolUse hook can block a command, and a PostToolUse hook can run your formatter. Use permission deny rules for commands that must never run.
5. Fighting built-in behavior. If your file sets commit-message or pull-request rules, Claude Code's own git instructions may compete with them. Turn those off with includeGitInstructions and set attribution instead.
6. Letting it rot. Commands change. Claude Code v2.1.283 and later has /doctor prompt-audit. It checks your CLAUDE.md, CLAUDE.local.md and AGENTS.md files for references to files or commands that don't exist, contradictions, and "instructions written for older models." It only proposes edits and changes nothing until you ask.

Test that the agent follows it

Don't assume. Check in three layers.

1. Is the file loaded?

• Claude Code: run /context and look under Memory files, or /memory, which lists every loaded file including AGENTS.md. When AGENTS.md loads instead of CLAUDE.md, an interactive session shows a line such as no CLAUDE.md found; AGENTS.md loaded: /path/AGENTS.md. For on-demand files, an InstructionsLoaded hook can log what loads and when. That hook doesn't fire for an AGENTS.md read through the Project instructions setting.
• Codex: run codex --ask-for-approval never "Summarize the current instructions." from the repository root. Use codex --cd subdir to check nested overrides. Codex rebuilds the instruction chain every run, so restart it after edits.
• Gemini CLI: /memory show prints the concatenated context.

2. Does it follow the rules? This isn't vendor guidance, just a simple routine: write three to five "canary" prompts that a rule in your file should change. For example:

• "Add a dependency for date parsing." Your file says to justify new dependencies.
• "Fix the typo in generated/schema.ts." Your file says not to edit generated/.
• "Finish up." Your file lists the commands to run before finishing.

Run each prompt in a fresh session. Record pass or fail against the rule, and repeat each prompt three times, because agent behavior varies between runs. Keep the prompts in the repository so you can rerun them after every edit to the file and every agent update.

3. Is it worth the context? Run the same small task with and without the file, and compare the diff and the number of corrections you had to make. If you can't see a difference, the file is too long or too vague. For why public coding-agent leaderboards can't answer this question for your repository, see our coverage of published coding-agent evaluations.

Troubleshooting

• Claude Code ignores AGENTS.md: there's almost certainly a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md on the path. Also check claude --version (2.1.277 or later), and that Project instructions in /config isn't set to claude-md or managed-only. If the setting doesn't appear at all, your session can't load AGENTS.md. Use the import.
• Instructions vanish after compaction: Anthropic says the project-root CLAUDE.md is re-read after /compact. Nested files and path rules reload only when Claude touches matching files again. Instructions given only in chat are lost.
• Codex ignores part of a long file: you've probably hit the 32 KiB cap. Raise project_doc_max_bytes or, better, split by directory.
• Gemini CLI doesn't see AGENTS.md: add it to context.fileName in settings.json.

Security notes

• Treat instruction files from other people as untrusted input. Claude Code asks for approval the first time a project's CLAUDE.md imports a file from outside the working directory. Decline if you don't recognize the files.
• Don't put credentials in any of these files. Put "never print secrets" rules in the file, and enforce them with permission rules or a sandbox. Our comparison of Claude Code, Codex and Cursor covers how each tool sandboxes commands. Our Codex explainer covers Codex's approval modes.