CLAUDE.md explicado:o arquivo que evita os erros da IA

CLAUDE.md explicado: é um arquivo de texto simples na raiz do seu projeto que a sua ferramenta de programação com IA lê antes de cada resposta — e ele evita cerca de 90% dos erros que a IA comete na sua base de código. Não é código. É o regulamento: os padrões do seu projeto, as suas regras inegociáveis, os erros que a IA nunca pode repetir.

A maioria das pessoas que constroem com IA não faz ideia de que ele existe. Aqui está o que ele é, por que muda tudo e exatamente o que colocar no seu.

CLAUDE.md explicado: a analogia do manual do funcionário

Imagine contratar um prestador de serviços brilhante que tem amnésia total entre uma reunião e outra. Toda manhã ele chega sem saber nada de como a sua empresa funciona — os seus padrões, o seu sistema de arquivos, as suas decisões passadas. Toda manhã você reexplica tudo, e toda manhã ele comete os mesmos erros até você explicar.

Agora imagine entregar a ele um manual do funcionário que ele relê no começo de cada reunião. De repente ele aparece já sabendo as suas regras.

Isso é o CLAUDE.md. As ferramentas de programação com IA começam cada conversa do zero — não se lembram das correções de ontem. O CLAUDE.md é o manual que elas leem automaticamente antes de responder a qualquer coisa. Pense nele como a constituição da sua base de código: as regras que a IA precisa seguir, os padrões que ela precisa usar, os erros que ela nunca pode cometer.

Por que a IA continua cometendo os mesmos erros sem ele

Eis o que aconteceu comigo. Eu estava construindo um sistema de avaliação de candidaturas para a minha plataforma — lógica de pontuação complexa, fluxos de várias etapas, dezenas de tabelas no banco de dados. Eu disse ao Claude: "Construa o serviço de avaliação de candidaturas."

O Claude gerou o código. Funcionou. E estava errado de cinco formas:

• Ignorou a estrutura que todas as outras partes da minha base de código seguem
• Inventou definições de dados que não batiam com o meu banco de dados real
• Adicionou um tratamento de erros que conflitava com o sistema que eu já tinha
• Usou saídas de depuração improvisadas em vez da minha estrutura de logs
• Esqueceu o multi-tenancy — o rótulo do cliente que precisa estar em toda consulta

Corrigi tudo na mão. E o próximo arquivo que pedi? Os mesmos erros. De novo. Eu estava brigando com o Claude em cada arquivo — não porque o Claude é ruim, mas porque ele tinha amnésia sobre as regras do meu projeto. Sem o CLAUDE.md, você está retreinando a sua IA do zero em cada conversa.

O livroA Revolução do EUpreendedorLuis Gonçalves sobre como construir um negócio de EUpreendedor com IA sem largar o emprego.Quero o livro →

O que vai num arquivo CLAUDE.md

Um bom CLAUDE.md tem sete seções. Nenhuma delas exige que você escreva código — elas exigem que você declare decisões, que é exatamente o trabalho do arquiteto:

As seções mais poderosas são as duas últimas. A IA é uma máquina de reconhecer padrões: mostre a ela um exemplo real de código bem feito, e ela o imita em todo lugar. Mostre o erro exato que ela cometeu na semana passada, com o rótulo "nunca faça isso", e o erro desaparece.

O que mudou depois que escrevi o meu

O mesmo pedido — "Construa o serviço de avaliação de candidaturas" — depois de adicionar o CLAUDE.md. O Claude leu as regras primeiro e depois gerou um código que seguia a minha estrutura, batia exatamente com o meu banco de dados, rotulava cada consulta para o multi-tenancy, tratava os erros do meu jeito e colocava cada arquivo no lugar certo. De primeira. Zero correções.

O momento em que eu soube que era mágica: eu precisava de uma funcionalidade de pareamento de mentores — lógica complexa, várias tabelas. Antes do CLAUDE.md, isso significaria horas corrigindo o que a IA gerasse. Depois, eu disse "construa o pareamento de mentores usando os mesmos padrões da avaliação de candidaturas". O Claude leu o regulamento, estudou a funcionalidade anterior e construiu tudo seguindo cada padrão. Levou 15 minutos e funcionou perfeitamente.

Sem o arquivo, conte com uns 30 minutos de correções em cada arquivo gerado — os padrões errados, as proteções faltando, os arquivos no lugar errado. Multiplique isso por centenas de arquivos e o CLAUDE.md é a diferença entre entregar e se afogar.

Como começar o seu hoje

Não escreva uma obra-prima. Comece com cinco regras — os cinco erros que a sua IA continua cometendo no seu projeto — mais uma linha descrevendo o que você está construindo e a sua stack técnica. Só isso.

Depois trate-o como um documento vivo. Toda vez que a IA cometer um erro novo, adicione uma regra. Toda vez que ela gerar algo ótimo, copie esse código para a seção de exemplos. O ponto ideal é de 200–400 linhas: menos de 100 linhas dá contexto de menos; mais de 500, e a IA se afoga nele.

Um limite que vale conhecer: o CLAUDE.md guarda as suas regras globais, sempre válidas. Para funcionalidades grandes e pontuais, você também vai querer um briefing específico da tarefa, com os requisitos exatos e o contexto daquela funcionalidade — essa é outra ferramenta, o método PRP, e as duas trabalham juntas: a constituição para todo dia, a planta para cada construção.

12 semanasA sua carreira corporativa nunca foi o planoCandidate-se à Aceleradora de EUpreendedores.Candidatar-se →

Perguntas frequentes

O que é um arquivo CLAUDE.md?

Um arquivo markdown (texto simples) na raiz do seu projeto que o Claude Code lê antes de cada resposta. Ele contém as regras, os padrões, a stack técnica, exemplos reais de código e os antipadrões do seu projeto — para que a IA siga os seus padrões desde a primeira tentativa em vez de ser retreinada a cada conversa.

Preciso saber programar para escrever um?

Não. O arquivo é escrito em linguagem comum: o que é o produto, as regras que precisam sempre valer, o que nunca pode acontecer. Para a seção de exemplos, você cola o código que a própria IA gerou quando acertou algo. Declarar decisões é o trabalho do fundador; implementá-las é o da IA.

Qual deve ser o tamanho de um arquivo CLAUDE.md?

Comece hoje com cinco regras. Faça-o crescer até 200–400 linhas — longo o bastante para carregar os seus padrões, curto o bastante para que a IA realmente use tudo. Menos de 100 linhas é pouco; passou de 500, enxugue. Revise-o toda semana: adicione padrões novos, apague regras desatualizadas.

O CLAUDE.md sozinho basta para construir funcionalidades?

Ele cobre as regras globais — os erros que, sem ele, se repetiriam em cada arquivo. Para uma funcionalidade complexa, você também quer uma especificação da tarefa, com os requisitos exatos, os dados e as etapas de validação daquela funcionalidade. Esse é o método PRP; CLAUDE.md mais um PRP é como as funcionalidades saem certas de primeira.