If you’ve used Claude Code, Cursor, Codex, Aider, Gemini CLI, GitHub Copilot, Grok, goose, or similar tools, you’ve seen the same pattern: the agent’s first priority is context. What is this project? How do I build it? How do I run the tests? What conventions should I follow? What must I not break?
AGENTS.md is the open answer. It’s a single Markdown file placed at the root of your repository that serves as a dedicated, predictable briefing for AI coding agents. Think of it as a README written specifically for the agent instead of a human. The format is deliberately simple and tool-agnostic — one file that works across many agents.
AGENTS.md was pioneered by OpenAI's Codex and shaped alongside tools like Cursor, Amp, Factory, and Google's Jules. In December 2025 it was donated to the Agentic AI Foundation under the Linux Foundation, where it's now stewarded as an open standard.
Most AGENTS.md files fail in one of two ways: they’re either too thin to be useful or they’re long, rambling documents the agent skims and mostly ignores. A good AGENTS.md sits in the middle — short, current, specific, and actionable.
This distinction determines everything that belongs in the file.
Do not duplicate content from the README. If the agent doesn’t need it to act effectively, leave it out. Every non-essential line dilutes the signal.
The highest-value sections, in rough priority order.
One-line orientation. A single sentence telling the agent what the project is and what stack it uses — for example, “A TypeScript REST API on Node 20 with Postgres, deployed to Fly.io.”
Setup and build commands. The single most valuable section. Give the real, copy-pasteable commands:
npm install
npm run build
npm run dev
How to run tests. Even more important than build commands — tests are how the agent verifies its own work:
npm test # all tests must pass before considering a change complete
npm run lint
npm run typecheck
Where things live. A short, focused map of key directories and entry points — not a full tree dump.
Conventions. Specific patterns you want followed: validation approach, error handling, naming, preferred libraries, architectural decisions. Vague statements like “write clean code” are useless; specific rules like “Validate all input with Zod at the route boundary” are useful.
Commit and PR rules. Message format, branch naming, changelog updates, and any other process requirements.
Guardrails — what NOT to do. The landmines that prevent expensive mistakes: don’t edit files in /generated
, never run migrations against production config, and don’t commit directly to main.
A bad AGENTS.md doesn’t just fail to help — it actively misleads the agent.
.env
, secrets manager) instead.AGENTS.md files rot when no one owns them. Treat the file the same way you treat production code:
A useful habit: every time you find yourself giving the same instruction to an agent twice in chat, move that instruction into AGENTS.md.
The strength of AGENTS.md is that it isn’t tied to any single tool. Most major coding agents either read it directly or converge on the same root-level instruction pattern. Write plain Markdown with tool-agnostic instructions. Avoid “if you are using X tool” branching.
For monorepos, you can place additional AGENTS.md
files in subdirectories. Most agents use the nearest file to the code they’re working on.
A TypeScript REST API on Node 20, Postgres, deployed to Fly.io.
## Setup
npm install
cp .env.example .env # fill in DATABASE_URL
## Build & run
npm run build
npm run dev # http://localhost:3000
## Test — all must pass before a change is considered done
npm test
npm run lint
npm run typecheck
## Structure
- src/routes/ HTTP handlers
- src/db/ Postgres queries (use the query builder, no raw SQL)
- src/lib/ shared utilities
- test/ Vitest tests, mirroring src/ structure
## Conventions
- Validate all input with Zod at the route boundary
- Throw AppError (from src/lib/errors.ts), never a bare Error
- Match the style and patterns of the surrounding file
## Commits & PRs
- Use Conventional Commits (feat:, fix:, chore:)
- One logical change per PR
- Update CHANGELOG.md when relevant
## Don't
- Don't edit anything in src/generated/ (regenerated from schema)
- Don't commit directly to main — always branch and open a PR
- Never run db:reset against a non-local DATABASE_URL
An agent (or a new human teammate) can read this in under 30 seconds and start being productive.
You’ll know it’s working when a fresh agent can land a correct, tested change in your repository without asking how to build, how to test, or which conventions to follow — and without touching the one thing you explicitly told it not to touch.
Short. Current. Specific. Actionable. That’s the entire job.
This was the field guide — the why and the what.
Coming next in the series: a step-by-step build-along, where we’ll write a complete AGENTS.md against a real repo, then point an agent at it and watch it build, test, and respect the guardrails without being asked. (A day or two out.)