AGENTS.md: o arquivo que dá memória ao seu agente

O AGENTS.md não deixa o modelo mais inteligente. Ele diz ao modelo o que ele teria que redescobrir toda santa vez.

O modelo não tem memória. Não é uma limitação que alguém planeja corrigir. É assim que a inferência de um transformer funciona: você dá tokens, ele produz tokens, e quando a sessão acaba tudo o que ele aprendeu sobre o seu projeto some. A próxima sessão começa do zero.

Isso não é um bug que você contorna. É uma restrição para a qual você projeta. O arquivo que faz mais trabalho nesse projeto é o AGENTS.md.

O modelo acorda com amnésia

A orientação da Anthropic para agentes de longa duração usa a analogia de engenheiros trabalhando em turnos. Cada engenheiro chega à obra sem nenhuma memória do que aconteceu no turno anterior. Lê as notas de passagem de turno, confere o git log e só então começa a trabalhar. A recomendação da Anthropic: deixe um arquivo de progresso, leia o histórico recente de commits, rode uma verificação ponta a ponta antes de mexer em qualquer coisa.

Seu agente de código é esse engenheiro, em toda sessão. Sem passagem de turno, ele supõe. Algumas dessas suposições estão erradas. Elas se acumulam em drift: o agente refatorando o que mandaram deixar quieto, escolhendo uma biblioteca que você já substituiu, quebrando convenções que nunca viu.

O AGENTS.md é a passagem de turno. Não um briefing completo. Uma lista enxuta do que a próxima sessão precisa mesmo saber antes de mexer no seu código.

O que é o AGENTS.md

O AGENTS.md é um padrão aberto emergente: um arquivo de texto simples, normalmente em Markdown, que o harness do agente lê no início da sessão e injeta no contexto do modelo antes de ele ver sua primeira mensagem. São instruções como memória. Não é documentação para humanos. Não é um README. Não é uma spec. São ordens permanentes que persistem entre sessões porque o arquivo persiste, mesmo quando o estado do modelo não.

Vários agentes já o tratam como primitiva nativa. O pi, agente de código open source da earendil-works (Mario Zechner), lê o AGENTS.md automaticamente do diretório atual e de cada diretório pai subindo a árvore, além de um ~/.pi/agent/AGENTS.md global para ordens permanentes entre projetos. A cascata é proposital: regras do projeto sobrepõem os padrões globais, e regras de diretório sobrepõem as do projeto. Você pode ter um arquivo que molda todos os projetos e um mais específico que molda este.

A LangChain trata o sistema de arquivos como a primitiva mais fundamental do harness e define um agente como modelo mais harness. Um AGENTS.md na raiz do repo é a expressão mais simples possível dessa primitiva: um arquivo durável que sobrevive a resets de contexto e diz ao modelo como se comportar neste projeto específico. O artigo sobre harness engineering aprofunda a arquitetura completa; este aqui foca na camada de memória dentro dela.

O que entra nele

A versão enxuta do AGENTS.md tem três coisas.

O que é o projeto. Um parágrafo. Não o pitch deck. O que o sistema faz, com o que é construído e como é uma tarefa típica. O modelo deve conseguir se orientar antes de ver sua primeira instrução.

Convenções não óbvias. O que um engenheiro competente erraria no primeiro dia. O módulo que nunca pode ser tocado sem uma migration. A regra de lint que parece redundante, mas pega uma classe real de bug. A sequência de deploy que tem uma dependência de ordem nada óbvia. Se um engenheiro sênior que conhece a sua stack ainda erraria, entra aqui. Se ele acertaria no chute, não entra.

Ponteiros para contexto mais profundo. Caminhos para os arquivos de spec, o diagrama de arquitetura, os ADRs, a referência de variáveis de ambiente. O agente busca quando precisar. Não cole isso no arquivo.

O que entra

• ✓Obrigatório:
  Resumo do projeto em um parágrafoO que ele faz, a stack e como é uma tarefa típica.
• ✓Obrigatório:
  Convenções não óbviasO que um engenheiro novo erraria no primeiro dia.
• ✓Obrigatório:
  Links ou caminhos para docs mais profundosSpecs, ADRs, referências de ambiente. Não cole no arquivo.
• ✗Anti-pattern:
  A stack completa listada exaustivamenteO modelo já conhece React. Diga só o que é incomum.
• ✗Anti-pattern:
  Princípios gerais de programaçãoSe vale para todo projeto em qualquer lugar, vai no arquivo global ou em lugar nenhum.
• ✗Anti-pattern:
  A arquitetura inteira do sistema explicada em prosaIsso é uma spec ou um ADR. Coloque o link.

O que não entra

