What's the difference between AGENTS.md and a README?

READMEs target humans evaluating or contributing to your project. AGENTS.md targets coding agents working in the repo. The agents file is shorter, more imperative, and assumes the reader has full file-system access. Many projects ship both; the AGENTS.md links to the README for human-facing context.

How long should AGENTS.md be?

There is no required or ideal line count. Keep the root file short enough to stay current and specific enough to prevent mistakes. Move deep architecture, domain, and release detail into maintained documents and use AGENTS.md as the map, while keeping critical commands and safety rules inline.

Does Claude Code read AGENTS.md automatically?

No. Anthropic documents that Claude Code reads CLAUDE.md, not AGENTS.md. Add a CLAUDE.md containing @AGENTS.md, or symlink CLAUDE.md to AGENTS.md when symlinks are practical, so Claude Code receives the shared instructions without duplicated copy.

Should AGENTS.md mention which AI model the project was built with?

Rarely useful. Coding agents care what the code looks like and how to work with it now, not which assistant wrote it originally. Skip it unless the model choice has a concrete bearing on conventions an agent must follow.

Can I link out to other Markdown files from AGENTS.md?

Yes. Use AGENTS.md as a concise map to maintained architecture notes, contribution guides, and domain references. Keep commands, non-negotiable constraints, and security rules in AGENTS.md itself, because tools differ in when they load linked files.

Do I need to update AGENTS.md every release?

