Como escrever AGENTS.md para o Codex entender as regras do seu projeto

O Codex diz “pronto”, você roda pnpm test e só então percebe que ele nem executou os testes. Ou, em um monorepo, ele roda a partir da raiz o test do package errado. Repetir esse tipo de instrução cansa: npm run build, pnpm test, não mexer em generated, rodar lint antes de terminar. AGENTS.md é onde você escreve essas regras no projeto para que o Codex não precise perguntar de novo.

Se você acabou de passar pelo guia inicial do Codex e pela escolha de entrada, o próximo passo não é pedir uma refatoração gigante. Primeiro, registre as regras do projeto que você costuma repetir.

Comece com um esqueleto de 12 a 20 linhas. Depois entenda as três camadas de carregamento, como verificar se funcionou, o que não deve entrar no arquivo, como conviver com CLAUDE.md ou Cursor Rules e quando atualizar.

AGENTS.md não é README; é o manual de trabalho persistente do Codex

README.md é escrito para pessoas. Ele explica o que é o projeto, como instalar e como começar. AGENTS.md é escrito para o Codex. Ele descreve as regras carregadas a cada início de tarefa: como fazer build, como testar, quais diretórios não tocar e quais verificações fazer antes de dizer que terminou.

Segundo a documentação oficial da OpenAI, o Codex lê AGENTS.md antes de começar a trabalhar e inclui o arquivo no contexto. Isso é diferente de repetir “npm run build” ou “pnpm test” em todo chat. AGENTS.md é orientação persistente do projeto.

Mas existe um limite: AGENTS.md não é memória de longo prazo nem uma base de conhecimento que aprende sozinha. É um arquivo estático carregado no início. Se você precisa acumular conhecimento entre sessões ou governar memória de agentes, o guia anterior sobre memória de agentes IA explica a divisão entre memória de longo prazo e regras de projeto.

Como o Codex encontra seu AGENTS.md: três camadas de carregamento

A ordem de leitura do Codex pode ser entendida em três camadas: global, projeto e fusão. Entender isso ajuda a saber onde uma regra vale e por que às vezes ela parece não valer.

Camada global: seus hábitos pessoais

O Codex primeiro procura no diretório de usuário ~/.codex. Essa camada é para hábitos pessoais, como idioma de resposta, preferências de estilo de código ou ferramentas comuns. Atenção: a camada global lê no máximo um arquivo, nesta ordem: AGENTS.override.md -> AGENTS.md. Ela não empilha os dois.

Camada de projeto: da raiz Git até o diretório atual

Na camada de projeto, o Codex varre da raiz Git ou do projeto até o diretório de trabalho atual. Em cada nível, ele também lê no máximo um arquivo, nesta ordem: AGENTS.override.md -> AGENTS.md -> fallback filenames. Os nomes fallback podem ser configurados com project_doc_fallback_filenames, por exemplo para incluir TEAM_GUIDE.md. Trate os nomes exatos das opções como parte da documentação oficial.

Ordem de fusão: quanto mais perto, mais específico

Todos os arquivos encontrados são concatenados da raiz até o diretório atual. Quanto mais perto um arquivo está do diretório atual, mais tarde ele aparece no contexto. Isso facilita que o Codex priorize a regra local.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Exemplo: a raiz de um monorepo tem AGENTS.md dizendo “use pnpm test”. apps/web/AGENTS.md diz “use pnpm --filter web test”. Se o Codex inicia em apps/web, ele lê primeiro as regras da raiz e depois as regras de apps/web. O comando de test de apps/web é mais específico.

Resumo das três camadas

A raiz deve conter regras compartilhadas da equipe. Subdiretórios devem conter regras locais, como um comando de test diferente para um package. AGENTS.override.md serve para substituições temporárias ou locais. Não transforme isso no padrão da equipe, porque a regra real fica escondida no override.

O modelo mínimo: quais 6 blocos escrever primeiro?

A OpenAI descreve AGENTS.md como um “open-format README for agents”. Na prática, ele precisa ser curto, real e verificável. Não copie de início um modelo de 300 linhas. Comece com 6 blocos básicos e amplie só quando o projeto mostrar necessidade.

O esqueleto inicial contém estes 6 blocos:

1. repo layout: stack e mapa de diretórios, para o Codex saber onde ficam frontend, backend e tests
2. Commands: comandos exatos de build, test e lint. Escreva pnpm test, não “rodar testes”
3. Constraints: diretórios e ações que o Codex deve evitar, como src/generated/
4. PR expectations: o que verificar antes de enviar e o que a review espera
5. Done when: critérios verificáveis de conclusão, como pnpm test e pnpm build
6. Convenções opcionais do projeto, como gerenciador de pacotes, estilo de código ou nomeação

