claude.md e agents.md: o que são e como escrever os teus — Ratos de IA
arquivos de instrução

claude.md e agents.md: o que são e como escrever os teus

claude.md e agents.md são os arquivos de instrução que o agente lê antes de começar. a diferença entre os dois, como a gente organiza aqui e um modelo pra copiar.

por · 17 nov 2026

claude.md e agents.md: o que são e como escrever os teus

aqui na DobraLabs (laboratório de design, tecnologia e IA que atende empresas) e no Ratos de IA (nosso canal, newsletter e cursos de IA na prática), a empresa inteira mora num repositório só (uma pasta versionada com o histórico de cada mudança): sites, clientes, cursos, propostas. e quem trabalha nele todo dia são agentes de IA como o Claude Code e o Codex. por isso o arquivo que diz pro agente como a casa funciona é dos mais importantes que a gente tem, e já deu problema.

em julho de 2026 a gente abriu o AGENTS.md da raiz desse repositório e descobriu que ele estava 20 dias atrasado em relação ao CLAUDE.md. pior: alguém tinha trocado “Claude” por “Codex” no texto, e o arquivo apontava pra pastas que não existiam. é o que acontece quando tu mantém duas cópias do mesmo manual. o CLAUDE.md e o AGENTS.md são esse manual: o arquivo de instruções que o agente lê antes de começar a trabalhar numa pasta. nesse post eu explico o que cada um é, a diferença entre eles, como a gente organiza os nossos e deixo um modelo pra copiar.

o que é o claude.md

o CLAUDE.md é um arquivo de texto que o Claude Code lê no começo de toda sessão. ali vai o que tu explicaria de novo em toda conversa: como o projeto é organizado, os comandos que importam, as regras da casa, o que nunca fazer. a documentação oficial resume bem: trata o CLAUDE.md como o lugar onde tu anota o que teria que reexplicar.

ele pode morar em quatro lugares, do mais amplo pro mais específico:

ondecaminhovale pra
organizaçãono Linux, /etc/claude-code/CLAUDE.mdtodo mundo daquela máquina
tu~/.claude/CLAUDE.mdtodos os teus projetos
projeto./CLAUDE.md ou ./.claude/CLAUDE.mdo time, pelo repositório
local./CLAUDE.local.md (fora do git)só tu, naquele projeto

o Claude Code lê o CLAUDE.md da pasta onde tu abriu e de todas as pastas acima, e junta tudo, sem um apagar o outro. o que está mais perto de onde tu abriu entra por último. os CLAUDE.md das subpastas entram sob demanda, quando o Claude mexe num arquivo daquela subpasta. é assim que dá pra ter um manual geral na raiz e um manual específico em cada projeto.

o que é o agents.md

o AGENTS.md é o mesmo tipo de arquivo, só que num padrão aberto que não é de ninguém. o site oficial chama ele de “um README pros agentes”: o lugar dos passos de build, dos testes e das convenções que iam poluir o README feito pra gente ler. segundo o site, mais de 60 mil projetos open source usam, e a lista de ferramentas que leem inclui Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, Zed, Warp, Jules e Devin, entre outras.

desde dezembro de 2025 o AGENTS.md é cuidado pela Agentic AI Foundation, da Linux Foundation, a mesma que recebeu o MCP da Anthropic (anúncio da Linux Foundation).

no Codex, a regra de leitura é parecida com a do Claude: ele começa na raiz do projeto e desce até a pasta onde tu abriu, pegando um arquivo por pasta, e o que está mais perto vale mais. tem um detalhe que pega muita gente: pela documentação do Codex, ele para de juntar arquivos quando a soma passa de 32 KiB, a não ser que tu aumente o limite na configuração.

qual a diferença entre claude.md e agents.md

na função, nenhuma. a diferença é quem procura cada nome. durante muito tempo o Claude Code era o único agente do mercado que lia só o CLAUDE.md, e isso virou treta pública. no episódio #31 do Ratos de IA (o vídeo semanal do canal com as novidades de IA), a gente comentou o Tobi Lütke, fundador da Shopify, ameaçando banir o Claude Code da empresa por causa disso. no episódio #34 veio a resposta: o time do Claude Code adicionou o suporte (os dois estão no canal).

hoje funciona assim, pela documentação: desde a versão 2.1.277, se não existe um CLAUDE.md (nem .claude/CLAUDE.md, nem CLAUDE.local.md) na pasta onde tu abriu ou acima dela, o Claude Code lê o AGENTS.md. se existe um CLAUDE.md, ele lê só o CLAUDE.md, a não ser que tu mude a opção Project instructions no /config pra ler os dois.

cenário na pastao que o Claude Code lê
só AGENTS.mdo AGENTS.md
AGENTS.md e CLAUDE.mdsó o CLAUDE.md (padrão)
CLAUDE.md com a linha @AGENTS.mdo CLAUDE.md, com o AGENTS.md dentro

atenção na pegadinha da segunda linha: criar um CLAUDE.local.md pra anotar coisa tua num projeto que vive de AGENTS.md faz o Claude parar de ler o AGENTS.md.

como a gente organiza aqui

o nosso repositório serve Claude Code, Codex e mais um agente ao mesmo tempo, e a regra é uma só: uma fonte de verdade, o outro nome vira ponteiro.

por que import e não um atalho de sistema (symlink)? porque o import funciona no Windows sem permissão de administrador, o que importa pros alunos, e porque deixa colocar embaixo da linha um bloco que só o Claude lê, invisível pro Codex. a própria doc do Claude Code mostra esse formato:

@AGENTS.md

## Claude Code

