Coding agents read your repo before they write code, and the file they read first is AGENTS.md. It is the open convention that Codex CLI, Cursor, Aider, OpenHands, and a growing list of other tools agreed on so a single context file works across every agent. For API development teams, that file is the difference between an agent that runs the right tests against a real local server and one that hallucinates endpoints and ships a broken client.
This guide covers what AGENTS.md is, why API teams should treat it as production code, the sections that matter for OpenAPI-first repos, concrete examples, and how to keep it fresh as the API evolves. We pair it with Apidog at the end so the agent’s contract testing flow stays grounded in a real spec.
TL;DR
AGENTS.mdis a plain Markdown file at the repo root that tells coding agents how to navigate, build, test, and ship code in your project.- The convention is open and supported across Codex CLI, Cursor, OpenHands, Aider, Claude Code, and other agent tooling.
- For API teams, the sections that pay back the most are build commands, the OpenAPI spec path, mock server endpoints, contract test commands, auth setup, and “do-not-touch” zones.
- Keep it short. 200 to 400 lines is plenty. Anything longer and the agent will skip the important parts.
- Pair it with an Apidog collection so the agent has both context (
AGENTS.md) and a runnable contract (the OpenAPI spec).
What AGENTS.md actually is
AGENTS.md is a Markdown file you commit at the root of a repository. Coding agents look for it on first contact with the codebase and treat its contents as the authoritative briefing on how the project works. The convention started inside OpenAI’s Codex CLI and was published as an open standard so other tools could read the same file. As of this year, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody, and several smaller agents all read it.
Three things make it useful:
- One file, every agent. You write the context once and every agent in the team’s tool belt picks it up. No per-tool config drift.
- Plain Markdown. No DSL, no schema, no build step. Engineers edit it like any other doc.
- Lives next to the code it describes. When the build script changes, the file changes in the same PR. The diff makes the change visible to reviewers and to the agent.
The closest cousin is CLAUDE.md, which Anthropic’s Claude Code reads. The two formats overlap heavily; many projects keep an AGENTS.md symlinked to CLAUDE.md so both tools work without extra config. The Codex team and Anthropic have publicly aligned on keeping the formats compatible going forward.
Why API development teams need it more than most
API teams sit at an awkward intersection: the code is small, the contracts are large, and the consequences of getting either wrong are visible to every downstream client. An agent that does not know the spec lives at openapi.yaml will rewrite types from the response shape it remembers from training data. An agent that does not know the contract test command will commit code that compiles but breaks the client SDK pipeline.
A well-written AGENTS.md for an API repo does four things:
- Pins the spec as the source of truth. Every change starts and ends with the OpenAPI or GraphQL schema. The agent learns to update the spec first, then regenerate types.
- Names the local servers. Agents that boot a local mock or live server pick the right URL for tests, not a Stack Overflow snippet.
- Lists test commands by intent. “Run unit tests” is not the same as “run contract tests” or “run integration tests against the staging environment.”
- Calls out forbidden paths. Generated SDK code, third-party client wrappers, and migration files often look editable but are not.
When the file does these four things, agent output stops looking like a junior developer who skipped the README and starts looking like a teammate.
The structure that works for API repos
AGENTS.md has no required schema. The community has settled on a few sections that show up in almost every well-tuned file. For an API team, the order below is a strong default.
1. Project summary (3-5 lines)
State what the API does, who the consumers are, and what language and framework the server runs on. Keep it factual.
# Project: Payments API
Internal payments service for the Acme product line. Customers are
mobile, web, and partner backends. Server is Go 1.23 on Echo, Postgres
17 for storage, and a Redis-backed idempotency layer.
This block tells the agent which language to default to, which idioms to follow, and which clients break if you ship the wrong response shape.
2. Quick start commands
Five to ten commands the agent will run constantly. Always include the command, never link out to a wiki.
## Commands
| Intent | Command |
|--------|---------|
| Install deps | `make deps` |
| Run server locally | `make dev` (binds 127.0.0.1:8080) |
| Run unit tests | `make test` |
| Run contract tests against the local mock | `make contract` |
| Lint | `make lint` |
| Regenerate clients from spec | `make codegen` |
| Apply migrations | `make migrate` |
If a command needs an env var to work, put the env var name next to it. Agents are good at exporting variables; they are bad at guessing.
3. The OpenAPI / GraphQL spec section
This is the single most valuable section in an API repo. Tell the agent where the spec lives, how the spec relates to generated code, and which direction edits flow.
## Source of truth
- The spec is at `apis/payments/openapi.yaml`.
- Generated clients live in `gen/clients/{go,ts,python}` and MUST NOT be hand-edited.
- The generation pipeline is `make codegen`. Run it after every spec change
and commit the regenerated clients in the same PR.
- Spec changes flow: spec -> `make codegen` -> server handler updates ->
contract tests -> ship.
This block alone removes a class of bug where agents edit the generated client to “fix” a type mismatch, the next codegen run wipes the change, and the build mysteriously breaks two days later.
4. Mock server and Apidog wiring
If you run mock servers (and you should), name them. List the URLs, the spec they read from, and how to start them.
## Local servers
- Real server: `make dev` -> `http://127.0.0.1:8080`
- Apidog mock server: `make mock` -> `http://127.0.0.1:4010`
- The mock reads from the same `openapi.yaml` and replays saved examples
from the Apidog collection at `apis/payments/apidog/`.
This is where Apidog earns its place in the file. The mock server, the spec, and the saved request examples form a contract the agent can run against without burning calls on the real backend. Pair it with the API testing without Postman guide for the underlying workflow.
5. Auth and secrets
Tell the agent how the API authenticates and which env vars hold what. Never put real secrets in the file.
## Auth
- Production uses OAuth 2 client credentials issued by Auth0.
- Local dev uses a static dev token; export `DEV_TOKEN` from `.env.local`.
- The Apidog collection uses the same env var names so the mock and the
real client behave identically.
- Tokens MUST NOT be committed; `.env.local` is in `.gitignore`.
6. Testing strategy
Rank the test layers. Agents will run them in the order you list.
## Testing
1. `make test` for unit tests. Fast, run on every change.
2. `make contract` for OpenAPI contract tests against the mock. Run before
any spec change is merged.
3. `make integration` for end-to-end tests against a local server with a
real Postgres. Run before merging to main.
4. Staging soak runs nightly via GitHub Actions; not a local command.
7. Do-not-touch list
Generated code, vendored dependencies, and migrations almost always belong here.
## Do not edit by hand
- `gen/**` (regenerated by `make codegen`)
- `vendor/**` (managed by `go mod vendor`)
- `migrations/*.up.sql` past the first unapplied migration
- `apis/payments/openapi.yaml` schema field names without owner sign-off
8. House style
Three to five rules. Anything more and the agent will pick the wrong one.
## Conventions
- Errors return RFC 7807 problem JSON; never bare strings.
- Use snake_case in JSON, camelCase in Go, PascalCase in TS clients.
Codegen handles the mapping.
- Idempotency keys are required on all POST endpoints that create resources.
- New endpoints require a contract test that exercises both 200 and 4xx paths.
Concrete example: a 90-line file that does the job
The temptation is to write 800 lines. Resist it. The file below covers a real API service in 90 lines of Markdown and is enough for any major agent to work productively.
# Project: Payments API
Internal payments service for the Acme product line. Go 1.23, Echo,
Postgres 17, Redis for idempotency. Consumers are mobile, web,
and partner backends.
## Commands
| Intent | Command |
|--------|---------|
| Install | `make deps` |
| Run server | `make dev` |
| Unit tests | `make test` |
| Contract tests | `make contract` |
| Lint | `make lint` |
| Regen clients | `make codegen` |
| Migrate DB | `make migrate` |
## Source of truth
- Spec: `apis/payments/openapi.yaml`
- Generated clients: `gen/clients/{go,ts,python}` (do not edit)
- Edit flow: spec -> `make codegen` -> handler -> contract tests -> ship
## Local servers
- Real server: `make dev` (`http://127.0.0.1:8080`)
- Apidog mock: `make mock` (`http://127.0.0.1:4010`)
- Apidog collection: `apis/payments/apidog/`
## Auth
- Production: Auth0 OAuth 2 client credentials.
- Local dev: static `DEV_TOKEN` from `.env.local`.
## Testing order
1. `make test`
2. `make contract`
3. `make integration`
## Do not edit by hand
- `gen/**`, `vendor/**`
- Applied migrations in `migrations/`
- Spec field names without owner approval
## Conventions
- RFC 7807 problem JSON for errors
- snake_case JSON, codegen handles language mapping
- Idempotency keys required on POST creates
- Every new endpoint ships with a contract test
That is enough. Add sections only when an agent makes the same wrong choice twice.
Keeping the file fresh
A stale AGENTS.md is worse than no file at all. The agent will believe it and ship code based on a build command that no longer works.
Three habits keep it fresh:
- Treat it as production code. Changes go through the same review as any other PR. Reviewers check that command lists match the actual
Makefile. - Wire it into CI. A short script that parses the command table and runs each command on a fresh checkout catches drift fast. Most teams write this in 30 lines of Bash.
- Update it in the same PR. When you add a new test command, do not promise to update
AGENTS.mdlater. Update it now. The cost is two minutes; the cost of skipping is two weeks of agent confusion.
Apidog as the runtime contract for your AGENTS.md
AGENTS.md gives the agent context. The OpenAPI spec gives it the contract. Apidog bridges the two: it reads the spec, runs a local mock at the URL listed in AGENTS.md, replays saved request examples for tests, and lets the agent see real responses without burning credits on the live backend.
The pattern that works:
- Commit
apis/<service>/openapi.yamlandapis/<service>/apidog/(the exported collection). - List the mock URL and
make mockcommand inAGENTS.md. - Agents run
make contractfor fast tests against saved examples. - When the spec changes, the agent regenerates clients, runs the contract suite, and only then touches the live server.
For a deeper walkthrough of the Apidog mock workflow with a real API, the DeepSeek V4 API guide covers the same pattern applied to a model API instead of a service API.
Common mistakes API teams make
After reviewing dozens of these files, the same five issues show up:
- Linking instead of listing. “See the wiki for build commands.” The agent does not browse the wiki. Inline the commands.
- Marketing-flavored prose. “Our world-class API platform empowers…” The agent does not need a pitch. State facts.
- Outdated commands. A command that broke in March is still in the file in April. Wire CI to catch this.
- Missing the spec section. The single most useful block. Always include it.
- No do-not-touch list. The agent edits generated code. The next codegen run wipes the edit. The build breaks. Repeat.
If you want a baseline to start from, copy the example above into your repo, edit the project summary, and adjust the command table. You can ship a usable file in 20 minutes.
FAQ
Is AGENTS.md the same as CLAUDE.md?The formats are compatible. Most teams keep one of them as the source of truth and symlink the other. Anthropic and OpenAI publicly aligned on keeping the conventions interoperable.
Where should I put the file?Always at the repo root. Some agents also read nested AGENTS.md files inside subdirectories, useful for monorepos. Start with one root-level file and add subdirectory files only when a single root file gets too long.
How long should it be?200 to 400 lines is the sweet spot. Beyond that, agents start skipping sections. If you need more depth, link to a separate doc with a one-line summary inline.
Should I include code samples?Short ones, yes. Long ones, no. Save full examples for tests; agents read tests too. The GPT-5.5 free Codex guide covers how Codex specifically uses example tests as additional signal.
Does the agent re-read the file on every turn?Most agents read it on session start and cache it. Some re-read after large file changes. If you make a major edit, restarting the agent session is the safest move.
How do I test that my file works?Run a fresh agent session with no other context, give it a small task (“add a 422 response to POST /payments”), and watch what it does. If it reads the spec, runs make codegen, and writes a contract test, the file is doing its job.