Agentes de codificação leem seu repositório antes de escrever código, e o primeiro arquivo que eles leem é AGENTS.md. É a convenção aberta que Codex CLI, Cursor, Aider, OpenHands e uma lista crescente de outras ferramentas concordaram para que um único arquivo de contexto funcione em todos os agentes. Para equipes de desenvolvimento de API, esse arquivo é a diferença entre um agente que executa os testes corretos contra um servidor local real e um que alucina endpoints e entrega um cliente quebrado.
Este guia aborda o que é AGENTS.md, por que as equipes de API devem tratá-lo como código de produção, as seções importantes para repositórios OpenAPI-first, exemplos concretos e como mantê-lo atualizado à medida que a API evolui. Nós o combinamos com o Apidog no final para que o fluxo de teste de contrato do agente permaneça baseado em uma especificação real.
TL;DR
AGENTS.mdé um arquivo Markdown simples na raiz do repositório que informa aos agentes de codificação como navegar, construir, testar e enviar código em seu projeto.- A convenção é aberta e suportada por Codex CLI, Cursor, OpenHands, Aider, Claude Code e outras ferramentas de agente.
- Para equipes de API, as seções que mais rendem são comandos de construção, o caminho da especificação OpenAPI, endpoints de servidores mock, comandos de teste de contrato, configuração de autenticação e zonas de "não tocar".
- Mantenha-o curto. 200 a 400 linhas são suficientes. Qualquer coisa mais longa e o agente pulará as partes importantes.
- Combine-o com uma coleção Apidog para que o agente tenha tanto o contexto (
AGENTS.md) quanto um contrato executável (a especificação OpenAPI).
O que AGENTS.md realmente é
AGENTS.md é um arquivo Markdown que você commit na raiz de um repositório. Agentes de codificação o procuram no primeiro contato com a base de código e tratam seu conteúdo como o briefing autoritário sobre como o projeto funciona. A convenção começou dentro do Codex CLI da OpenAI e foi publicada como um padrão aberto para que outras ferramentas pudessem ler o mesmo arquivo. A partir deste ano, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody e vários agentes menores o leem.
Três coisas o tornam útil:
- Um arquivo, todo agente. Você escreve o contexto uma vez e todo agente na caixa de ferramentas da equipe o pega. Sem desvio de configuração por ferramenta.
- Markdown simples. Sem DSL, sem esquema, sem etapa de construção. Engenheiros o editam como qualquer outro documento.
- Vive ao lado do código que descreve. Quando o script de construção muda, o arquivo muda no mesmo PR. A diferença torna a mudança visível para os revisores e para o agente.
O parente mais próximo é CLAUDE.md, que o Claude Code da Anthropic lê. Os dois formatos se sobrepõem muito; muitos projetos mantêm um AGENTS.md com symlink para CLAUDE.md para que ambas as ferramentas funcionem sem configuração extra. A equipe Codex e a Anthropic se alinharam publicamente para manter os formatos compatíveis no futuro.
Por que as equipes de desenvolvimento de API precisam dele mais do que a maioria
As equipes de API estão em uma interseção estranha: o código é pequeno, os contratos são grandes, e as consequências de errar qualquer um deles são visíveis para cada cliente downstream. Um agente que não sabe que a especificação está em openapi.yaml reescreverá os tipos a partir da forma de resposta que ele lembra dos dados de treinamento. Um agente que não sabe o comando de teste de contrato cometerá código que compila, mas quebra o pipeline do SDK do cliente.
Um AGENTS.md bem escrito para um repositório de API faz quatro coisas:
- Fixa a especificação como fonte da verdade. Toda mudança começa e termina com o esquema OpenAPI ou GraphQL. O agente aprende a atualizar a especificação primeiro, depois regenerar os tipos.
- Nomeia os servidores locais. Agentes que iniciam um mock local ou servidor ativo escolhem a URL correta para testes, não um trecho do Stack Overflow.
- Lista comandos de teste por intenção. "Executar testes de unidade" não é o mesmo que "executar testes de contrato" ou "executar testes de integração contra o ambiente de staging".
- Aponta caminhos proibidos. Código SDK gerado, wrappers de cliente de terceiros e arquivos de migração geralmente parecem editáveis, mas não são.
Quando o arquivo faz essas quatro coisas, a saída do agente para de parecer a de um desenvolvedor júnior que pulou o README e começa a parecer a de um colega de equipe.
A estrutura que funciona para repositórios de API
AGENTS.md não tem esquema obrigatório. A comunidade se estabeleceu em algumas seções que aparecem em quase todos os arquivos bem ajustados. Para uma equipe de API, a ordem abaixo é um padrão forte.
1. Resumo do projeto (3-5 linhas)
Declare o que a API faz, quem são os consumidores, e em que linguagem e framework o servidor é executado. Mantenha-o 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.
Este bloco informa ao agente qual linguagem usar por padrão, quais idiossincrasias seguir e quais clientes quebrarão se você enviar a forma de resposta errada.
2. Comandos de início rápido
Cinco a dez comandos que o agente executará constantemente. Sempre inclua o comando, nunca link para uma 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` |
Se um comando precisar de uma variável de ambiente para funcionar, coloque o nome da variável de ambiente ao lado dele. Agentes são bons em exportar variáveis; são ruins em adivinhar.
3. A seção de especificação OpenAPI / GraphQL
Esta é a seção mais valiosa em um repositório de API. Diga ao agente onde a especificação reside, como ela se relaciona com o código gerado e em que direção as edições fluem.
## 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.
Este bloco sozinho remove uma classe de bug onde agentes editam o cliente gerado para "corrigir" uma incompatibilidade de tipo, a próxima execução de codegen apaga a mudança, e a compilação quebra misteriosamente dois dias depois.
4. Servidor Mock e Configuração Apidog
Se você executa servidores mock (e deveria), nomeie-os. Liste as URLs, a especificação que eles leem e como iniciá-los.
## 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/`.
É aqui que o Apidog ganha seu lugar no arquivo. O servidor mock, a especificação e os exemplos de requisição salvos formam um contrato que o agente pode executar sem gastar chamadas no backend real. Combine-o com o guia de teste de API sem Postman para o fluxo de trabalho subjacente.
5. Autenticação e segredos
Diga ao agente como a API se autentica e quais variáveis de ambiente contêm o quê. Nunca coloque segredos reais no arquivo.
## 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. Estratégia de teste
Classifique as camadas de teste. Os agentes as executarão na ordem em que você as listar.
## 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. Lista de "Não tocar"
Código gerado, dependências de fornecedores e migrações quase sempre pertencem aqui.
## 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. Estilo da casa
Três a cinco regras. Mais do que isso e o agente escolherá a errada.
## 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.
Exemplo concreto: um arquivo de 90 linhas que cumpre a tarefa
A tentação é escrever 800 linhas. Resista. O arquivo abaixo cobre um serviço de API real em 90 linhas de Markdown e é suficiente para qualquer agente principal trabalhar produtivamente.
# 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
Isso é suficiente. Adicione seções apenas quando um agente cometer o mesmo erro duas vezes.
Mantendo o arquivo atualizado
Um AGENTS.md obsoleto é pior do que não ter arquivo algum. O agente acreditará nele e enviará código baseado em um comando de construção que não funciona mais.
Três hábitos o mantêm atualizado:
- Trate-o como código de produção. As mudanças passam pela mesma revisão que qualquer outro PR. Os revisores verificam se as listas de comandos correspondem ao
Makefilereal. - Conecte-o ao CI. Um pequeno script que analisa a tabela de comandos e executa cada comando em um checkout novo detecta a divergência rapidamente. A maioria das equipes escreve isso em 30 linhas de Bash.
- Atualize-o no mesmo PR. Ao adicionar um novo comando de teste, não prometa atualizar
AGENTS.mddepois. Atualize-o agora. O custo é de dois minutos; o custo de pular é de duas semanas de confusão do agente.
Apidog como o contrato de tempo de execução para o seu AGENTS.md
AGENTS.md fornece contexto ao agente. A especificação OpenAPI fornece o contrato. O Apidog faz a ponte entre os dois: ele lê a especificação, executa um mock local na URL listada em AGENTS.md, reproduz exemplos de requisição salvos para testes e permite que o agente veja respostas reais sem gastar créditos no backend ao vivo.
O padrão que funciona:
- Commit
apis/<service>/openapi.yamleapis/<service>/apidog/(a coleção exportada). - Liste a URL do mock e o comando
make mockemAGENTS.md. - Agentes executam
make contractpara testes rápidos contra exemplos salvos. - Quando a especificação muda, o agente regenera os clientes, executa a suíte de contrato e só então toca no servidor ativo.
Para uma visão mais aprofundada do fluxo de trabalho de mock do Apidog com uma API real, o guia da API DeepSeek V4 cobre o mesmo padrão aplicado a uma API de modelo em vez de uma API de serviço.
Erros comuns cometidos por equipes de API
Após revisar dezenas desses arquivos, os mesmos cinco problemas aparecem:
- Linkar em vez de listar. "Veja a wiki para comandos de construção." O agente não navega na wiki. Inclua os comandos inline.
- Prosa com sabor de marketing. "Nossa plataforma de API de classe mundial empodera..." O agente não precisa de um pitch. Declare fatos.
- Comandos desatualizados. Um comando que quebrou em março ainda está no arquivo em abril. Conecte o CI para pegar isso.
- Falta da seção de especificação. O bloco mais útil. Sempre inclua.
- Nenhuma lista de "não tocar". O agente edita código gerado. A próxima execução de codegen apaga a edição. A compilação quebra. Repete.
Se você quiser um ponto de partida, copie o exemplo acima para seu repositório, edite o resumo do projeto e ajuste a tabela de comandos. Você pode enviar um arquivo utilizável em 20 minutos.
FAQ
AGENTS.md é o mesmo que CLAUDE.md?Os formatos são compatíveis. A maioria das equipes mantém um deles como fonte da verdade e faz um symlink do outro. Anthropic e OpenAI se alinharam publicamente para manter as convenções interoperáveis.
Onde devo colocar o arquivo?Sempre na raiz do repositório. Alguns agentes também leem arquivos AGENTS.md aninhados dentro de subdiretórios, útil para monorepos. Comece com um arquivo de nível raiz e adicione arquivos de subdiretório apenas quando um único arquivo raiz ficar muito longo.
Qual deve ser o comprimento?200 a 400 linhas é o ideal. Além disso, os agentes começam a pular seções. Se precisar de mais profundidade, link para um documento separado com um resumo de uma linha inline.
Devo incluir exemplos de código?Pequenos, sim. Longos, não. Guarde exemplos completos para testes; agentes também leem testes. O guia GPT-5.5 free Codex aborda como o Codex usa especificamente exemplos de testes como sinal adicional.
O agente relê o arquivo a cada turno?A maioria dos agentes o lê no início da sessão e o armazena em cache. Alguns o releem após grandes alterações de arquivo. Se você fizer uma edição importante, reiniciar a sessão do agente é a medida mais segura.
Como testo se meu arquivo funciona?Execute uma nova sessão de agente sem outro contexto, dê a ela uma pequena tarefa ("adicionar uma resposta 422 a POST /payments"), e observe o que ela faz. Se ela ler a especificação, executar make codegen e escrever um teste de contrato, o arquivo está cumprindo seu trabalho.