Até aqui você aprendeu a instalar o Codex, controlar o que ele pode executar e escrever pedidos precisos. Neste capítulo você vai aprender a parar de repetir as mesmas instruções em todo pedido. Ao final, você saberá criar um arquivo AGENTS.md para o seu projeto, distribuí-lo em hierarquia entre a pasta do usuário, a raiz do repositório e subpastas, e perceber na prática a diferença no comportamento do agente.
O que é o AGENTS.md
O AGENTS.md é um arquivo de texto em formato Markdown que contém as instruções permanentes do seu projeto para o agente. O Codex lê esse arquivo automaticamente no início de cada sessão, antes do seu primeiro pedido, e passa a tratar o conteúdo como regras de casa. É o lugar onde ficam as informações que você não quer digitar de novo: qual é o comando de teste, onde mora cada tipo de código, quais bibliotecas são permitidas e o que nunca deve ser tocado.
Vale a comparação com o capítulo anterior. Um prompt descreve uma tarefa e morre com ela. O AGENTS.md descreve o projeto e sobrevive a todas as tarefas. Quando as duas coisas entram em conflito, o pedido imediato tende a vencer, porque ele é mais específico e mais recente. Por isso o AGENTS.md deve conter convenções estáveis, e não desejos de um dia só.
Uma vantagem prática: o mesmo arquivo funciona nas três formas de uso já apresentadas. O Codex CLI no terminal, a extensão do editor e o Codex na nuvem leem o AGENTS.md do repositório. Como ele é versionado no Git, toda a equipe herda as mesmas regras, e o agente se comporta de modo parecido na máquina de qualquer pessoa. Justamente por isso, nunca escreva segredos no AGENTS.md: senhas, tokens, chaves de interface de programação ou endereços internos não devem entrar nele, porque o arquivo fica no histórico do repositório e é enviado ao modelo como contexto em toda sessão. Segredos ficam em variáveis de ambiente ou em um gerenciador de segredos.
Onde colocar e como a hierarquia funciona
Existem três lugares úteis para esses arquivos, e o Codex combina todos eles.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
- Na pasta .codex do usuário, a mesma que guarda o config.toml. Aqui entram preferências suas que valem para qualquer projeto, como o idioma das explicações ou o pedido de sempre mostrar um plano antes de editar arquivos grandes.
- Na raiz do repositório, ao lado do README. Este é o arquivo principal, versionado e compartilhado com o time. Vale para todo o projeto.
- Em subpastas, para partes do projeto com regras próprias. Em um repositório que reúne backend e frontend, cada pasta pode ter o seu AGENTS.md com comandos e padrões diferentes.
A regra de combinação é simples: quanto mais perto do arquivo que está sendo editado, mais peso a instrução tem. Só tenha em mente que o agente monta esse conjunto a partir da pasta do usuário, da raiz do repositório e do diretório em que ele está trabalhando, então um arquivo de subpasta pode não ser lido se a sessão foi aberta longe dele; na dúvida, abra a sessão dentro da subpasta ou cite o arquivo no pedido. As instruções da pasta do usuário formam a base, as da raiz do repositório vêm por cima, e as da subpasta valem em último lugar para os arquivos daquela subárvore. Nada é descartado; o que é específico apenas prevalece quando há contradição. Na prática, isso significa que você pode dizer na raiz que o gerenciador de pacotes é o Poetry e, na pasta do frontend, que ali o gerenciador é o npm.
O que vale registrar
Pense no AGENTS.md como o texto de integração que você daria a uma pessoa competente que nunca viu o projeto. Seis blocos cobrem quase tudo.
- Comandos de build, execução e teste. O item mais valioso de todos. Sem ele, o agente adivinha, e adivinhar significa rodar o comando errado e concluir que está tudo bem.
- Estrutura de pastas. Uma linha por pasta, dizendo o que pode e o que não pode viver nela. Isso evita que regra de negócio apareça dentro de uma rota de API.
- Padrões de código. Tipagem, tratamento de erros, logging, nomes, idioma dos comentários, estilo de mensagens de commit.
- Bibliotecas preferidas e proibidas. Diga qual cliente HTTP usar e, principalmente, que dependências novas exigem confirmação. Isso reduz o risco de dependências inventadas, mas não substitui a conferência manual: antes de aceitar, verifique se o pacote realmente existe no PyPI ou no npm, quem o mantém e o que mudou no arquivo de lock.
- O que nunca alterar. Código legado congelado, migrações já aplicadas, arquivos gerados automaticamente, configuração de produção e segredos.
- Fluxo de trabalho. Se o agente deve commitar por etapa, se pode fazer push, se pode abrir pull request.
Evite dois excessos. Não transforme o arquivo em manual de arquitetura com páginas de teoria, porque tudo isso consome contexto em toda sessão. E não escreva o que o próprio código já diz melhor.
Um AGENTS.md completo de exemplo
O projeto de exemplo é uma interface de programação de aplicações, ou API, de catálogo de livros, escrita em Python com FastAPI e PostgreSQL. Este é o arquivo na raiz do repositório.
# AGENTS.md
## Projeto
API de catalogo de livros. Python 3.12, FastAPI, PostgreSQL, Poetry.
## Comandos
- Dependencias: `poetry install`
- Servidor local: `poetry run uvicorn app.main:app --reload`
- Testes: `poetry run pytest -q`
- Lint e formato: `poetry run ruff check . && poetry run ruff format .`
Sempre rode os testes e o lint antes de dizer que a tarefa terminou.
## Estrutura
- `app/routers/`: rotas e validacao de entrada, sem regra de negocio
- `app/services/`: regras de negocio
- `app/repositories/`: unico lugar com SQL
- `tests/`: espelha a estrutura de `app/`
## Padroes de codigo
- Type hints obrigatorios em funcoes publicas.
- Erros de dominio herdam de `AppError`, em `app/errors.py`.
- Nunca usar `print`; usar o logger de `app/logging.py`.
- Comentarios e docstrings em portugues.
## Bibliotecas
- Cliente HTTP: `httpx`. Datas: modulo `datetime` padrao.
- Nao adicionar dependencia nova sem me pedir confirmacao.
## Nunca alterar
- `app/legacy_billing/`: congelado, abrir issue em vez de editar.
- Migracoes ja aplicadas em `migrations/versions/`.
- `.env`, chaves e o Dockerfile de producao.
## Fluxo
- Um commit por etapa logica, mensagem no imperativo.
- Nao fazer push nem abrir pull request sem pedido explicito.
Na pasta do frontend, um arquivo curto basta, porque ele só precisa registrar as diferenças:
# AGENTS.md (frontend)
- Gerenciador: npm. Testes: `npm run test`.
- React com TypeScript. Componentes em `src/components/`.
- Estilos apenas com Tailwind; nao criar arquivos CSS novos.
- Nao editar `src/api/generated/`, gerado a partir do OpenAPI.
Antes e depois: o que muda no comportamento
O teste honesto é repetir o mesmo pedido curto em um repositório sem AGENTS.md e depois com ele. O pedido foi: corrigir o cálculo de desconto para assinantes e cobrir o caso com teste.
Sem o arquivo, a sessão típica é esta. O agente varre muitos arquivos até entender a estrutura, coloca a lógica corrigida dentro da rota porque foi ali que encontrou o cálculo, cria um arquivo de teste solto na raiz do projeto, tenta rodar apenas pytest, recebe erro de dependência porque está fora do ambiente do Poetry, e conclui dizendo que os testes não puderam ser executados. Você gasta duas ou três rodadas apenas consertando o processo.
Com o arquivo no lugar, o agente vai direto à pasta de serviços, mantém a rota fina, escreve o teste espelhando a estrutura esperada, usa o logger em vez de imprimir na tela, roda os testes e o lint com os comandos corretos e mostra a saída verde. Quando percebe que seria conveniente adicionar uma biblioteca de datas, ele pergunta antes. E não encosta na pasta de faturamento legado, mesmo passando por ela na investigação. Ainda assim, guarde este aviso: o AGENTS.md é orientação, não trava técnica. O modelo pode contrariar o que está escrito, então o que de fato protege arquivos sensíveis é o modo de aprovação, o sandbox, as permissões do sistema e a revisão do diff antes de cada commit.
O ganho não é mágica. É o agente parando de adivinhar aquilo que você já sabia e não havia escrito.
Mantendo o arquivo curto e vivo
Um AGENTS.md bom é curto, específico e verdadeiro. Algumas práticas ajudam.
- Mire em uma página. Se passar de duas, algo ali é documentação e deveria ir para o README ou para a pasta de documentos.
- Escreva no imperativo. Frases como sempre rode os testes funcionam melhor que descrições vagas de filosofia.
- Só registre regra que você realmente cobraria. Regra que ninguém segue confunde o agente e o time.
- Atualize quando doer. Toda vez que você corrigir a mesma coisa duas vezes no Codex, essa correção virou candidata a linha nova no arquivo.
- Reveja quando o projeto mudar. Troca de gerenciador de pacotes, de framework de teste ou de estrutura de pastas exige atualização imediata, senão o arquivo passa a mentir.
- Peça ajuda ao próprio agente. Um pedido útil é analisar o repositório e propor um rascunho de AGENTS.md com comandos e convenções detectados. Revise linha por linha antes de aceitar, porque aqui também cabe alucinação.
- Verifique se está sendo lido. Pergunte ao Codex quais regras do projeto ele está seguindo e qual comando de teste vai usar. Se a resposta não bater com o arquivo, confira o nome, a localização e se você abriu a sessão na pasta correta.
Por fim, trate o arquivo como código: ele entra em pull request, é revisado e tem histórico. Mudança de convenção discutida no AGENTS.md é mudança combinada com a equipe, não preferência individual.
Recapitulando
O AGENTS.md guarda as instruções permanentes do projeto e é lido automaticamente pelo Codex em toda sessão, no terminal, no editor e na nuvem. Ele pode existir na pasta do usuário, na raiz do repositório e em subpastas, e o Codex combina os três níveis dando prioridade ao mais específico. Os blocos que mais rendem são comandos de build e teste, estrutura de pastas, padrões de código, bibliotecas permitidas, o que nunca alterar e o fluxo de commits. Com o arquivo no lugar, o agente para de adivinhar e passa a trabalhar dentro das suas convenções. E o segredo para que isso continue funcionando é manter o texto curto, imperativo e atualizado a cada mudança real do projeto.
