AGENTS.md: the open format for coding agents

AGENTS.md is a plain markdown file in your repository root that tells AI coding agents how to work in your codebase. It's an open convention — not owned by any one vendor — and it has become the closest thing the agent ecosystem has to a standard: one file, read by many tools, instead of a different config per assistant.

Who reads it

A growing set of coding agents and editors look for AGENTS.md automatically, and vendor-specific files (like Claude Code's CLAUDE.md) carry the same substance. The practical takeaway: write the content once, ship it as AGENTS.md for broad coverage, and mirror it into vendor files where you use those tools. Many teams simply commit both; our generator emits both from one pass.

What belongs in it

• Setup and commands — install, dev server, build, lint, and tests, with the exact single-test invocation. Wrong or missing commands are the #1 way agents waste time and break builds.
• Testing instructions — what to run before finishing, and what "done" means here.
• Code style and conventions — the rules your reviewers actually enforce, written imperatively.
• PR expectations — scope, description style, what must be green before opening one.

A complete example

# AGENTS.md

## Project

**acme-storefront** — e-commerce frontend.
Stack: TypeScript, Next.js (App Router), pnpm, Vitest.

## Setup and commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Build: `pnpm build`
- Run all tests: `pnpm test`
- Run a single test: `pnpm vitest run path/to/file.test.ts -t "name"`
- Lint: `pnpm lint`

## Testing

Tests use Vitest. Write or update tests alongside behavior changes;
run the full suite before finishing.

## Code style and conventions

- Components are Server Components by default — add `"use client"`
  only when the component needs state, effects, or browser APIs.
- Never commit secrets. `.env*` files are local-only.
- After changes, run tests and lint before considering work done.

## Pull requests

- One focused change per PR; describe what and why.
- Tests and lint must pass before opening.

AGENTS.md vs CLAUDE.md

CLAUDE.md is Claude Code's native instruction file; AGENTS.md is the tool-agnostic standard. Same job, different scope. If your team uses multiple agents, maintain AGENTS.md as the source of truth. If you're all-in on Claude Code, CLAUDE.md gets you Claude-specific loading behavior. Committing both costs nothing — they're small files — and covers every tool. See also our CLAUDE.md guide.

Keeping it useful

• Review changes to it in PRs like code — agents trust it over their own exploration, so a stale file actively misleads.
• Keep it short and imperative; 60 good lines beat 400 thorough ones.
• When an agent makes the same mistake twice, that's a missing line — add it.