How to Write a Good AGENTS.md

AGENTS.md is a plain Markdown file at the root of a repository that tells any coding agent how to work in it: setup commands, test commands, code style and review rules. There is no required schema. Write it like a note to a new teammate, keep it short, and put Claude-specific lines in a CLAUDE.md that imports it. Facts checked 31 October 2026.

What you will have at the end

• An AGENTS.md you can commit today
• Nested files for the packages that need their own rules
• A working setup so Claude Code, Codex and other agents read the same file
• A short list of mistakes that make the file useless

If you only use Claude Code, our CLAUDE.md guide is the better starting point. This page matters when more than one tool touches the repo, which is common now that AI coding agents come in a dozen shapes.

What the format is

The site agents.md describes AGENTS.md as a simple, open format for guiding coding agents, and as a README for agents. The README is for humans: quick starts, descriptions and contribution notes. AGENTS.md holds the extra detail agents need, such as build steps, tests and conventions that would clutter a README or do not matter to a human contributor.

The project says it emerged from work across OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and that it is now stewarded by the Agentic AI Foundation under the Linux Foundation. The site lists many compatible tools, including Codex, Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Gemini CLI, Cursor, Amp and GitHub's Copilot coding agent. Check a tool's own docs before relying on its support, since the list is the project's claim, not a test we ran.

Step 1: Create the file

At the root of the repository, create AGENTS.md. Most coding agents can scaffold one if you ask. The site suggests these sections as the popular choices.

• Project overview
• Build and test commands
• Code style guidelines
• Testing instructions
• Security considerations

Add anything else you would tell a new teammate: commit message format, pull request rules, gotchas with large datasets, deployment steps.

Step 2: Write the setup and test commands first

If the file only does one job, it should be this one. An agent that cannot run your tests cannot check its own work. Give exact commands, including how to run a single test and how to run the checks for one package.

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Testing instructions
- CI plan lives in `.github/workflows/`
- Run one package's checks: `pnpm turbo run test --filter <project_name>`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix any test or type errors until the whole suite is green
- After moving files or changing imports, run `pnpm lint --filter <project_name>`

This is based on the example on agents.md, lightly trimmed. Notice that each line is a command or a rule with a clear check. That is what separates a useful file from a vague one.

Step 3: Add code style, but only what differs

The agents.md sample has a short style block: TypeScript strict mode, single quotes with no semicolons, functional patterns where possible. Three lines that an agent can follow and a reviewer can check.

Leave out what a linter already enforces, because the agent will see lint failures when it runs the command you gave it. Leave out what is obvious from the code. Put in the rules that surprise people.

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
- Do not import from `src/legacy/` in new code

Step 4: Say how to open a pull request

Agents that open pull requests need your format spelled out, or each one invents its own.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing
- Keep PRs to one concern; link the issue in the description

If your team has rules about signing commits or about trailers on commit messages, state them here too, in plain words. Agents follow a written rule far more often than an unwritten one.

Step 5: Add security notes that an agent can act on

A security section is only useful if it names something the agent could otherwise do wrong. Compare these two.

A file cannot enforce any of these. If one must hold without exception, enforce it in the tool's own permission settings and treat AGENTS.md as the explanation. Our hooks guide shows how that works in Claude Code.

Step 6: Split it for a monorepo

For a large repository, place another AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence and each subproject can carry its own instructions. As of the agents.md page, the main OpenAI repository has 88 of them, which shows the format scales to a very large codebase.

repo/
├── AGENTS.md              # shared commands, PR format, global rules
├── apps/
│   └── web/
│       └── AGENTS.md      # Next.js specifics, how to run e2e tests
└── packages/
    └── ui/
        └── AGENTS.md      # component conventions, Storybook command

Keep the root file about what is true everywhere, and let each package file say only what differs. If both files repeat a rule, a future edit will update one and not the other.

How Claude Code reads AGENTS.md

Claude Code reads AGENTS.md as project instructions from version 2.1.277. The behavior depends on what else is in the repo.

Your own ~/.claude/CLAUDE.md, your organization's managed file and .claude/rules/ files do not count in that check and keep loading alongside AGENTS.md. In subdirectories, Claude reads a subdirectory's AGENTS.md when it opens a file there with the Read tool and that folder has none of the three CLAUDE.md files of its own. It does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory.

The surprise: adding a personal CLAUDE.local.md makes Claude stop reading AGENTS.md for you, because the local file counts. To keep both, open /config and set Project instructions to claude-md-and-agents-md.

The one-file setup

To keep AGENTS.md as the single source and still add Claude-only rules, put an import in a CLAUDE.md next to it.

@AGENTS.md

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

Claude reads the imported file first, then the rest. The docs say you can leave an old @AGENTS.md workaround in place, since Claude Code never reads the file twice. Remove a SessionStart hook that prints AGENTS.md, because it would add a second copy.

When it does not load

If Claude seems unaware of your AGENTS.md, check in this order.

