A reclamação mais comum de quem começa a usar agentes de código é: “ele escreve rápido, mas não do jeito do projeto”. Importa a biblioteca errada, cria pasta fora do padrão, ignora a camada de serviço, pula os testes. O problema quase nunca é o modelo. É falta de contexto.
Neste artigo mostramos a abordagem que usamos em produção — inclusive em um CRM com agentes de IA que passou de 800 commits em cerca de seis meses — para fazer agentes seguirem a arquitetura do time.
O que é o AGENTS.md
AGENTS.md é um arquivo na raiz do repositório com instruções para agentes de código. Ferramentas como Codex e Cursor o leem automaticamente, e o Claude Code lê o CLAUDE.md, que pode simplesmente apontar para o AGENTS.md. Pense nele como o guia de onboarding do projeto, só que escrito para a IA.
O que colocar nele
- Estrutura de pastas e responsabilidade de cada camada.
- Regras de dependência: quem pode importar quem.
- Padrões de código: nomenclatura, tipagem, tratamento de erros.
- Comandos para rodar lint, testes e build — e a exigência de rodá-los.
- O que o agente nunca deve fazer, como alterar migrações já aplicadas ou mexer em segredos.
Hierarquia de regras: constituição, AGENTS.md e skills
Em projetos maiores vale separar as regras em níveis. Uma constituição define princípios que não mudam com frequência — isolamento entre clientes, stack aprovada, regras de dados. O AGENTS.md detalha o dia a dia. Skills ou regras específicas cobrem tarefas recorrentes, como criar um módulo novo ou escrever uma migração.
Deixe explícita a ordem de prioridade: instrução do usuário, especificação aprovada, constituição e, por fim, as convenções do código existente. Quando duas regras conflitam, o agente sabe qual seguir.
Desenvolvimento orientado a especificação
Para entregas maiores do que uma correção pontual, pedir código direto ao agente gera retrabalho. O fluxo que funciona melhor é: escrever a especificação, revisar, quebrar em tarefas e só então implementar.
- Especificação: o que será construído, para quem, com critérios de aceite e fora de escopo.
- Plano técnico: como a funcionalidade se encaixa na arquitetura, checado contra a constituição.
- Tarefas: passos pequenos e verificáveis, cada um com seus testes.
- Implementação: o agente executa tarefa por tarefa, rodando testes a cada passo.
A especificação vira documentação da decisão. Meses depois, qualquer pessoa — ou agente — entende por que a funcionalidade é como é.
Agentes revisores especializados
Um único agente revisando tudo tende a dar feedback genérico. Funciona melhor ter revisores com foco estreito, cada um com seu próprio arquivo de instruções: um para arquitetura e manutenibilidade, outro para segurança de API, outro para performance de banco de dados, outro para confiabilidade (filas, retentativas, idempotência) e um para simplificar código. Eles rodam antes da revisão humana, que passa a olhar para o que importa.
Testar o fluxo real com ferramentas MCP
Testes unitários não mostram tudo. Em sistemas com webhooks, filas e workers, vale dar ao agente uma ferramenta MCP local que dispara o fluxo real — por exemplo, uma mensagem chegando pelo webhook — e inspeciona o banco, o Redis e as filas para descrever o que aconteceu. Com travas que impedem a ferramenta de rodar contra produção, o agente consegue depurar e validar o próprio trabalho de ponta a ponta.
Testes como portão
Nenhuma regra substitui um portão automático. Lint estrito, verificação de tipos e testes rodando em todo pull request garantem que o código gerado pela IA atenda ao mesmo padrão do resto. No projeto citado acima, isso significou mais de 770 arquivos de testes automatizados acompanhando o crescimento do sistema.
Por onde começar
- Crie um AGENTS.md curto com estrutura, padrões e comandos de verificação.
- Toda vez que o agente errar algo recorrente, transforme a correção em regra.
- Para a próxima funcionalidade média, experimente escrever a especificação antes do código.
- Garanta que lint e testes rodem em todo pull request.