AGENTS.md Guide: Format, Example, Claude Code, Codex and Cursor Support

AGENTS.md is a plain Markdown file that tells AI coding agents how to work in your repository: how to build, how to test, which style rules to follow and what never to touch.

It is now read by Codex, Cursor, GitHub Copilot’s coding agent, Gemini CLI and many more, and since Claude Code v2.1.277 (September 2026) Claude Code can read it too.

This guide covers the format, a copyable example, nested files for monorepos, how it compares with CLAUDE.md and .cursor/rules, and what to do when your agent ignores it.

What Is AGENTS.md?

The official agents.md site describes it as “a simple, open format for guiding coding agents.” Think of it as a README written for AI instead of people. Your normal README stays short and friendly for humans.

AGENTS.md holds the extra details an agent needs, such as exact build commands, test steps, code style rules and project gotchas.

The format came out of work between OpenAI Codex, Amp, Google’s Jules, Cursor and Factory. It is now looked after by the Agentic AI Foundation under the Linux Foundation, and the site says it is used by over 60,000 open-source projects.

Why does it matter? Before AGENTS.md, every tool wanted its own file: CLAUDE.md, .cursorrules, GEMINI.md, .github/copilot-instructions.md and more. Teams ended up copying the same rules into five places. AGENTS.md gives you one file that most agents understand.

Which Tools Read AGENTS.md

The agents.md site lists these supporting tools. Some read it automatically, and a couple need one line of config.

If you use Codex, my OpenAI Codex guide covers the CLI and app in more depth. For Gemini CLI limits and setup, see my Gemini CLI guide.

Does Claude Code Read AGENTS.md?

Yes, but with a rule you need to know. For a long time Claude Code only read CLAUDE.md. That changed with v2.1.277 in September 2026.

The official Claude Code memory docs now say Claude Code “can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting.”

The default rule

Note: By default, Claude Code reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.

• These block AGENTS.md: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it.
• These do not block it: your personal ~/.claude/CLAUDE.md, your organization’s managed CLAUDE.md, and .claude/rules/ files. They load alongside AGENTS.md.
• Not read at all: AGENTS.local.md, AGENTS.override.md, or anything in a .agents/ folder.

When it works, you see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md at the start of an interactive session.

The Project instructions setting

Type /config in Claude Code and look for Project instructions. It has four values:

You can also set this in ~/.claude/settings.json under pluginConfigs, using the built-in plugin ID cc-plugin-agents-md@builtin. Before v2.1.285 the ID was agents-md@builtin. Claude Code ignores this entry in project and local settings files.

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

For more Claude Code commands like /config and /memory, keep my Claude Code commands cheat sheet handy.

The File Format

There is no schema. AGENTS.md is plain Markdown, there are no required fields, and you can use any headings you like. The agent simply reads the text. The agents.md site suggests these sections:

• Project overview: what the app does and the main tech stack.
• Build and test commands: the exact commands, copy-paste ready.
• Code style: formatting, naming and patterns to follow.
• Testing instructions: how to run one test, the full suite and linting.
• Security considerations: secrets, auth code and things the agent must never change.
• PR and commit rules: title format and checks to run before committing.

Good rules of thumb:

• Write commands, not wishes. “Run pnpm test” beats “make sure tests pass.”
• Keep it short. Codex stops adding instruction files once they reach 32 KiB by default, and Cursor suggests keeping each rule under 500 lines.
• Be specific about “never” rules, such as “never edit files in migrations/.”
• Treat it as living documentation. Update it when the agent keeps making the same mistake.

A Copyable AGENTS.md Example

Here is a full example for a typical TypeScript web app. Change the commands to match your project.

# AGENTS.md

## Project overview
- Next.js 15 web app with a Node API in `apps/api` and shared code in `packages/`.
- Package manager: pnpm. Node 20+.

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- Run one test file: `pnpm vitest run path/to/file.test.ts`
- Lint and type check: `pnpm lint && pnpm typecheck`
- Add or update tests for any code you change.
- All tests and lint must pass before you finish a task.

## Code style
- TypeScript strict mode. No `any` unless there is a comment explaining why.
- Use named exports. Prefer functional React components.
- Single quotes, no semicolons (Prettier handles this, run `pnpm format`).

## Project rules
- Never edit files in `db/migrations/`. Create a new migration instead.
- Never commit `.env` files or print secrets in logs.
- Put new UI components in `packages/ui/src/components/`.

## Pull requests
- Title format: `[area] short description`, for example `[api] add rate limit`.
- Keep PRs small and focused on one change.
- Run `pnpm lint` and `pnpm test` before committing.

Tip: The agents.md FAQ notes that if you list test commands, agents will try to run them and fix failures before finishing the task. That is one of the biggest wins of a good file.

How to Create Your AGENTS.md

1. Open your terminal at the root of your repository.
2. Create the file: touch AGENTS.md. Most agents can also draft one for you. In Claude Code, /init can generate project instructions.
3. Add the sections above: overview, setup, testing, style, rules and PR guidelines.
4. If you already have a CLAUDE.md or .cursorrules, move its content into AGENTS.md.
5. For Claude Code users, either delete the old CLAUDE.md so Claude reads AGENTS.md directly, or replace its contents with one line: @AGENTS.md.
6. Commit the file so the whole team and every agent get the same instructions.
7. Test it. Ask your agent “Summarize your project instructions” and check that it repeats your rules.

Sharing one file with Claude Code

The Claude Code docs give two ways to keep a single source of truth. The import method works everywhere:

