Skip to content
Search
DevelopmentGlossary

AGENTS.md

The AGENTS.md site calls it a README for agents: a dedicated, predictable place for the build steps, tests and conventions that coding agents need and that would clutter a README written for people. It's an open format with no required fields, and many coding agents read it, so one file can serve several tools. The format is maintained in the open at agentsmd/agents.md.

Write it the way you'd brief a new contractor: how to install, how to run the tests, what done means, which folders are off limits, and any decision that isn't obvious from the code. Keep it short and current, because the agent reads it at the start of each session and treats it as instructions. In a monorepo you can add an AGENTS.md inside each package; the AGENTS.md site says agents read the nearest file in the directory tree, so the closest one takes precedence. Qurtoo's article on system prompt architecture for coding agents explains how these files sit alongside the agent's own system prompt.

Example

# AGENTS.md

## Setup
- Install dependencies: pnpm install
- Start the dev server: pnpm dev

## Before you finish
- Run pnpm test and pnpm check. Both must pass.
- Add a test next to any new function.

## Rules
- Don't edit files in src/generated/; run pnpm codegen instead.
- Use the existing logger in src/lib/log.ts, not console.log.
- Ask before adding a dependency.

When to use it

  • Any repository where people use AI coding agents
  • Project rules a new contributor would otherwise have to discover by trial and error
  • Monorepos where each package has its own commands

When not to use it

  • Secrets, tokens or passwords, ever
  • Long documentation that already lives in the README or docs folder; link to it instead
  • Rules that change every week and will go stale