AGENTS.md: How to Write Instructions for AI Coding Agents

Table of content

AGENTS.md is a markdown file in your repository root that tells AI coding agents how to work on your project. it contains build commands, code conventions, and project structure. Claude Code, Cursor, Codex, and a dozen other tools read it automatically. think of it as a README for robots.

what is AGENTS.md?

AGENTS.md is a markdown file placed in your repository root that provides context and instructions to AI coding assistants. when an agent opens your project, it reads this file first to understand your conventions, build commands, and preferences.

the format emerged in 2025 from Sourcegraph’s Amp team as a vendor-neutral alternative to tool-specific files like .cursorrules and CLAUDE.md. the idea: write instructions once, use them everywhere.

# AGENTS.md

## setup
- install deps: `pnpm install`
- start dev: `pnpm dev`
- run tests: `pnpm test`

## code style
- typescript strict mode
- single quotes, no semicolons
- functional patterns over classes

over 60,000 open-source projects now use AGENTS.md. the Agentic AI Foundation under Linux Foundation stewards the spec.

AGENTS.md vs CLAUDE.md vs .cursorrules

every AI coding tool invented its own config file:

toolconfig file
Claude CodeCLAUDE.md
Cursor.cursorrules, .cursor/rules/
GitHub Copilot.github/copilot-instructions.md
Windsurf.windsurfrules
Aider.aider.conf.yml

maintaining five files with the same content is dumb. AGENTS.md consolidates them into one portable format.

the irony: each AI writes better instructions for itself. copying CLAUDE.md to Copilot’s format often produces worse results than letting Copilot generate its own. but AGENTS.md is generic enough to work across tools without optimization for any.

migration path

rename your existing file and symlink for backward compatibility:

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

for Aider, add to .aider.conf.yml:

read: AGENTS.md

for Gemini CLI, configure .gemini/settings.json:

{ "contextFileName": "AGENTS.md" }

what to put in AGENTS.md

here’s the uncomfortable truth: a good AGENTS.md looks exactly like documentation that should have been in your README. developers who repeat the same context to AI agents 100 times finally write it down. AI tricked us into documenting our code.

but if your README is already comprehensive, AGENTS.md should be tiny. include only what the AI needs that humans don’t:

essential sections

build and test commands

## commands
- `pnpm install` — install dependencies
- `pnpm dev` — start dev server on :3000
- `pnpm test` — run vitest
- `pnpm lint` — eslint + prettier

agents run these automatically. list what they should execute before committing.

code conventions

## style
- typescript strict mode, no `any`
- prefer interfaces over type aliases
- max 80 chars per line
- test files: `*.test.ts` alongside source

the patterns you’d correct a junior developer on.

project structure

## structure
- `src/api/` — API routes
- `src/lib/` — shared utilities
- `src/components/` — React components
- `tests/` — integration tests

helps the agent navigate without scanning every directory.

common pitfalls

## gotchas
- auth uses JWT with 24h expiry (see src/lib/auth.ts)
- database migrations require `pnpm db:push` after schema changes
- env vars must be prefixed with `NEXT_PUBLIC_` for client access

things you’d tell a new team member on day one.

what doesn’t belong

if information helps a human developer, put it in the README. duplicating content wastes context window tokens and creates maintenance burden.

don’t include:

AGENTS.md is for operational context. what the agent needs to modify code, run tests, and ship changes.

directory structure and nesting

for simple projects, one AGENTS.md in the root is enough:

my-project/
├── AGENTS.md
├── src/
├── tests/
└── package.json

for monorepos, use nested files. the closest AGENTS.md to the file being edited takes precedence:

monorepo/
├── AGENTS.md                    # general rules
├── packages/
│   ├── api/
│   │   ├── AGENTS.md            # API-specific rules
│   │   └── src/
│   └── web/
│       ├── AGENTS.md            # frontend-specific rules
│       └── src/
└── pnpm-workspace.yaml