# CLAUDE.md
@AGENTS.md

## Claude-specific notes
- Use plan mode for changes that touch more than 3 files.

Or use a symlink on macOS and Linux:

ln -s AGENTS.md CLAUDE.md

Note: The docs warn that the symlink is a poor fit for Windows teams. Creating one needs Administrator rights or Developer Mode, and Git may check it out as a one-line text file unless core.symlinks is on. Use the @AGENTS.md import instead.

Nested Files and Monorepos

Big repos can have one AGENTS.md per package. The agents.md site says agents read the nearest file in the directory tree, so the closest one takes precedence. OpenAI’s main repository had 88 AGENTS.md files when the site was written.

my-monorepo/
  AGENTS.md              # global rules: pnpm, PR format, security
  apps/
    web/
      AGENTS.md          # Next.js rules, UI tests
    api/
      AGENTS.md          # API rules, database tests
  packages/
    ui/
      AGENTS.md          # component library rules

Each tool handles nesting a little differently:

• Codex walks from the project root (usually the Git root) down to your current folder and takes at most one file per directory, checking AGENTS.override.md first, then AGENTS.md. Files are joined root first, so deeper files appear later and win on conflicts. A global file in ~/.codex loads before all of them.
• Cursor supports AGENTS.md in the root and in subdirectories. Nested files apply to their folder and below, they combine with parent files, and the more specific one wins.
• Claude Code loads every AGENTS.md from your working directory and the directories above it at start. It loads a subdirectory’s AGENTS.md when it opens a file there, as long as that subdirectory has no CLAUDE.md of its own.

Two monorepo tips. Put shared rules in the root file and only package-specific details below, so you do not repeat yourself. And remember that your chat prompt always overrides AGENTS.md, so you can bend a rule for one task without editing the file.

AGENTS.md vs CLAUDE.md vs .cursor/rules

My recommendation for most teams: keep your main rules in AGENTS.md. Use CLAUDE.md only for an @AGENTS.md import plus a few Claude-only notes.

Use .cursor/rules for rules that should only apply to certain files, such as “for *.test.ts, use Vitest.” One Cursor detail catches people out: rules in .cursor/rules must use the .mdc extension, because a plain .md file there is ignored.

Comparing the tools themselves? See Cursor vs Windsurf vs Claude Code vs Cline. For reusable workflows beyond instructions, read my Claude Skills guide.

Troubleshooting: When the Agent Ignores AGENTS.md

Claude Code ignores my AGENTS.md

The usual cause is a CLAUDE.md somewhere on the path. Check these in order, as the Claude Code docs suggest:

1. Look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. If one exists, Claude reads it instead, unless you set Project instructions to claude-md-and-agents-md.
2. Run claude --version and make sure you have v2.1.277 or later. On versions before v2.1.281, some sessions, such as Amazon Bedrock or telemetry-disabled sessions, could not load AGENTS.md, so update to v2.1.281 or later.
3. Open /config and make sure Project instructions is not set to claude-md or managed-only.
4. Run /memory and look for the AGENTS.md path in the list.

Also note that the first session right after upgrading from v2.1.276 or earlier may not load it. It works from the next session on. If you are new to Claude Code, my Claude Code install guide shows how to update.

I added CLAUDE.local.md and AGENTS.md stopped working

CLAUDE.local.md counts as a CLAUDE.md. Set Project instructions to claude-md-and-agents-md to load both.

Codex loads the wrong instructions

Look for an AGENTS.override.md higher in the tree or in your Codex home folder. Run echo $CODEX_HOME to see which home is active. Then ask Codex to “Summarize the current instructions” to confirm what it sees.

Codex seems to cut off the end of my file

The combined instructions hit the 32 KiB default limit. Raise project_doc_max_bytes in ~/.codex/config.toml or split the content into nested files.

Cursor applies a subfolder AGENTS.md in the wrong place

Update Cursor, since early versions only read the root file. In multi-repo workspaces, open the repo you are working on as its own workspace.

The agent reads the file but still breaks a rule

Instructions are context, not hard limits. Make the rule shorter and more specific, move it near the top, and give the exact command. For things that must never happen, use real guards such as tests, CI checks or Claude Code hooks.

FAQ

Where should AGENTS.md go?

Put it in the root of your repository. In monorepos, you can add more AGENTS.md files inside packages. The nearest file to the code being edited takes precedence.

Does AGENTS.md have required fields?

No. It is plain Markdown with any headings you like. Most files cover setup, testing, code style, rules and PR guidelines.

Does Claude Code read AGENTS.md?

Yes, since v2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above. Change this with the Project instructions setting in /config.

Should I delete my CLAUDE.md?

You do not have to. Replace its content with @AGENTS.md and keep any Claude-only notes below it. The import never makes Claude read AGENTS.md twice.

Does Cursor still need .cursor/rules?

No. Cursor reads AGENTS.md on its own. Use .cursor/rules only when you want glob-scoped or on-request rules, and save them as .mdc files.

What happens if AGENTS.md conflicts with my prompt?

Your chat prompt wins. The agents.md site says explicit user prompts override everything in the file.

Is AGENTS.md safe to commit?

Yes, and you should commit it. Just never put secrets, API keys or passwords in it, because every agent and every teammate will read it.

Sources

• AGENTS.md official site
• Claude Code docs: How Claude remembers your project (AGENTS.md section)
• OpenAI Codex docs: Custom instructions with AGENTS.md
• Cursor docs: Rules
• GitHub: Claude Code issue 6235, Support AGENTS.md