Para um painel SaaS, o arquivo inicial pode ser assim:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Esse modelo é curto o bastante para não poluir o contexto. Comece por esses 6 blocos e amplie quando aparecer um problema repetido. Não coloque visão de produto, lista completa de dependências, diagramas de arquitetura ou índice de API docs logo na primeira versão. Um arquivo enorme enterra as regras que realmente importam.

Como confirmar que o Codex realmente leu AGENTS.md

Depois de escrever AGENTS.md, verifique se ele foi carregado. A documentação da OpenAI recomenda:

codex --ask-for-approval never "Summarize the current instructions."

Esse comando pede para o Codex resumir as instruções atuais. Se a saída contiver suas regras, como comando de test ou diretório proibido, está funcionando. Se não aparecer nada, ou se aparecerem outras regras, depure a cadeia de carregamento.

Checklist de diagnóstico

Se ainda não funcionar, consulte a documentação de Custom instructions da OpenAI ou atualize o Codex. Não trate o carregamento de AGENTS.md como mágica. Caminho, versão, configuração e diretório atual influenciam o resultado.

O que não deve entrar em AGENTS.md

AGENTS.md não é um depósito universal. Algumas coisas criam risco de segurança, custo de manutenção ou ruído de contexto. Mantenha o seguinte fora.

1. Secrets, API keys e senhas de produção

Nenhum secret, senha de produção ou API token deve entrar em AGENTS.md. O Codex lê o arquivo no contexto, e ele pode ficar visível para a equipe ou ser commitado no Git. Use variáveis de ambiente, arquivos .env não commitados ou um sistema dedicado de secrets. Se o Codex precisar de secrets em um workflow sandboxed, trate isso como uma questão da camada de execução.

2. Listas grandes que envelhecem rápido

Não liste todas as dependências, números do ecossistema, preços, quotas, rotas ou campos de banco de dados. Uma lista como “React 18.2, Vue 3.4, TypeScript 5.0…” fica errada em pouco tempo. Escreva o processo para adicionar uma dependência, não o inventário completo.

3. Slogans abstratos

“Manter alta qualidade”, “escrever código elegante” ou “garantir manutenibilidade” não são executáveis. Transforme isso em checks: pnpm test passa, pnpm lint não tem erros, features novas têm tests ou Lighthouse não cai abaixo do limite combinado.

4. Comandos vagos

“Rodar testes” e “verificar build” são vagos demais. Escreva comandos exatos: pnpm test, pnpm build ou lighthouse --preset=desktop.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

5. Requisitos não verificáveis

“Garantir melhor desempenho” ou “melhorar UX” não tem limite claro. Use checks mensuráveis, como API abaixo de 200 ms ou meta de Lighthouse.

6. Preferências pessoais na raiz do repo

“Responder em chinês”, “respostas abaixo de 100 palavras” ou “usar VS Code por padrão” são preferências pessoais, não regras compartilhadas do projeto. Coloque isso em ~/.codex/AGENTS.md. A raiz do repo deve conter padrões da equipe.

A regra é simples: curto, real e verificável. AGENTS.md reduz instruções repetidas. Não é lugar para colar toda a documentação do projeto.

Se você já tem CLAUDE.md ou Cursor Rules

Se você usa Claude Code ou Cursor, talvez o repositório já tenha CLAUDE.md ou Cursor Rules. Não é preciso manter três cópias. Use importação ou coexistência.

AGENTS.md vs CLAUDE.md: importar regras compartilhadas

Claude Code lê CLAUDE.md, não AGENTS.md. Se o repo já tem AGENTS.md, crie um CLAUDE.md pequeno que o importe:

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md é a sintaxe de importação. O Claude Code lê AGENTS.md e depois a seção Claude-specific. Assim, regras compartilhadas ficam em AGENTS.md e preferências próprias do Claude ficam em CLAUDE.md.

AGENTS.md vs Cursor Rules: Cursor tem seu próprio sistema

Cursor tem seu próprio sistema de Rules, com regras de projeto, equipe e usuário. A documentação oficial e resumos de busca do Cursor mencionam suporte a AGENTS.md, mas os detalhes de carregamento devem ser conferidos na documentação atual do Cursor. Se você usa Cursor e Codex, deixe regras comuns em AGENTS.md e comportamentos próprios do editor Cursor em Cursor Rules.

AGENTS.md vs config.toml, Rules, Skills e MCP

AGENTS.md é a camada de instrução. Ele diz ao Codex como trabalhar. Controles de execução vivem em outro lugar: permissões, sandbox, política de comandos e integrações de ferramentas.

