O Codex consegue explorar um repositório e encontrar contexto sozinho. Isso não significa que um pedido vago seja uma boa estratégia. Quanto maior o projeto, mais importante separar regras duráveis do repositório e o objetivo específico da tarefa.
O briefing informa o que precisa mudar agora. O AGENTS.md registra como o trabalho deve ser feito naquele projeto. Juntos, eles reduzem adivinhação e tornam a entrega verificável.
Em uma frase: coloque no briefing o resultado da tarefa e no AGENTS.md os padrões que continuam válidos depois que ela terminar.
O que um bom briefing precisa resolver
Antes de editar arquivos, o Codex precisa responder:
- qual resultado deve existir no final;
- qual é o estado atual;
- que parte do projeto está em escopo;
- quais restrições não podem ser quebradas;
- como comprovar que a mudança funciona;
- qual formato de entrega o usuário espera.
“Melhore o checkout” não responde a nenhuma dessas perguntas. “Corrija a validação do CEP sem alterar o contrato da API; adicione teste de regressão e execute a suíte do módulo” é mais útil.
O guia oficial de prompting no Codex reforça a importância de intenção clara, contexto relevante e verificação.
Estrutura de briefing em sete blocos
1. Resultado
Descreva o estado final, não apenas a atividade.
Resultado: o formulário deve impedir envio com telefone inválido e mostrar
uma mensagem acessível ao lado do campo, sem alterar o layout em desktop.
2. Contexto
Explique por que a mudança existe, quem é afetado e qual comportamento ocorre hoje.
3. Escopo
Indique módulos e comportamentos permitidos. Se não souber os arquivos, diga para o Codex localizá-los antes de propor alterações.
4. Fora de escopo
Declare o que não deve ser refeito. Isso evita uma correção pequena virar refatoração geral.
5. Restrições
Compatibilidade, dependências, padrões de segurança, produção, acessibilidade e dados.
6. Critérios de aceite
Use condições observáveis:
- teste X passa;
- resposta da API mantém o schema;
- página funciona em 375 e 1280 pixels;
- nenhuma credencial aparece no diff;
- erro é reproduzido antes e resolvido depois.
7. Entrega
Peça resumo, arquivos alterados, testes executados, evidências e riscos restantes.
Leia também: Entenda o fluxo básico do OpenAI Codex
Modelo pronto de briefing
Objetivo: [resultado verificável].
Estado atual: [comportamento observado e evidência].
Escopo: [módulos, páginas ou arquivos].
Fora de escopo: [mudanças proibidas].
Restrições: [compatibilidade, dados, segurança, design].
Critérios de aceite:
- [condição 1]
- [condição 2]
- [condição 3]
Verificação: [comandos e QA].
Entrega: resumo, diff, testes, evidências e pendências.
Antes de editar, inspecione o projeto e apresente um plano curto.
Se encontrar conflito entre estas instruções e o repositório, pare e explique.
Esse modelo não precisa virar burocracia. Para uma correção simples, cada campo pode ter uma linha.
O que é AGENTS.md
O guia oficial de AGENTS.md descreve um arquivo de instruções persistentes para orientar o agente dentro de um repositório ou diretório.
Ele pode registrar:
- comandos de instalação, teste e build;
- organização do código;
- convenções de nomes;
- limites de edição;
- requisitos de segurança;
- processo de QA;
- formato de commit ou entrega;
- caminhos para documentação relevante.
Ele não deve tentar explicar todo o negócio, substituir a documentação técnica nem guardar segredos.
Onde colocar o arquivo
Use um AGENTS.md na raiz para regras gerais. Quando uma área tem regras próprias, um arquivo mais próximo pode registrar instruções daquele subdiretório.
Exemplo:
repositorio/
├── AGENTS.md
├── backend/
│ └── AGENTS.md
└── frontend/
└── AGENTS.md
O arquivo da raiz pode definir testes gerais e proibir credenciais. O de frontend/ pode definir acessibilidade e QA visual. O de backend/ pode exigir migrações reversíveis e testes de contrato.
Evite duplicar a mesma regra em vários níveis. Duplicação produz divergência quando alguém atualiza um arquivo e esquece os outros.
Exemplo de AGENTS.md enxuto
# Projeto
## Comandos
- Instalar: `npm ci`
- Testar: `npm test`
- Lint: `npm run lint`
## Regras
- Preserve o contrato público da API.
- Não adicione dependência sem justificar.
- Nunca inclua segredos ou arquivos `.env` no commit.
- Faça mudanças pequenas e relacionadas ao pedido.
## Verificação
- Execute testes do módulo alterado.
- Para interface, confira desktop e mobile.
- Na entrega, liste comandos e resultados.
Tudo é observável. “Escreva código excelente” não é uma instrução útil porque cada pessoa interpreta de uma forma.
O que não colocar
Senhas e tokens
Use um gerenciador ou mecanismo de segredo. Nunca coloque valores no arquivo.
Regras temporárias
“Hoje não mexa no módulo X” pertence ao briefing da tarefa ou a uma issue.
História completa do projeto
Referencie um documento. O AGENTS.md deve funcionar como mapa operacional.
Instruções conflitantes
Se a raiz manda editar livremente e um subdiretório proíbe alterações, o agente terá que resolver uma ambiguidade que a equipe poderia remover.
Preferências sem consequência
Troque “prefira código simples” por critérios: limite de escopo, padrões do módulo e testes exigidos.
Briefing e AGENTS.md em uma tarefa real
Imagine um bug no login.
O AGENTS.md informa que autenticação exige revisão, que testes rodam com um comando e que não se deve mudar o schema público.
O briefing informa que usuários com e-mail em maiúsculas não conseguem entrar, aponta um exemplo, limita a mudança à normalização e exige teste de regressão.
O Codex começa sabendo tanto o padrão do projeto quanto o problema atual.
Peça inspeção antes da implementação
Em projeto desconhecido:
Antes de editar, localize o fluxo completo, os testes existentes e as instruções
aplicáveis. Resuma a causa provável, os arquivos relevantes e o plano.
Não altere nada até concluir essa inspeção.
Isso reduz o risco de corrigir o sintoma no arquivo errado. Depois, aprove o plano ou ajuste o escopo.
Critérios de aceite que realmente ajudam
Critérios bons são binários ou mensuráveis.
Fraco: “a página deve ficar melhor”.
Melhor: “o título não quebra em 375 px; o botão permanece visível sem rolagem horizontal; contraste atende ao padrão do projeto”.
Fraco: “corrija a API”.
Melhor: “requisição sem customer_id retorna 400 com o mesmo schema de erro e teste de contrato passa”.
Inclua também um critério negativo: o que não pode regredir.
Como manter as instruções saudáveis
Revise o AGENTS.md quando:
- comandos mudarem;
- a arquitetura ganhar novo módulo;
- um incidente revelar regra ausente;
- instruções deixarem de ser aplicáveis;
- a equipe adotar novo processo de teste;
- o arquivo começar a crescer por repetição.
Peça ao Codex para apontar regras duplicadas, mas aprove manualmente qualquer alteração nas instruções. Elas governam trabalhos futuros.
Relação com skills e plugins
Se uma regra descreve o projeto, ela pertence ao AGENTS.md. Se descreve um procedimento reutilizável em vários projetos, pode virar skill. Se precisa ser distribuída com ferramentas ou conectores, pode fazer parte de um plugin.
O artigo Skills, plugins e MCP no Codex explica essa divisão. Para revisão e testes, veja Codex para testes e code review.
Checklist antes de enviar
- O resultado final está explícito?
- Estado atual tem evidência?
- Escopo e fora de escopo estão separados?
- Critérios são verificáveis?
- Comandos de teste estão corretos?
- Regras duráveis estão no AGENTS.md?
- Regras temporárias ficaram no briefing?
- Não há senha, token ou dado sensível?
- O formato da entrega está definido?
Um bom briefing não tenta controlar cada linha de código. Ele dá ao Codex liberdade para investigar dentro de fronteiras claras e exige evidência suficiente para a equipe aceitar ou rejeitar a mudança.
Como escrever briefings para diferentes tarefas
Correção de bug
Priorize reprodução, comportamento esperado, erro observado, ambiente e teste de regressão. Não peça refatoração junto.
Nova funcionalidade
Descreva usuário, fluxo, estados, dados, permissões, critérios e integração. Inclua estados vazio, carregando, erro e sucesso.
Refatoração
Defina o que deve permanecer igual, métrica de melhoria e testes de caracterização. “Deixe mais limpo” não é critério.
Investigação
Proíba edição no primeiro momento. Peça mapa do fluxo, hipóteses, evidências e perguntas ainda sem resposta.
Documentação
Defina audiência, fonte da verdade, exemplos executáveis e versão. Peça validação de comandos.
Um teste simples para o AGENTS.md
Entregue o arquivo a uma pessoa nova e pergunte:
- como instalar o projeto?
- que comando testa a mudança?
- quais áreas são sensíveis?
- o que exige aprovação?
- como entregar evidência?
Se ela não encontra a resposta, o agente também pode perder tempo. Se o arquivo responde com três versões conflitantes, a equipe precisa consolidar.
Como tratar conflitos de instrução
Escreva no briefing:
Se uma regra do pedido conflitar com AGENTS.md, documentação do repositório
ou comportamento dos testes, não escolha silenciosamente. Mostre o conflito,
explique o impacto e peça decisão antes de editar.
Esse mecanismo é útil quando uma demanda comercial pede algo incompatível com contrato técnico ou segurança.
Registro de decisões
O briefing termina quando a tarefa termina. Decisões arquiteturais ou de processo que afetam trabalhos futuros devem ir para documentação própria. Atualize o AGENTS.md apenas quando a decisão muda como o agente deve trabalhar.
Registre data, motivo, alternativas e responsável. Assim, uma regra como “não adicionar dependências” deixa de parecer capricho e pode ser revisada quando o contexto mudar.
Sinal de que o briefing está pronto
Outra pessoa consegue ler e responder: qual problema, qual limite, como testar e quem aprova. Se a resposta depende de uma reunião não registrada, consolide essa decisão antes de chamar o Codex.
Antipadrões que confundem o agente
Objetivos incompatíveis
“Mude o mínimo possível e refaça toda a arquitetura” precisa de prioridade. Divida em tarefas ou escolha o objetivo dominante.
Termos subjetivos
“Moderno”, “rápido” e “seguro” precisam de referência ou métrica. Informe layout aprovado, tempo máximo ou controle exigido.
Permissão escondida
Não use “faça o necessário” para autorizar rede, instalação ou produção. Declare ações permitidas e gates.
Arquivo citado sem caminho
Se existem várias versões, identifique a fonte. Peça ao Codex para confirmar que a encontrou.
Critério que depende do próprio agente
“Está pronto quando você achar bom” não cria revisão. Use teste, screenshot, schema ou aprovação humana.
Briefing como contrato de mudança
Durante a execução, novas ideias surgem. Registre-as como pendências e não as inclua silenciosamente. Se uma descoberta exige ampliar escopo, pare, mostre impacto e obtenha decisão.
Ao final, compare entrega e briefing. Liste critérios atendidos, parcialmente atendidos e não atendidos. Essa reconciliação protege a equipe de aceitar uma mudança convincente que resolveu outro problema.
Perguntas frequentes
O que é AGENTS.md? +
É um arquivo de instruções persistentes que orienta o Codex sobre comandos, padrões, estrutura e regras do repositório dentro do escopo em que se aplica.
AGENTS.md substitui o briefing da tarefa? +
Não. O arquivo registra regras duráveis; o briefing informa objetivo, escopo, critérios de aceite e restrições específicas da tarefa atual.
Onde colocar o AGENTS.md? +
Coloque regras gerais na raiz e, quando necessário, regras mais específicas em subdiretórios. Confirme a precedência na documentação atual do Codex.
Um AGENTS.md muito longo ajuda? +
Nem sempre. Instruções redundantes, antigas ou contraditórias consomem contexto e prejudicam decisões. Mantenha apenas regras úteis e testáveis.
Qual é o melhor formato de briefing? +
Resultado esperado, estado atual, escopo, arquivos relevantes, restrições, critérios de aceite, comandos de teste e formato de entrega.
Artigos Relacionados
