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:
| onde | caminho | vale pra |
|---|---|---|
| organização | no Linux, /etc/claude-code/CLAUDE.md | todo mundo daquela máquina |
| tu | ~/.claude/CLAUDE.md | todos os teus projetos |
| projeto | ./CLAUDE.md ou ./.claude/CLAUDE.md | o 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 pasta | o que o Claude Code lê |
|---|---|
| só AGENTS.md | o AGENTS.md |
| AGENTS.md e CLAUDE.md | só o CLAUDE.md (padrão) |
CLAUDE.md com a linha @AGENTS.md | o 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.
- o AGENTS.md é o arquivo real. todo o conteúdo mora nele
- o CLAUDE.md tem uma linha só:
@AGENTS.md. o@é o import do Claude Code, que puxa outro arquivo pra dentro do contexto - cada projeto grande tem o seu. o da raiz é o mapa da empresa (quem somos, onde fica cada coisa, regras globais), e cada área importante (o site, a plataforma de cursos, a Ratoeira, que é o portal que a gente fez pra rodar agentes num servidor pelo navegador, o canal) tem o próprio AGENTS.md com os detalhes. hoje são mais de 60 AGENTS.md espalhados pelo repositório
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:
- instrução que dá pra conferir. “roda
npm testantes de commitar” funciona. “testa tuas mudanças” não diz nada - curto. a recomendação é menos de 200 linhas por arquivo. arquivo longo gasta contexto e o modelo segue pior. e import não alivia: o arquivo importado entra inteiro junto
- sem contradição. se duas regras brigam, o Claude pode escolher qualquer uma. tem até um
/doctor prompt-auditque procura instrução velha ou conflitante - procedimento vai pra skill. se é um passo a passo de várias etapas, ou só importa numa parte do projeto, vira skill ou regra em
.claude/rules/ - começa pelo
/init. ele lê a pasta e escreve o ponto de partida. depois tu completa com o que ele não descobre sozinho
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.