← todos os posts
Manutenção 6 min de leitura

"Regras do projeto num arquivo: o CLAUDE.md explicado pra quem nunca abriu um"

"É só um arquivo de texto. Como criar o seu em 15 minutos com o que o app usa, o que não mexer e como testar, e como conferir que a IA obedece."

"Parece que fica algo remendado, como se fosse uma pintura com 3 estilos diferentes."

Quem escreveu isso num fórum brasileiro falava do próprio app. Quando alguém com esse problema pede ajuda, a resposta que costuma vir de quem programa é curta: "põe no CLAUDE.md". Fim da conversa.

É o mesmo tipo de conselho que "é só ligar o RLS": certo e inútil, porque pula o que importa. Ninguém diz o que é o arquivo, onde fica, o que vai dentro e como saber se funcionou. Se você nunca abriu um, não deixou passar nada. Ninguém explicou pra quem não é dev. Então, do zero.

O que é, fisicamente

Um arquivo de texto comum. Abre no Bloco de Notas. O .md no fim quer dizer markdown, um jeito de escrever texto em que # vira título e - vira item de lista. Só isso.

A IA lê esse arquivo no começo de toda conversa. Como cada conversa começa do zero, ele é a única coisa que chega em todas.

O nome muda conforme a ferramenta:

  • Claude Code (a ferramenta de programar da Anthropic): CLAUDE.md, na pasta principal do projeto.
  • Cursor, Codex, Copilot e outras: AGENTS.md. É um formato aberto, hoje mantido por uma fundação ligada à Linux Foundation, e o site oficial lista mais de quinze ferramentas que leem. O Claude Code também lê, quando não existe CLAUDE.md na pasta.
  • Lovable: o campo Knowledge (Conhecimento), em Project settings, com até 10.000 caracteres (mostrei onde fica aqui). Se o seu projeto tá ligado ao GitHub, a documentação diz que ele também lê um AGENTS.md ou CLAUDE.md que estiver lá.

Minha recomendação: um arquivo só. Se você usa duas ferramentas, escolha um nome e não mantenha dois com regras diferentes. A documentação do Claude Code avisa que, quando duas instruções se contradizem, a IA "pode escolher uma arbitrariamente".

Passo 1: deixe a IA escrever o rascunho de "do que é feito"

Quem não programa trava aqui: "não sei qual é a minha stack". Stack é a lista de peças do app: linguagem, banco que guarda os dados, onde roda o login, onde tá publicado. Você não precisa saber de cabeça. A IA lê o código.

  • No Claude Code: digite /init. Pela documentação, ele analisa o projeto e cria um CLAUDE.md inicial com os comandos de rodar e de testar que encontrar. Se o arquivo já existe, ele sugere melhorias em vez de apagar.
  • Em qualquer outra: peça, no modo que não altera código (no Lovable, o Plan mode):

"Sem alterar nada, me diga em português simples: do que este app é feito (linguagem, banco de dados, login, onde está publicado) e como eu rodo os testes, se existirem. Uma linha por item."

Vai sair comprido. Seu trabalho é cortar.

Passo 2: os três blocos

Abra o rascunho e deixe só isto, com as suas palavras:

# Do que este app é feito
- App de agendamento pra salão. Quem usa: a recepcionista e as clientes.
- Banco: Supabase. Login: Supabase Auth. Publicado na Vercel.

# O que não mexer sem eu pedir com essas palavras
- Login e cadastro.
- Tabela de pagamentos e o cálculo do total.
- Qualquer coisa que apague dado.

# Como testar antes de dizer que terminou
- Rodar o comando de teste e colar a saída na resposta.
- Se não existir teste pra aquilo, me dizer quais 3 cliques eu faço pra conferir.

O exemplo é inventado, pra mostrar o formato. Três critérios pra cada linha:

  • Ela erraria sem isso? Se não, corta. A documentação pede menos de 200 linhas e diz que arquivo longo "reduz a obediência".
  • Dá pra conferir? A própria documentação compara: "rode npm test antes de salvar" funciona, "teste suas mudanças" não.

O próximo degrau é o "nunca" no topo e o vocabulário do negócio.

Passo 3: confira que ela leu

Escrever não garante nada: a documentação do Claude Code diz que o arquivo é tratado "como contexto, não como configuração obrigatória". Teste em dois tempos:

1. Ela tá vendo? No Claude Code, digite /context e procure o arquivo na lista Memory files. Se não aparece, ela não lê. Em qualquer ferramenta, abra uma conversa nova e mande:

"Sem mexer em nada: liste as regras do projeto que você recebeu, com as suas palavras."

Se ela não citar o "não mexer", o arquivo tá no lugar errado ou com o nome errado.

2. Ela respeita? Faça um pedido inocente que encosta numa regra, tipo "deixa o formulário de cadastro mais bonito". O certo é ela perguntar antes, porque cadastro tá no "não mexer". Se ela sair mexendo, a regra tá vaga: reescreva com o nome da tela e teste de novo.

Passo 4: o arquivo cresce com os seus erros

A regra de manutenção é uma: corrigiu a IA duas vezes na mesma coisa, vira linha no arquivo. No Claude Code dá pra pedir direto, "adicione isso ao CLAUDE.md", ou abrir o arquivo com /memory. No Lovable, você mesmo cola no Knowledge.

Uma vez por mês, apague o que não vale mais: regra velha contradizendo regra nova é o caminho de volta pros três estilos.

O que esse arquivo não faz

Ele impede o próximo remendo, não desfaz os que existem: pra isso tem o inventário e a tela-modelo. E é conselho, não trava. Pro que não pode acontecer nunca, como apagar o banco de produção, existem travas de verdade.

Era uma parede de várias

O arquivo de regras é o primeiro portão, não o último. Ele depende de você saber o que não pode quebrar, e isso pede um ponto de retorno marcado antes de qualquer mudança e, depois, um teste que confere a regra sem você clicar em tudo. Cada peça segura a seguinte, e é por isso que elas entram numa ordem.

Faça hoje: rascunho, corte, três blocos, teste na conversa nova. Quinze minutos, e amanhã a IA ainda sabe o que você disse hoje.

Fontes

  • Relato "parece uma pintura com 3 estilos diferentes", TabNews (registrado na pesquisa do blog; relato, não estatística)
  • Claude Code Docs, "How Claude remembers your project" (/init; menos de 200 linhas; instruções concretas e verificáveis; contradição faz escolher uma arbitrariamente; tratado como contexto, não configuração obrigatória; /context e /memory; leitura de AGENTS.md quando não há CLAUDE.md): https://code.claude.com/docs/en/memory
  • AGENTS.md, site oficial do formato (formato aberto, mantido pela Agentic AI Foundation, da Linux Foundation; lista de ferramentas que leem): https://agents.md/
  • Cursor Docs, "Rules" (AGENTS.md como arquivo de regras simples na raiz do projeto): https://cursor.com/docs/context/rules
  • Lovable Docs, "Define workspace and project knowledge" (Project settings → Knowledge; até 10.000 caracteres; lê AGENTS.md ou CLAUDE.md do repositório Git): https://docs.lovable.dev/features/knowledge