The Ultimate AGENTS.md Handbook

A friendly, field-tested guide for developers who want AI coding assistants—and human teammates—to get up to speed in minutes.

Table of Contents

1. What Is AGENTS.md and Why Should I Care?
2. Anatomy of a Great AGENTS.md File
3. Step-by-Step: Writing Your First AGENTS.md
4. Real-World Templates You Can Copy-Paste
5. Working with Monorepos: One File per Package
6. Common Pitfalls and How to Dodge Them
7. Quick FAQ from the Community
8. Ten-Minute Upgrade: Turn an Existing README into AGENTS.md
9. Appendix: Production-Ready Examples
10. Final Thoughts

1. What Is AGENTS.md and Why Should I Care?

Picture this:
It is Tuesday evening, you are fixing a bug, and you ask your AI assistant to “run the tests.”

• Scenario A (no AGENTS.md): The assistant guesses npm run build, switches your Next.js cache to production assets, and kills hot-reload.
• Scenario B (with AGENTS.md): The assistant reads one short file and quietly runs pnpm test. You ship the fix and go to dinner.

That is all AGENTS.md does—it is a README for machines.
Humans still have README.md for vision statements and contribution guidelines; AGENTS.md gives AI agents the exact commands, conventions, and guardrails they need to stay helpful instead of harmful.

Who Uses It?

• Open-source maintainers (88 AGENTS.md files in the OpenAI repo at the time of writing)
• Internal teams with junior developers who rely on Cursor, Copilot, or Codex CLI
• Solo developers who simply do not want to repeat themselves in chat

Core Promise

One small file, committed to Git, works across every popular agent tool—no vendor lock-in, no extra YAML dialects.

2. Anatomy of a Great AGENTS.md File

Think of five short chapters a new teammate would ask about on day one.

Each section is plain Markdown. Bullet lists work better than paragraphs; code blocks work better than prose.

3. Step-by-Step: Writing Your First AGENTS.md

You need ten lines to get started. Open your editor and follow along.

Step 1: Create the File

touch AGENTS.md

Step 2: Add a Title

# AGENTS.md

Step 3: Environment Setup

## Environment
- Node.js 18 or newer  
- Package manager: pnpm (swap to yarn or npm if your team insists)

Step 4: Development Commands

## Start Development
1. `pnpm install`
2. `pnpm dev`  
   → Opens http://localhost:3000 with hot-reload enabled  
   ⚠️ Do **not** run `pnpm build`; it disables HMR and may corrupt the cache.

Step 5: Code Style Snapshot

## Style Guide
- TypeScript strict mode  
- Single quotes, no semicolons  
- Co-locate CSS Modules next to components

Step 6: Testing One-Liner

## Test
- `pnpm test` runs Jest in watch mode  
- `pnpm e2e` runs Playwright headless

Step 7: Save and Commit

git add AGENTS.md
git commit -m "docs: add AGENTS.md to guide AI assistants"

That is it—your repository is now robot-friendly.

4. Real-World Templates You Can Copy-Paste

Template A: Next.js App Router Project

# AGENTS.md

## Stack
- Next.js 14 with App Router  
- TypeScript strict  
- TailwindCSS  
- Vitest + React Testing Library for unit tests  
- Playwright for e2e

## Quick Start
1. `pnpm install`
2. `pnpm dev` → http://localhost:3000
3. Hot-reload broken? `rm -rf .next && pnpm dev`

## Tests
- Unit: `pnpm test`  
- Coverage gate: 80 %  
- e2e: `pnpm e2e`

## Lint & Format
- `pnpm lint` runs ESLint + Prettier  
- `pnpm format` fixes style issues

## Commit Style
- Conventional Commits  
- PR template: `.github/pull_request_template.md`

Template B: Reusable React Component Library

# AGENTS.md

## Library Purpose
Shared React components used by three internal apps.

## Commands
- Install: `pnpm install`
- Storybook: `pnpm storybook`
- Build: `pnpm build` outputs to `dist/`
- Release: `pnpm release` uses changesets

## Folder Convention
Each component lives in `src/ComponentName/` with:
- `index.ts` (public API)
- `ComponentName.tsx`
- `ComponentName.test.tsx`
- `ComponentName.stories.tsx`

## Tests
- Unit: `pnpm test`
- Visual regression: `pnpm test:vr`
- Must pass before release

Template C: Express API with Prisma

# AGENTS.md

## Environment
- Node.js 20
- PostgreSQL 15 (Docker compose provided)

## Install & Run
1. `pnpm install`
2. `cp .env.example .env` and fill in your DB URL
3. `pnpm db:push` to migrate
4. `pnpm dev` → http://localhost:4000/graphql