OpenAI’s main repository has 88 AGENTS.md files. each subcomponent gets tailored instructions.

real example

here’s an AGENTS.md from a Next.js project:

# AGENTS.md

## dev environment
- use `pnpm dlx turbo run where <project>` to jump to a package
- run `pnpm install --filter <project>` to add to workspace
- check `name` field in each package.json for correct name

## testing
- CI config lives in `.github/workflows/`
- run `pnpm turbo run test --filter <project>` for all checks
- focus on one test: `pnpm vitest run -t "<test name>"`
- add tests for code you change, even if nobody asked

## code style
- typescript strict
- single quotes, no semicolons
- prefer functional patterns
- no `console.log` in committed code

## pr requirements
- title format: `[<project>] <description>`
- run `pnpm lint && pnpm test` before committing
- squash commits on merge

notice: no project overview, no architecture explanation, no API docs. just operational context the agent needs to make changes.

patterns that work

be specific, not aspirational

bad:

- write clean, maintainable code

good:

- functions under 20 lines
- no nested callbacks deeper than 2 levels
- extract repeated code into utils/

include the “why” for non-obvious rules

## auth
- never log JWT tokens (security requirement)
- always refresh tokens on 401 (mobile clients cache aggressively)

agents follow rules better when they understand the reason.

version your dependencies

## framework versions
- Next.js 16 (use 'use cache' directive, not getStaticProps)
- React 19 (server components by default)

this prevents the agent from suggesting outdated patterns from its training data.

anti-patterns

dumping your entire README

if AGENTS.md is 500 lines, you’re doing it wrong. the agent’s context window is limited. every token spent on your life story is a token not spent on your actual code.

contradicting existing docs

# AGENTS.md
- use npm for package management

# package.json
"packageManager": "pnpm@9.0.0"

agents get confused. they might use npm anyway or ask which is correct. keep files consistent.

overly restrictive rules

- NEVER use any external libraries
- ALL code must be reviewed by three senior engineers
- ALWAYS write 100% test coverage

the agent will either ignore impossible rules or produce worse code trying to follow them.

no update mechanism

AGENTS.md is living documentation. if you write it once and never update it, lessons get lost. see self-updating instructions for automation approaches.

AGENTS.md and context management

vercel ran evals comparing AGENTS.md to skill-based retrieval . AGENTS.md achieved 100% pass rate. skills maxed at 79% even with explicit instructions.

why? no decision point. with AGENTS.md, context is already present. the agent doesn’t decide whether to look something up. the information is just there.

this matters for context window management . AGENTS.md content loads on every turn. keep it small — under 2K tokens ideally. save detailed docs for files the agent can read on demand.

## detailed docs
- API reference: docs/api.md
- architecture decisions: docs/adr/
- deployment guide: docs/deploy.md

point to files rather than inlining everything.

security considerations

researchers found “Rules File Backdoor” attacks where malicious actors inject hidden instructions using unicode characters. AGENTS.md content goes directly into system prompts, creating an attack vector.

don’t copy-paste rules from the internet without reading them. review AGENTS.md files in pull requests like you would code. keep it minimal — the smaller the file, the smaller the attack surface.

getting started

  1. create AGENTS.md in your project root:
touch AGENTS.md
  1. add minimal content — build commands and key conventions:
# AGENTS.md

## setup
- `npm install`
- `npm run dev`
- `npm test`

## style
- typescript, strict mode
- prettier for formatting
  1. ask your AI to scaffold the rest:
read the codebase and suggest additions to AGENTS.md

  1. iterate. when the agent makes a mistake you’ve corrected before, add a rule. this is how procedural memory builds — one correction at a time.

  2. review periodically. delete rules that no longer apply. prune aggressively. a shorter file is a better file.

AGENTS.md works alongside:

the file is documentation. the agent is your reader. write for that audience — and maybe you’ll accidentally end up with docs good enough for humans too.

Topics: ai-coding claude-code workflow agents