AGENTS.md resolve explicações repetidas de regras do projeto. Rules, config, sandbox e permissões controlam execução. Skills encapsulam workflows reutilizáveis. MCP conecta ferramentas externas. Manter essas fronteiras claras evita confusão.

Quando atualizar AGENTS.md

AGENTS.md não precisa mudar a cada alteração do projeto. Atualize quando a mesma fricção se repetir.

Gatilhos de atualização

A documentação da OpenAI recomenda atualizar nestes casos:

1. O Codex repete o mesmo erro: edita duas vezes o diretório errado ou sempre executa o test do package errado. Adicione uma restrição concreta, como “Do NOT edit src/generated/” ou “Use pnpm --filter web test for web changes.”

2. A PR review repete o mesmo comentário: reviewers pedem “esta mudança precisa de tests”, “não altere generated code” ou “evite default export”. Coloque esse padrão em PR expectations.

3. O Codex lê arquivos demais para achar a resposta: se ele precisa vasculhar várias docs para encontrar o test correto ou o fluxo de build, coloque a informação central no topo.

Atualize o diretório mais próximo

Coloque a regra onde o erro acontece. Nem tudo deve ir para a raiz. Em monorepos, packages diferentes podem ter regras diferentes, então cada package pode ter seu AGENTS.md local.

Se o Codex roda o test errado em apps/web, adicione a regra em apps/web/AGENTS.md. Uma regra na raiz pode acabar ampla demais.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Diferença para memória de longo prazo

AGENTS.md é um arquivo estático carregado no início. Não é um memory store que aprende sozinho. O Codex não vai atualizá-lo a partir das suas correções, a menos que você peça explicitamente.

Se você precisa de conhecimento entre sessões ou governança de memória, o guia sobre memória de agentes IA é o próximo ponto de referência.

Fazer a plantilla crescer: da semente à versão expandida

Não comece com um modelo de 300 linhas. Comece com 12 a 20 linhas e amplie apenas quando aparecer um gatilho repetível.

Versão semente: só os 6 blocos principais

A versão semente cobre repo layout, comandos comuns, constraints, PR expectations e done/verify. Pode ser pequena assim:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Gatilhos de expansão: quando adicionar um bloco

Depois de algumas execuções, amplie só por problemas concretos:

1. A primeira vez que o Codex editar o diretório errado: se tocar em migrations/ ou generated/, adicione em Constraints “Do NOT commit migrations/ without team review” ou “Do NOT edit any file in src/generated/”.

2. O primeiro comentário repetido em PR review: se reviewers pedem tests ou named exports repetidamente, adicione “Add tests for new features” ou “Use named exports, not default exports”.

3. O primeiro erro de gerenciador de pacotes: se um projeto pnpm recebe comandos npm, adicione “Always use pnpm, not npm or yarn”.

4. O primeiro lint esquecido: se o Codex termina sem lint, adicione “pnpm lint passes with no errors” em Done when.

Versão expandida: 30 a 50 linhas

Uma versão expandida pode adicionar constraints, PR expectations, regras de gerenciador de pacotes e requisitos de lint:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

A regra central é crescer por gatilho, não por antecipação. AGENTS.md vale porque reduz explicações repetidas, não porque exibe toda a documentação do projeto.

Conclusão

AGENTS.md é orientação persistente do projeto. Não é um depósito universal nem um sistema de memória de longo prazo. Ele resolve um problema concreto: você não precisa repetir as mesmas regras toda vez que o Codex começa a trabalhar.

Próximos passos práticos:

1. Comece com uma semente de 12 a 20 linhas: repo layout, comandos, constraints, PR expectations e done/verify. Não comece por um modelo gigante.

2. Verifique se o Codex carregou: rode codex --ask-for-approval never "Summarize the current instructions." e procure suas regras na resposta.

3. Amplie por gatilhos repetidos: o Codex repete um erro, a PR review repete uma observação ou o Codex precisa procurar demais para achar a informação.

4. Mantenha fora o que é perigoso ou perecível: nada de secrets, inventários caducos, slogans, comandos vagos, metas não verificáveis ou preferências pessoais na raiz.

5. Use importação e coexistência com CLAUDE.md ou Cursor Rules: regras compartilhadas em AGENTS.md e comportamentos específicos nos arquivos de cada ferramenta.

AGENTS.md dá ao Codex um contexto estável do projeto. Outros artigos desta série Codex podem mover workflows repetíveis para Skills, tratar limites de permissões e secrets, e tornar done/verify mais confiável com failure reviews e PR checks.