Você provavelmente já usou uma IA para resolver um problema técnico num repositório seu. Funcionou. Então usou de novo, explicando o contexto na mão. Funcionou também. Mas a cada nova sessão, você recomeça do zero — repetindo o mesmo briefing, corrigindo as mesmas suposições erradas, desfazendo decisões “corretas” que ignoraram algo que só você sabia.
O AGENTS.md é a solução para isso. E este artigo é um argumento pela adoção desse arquivo como prática padrão em qualquer projeto onde você use agentes de IA.
O problema invisível com agentes de IA
Quando você senta com um dev sênior para fazer pair programming, ele traz contexto da última semana de trabalho junto. Ele sabe que a migração do banco está congelada, que o cliente X não aceita breaking changes, que vocês evitam async void naquele módulo legado por uma razão específica.
Um agente de IA não tem isso. Cada sessão começa do zero. Sem memória do que foi discutido antes, sem conhecimento das decisões de arquitetura que custaram três sprints para chegar, sem saber que aquela dependência “estranha” no .csproj está lá por um motivo muito específico.
O resultado? O agente resolve o problema técnico imediato com competência — mas frequentemente desfaz algo que você não tinha documentado em lugar nenhum, porque estava “na cabeça do time”.
Um agente sem contexto não é burro. Ele é competente e desinformado — que é, de certa forma, mais perigoso.
E à medida que as ferramentas evoluem — Claude Code, Cursor, GitHub Copilot Workspace, Devin — os agentes não apenas sugerem código. Eles criam arquivos, modificam configurações, fazem commits. O espaço para dano involuntário cresce proporcionalmente à autonomia que você dá a eles.
O que é o AGENTS.md (e por que esse nome)
O AGENTS.md é um arquivo de texto em Markdown, colocado na raiz do repositório, que funciona como um briefing estruturado para qualquer agente de IA que for trabalhar naquele projeto.
Ferramentas diferentes têm convenções de nomenclatura ligeiramente diferentes:
- Claude Code lê
CLAUDE.md - Cursor usa
.cursorrulesouCURSOR.md - Codex / ChatGPT respondem bem a
AGENTS.md - Convenção emergente:
AGENTS.mdestá se tornando o padrão agnóstico de ferramenta
Recomendação prática: crie
AGENTS.mdcomo o documento canônico e, se necessário, crie umCLAUDE.mdou.cursorrulesque simplesmente inclua uma referência a ele. Evita duplicação e mantém uma fonte única de verdade.
O arquivo é lido automaticamente por essas ferramentas antes de qualquer ação. É como um README, mas escrito para ser consumido por uma máquina que vai agir — não por um humano que vai entender.
O que colocar no arquivo
Não existe um esquema obrigatório, mas há categorias que fazem diferença real na qualidade das interações com agentes. Veja um exemplo comentado:
# AGENTS.md
## Visão geral
API REST em .NET 8 para gestão de agendamentos médicos.
Integra com sistema legado via SOAP e expõe endpoints REST
para aplicativo mobile. Multi-tenant, dados isolados por schema.
## Stack e versões
- .NET 8 (LTS) — não migrar para versões preview sem aprovação
- PostgreSQL 15 com EF Core 8 (Code First)
- Autenticação via JWT + refresh token
- Logs com Serilog → OpenTelemetry → Elastic
## Decisões de arquitetura documentadas
- TLS usa BouncyCastle, não Schannel nativo (compatibilidade
com Windows Server 2012 R2 no ambiente do cliente)
- Não usar HttpClient diretamente — usar o wrapper interno
em Infrastructure/Http/ApiClient.cs que já tem retry e timeout
- Migrations são aplicadas pelo pipeline CI, nunca manualmente
e nunca pelo agente
## Convenções de código
- PascalCase para classes, interfaces, métodos e propriedades
- camelCase para variáveis locais e parâmetros
- Prefixo I para interfaces (IAgendamentoService)
- Testes: xUnit + Bogus para dados falsos, sem Moq
- Commits seguem Conventional Commits
## Restrições explícitas para o agente
- NÃO alterar arquivos de migration já aplicados em produção
- NÃO remover ou atualizar pacotes NuGet sem aprovação explícita
- NÃO fazer push direto em main ou develop
- NÃO alterar arquivos em /Infrastructure/Legacy sem revisar
o contrato SOAP primeiro — o sistema legado não tem versionamento
- Todo novo serviço de domínio precisa de testes unitários
antes de ser considerado completo
Repare no tom direto das restrições. Não é documentação técnica para humanos — é instrução operacional para um agente que vai tomar decisões sem te perguntar a cada passo.
Por que arquitetos e tech leads precisam liderar isso
Aqui vem a parte opinativa: se você ocupa uma cadeira de arquitetura ou tech lead e ainda não tem esse arquivo nos seus projetos, você está gerenciando um risco que ainda não percebeu.
Desenvolvedores júnior e pleno estão usando agentes de IA ativamente — para bem. Eles resolvem problemas mais rápido, aprendem mais rápido, entregam mais. Mas eles usam esses agentes sem o contexto que só você tem: as decisões de design que não estão no código, as restrições de ambiente do cliente, as razões pelas quais aquela solução “mais simples” foi descartada há seis meses.
O AGENTS.md é o mecanismo pelo qual você transfere contexto arquitetural para o agente antes que ele aja, independentemente de quem está na sessão. É governança de IA aplicada no nível do repositório.
Um agente sem
AGENTS.mdem um repositório com decisões não documentadas não é um assistente. É um colaborador talentoso que foi jogado no projeto no primeiro dia, sem onboarding, com acesso de escrita.
Exemplos do mundo real: o que pode dar errado sem ele
Caso 1 — Atualização de dependência destrutiva
Um agente recebe a tarefa de “atualizar os pacotes desatualizados”. Sem contexto, ele atualiza corretamente. Mas uma das atualizações quebra a compatibilidade com uma API de terceiros que estava fixada naquela versão específica por acordo contratual com o cliente. Nada disso estava no código — estava num email de 2022.
Com um AGENTS.md:
Não atualizar o pacote AwesomeClient além da versão 3.x —
contrato com cliente exige compatibilidade com API v2.
Problema evitado.
Caso 2 — Migration reescrita
Um agente identificou que uma migration antiga tinha uma coluna com nome errado (typo). Ele “corrigiu” criando uma nova migration que renomeava a coluna. Em produção, aquela coluna era referenciada por três views e dois jobs externos. Zero testes cobria isso.
Com um AGENTS.md:
Migrations já aplicadas em produção são imutáveis. Nunca alterar
ou recriar — criar nova migration incremental se necessário.
Caso 3 — Padrão ignorado por “ineficiência”
O projeto usava um padrão de repositório verbose por design — cada query era explícita, sem abstração de LINQ genérico. O agente, interpretando isso como código ruim, refatorou para um repositório genérico “mais limpo”. A mudança quebrou um requisito de auditoria que exigia queries rastreáveis por nome.
Com um AGENTS.md:
O padrão de repositório explícito é intencional (requisito de
auditoria #COMP-112). Não refatorar para repositório genérico.
AGENTS.md não é documentação — é contrato
Essa distinção é importante. Documentação é para humanos lerem quando têm dúvidas. O AGENTS.md é lido sempre, antes de qualquer ação, por um agente que vai usar essas informações para tomar decisões em seu nome.
Isso muda a forma como você escreve. Menos prosa explicativa, mais instruções diretas. Menos “o projeto faz X porque Y” e mais “não faça Z”. O tom deve ser o de um briefing técnico, não de uma wiki.
E assim como um contrato, ele precisa ser mantido. Toda decisão arquitetural relevante que você tomar daqui pra frente merece uma linha nesse arquivo. Toda restrição de ambiente. Toda dependência fixada por razão não óbvia.
A qualidade das suas interações com agentes de IA vai ser proporcional à qualidade do contexto que você fornece. O AGENTS.md é a infraestrutura desse contexto.
Por onde começar agora
Não espere o projeto estar “pronto” para criar o arquivo. Comece hoje, com o que você sabe que é crítico não quebrar:
- Liste as três coisas que um dev novo jamais deveria alterar sem perguntar. Coloque como restrições.
- Documente a stack com versões. Especialmente onde há restrições de versão não óbvias.
- Registre decisões de arquitetura que não aparecem no código. O “porquê” de escolhas não convencionais.
- Defina o fluxo de trabalho esperado. Branch policy, como rodar testes, onde ficam os ambientes.
- Itere. A cada vez que você se pegar corrigindo algo que o agente fez errado, pergunte: isso deveria estar no
AGENTS.md?
Dica prática: use o próprio agente para ajudar a criar o arquivo. Descreva o projeto em conversa e peça para ele gerar um rascunho de
AGENTS.md. Você vai revisar e corrigir — mas o esqueleto vai estar lá, e o exercício em si vai forçar você a articular decisões que estavam só na sua cabeça.
Conclusão
A adoção de agentes de IA em fluxos de desenvolvimento é irreversível. A questão não é se você vai usá-los — é se você vai usá-los com governança ou na base do improviso.
O AGENTS.md é um arquivo pequeno com impacto desproporcional. Ele não resolve todos os problemas de usar IA em software — mas resolve um problema específico e crítico: impede que um agente competente e bem-intencionado tome decisões erradas por falta de contexto que só existia na sua cabeça.
Para arquitetos e tech leads, criar e manter esse arquivo é uma responsabilidade de papel — não uma tarefa opcional. Você é o guardião do contexto que os agentes precisam para agir com segurança no seu repositório.
Comece com dez linhas. Melhore com o tempo. Seu eu do futuro — e seu agente — vão agradecer.