instruções que só o Claude precisa ver

e a doc diz que, mesmo com a leitura nativa do AGENTS.md, dá pra manter esse CLAUDE.md: o import nunca faz o Claude ler o arquivo duas vezes. a gente mantém, porque nem toda sessão roda a versão mais nova.

o kit do Ratos OS (a estrutura de pastas, instruções e skills que monta um sistema de trabalho com agente pro teu negócio), que a gente entrega no curso, já vem nesse formato. e o passo a passo completo, incluindo a pasta de skills servindo os dois agentes, está no guia de vários agentes num repositório só.

como escrever um bom claude.md (ou agents.md)

a doc do Claude Code dá umas regras que a gente aprendeu na marra:

e quando acrescentar? a doc lista quatro sinais: o Claude errou a mesma coisa duas vezes, uma revisão pegou algo que ele devia saber, tu digitou a mesma correção da sessão passada, ou uma pessoa nova no time precisaria daquela informação.

confissão honesta: o nosso AGENTS.md da raiz tem quase 500 linhas e uns 75 KB. passa da recomendação de 200 linhas do Claude e do limite padrão de 32 KiB do Codex. ele cresceu porque cada projeto novo ganhou um parágrafo no mapa. a direção certa é o mapa só apontar pro AGENTS.md de cada área e deixar o detalhe lá, e é a dívida que a gente carrega. a DobraLabs escreveu sobre esse movimento de enxugar as instruções sem zerar.

modelo de agents.md pra copiar

esse é um ponto de partida pra um negócio pequeno que usa o agente no dia a dia, sem ser projeto de programação. troca o que está entre colchetes:

# [nome da empresa]

## quem somos
[o que a empresa faz, em 2 linhas] · time: [nome e papel de cada um]

## onde fica cada coisa
- clientes/[nome-do-cliente]/  ← uma pasta por cliente, com histórico e materiais
- propostas/                   ← propostas enviadas, uma pasta por proposta
- marca/                       ← logo, cores e o tom de voz (ler antes de escrever qualquer texto)
- financeiro/                  ← só leitura, nunca alterar sem pedir

## regras
1. português do Brasil, com acento
2. antes de mexer numa área, ler o AGENTS.md daquela pasta, se tiver
3. nunca mostrar nem salvar senha ou chave em arquivo
4. antes de apagar, enviar e-mail ou publicar algo, mostrar o que vai fazer e esperar o ok
5. se uma informação daqui estiver errada, avisar e propor a correção

## ferramentas
- [CRM, planilha, e-mail]: [como o agente acessa cada uma]

e o CLAUDE.md, do lado dele, com uma linha:

@AGENTS.md

pronto. abre o Claude Code ou o Codex na pasta e pergunta “o que tu sabe sobre essa empresa?”. se ele responder com o que está no arquivo, funcionou. daqui pra frente, toda vez que tu repetir uma explicação, ela vai pro arquivo.

perguntas frequentes

ainda em dúvida?

o que é o CLAUDE.md?

é um arquivo de texto com as instruções do teu projeto que o Claude Code lê no começo de toda sessão: regras, comandos, onde fica cada coisa, o que nunca fazer. tu escreve uma vez e para de repetir a mesma explicação em toda conversa.

qual a diferença entre CLAUDE.md e AGENTS.md?

a função é a mesma. o CLAUDE.md é o nome que o Claude Code procura; o AGENTS.md é o padrão aberto que Codex, Cursor, Gemini CLI, GitHub Copilot e outros leem, hoje cuidado pela Agentic AI Foundation, da Linux Foundation. o Claude Code também lê o AGENTS.md quando não acha um CLAUDE.md.

preciso ter os dois arquivos?

se tu só usa o Claude Code numa versão recente, um AGENTS.md basta. se o time usa mais de um agente, ou se alguém roda versão antiga, deixa o conteúdo no AGENTS.md e um CLAUDE.md com a linha @AGENTS.md. nunca duas cópias com o mesmo texto.

qual o tamanho ideal do CLAUDE.md?

a documentação do Claude Code recomenda menos de 200 linhas por arquivo, porque arquivo longo gasta contexto e o modelo segue pior. o Codex, por padrão, para de ler os arquivos de instrução quando a soma passa de 32 KiB.

como gerar um CLAUDE.md automaticamente?

roda /init dentro do Claude Code. ele analisa a pasta e escreve um ponto de partida com comandos e convenções que encontrou. se já existe um CLAUDE.md, ele sugere melhorias em vez de sobrescrever. depois tu completa com o que ele não tem como descobrir sozinho.

black friday da ratos · lote 2
tudo que a gente ensina, a Ratoeira e a comunidade, numa assinatura só.

os cursos inteiros, as skills que a gente usa no dia a dia, a Ratoeira pra rodar teus agentes numa máquina tua e a comunidade pra trocar com quem tá fazendo o mesmo. no lote 2 da Black sai por 12x de R$ 113,46 ou R$ 1.097 à vista, e o preço sobe a cada lote.

ver a oferta da Black → 7 dias de garantia
últimos posts
Tutoriais criativo de anúncio com IA: os 3 formatos da meta, na tua marca, sem texto torto Tutoriais google ads pelo claude code: termos de busca, negativas e quality score numa conversa Tutoriais rotinas: o agente de ia trabalhando sozinho num horário
guias da ratos
ver todos os guias →
🔷 a Ratos é feita pela DobraLabs
laboratório de IA que testa inteligência artificial de verdade no próprio dia a dia pra ensinar e construir pra empresas: workshops in-company, automações e sistemas sob medida.
conhecer a dobralabs →