## Tests
- `pnpm test` runs Jest with an in-memory SQLite database
- `pnpm test:e2e` spins up a real Postgres container

## Style
- ESLint Airbnb base
- JSDoc required on public functions

5. Working with Monorepos: One File per Package

Large codebases often look like this:

acme-corp/
├─ AGENTS.md                 # root-level notes
├─ apps/web/
│  └─ AGENTS.md             # Next.js specific
├─ apps/docs/
│  └─ AGENTS.md             # Astro specific
└─ packages/ui/
   └─ AGENTS.md             # Storybook & build

AI agents always pick the closest AGENTS.md to the file they are editing, so each package can override or extend instructions without noise.

Example: Package-Specific Override

# apps/web/AGENTS.md

## Overrides for Web App
- Use `pnpm dev:turbo` to enable Turbopack
- Environment variables must be prefixed with `NEXT_PUBLIC_`

6. Common Pitfalls and How to Dodge Them

7. Quick FAQ from the Community

Q1: Can I name the file AGENT.md or ROBOTS.txt instead?
A: Please stick to AGENTS.md. The growing ecosystem (OpenAI Codex, Cursor, Jules, Factory, Amp) looks for that exact name.

Q2: Will AI run commands automatically?
A: Only if you list them explicitly. The agent treats AGENTS.md as a checklist—if you write “run pnpm test before commit,” it will attempt to do so.

Q3: Is AGENTS.md a security risk?
A: It contains no secrets—only public commands and conventions. Keep secrets in .env files, never in AGENTS.md.

Q4: How often should I update it?
A: Treat it like code comments. If a command changes, change the file in the same PR to avoid drift.

Q5: Can I use YAML or TOML instead of Markdown?
A: Markdown is intentionally simple and human-readable. YAML feels like config; AGENTS.md is meant to be skimmed in a browser or editor preview pane.

Q6: Does AGENTS.md replace CONTRIBUTING.md?
A: No. CONTRIBUTING.md covers legal and social rules (CLA, code of conduct). AGENTS.md covers mechanical steps.

8. Ten-Minute Upgrade: Turn an Existing README into AGENTS.md

Step 1: Copy the Relevant Bits

Open README.md and locate:

• Installation section
• “Getting started” commands
• Test instructions
• Style notes

Step 2: Strip Human-Friendly Narrative

Change:

“First, make sure you have Node.js installed, preferably version 18 or later…”
To:

• Node.js ≥ 18

Step 3: Add Robot-Specific Guardrails

Insert after the dev command:

⚠️ Never run `npm run build` during active development; it disables HMR.

Step 4: Save as AGENTS.md

Leave README.md untouched for human readers.

Step 5: Commit

git add AGENTS.md
git commit -m "docs: scaffold AGENTS.md for AI agents"

9. Appendix: Production-Ready Examples

Example 1: Vite + React + TypeScript SPA

# AGENTS.md

## Prerequisites
- Node.js 18
- pnpm

## Quick Start
1. `pnpm install`
2. `pnpm dev` → http://localhost:5173
3. `pnpm build` creates `dist/` (only for CI/production)

## Testing
- `pnpm test` runs Vitest in watch mode
- `pnpm test:ui` launches Vitest UI at http://localhost:51204

## Lint & Format
- ESLint + prettier
- `pnpm lint:fix` auto-fixes

## Environment Variables
Prefix custom env vars with `VITE_`

Example 2: Turborepo Monorepo Root

# AGENTS.md

## Global Commands
- Install all deps: `pnpm install`
- Run dev for every app: `pnpm dev`
- Run tests for every package: `pnpm test`

## Filtering Examples
- Dev only web app: `pnpm dev --filter=web`
- Test only ui package: `pnpm test --filter=ui`

## CI
- GitHub Actions in `.github/workflows/ci.yml`
- Must pass lint, test, and type-check before merge

Example 3: Python FastAPI Service

# AGENTS.md

## Environment
- Python 3.11
- Poetry for dependency management

## Quick Start
1. `poetry install`
2. `poetry run uvicorn app.main:app --reload`

## Tests
- `poetry run pytest`
- Coverage gate: 90 %

## Code Style
- black + isort + flake8
- `poetry run pre-commit install` to auto-format on commit

10. Final Thoughts

AGENTS.md is not another fad. It is a tiny, low-effort contract between you and the growing army of AI coding assistants. Write it once, commit it, and watch both humans and robots stay in sync.

Keep it short, keep it truthful, and keep it next to your code.
The ten minutes you spend today will save hours of “why did the build break?” tomorrow.