O problema: por que a IA sempre tropeça no mesmo lugar

Quem usa Cursor, Windsurf ou Claude Code para escrever código já passou por isso: a IA cospe um bloco inteiro, você cola, roda — build quebra, testes ficam vermelhos, dependências vão parar no lugar errado. O problema não é a inteligência da IA, é que ela simplesmente não conhece as “regras não ditas” do seu projeto.

AGENTS.md é um arquivo Markdown na raiz do projeto, escrito exclusivamente para a IA. Diz a ela como buildar, como testar, quais convenções seguir. O README.md é para humanos — cheio de apresentação do projeto, guia de contribuição, história da marca. Quando a IA lê esse conteúdo, é como um funcionário novo que no primeiro dia recebe um panfleto institucional e já é mandado para o código: sabe o que a empresa faz, mas não sabe o comando de build, não sabe como rodar os testes, não sabe quais regras o ESLint aplica. Resultado: você fica repetindo no chat “usa pnpm, não npm”, “os testes estão em packages/web”, “não esquece de rodar o lint”. Repete cem vezes, o projeto continua bagunçado.

No trabalho freelance, o prejuízo é direto: você pegou um projeto de Next.js + Prisma, pediu ajuda ao Cursor para acelerar, e a IA rodou npm install, jogando fora toda a configuração de workspace do pnpm; ela não sabia onde estava o schema do banco e gerou migrations quebradas. Cliente cobrando entrega, você gasta três horas debugando código gerado por IA — dinheiro ganho com gosto amargo.

Três cenários clássicos em que a IA ignora as regras do projeto: ① gerenciador de pacotes errado (o projeto usa pnpm, a IA usa npm install por padrão), dependências no lugar errado, workspace desconfigurado; ② entrada de testes não encontrada (testes em packages/web, a IA roda pnpm test na raiz e recebe “arquivo de teste não encontrado”); ③ estilo de código inconsistente (projeto usa ESLint + Prettier, a IA gera código com indentação e aspas erradas, CI quebra na hora).

A virada: AGENTS.md separa de vez “documentação humana” de “documentação de máquina”

O projeto open source AGENTS.md no GitHub (repositório github.com/agentsmd/agents.md, cerca de 24 mil stars em 2026-08-25) resolve exatamente isso. A ideia é simples: um Markdown na raiz do projeto, dedicado a dizer à IA como buildar, testar e estilizar o código.

Não substitui o README, complementa. README serve para contribuidores humanos, AGENTS.md serve para agentes de IA. Funções claras, sem conflito.

Segundo o post original, AGENTS.md já foi adotado por dezenas de milhares de projetos open source (número exato a confirmar), cobrindo as principais ferramentas de programação com IA: VS Code, Cursor, Windsurf, Aider, GitHub Copilot (confirmado); além disso, relatos da comunidade indicam suporte também em OpenAI Codex, Google Jules e outros (⚠️ não verificado). Se você não aprender agora, vai continuar falando “dialeto de IA” sem entender nada.

Caminho 1: escrever um AGENTS.md mínimo viável à mão

Custo quase zero. Crie o arquivo, escreva três blocos e pronto.

Contexto rápido: os exemplos abaixo usam pnpm (mais leve que npm, suporta workspaces de monorepo), turbo é o orquestrador de tarefas do monorepo, e o parâmetro --filter aplica o comando só em um subpacote, sem afetar o resto do repositório.

Primeiro bloco “Dev environment tips”: diz à IA qual gerenciador usar, como navegar entre subpacotes, como criar módulos. Exemplo do repositório oficial:

• pnpm dlx turbo run where <project_name> — pula direto para o diretório do subpacote, sem ficar dando ls
• pnpm install --filter <project_name> — instala dependências só de um subpacote, sem tocar no monorepo inteiro
• pnpm create vite@latest <project_name> -- --template react-ts — cria um subpacote React + Vite com checagem TypeScript

São comandos que a IA não adivinha sozinha, mas obedece na hora se você escrever.

Segundo bloco “Testing instructions”: diz como rodar testes, onde fica o pipeline de CI, quais checagens rodar antes do commit. Exemplo oficial:

• pnpm turbo run test --filter <project_name> — roda todas as checagens do subpacote
• pnpm vitest run -t "<test name>" — roda só o teste que bate com aquele nome
• “Fix any test or type errors until the whole suite is green” — não para até tudo passar
• “Add or update tests for the code you change, even if nobody asked” — essa é a chave: sem ela, a IA costuma economizar nos testes