Only when commands, conventions, or constraints change. Treat it as living documentation — bump it whenever an agent (yours or someone else's) makes a mistake that the file could have prevented. Stale instructions are worse than missing instructions.

How to write an effective AGENTS.md

What is AGENTS.md?

AGENTS.md is a plain-Markdown repository instruction file for coding agents. It tells an agent how to set up, build, test, and safely change your codebase. It is not a package manifest or an Agent Skill: the format has no required schema or fixed headings. The open convention is documented at agents.md and stewarded by the Agentic AI Foundation under the Linux Foundation. For the related terms, see the agent-readability glossary.

Where should AGENTS.md live in your repo?

Put an exact-case AGENTS.md at the repository root. For a monorepo, add narrower AGENTS.md files inside packages that need different commands or rules. The official convention says the nearest file to the code being changed takes precedence, while explicit instructions in the user's prompt override the repository files.

Do not confuse repository discovery with public website discovery. The Agent Ready validator also probes public URL fallbacks such as /agents.md, /.well-known/agents.md, and /docs/AGENTS.md. Those are scanner compatibility paths, not substitutes for the root file that coding tools inspect in a checkout.

Which coding agents support AGENTS.md?

Support is broad, but not identical. Check the tool's current documentation instead of assuming one discovery model applies everywhere. The AGENTS.md, CLAUDE.md, and Cursor rules comparison covers the file formats in more detail.

Codex, Cursor, and GitHub Copilot: These tools have documented AGENTS.md support. Codex loads a hierarchy of AGENTS.md and AGENTS.override.md files; Cursor documents a root AGENTS.md as the simple alternative to project rules; Copilot support depends on the IDE, CLI, cloud-agent, or review surface.
Claude Code: Claude Code does not read AGENTS.md directly. Anthropic says to create a CLAUDE.md that imports it with @AGENTS.md, or use a symlink when appropriate.
Aider and Gemini CLI: Both can use the file after configuration. Aider's config reads AGENTS.md explicitly; Gemini CLI can set AGENTS.md as its context filename. Do not describe either as automatic discovery in every installation.

Step 1 — Create AGENTS.md at the repo root

From your project root, create the file. The exact case matters: AGENTS.md is the conventional filename. Commit it so every contributor and supported agent receives the same project instructions.

# from your repo root
touch AGENTS.md

Step 2 — Define scope and instruction precedence

State that the root file applies repository-wide. In a monorepo, place a nested AGENTS.md in each package that needs different commands, conventions, or safety boundaries. Keep shared rules at the root and only repeat a rule lower down when you are replacing it. The closest applicable file wins; the user's explicit prompt still has higher priority.

Step 3 — Open with a one-sentence project overview

Start with an H1 naming the project and one or two factual sentences describing what the repository contains and its stack. Include a version only when it changes what code the agent should write. Link to the human-facing README for product context instead of duplicating its marketing copy.

Step 4 — Document install, build, and test commands

List copy-pasteable commands for dependency installation, local development, targeted tests, the full test suite, linting, type-checking, and production builds. Include the working directory and prerequisites when they are not obvious. Use fenced blocks tagged bash or sh so the commands are unambiguous.

Step 5 — Spell out conventions, boundaries, and permissions

Record rules an agent can verify: language and framework choices, naming and test conventions, generated or vendored paths that must not be edited, and the quality gates that must pass. State which actions require human approval, including destructive commands, migrations, production changes, releases, and changes to credentials or permissions. “Use TypeScript strict mode” is actionable; “write clean code” is not.

Step 6 — Validate the file with a real agent task

First run every documented command yourself. Then give a supported coding agent a small representative task and note every place it still has to guess. Tighten the file around those failures. If you publish the instructions on your product website, run the public copy through the AGENTS.md validator to check its install, configuration, and usage coverage.

What does a strong AGENTS.md look like?

A complete example covering the six steps above: an imaginary TypeScript SDK with scope, executable checks, conventions, approval boundaries, and links to deeper documentation.

# Acme SDK

> TypeScript client library for the Acme API. Targets Node.js 20+ and modern browsers.

## Scope

- Applies to the entire repository.
- Files under `src/generated/` are generated; never edit them directly.

## Install

```bash
pnpm install
```

## Build & test

```bash
pnpm build          # bundles dist/
pnpm test           # vitest, full suite
pnpm test --watch   # watch mode for the file you're editing
pnpm lint           # eslint + prettier --check
pnpm typecheck      # tsc --noEmit
```

## Run the example

Set `ACME_API_KEY` in your environment, then:

```bash
pnpm tsx examples/quickstart.ts
```

## Conventions

- Public functions take a single options object, never positional args.
- Async functions only; never callbacks.
- All errors throw `AcmeError` subclasses — never plain `Error`.
- Use `#private` field syntax, not TypeScript `private`.
- Tests live next to source as `*.test.ts`, not in a top-level `tests/` dir.

## Safety and approvals

- Never print, commit, or replace API keys.
- Ask before changing public API signatures or adding a production dependency.
- Do not run release, publish, migration, or destructive database commands.

## Don't touch

- `dist/` (generated by `pnpm build`)
- `src/generated/` (codegen from OpenAPI; run `pnpm codegen` to regenerate)
- `CHANGELOG.md` (managed by release-please)

## Further reading

- `docs/architecture.md` — module boundaries and data flow
- `CONTRIBUTING.md` — human-facing contribution guide

The file is short enough to maintain, but every command is copy-pasteable and every constraint changes how an agent acts.

Common pitfalls when writing AGENTS.md

Too much marketing prose. Agents don’t care about your vision; they need facts about how the code works. Cut anything that doesn’t change what they’ll type.
Vague conventions. “Follow our code style” is useless. “Use #private field syntax instead of TypeScript private” is actionable.
Missing “don’t touch” section. Generated files, vendored code, files under release-please control — flag anything an agent should never edit, with the reason in one line.
Assuming every tool loads it the same way. Claude Code needs a CLAUDE.md bridge, Aider and Gemini CLI need configuration, and Copilot support varies by surface. Document the setup your team actually uses.
Stale commands. When you switch package managers or test runners, update AGENTS.md the same commit. An outdated npm test command in a pnpm project breaks every agent session.
Putting secrets or unsafe automation in the file. AGENTS.md is normally committed. Name environment variables, never values, and require approval for destructive, production, release, credential, and permission changes.
Trying to be exhaustive. AGENTS.md is the index, not the encyclopedia. Link out to deeper docs (docs/architecture.md, ADRs) rather than inlining everything.

Primary sources and current tool documentation

Tool behaviour changes. These are the sources used for this guide; check them again when your team changes coding agents.

AGENTS.md open convention — format, nesting, precedence, and configuration examples.
OpenAI: how Codex loads repository instructions.
Anthropic: using AGENTS.md with Claude Code.
GitHub Copilot custom-instruction support matrix.

Frequently asked questions

What's the difference between AGENTS.md and a README?: READMEs target humans evaluating or contributing to your project. AGENTS.md targets coding agents working in the repo. The agents file is shorter, more imperative, and assumes the reader has full file-system access. Many projects ship both; the AGENTS.md links to the README for human-facing context.
How long should AGENTS.md be?: There is no required or ideal line count. Keep the root file short enough to stay current and specific enough to prevent mistakes. Move deep architecture, domain, and release detail into maintained documents and use AGENTS.md as the map, while keeping critical commands and safety rules inline.
Does Claude Code read AGENTS.md automatically?: No. Anthropic documents that Claude Code reads CLAUDE.md, not AGENTS.md. Add a CLAUDE.md containing @AGENTS.md, or symlink CLAUDE.md to AGENTS.md when symlinks are practical, so Claude Code receives the shared instructions without duplicated copy.
Should AGENTS.md mention which AI model the project was built with?: Rarely useful. Coding agents care what the code looks like and how to work with it now, not which assistant wrote it originally. Skip it unless the model choice has a concrete bearing on conventions an agent must follow.
Can I link out to other Markdown files from AGENTS.md?: Yes. Use AGENTS.md as a concise map to maintained architecture notes, contribution guides, and domain references. Keep commands, non-negotiable constraints, and security rules in AGENTS.md itself, because tools differ in when they load linked files.
Do I need to update AGENTS.md every release?: Only when commands, conventions, or constraints change. Treat it as living documentation — bump it whenever an agent (yours or someone else's) makes a mistake that the file could have prevented. Stale instructions are worse than missing instructions.