AGENTS.md: O Arquivo Mais Importante de um Codebase AI-Native

O arquivo que nenhum codebase convencional tem

A Powertrend é especialista em Engenharia AI-Native — a metodologia que projeta sistemas para que agentes de IA consigam construir, testar e implantar de forma autônoma. O AGENTS.md é um dos artefatos centrais dessa metodologia e um dos primeiros arquivos que a Powertrend cria em qualquer projeto.

Em um time humano, quando um novo desenvolvedor entra, ele passa por um processo de onboarding: alguém explica a arquitetura, os módulos principais, as convenções do projeto, o que não pode ser tocado sem alinhamento, como rodar os testes localmente. Esse conhecimento existe na cabeça das pessoas — e é transferido via conversa.

Um agente de IA não tem esse processo. Ele começa do zero a cada contexto. Sem um documento que concentre esse conhecimento, o agente opera no codebase como alguém que chegou no primeiro dia sem nenhuma orientação — cometendo erros evitáveis, repetindo perguntas, tomando decisões com informação incompleta.

O AGENTS.md existe para resolver exatamente isso. É o onboarding do agente, comprimido em um arquivo que ele lê em segundos.

O que um AGENTS.md eficaz contém

Um AGENTS.md eficaz não é um README melhorado. Ele tem seções específicas, escritas para agentes — não para humanos. A diferença é sutil mas crucial: humanos inferem contexto; agentes precisam de declarações explícitas.

Seção 1: Visão geral arquitetural (máx. 200 palavras)

Descreva o sistema em termos que um agente pode usar para raciocinar: qual problema resolve, quais são os módulos principais, como eles se comunicam, qual o fluxo de dados principal. Sem história da empresa ou contexto de negócio genérico — apenas o suficiente para o agente entender onde cada peça se encaixa.

Seção 2: Mapa de módulos

Liste cada módulo/diretório com sua responsabilidade em uma linha. Inclua: o que o módulo faz, quem consome sua saída, quais são suas dependências externas, se há invariantes críticas que o módulo mantém. Exemplo:

• src/domain/ — Regras de negócio puras, sem dependências externas. Nunca importar de infrastructure/ aqui.
• src/application/ — Casos de uso. Orquestra domain/ e chama ports de infrastructure/.
• src/infrastructure/ — Adaptadores externos (banco, APIs, filas). Implementa interfaces definidas em application/.
• src/api/ — Handlers HTTP. Validação de entrada com Zod, sem lógica de negócio.

Seção 3: Convenções críticas

Declare explicitamente as convenções que o agente precisa seguir. Não as óbvias (use TypeScript, siga o prettier) — mas as específicas do projeto que são fáceis de violar sem saber que existem:

• Toda nova entidade de domínio precisa de um Value Object para seu identificador (ex: UserId, not string)
• Nunca lançar exceções de infraestrutura para a camada de domínio — use Result<T, E>
• Testes de unidade não podem fazer I/O — se precisar de banco, é teste de integração e vai em __tests__/integration/
• Toda nova API route precisa de schema Zod de input antes de qualquer implementação

Seção 4: O que não tocar sem alinhamento

Essa é a seção mais importante para segurança operacional. Liste explicitamente as partes do sistema que têm alto impacto e precisam de revisão humana antes de qualquer mudança:

• src/domain/billing/ — Regras de cobrança. Qualquer mudança precisa de revisão do lead engineer.
• migrations/ — Migrações de banco de dados. Nunca modificar uma migração já rodada em produção.
• src/infrastructure/payment/ — Integração com gateway de pagamento. Mudanças precisam de teste em sandbox antes de PR.

Seção 5: Como verificar seu próprio trabalho

Instrua o agente sobre como rodar a verificação local e o que cada resultado significa:

• npm run check — Roda lint + typecheck + jest em paralelo. Deve terminar em < 2 minutos.
• Se um teste de contrato falhar em src/__tests__/contracts/, você mudou uma interface pública. Atualize o consumidor ou crie uma nova versão do contrato.
• Se o typecheck falhar em strict mode, não use @ts-ignore. Corrija o tipo.

Onde colocar o AGENTS.md

Na raiz do repositório — não em docs/ ou em subdiretórios. A razão é prática: ferramentas de IA como Cursor, Claude Projects e GitHub Copilot têm comportamentos padrão de leitura de arquivos na raiz do repositório. Colocar o AGENTS.md na raiz maximiza a probabilidade de ser lido automaticamente antes de qualquer interação.

Para projetos monorepo com múltiplos serviços, cada serviço pode ter seu próprio AGENTS.md em sua raiz, além de um AGENTS.md global na raiz do monorepo que descreve a estrutura geral.

A diferença na prática

Um codebase sem AGENTS.md força o agente a deduzir a arquitetura explorando arquivos — o que produz inferências incorretas, especialmente sobre convenções não aparentes no código. Um codebase com um AGENTS.md bem escrito permite que o agente faça perguntas melhores, tome decisões mais alinhadas e cometa menos erros de convenção.

Em nosso AI-Readiness Assessment, a dimensão de Autodescritibilidade — que inclui o AGENTS.md — tem peso de 10% no score final. É a dimensão com melhor relação entre esforço de implementação e ganho em autonomia do agente.

• Leia também: Os 6 Princípios da Arquitetura AI-Native → /blog/principios-arquitetura-ai-native
• Leia também: AI-Readiness Score — como medir se seu codebase está pronto → /blog/ai-readiness-score
• Leia também: De 50 para 5 engenheiros com Arquitetura AI-Native → /blog/time-encolheu-entregou-mais-rapido
• Conheça nosso serviço de Engenharia AI-Native → /engenharia-de-software