1. Look for a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above, other than your home one.
2. Run claude --version and confirm v2.1.277 or later.
3. Open /config and confirm Project instructions is not claude-md or managed-only.

Run /memory to see whether the file is in the loaded list. Differences also exist: InstructionsLoaded hooks do not fire for an AGENTS.md read directly, though they do for one a CLAUDE.md imports.

Other tools

Most tools in the compatible list read AGENTS.md without setup, so for Codex, Amp and similar agents the file at the root is enough. Cursor and others also keep their own rule formats, and a few tools need a setting turned on.. If a tool does not read the file, a short tool-specific file that points to it is a fine fallback.

See our pages for Codex, Cursor and Gemini CLI for each tool's own configuration.

A complete example for a small web app

Here is a full file for an imaginary TypeScript web app, stitched from the sections above. Every figure in it is an example, not a recommendation.

# AGENTS.md

## Overview
Customer portal. Next.js front end in apps/web, shared UI in packages/ui.

## Setup commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Unit tests: `pnpm test`
- One test: `pnpm vitest run -t "<test name>"`

## Code style
- TypeScript strict mode
- Server code never imports from `apps/web/components`
- New endpoints validate input with the zod schemas in `src/api/schemas/`

## Security
- Never read or print `.env`; variable names live in `.env.example`
- Do not call production URLs; staging is in `docs/staging.md`

## PR instructions
- Title format: [<package>] <Title>
- Run `pnpm lint` and `pnpm test` before committing
- One concern per PR

It runs to about thirty lines. That is the right order of size for a file that every agent in the repo reads on every task. When you feel the urge to add a paragraph on architecture, ask whether the agent could find it by opening the folder.

Keep it alive

A file is only as good as its last edit. Three habits help.

1. Fix it in the same pull request. When a script name, a test command or a rule changes, change AGENTS.md in that pull request. Reviewers can catch the mismatch because both edits sit in one diff.
2. Add a line after a repeated correction. If you tell an agent the same thing twice, the file is missing a line. This is the same rule Claude Code's docs give for CLAUDE.md.
3. Run an audit. For Claude Code, /doctor prompt-audit covers AGENTS.md as well as CLAUDE.md, and reports stale references and contradictions without changing files. For other tools, ask the agent to check each command in the file against the repo, then run each one yourself.

Review the file when a new tool joins the team. Different agents trip on different things, and the new one often exposes a missing line.

Moving an existing rules file over

If you already maintain a tool-specific file, such as a Cursor rules folder or a long CLAUDE.md, do not copy it whole into AGENTS.md. Sort its lines first.

Then delete the duplicates from the tool-specific file, so a future edit has one place to land. A short pointer line in the old file is better than a second copy that will drift.

Mistakes that make the file useless

• Copying the README. Agents can read the README. Do not repeat it.
• Principles in place of commands. "Write maintainable code" changes nothing.
• Length. Long files crowd the context the agent needs for your task. Claude Code's own docs recommend under 200 lines for CLAUDE.md, and the same logic applies here.
• Contradictions between root and nested files. The nearest file wins, which hides the conflict until it bites.
• Stale commands. A wrong test command teaches the agent to distrust the file. Update it in the same pull request that changes the script.
• Secrets. The file is committed. Never put keys or tokens in it.

Common questions from teams

Should AGENTS.md hold personal preferences? No. It is committed and shared. Personal habits belong in a home-folder file or a gitignored local file for the tool you use. Remember the Claude Code catch: a local CLAUDE.md file changes which file Claude reads.

How do two agents with different strengths share one file? Write to the lowest common behavior. Both need the same test command, the same PR format and the same off-limits paths. Anything one tool can do that the other cannot, such as importing files, goes in that tool's own file.

Do I need a test to know the file works? A simple one helps. Start a fresh session in each tool and ask it, without hints, to run the single-test command from the file. If it finds the command on its own and runs it, the file is loaded and readable. If it asks you for the command, the tool did not read the file, and you should check that tool's loading rules.

What about very large files that someone insists on keeping? Split by package with nested files. The nearest-file rule exists for exactly this case, and it keeps each file small enough that an agent reads all of it.

Our take

AGENTS.md wins on one point: it is the file most tools agree on, so one honest file serves a team where people use different agents. We would write it once, keep it small, and treat each tool's own file as a thin layer on top.

If your whole team uses Claude Code, a CLAUDE.md alone is fine and gives you imports, path rules and the audit command. If the team is mixed, start with AGENTS.md and add the one-line import. Moving from one to the other later takes a minute.

Checklist

• AGENTS.md at the repo root, committed
• Setup, test and single-test commands that actually run
• Style rules limited to what differs from defaults
• PR and commit rules in plain words
• Nested files only where a package truly differs
• A CLAUDE.md with @AGENTS.md if Claude Code is in use
• No secrets, no README copy, no stale commands

Related pages

• Write a good CLAUDE.md
• Claude Code hooks guide
• Choose an AI coding agent
• AI coding agents
• Claude Code