Um AGENTS.md inchado é pior que nenhum. Cada linha que você adiciona queima context window em todo turno. Se o arquivo chega a 500 linhas, o agente gasta milhares de tokens em ordens permanentes antes de ver sua primeira mensagem. O custo em tokens se acumula rápido nesse ritmo: um AGENTS.md longo não é memória grátis, é memória que você paga em cada requisição.

Pior: um arquivo longo é um arquivo que ninguém atualiza. Seis meses depois, metade está desatualizada e o agente está operando sobre uma ficção. O projeto migrou para um ORM novo há dois meses. O arquivo ainda diz Prisma.

Os padrões que matam um AGENTS.md:

Instruções genéricas que o modelo já segue. “Escreva código limpo.” “Trate erros com elegância.” “Use nomes de variáveis descritivos.” Custam tokens e não mudam nada.

Princípios gerais que valem para todo projeto. Esses vão numa config global ou num arquivo do time, não no arquivo deste projeto.

A spec inteira da feature que você está construindo agora. Ela é um artefato separado por um motivo. Uma spec mora num arquivo de spec, versionado junto com a feature, carregado quando você trabalha nela e arquivado quando ela vai para produção. Não cole nas ordens permanentes.

Um paredão de contexto que o agente consegue consultar sozinho. Ele tem um sistema de arquivos. Use.

O teste de poda

A Anthropic publicou esse teste diretamente na orientação sobre agentes. O teste é uma pergunta por linha: se remover esta linha não faria o agente errar, corte.

Rode esse teste no seu AGENTS.md todo mês. Pegue cada linha. Pergunte se o agente faria algo errado sem ela. Se a resposta é não, a linha é ruído. Corte.

Isso não é edição de estilo. É edição de função. O objetivo é o menor arquivo que evite os erros reais que o seu projeto gera, e nada além disso.

Um AGENTS.md real, curto o bastante para ser útil

Este é bem parecido com o que eu usei durante o build de 70 dias: uma fintech cripto com 13 apps, construída sozinho com agentes de IA. Toda sessão começava lendo este arquivo.

# Project context

Crypto fintech monorepo. 13 apps, 3 APIs (Rust), 3 PostgreSQL databases,
Kubernetes in production. Each app is a standalone Next.js workspace.
Work targets one app at a time unless a task explicitly spans multiple.

# Non-obvious conventions

- Never modify `packages/db` shared schema directly. All schema changes
  go through a migration in the target app's `migrations/` directory.
- The `core-api` service owns auth. Do not implement auth logic in app-level
  code.
- Linting: `pnpm lint` must pass before any commit. The rule set is strict;
  do not disable rules inline without a comment explaining why.
- Environment variables: see `.env.example` in each app root. No secrets
  in code or in this file.

# Where to find context

- Architecture: `docs/architecture.md`
- Feature specs: `docs/specs/<feature>.md`
- ADRs: `docs/adr/`
- API contracts: `packages/openapi/`

É isso. Menos de 200 palavras. O agente navega até esses caminhos quando precisa de profundidade. O arquivo em si continua enxuto.

AGENTS.md não é spec

As duas coisas se confundem. Não são a mesma ferramenta.

O AGENTS.md é memória sempre ligada. Carrega em toda sessão, custa contexto em todo turno e deve conter só as ordens permanentes que valem para qualquer tarefa que você for rodar neste repo. Ele responde: como este projeto funciona, sempre.

Uma spec é um artefato por feature. Descreve uma mudança em detalhe: requisitos, restrições, critérios de aceite, edge cases. Carrega quando você está trabalhando naquela feature e é arquivada quando a feature vai para produção. O artigo sobre Spec-Driven Development mostra como escrever uma direito.

O modelo mental certo: o AGENTS.md é o manual do funcionário. A spec é o briefing do projeto. O manual vale para todo mundo, todo dia. O briefing vale para um trabalho. Não coloque o briefing no manual.

AGENTS.md

1. 01Carrega em toda sessão, em todo turno
2. 02Contém ordens permanentes para o repo inteiro
3. 03Curto, podado, sempre atual
4. 04Mora na raiz do repo (e nos pais, e no global)
5. 05Cobre convenções, não detalhes de feature

Arquivo de spec

1. 01Carregado para uma feature, depois arquivado
2. 02Contém os requisitos de uma mudança
3. 03Tão longo quanto a feature precisar
4. 04Mora em docs/specs/ junto com a feature
5. 05Cobre intenção, restrições, critérios de aceite

Como evitar que ele apodreça

O arquivo apodrece no momento em que você para de tratá-lo como código.

Versione. O AGENTS.md mora no repo. Toda mudança é um commit. Se uma convenção muda, o arquivo muda no mesmo PR. Se você trocou o ORM, o arquivo é atualizado na mesma mudança que faz a troca.