Terceiro bloco “PR instructions”: padroniza o título do commit e obriga lint + test. Exemplo oficial: Title format: [<project_name>] <Title> e “Always run pnpm lint and pnpm test before committing”.

São menos de 50 linhas no total, mas a taxa de acerto do código gerado pela IA sobe de forma visível (segundo relatos da comunidade, número exato a confirmar).

Caminho 2: aninhando em monorepos grandes

Se você pegou um projeto corporativo com estrutura de monorepo (vários projetos relacionados no mesmo repositório Git — frontend, backend, código compartilhado, cada um em seu subdiretório), um único AGENTS.md não dá conta. O AGENTS.md suporta aninhamento: coloque um arquivo dedicado em cada subdiretório, e a IA lê automaticamente o “mais próximo”.

Na prática: o AGENTS.md da raiz traz as regras globais (gerenciador de pacotes, fluxo de CI, segurança); depois coloque um em packages/web/, packages/api/, packages/shared/, com comandos de build, entrada de testes e dependências específicas daquele subpacote. Exemplo: o pacote de front pode dizer “componentes com shadcn, estilo com Tailwind, ícones com lucide-react”; o de back pode dizer “migrations com Prisma, rotas em src/routes, autenticação com JWT”.

Quando a IA trabalha dentro de um subdiretório, ela carrega o AGENTS.md mais próximo, com prioridade sobre o da raiz. Isso significa que, no mesmo projeto, o assistente de front e o de back recebem instruções totalmente diferentes, sem se misturar.

Caminho 3: transforme isso em diferencial competitivo nos freelas

O mercado de freelances com IA já está saturado — todo mundo sabe usar Cursor, mas a qualidade da entrega varia demais. Se você colocar na proposta uma frase como “este projeto já vem com AGENTS.md configurado, desenvolvimento assistido por IA seguindo as convenções do projeto”, sua taxa de fechamento sobe na frente de quem só diz “uso IA para escrever código”.

Tática concreta: ao receber o job, gaste 30 minutos entendendo a estrutura do projeto do cliente e escreva um AGENTS.md sob medida. Esse documento em si já é parte da entrega — o cliente, no futuro, vai manter o código com IA com muito mais tranquilidade.

Cobre a configuração de AGENTS.md como serviço avulso (valores de referência, ajustar ao mercado local): versão básica R$ 350 (arquivo único + um README explicativo), versão empresarial R$ 2.000 (aninhamento em monorepo + normas de segurança + treinamento da equipe). O que entregar: ① arquivo AGENTS.md personalizado ② 30 dias de suporte por WhatsApp ③ vídeo de treinamento de 10 minutos. Ideal para: cliente que já tem assinatura de Cursor/Windsurf mas não consegue extrair resultado. Não serve para: cliente que ainda desenvolve 100% manual, sem nenhuma ferramenta de IA.

Caso real: o fosso de compatibilidade do AGENTS.md

AGENTS.md usa licença MIT (confirmado), é mantido pela comunidade (estrutura de governança exata a confirmar), site oficial é agents.md.

O fosso competitivo é a compatibilidade: confirmado que VS Code, Cursor, Windsurf, Aider e GitHub Copilot leem AGENTS.md; relatos da comunidade indicam suporte também em OpenAI Codex, Claude Code, Gemini CLI, Google Jules (⚠️ não verificado). Isso significa que um único arquivo serve para todas as ferramentas principais — sem precisar escrever uma config para cada uma.

Compare com as alternativas: o .cursorrules do Cursor só funciona no Cursor; o CLAUDE.md do Claude Code só serve para o Claude; o sistema de instruções do GitHub Copilot é outra coisa. O “escreve uma vez, roda em qualquer lugar” do AGENTS.md é a razão pela qual ele foi adotado tão rápido.

Custo de migração de ferramenta zerado. Hoje você usa Cursor, amanhã troca para Windsurf, o AGENTS.md continua valendo, sem reescrever regra nenhuma.

Chamada para ação: crie o manual de máquina do seu projeto hoje à noite

Checklist de 5 minutos: ① abra a raiz do projeto ② crie AGENTS.md ③ copie o modelo oficial (github.com/agentsmd/agents.md) ④ preencha três comandos (build, test, lint) ⑤ na próxima vez que pedir código à IA, observe o resultado.

Se o seu projeto é monorepo, gaste mais 20 minutos hoje à noite configurando um arquivo aninhado em cada subpacote. Amanhã, quando você abrir o editor, o código gerado pela IA não vai mais precisar de correção em loop.

AGENTS.md é, hoje, a configuração de programação com IA com melhor retorno por minuto investido — 30 minutos de setup para economizar várias horas de debug por mês.