AGENTS.md: como orientar agentes no repositório

O arquivo AGENTS.md resolve uma parte desse problema. Ele guarda instruções que o agente deve ler no contexto do projeto, como comandos de teste, padrões de arquitetura, limites de segurança e critérios de revisão.

O que é AGENTS.md e quando usar

AGENTS.md é um arquivo de orientação para agentes de programação. A documentação do Codex descreve uma cadeia de instruções global e específica do projeto, lida antes do trabalho começar. O GitHub também documenta o arquivo como uma forma de dar contexto do repositório ao Copilot durante uma revisão.

Use o arquivo para registrar decisões que o agente precisa respeitar sempre. Exemplos: como instalar dependências, quais testes executar, onde ficam os módulos importantes, quais arquivos não devem ser alterados e quais verificações são obrigatórias antes de abrir um pull request.

Não transforme o arquivo em uma cópia do README. O README explica o projeto para pessoas. O AGENTS.md deve responder o que um agente precisa saber para agir com segurança e entregar uma mudança revisável.

Crie o arquivo na raiz do repositório

Comece pela raiz do Git, para que a orientação valha para o projeto inteiro. No terminal integrado do VS Code, confirme o diretório atual e crie o arquivo:

$ git rev-parse --show-toplevel
$ touch AGENTS.md
$ code AGENTS.md

No PowerShell, a criação equivalente é:

PS> git rev-parse --show-toplevel
PS> New-Item AGENTS.md -ItemType File
PS> code AGENTS.md

Use uma estrutura curta e operacional. Um exemplo inicial pode ser:

# Regras do repositório

## Antes de editar
* Leia o README e os arquivos de configuração do pacote.
* Explique o plano antes de alterar mais de um módulo.

## Testes
* Rode o lint depois de mudar JavaScript ou TypeScript.
* Rode a suíte relacionada antes de abrir o pull request.

## Limites
* Não altere segredos, arquivos de produção ou migrações sem explicar o impacto.
* Não adicione dependências sem justificar a necessidade.

Troque os exemplos pelos comandos reais do seu projeto. Uma regra vaga, como "faça código bom", quase não ajuda. Uma regra observável, como "rode pnpm test --filter api quando mudar services/api", dá ao agente uma ação que pode ser conferida.

Organize camadas sem criar conflitos

A documentação atual do Codex permite combinar instruções globais com arquivos do projeto e regras mais específicas em subpastas. Um arquivo próximo do diretório em que o agente trabalha pode complementar ou substituir uma orientação geral.

Use a raiz para regras compartilhadas por todo o time. Coloque instruções de um serviço em um AGENTS.md dentro daquela pasta. Quando precisar de uma substituição temporária, use AGENTS.override.md e remova o arquivo depois da tarefa.

Evite duplicar a mesma regra em cinco lugares. A duplicação cria contradições e torna difícil descobrir qual instrução venceu. Prefira esta ordem:

• regras de segurança e qualidade na raiz;
• regras de domínio dentro do serviço;
• exceções locais somente quando forem realmente necessárias.

O Codex também documenta um limite de tamanho para o conjunto de instruções. Se o arquivo ficar grande demais, divida o conteúdo por diretório e remova explicações que não mudam uma decisão do agente.

Diferencie AGENTS.md, CLAUDE.md e regras do editor

Nem todo agente lê os mesmos nomes de arquivo. O Codex e o GitHub Copilot documentam AGENTS.md; o Claude Code documenta CLAUDE.md para memória e instruções do projeto. Isso não significa que um arquivo substitui automaticamente o outro.

Se o seu time usa ferramentas diferentes, mantenha uma fonte curta de regras comuns e faça adaptações pequenas para cada ferramenta. Não copie instruções enormes sem conferir o comportamento documentado de cada agente.

A regra mais importante é declarar o que foi realmente verificado. Se uma ferramenta não reconhece AGENTS.md, diga isso no arquivo específico dela. Um nome parecido não é prova de compatibilidade.

Valide o carregamento antes de confiar no arquivo

Depois de salvar o arquivo, abra uma nova sessão do agente. Sessões já abertas podem ter carregado as instruções antigas, então reiniciar evita um falso positivo.

Peça ao agente para listar as fontes de instrução que ele encontrou. No Codex, a própria documentação usa uma solicitação de resumo para confirmar que o arquivo global foi carregado:

$ codex --ask-for-approval never "Resuma as instruções carregadas antes de propor qualquer mudança."

Depois compare a resposta com o conteúdo real do arquivo. Se uma regra não aparecer, confira a pasta em que o comando foi executado, o nome exato do arquivo e se existe um AGENTS.override.md alterando a ordem.

Também faça uma validação prática. Peça uma tarefa que exija um comando de teste e confira se o agente o menciona no plano. A presença do arquivo no Git não garante que o agente leu o conteúdo correto.

Combine instruções com revisão e squads

AGENTS.md reduz contexto repetido, mas não substitui branch, diff, teste ou revisão humana. Use o arquivo para explicar o padrão e use o Git para provar o que mudou.

Se você ainda está montando esse fluxo, veja o guia de agentes de IA para programar com revisão. Para um projeto maior, o artigo sobre criar um sistema com IA usando Codex ajuda a dividir entregas em partes menores.

Quando vários agentes trabalham no mesmo projeto, o arquivo pode servir como contrato comum. Um agente planeja, outro implementa e outro revisa, cada um com o mesmo conjunto de limites. No bridgecode, essa divisão faz sentido quando você quer acompanhar papéis diferentes em paralelo, mantendo a decisão final com uma pessoa.