Aplique o teste de poda com cadência. Uma vez por mês basta para projetos ativos. O objetivo é pegar linhas que deixaram de ser verdade ou deixaram de evitar erros reais.

Mantenha o arquivo global separado. O seu ~/.pi/agent/AGENTS.md global (ou o equivalente no seu harness) guarda o que vale para todo projeto: seu nome, seu test runner preferido, o estilo de código que você sempre usa. O arquivo do projeto guarda só o que é específico deste repo. Misturar os dois causa drift nas duas direções: o arquivo do projeto se enche de ruído genérico e o global se enche de detalhes de projeto.

Escreva o arquivo para a próxima sessão, não para a atual. Quando terminar uma tarefa e as convenções tiverem mudado, atualize o AGENTS.md antes de fechar a sessão. O arquivo deve refletir o estado do projeto agora, não de seis meses atrás, quando você o criou.

A versão honesta

O modelo não vai lembrar das suas convenções. Não vai lembrar que você pediu para ele deixar um módulo quieto. Não vai lembrar do padrão de migration que você explicou semana passada.

Isso não é defeito. É a arquitetura. Projete para ela.

O AGENTS.md dá ao harness um arquivo para ler. O harness injeta. O modelo começa a sessão sabendo o que de outro jeito teria que redescobrir ou erraria. Não é mágica. É anotar as coisas no único lugar que o sistema de fato lê.

Mantenha o arquivo curto. Mantenha verdadeiro. Rode o teste de poda. O agente rodando com um AGENTS.md de 150 palavras que alguém mantém ganha do agente rodando com um AGENTS.md de 700 palavras que ninguém lê.

Perguntas frequentes

Todo projeto precisa de um AGENTS.md?+

Não. Um experimento de vida curta ou um script de um arquivo só não precisa. O AGENTS.md se paga quando o projeto tem convenções que o modelo erraria, quando várias sessões acontecem na mesma base de código ou quando mais de uma pessoa roda sessões de agente no mesmo repo.

Se você consegue descrever todas as convenções num system prompt de uma frase, coloque no system prompt. O AGENTS.md é para os projetos em que essa descrição passa de um parágrafo.

Qual a diferença entre AGENTS.md e system prompt?+

Um system prompt é efêmero: você define para uma sessão e ele some. O AGENTS.md é um arquivo no repo, versionado com o código, que o harness pode ler a qualquer momento. O system prompt é algo que você configura por sessão. O AGENTS.md é algo que o harness lê automaticamente, então toda sessão recebe as mesmas ordens permanentes sem você precisar lembrar de colar.

Qual deve ser o tamanho de um AGENTS.md?+

Curto o bastante para ler em sessenta segundos. Na maioria dos projetos, isso dá de 100 a 250 palavras. O exemplo acima cobre um monorepo de 13 apps em menos de 200 palavras.

Se o seu arquivo passa de 400 palavras, aplique o teste de poda antes de adicionar qualquer outra coisa. Cada linha além disso é um custo que você paga em todo turno. A maioria não vale a pena.

O AGENTS.md deve ir para o repo ou ficar fora do controle de versão?+

Faça commit. O AGENTS.md descreve como trabalhar nesta base de código, e essa descrição deve mudar quando a base de código muda. O Git te dá histórico, blame e review. Deixar fora do controle de versão faz as convenções derivarem em silêncio. A única exceção é se o seu AGENTS.md tiver algo sensível: secrets nunca podem ir para um arquivo commitado, e nem deveriam estar no AGENTS.md.

O pi lê o AGENTS.md dos diretórios pais. Devo colocar um na raiz do repo e outro mais fundo?+

Sim, quando o repo tem subcontextos relevantes. Um monorepo pode ter um AGENTS.md na raiz com convenções do repo inteiro e um AGENTS.md por pacote com regras específicas. O pi junta os dois carregando do diretório atual para cima, então o arquivo mais específico é lido por último e pode sobrepor o mais amplo. Não duplique conteúdo entre níveis: se uma regra vale para tudo, ela vai só no arquivo da raiz.

Qual a diferença entre AGENTS.md e um CLAUDE.md ou um arquivo de regras do Cursor?+

O conceito é o mesmo: um arquivo que o harness lê antes de o modelo ver sua mensagem. O nome do arquivo muda conforme o harness. O Claude Code lê CLAUDE.md. O Cursor tem seu próprio formato de regras. O pi lê AGENTS.md. AGENTS.md é o nome com mais tração para virar um padrão aberto entre harnesses, e por isso vale conhecer, seja qual for a ferramenta que você usa hoje.

Se você trocar de harness, o conteúdo do arquivo vai junto direto. O nome do arquivo é só convenção.