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

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

A maioria das pessoas que constrói com IA não faz ideia de que ele existe. Eis o que é, porque muda tudo e o que deves pôr exatamente no teu.

CLAUDE.md explicado: a analogia do manual do colaborador

Imagina que contratas um prestador de serviços brilhante que sofre de amnésia total entre reuniões. Todas as manhãs chega sem saber nada sobre como a tua empresa funciona — os teus padrões, a forma como organizas os documentos, as tuas decisões passadas. Todas as manhãs voltas a explicar tudo, e todas as manhãs ele comete os mesmos erros até o fazeres.

Agora imagina que lhe entregas um manual do colaborador que ele relê no início de cada reunião. De repente, aparece já a conhecer as tuas 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 leem automaticamente antes de responder ao que quer que seja. Pensa nele como a constituição da tua base de código: as regras que a IA tem de seguir, os padrões que tem de usar, os erros que nunca pode cometer.

Porque é que a IA continua a cometer os mesmos erros sem ele

Eis o que me aconteceu. Estava a construir um sistema de avaliação de candidaturas para a minha plataforma — lógica de pontuação complexa, fluxos em várias etapas, dezenas de tabelas na base de dados. Disse ao Claude: «Constrói o serviço de avaliação de candidaturas.»

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

• Ignorava a estrutura que todas as outras partes da minha base de código seguem
• Inventava definições de dados que não correspondiam à minha base de dados real
• Acrescentava um tratamento de erros que entrava em conflito com o sistema que eu já tinha
• Usava mensagens de depuração improvisadas em vez da minha configuração de registos
• Esquecia-se do multi-tenancy — a etiqueta do cliente que tem de estar em todas as consultas

Corrigi tudo à mão. E o ficheiro seguinte que pedi? Os mesmos erros. Outra vez. Estava a lutar com o Claude em cada ficheiro — não porque o Claude seja mau, mas porque tinha amnésia sobre as regras do meu projeto. Sem o CLAUDE.md, estás a treinar a tua IA do zero em cada conversa.

O livroThe Solopreneur RevolutionLuis Gonçalves sobre como construir um negócio de EUpreendedor com IA sem deixar o emprego.Quero o livro →

O que vai num ficheiro CLAUDE.md

Um bom CLAUDE.md tem sete secções. Nenhuma te obriga a escrever código — obrigam-te a enunciar decisões, que é exatamente o trabalho do arquiteto:

As secções mais poderosas são as duas últimas. A IA é uma máquina de reconhecer padrões: mostra-lhe um exemplo real de código bem feito e ela imita-o em todo o lado. Mostra-lhe o erro exato que cometeu na semana passada, com a etiqueta «nunca faças isto», e o erro desaparece.

O que mudou depois de escrever o meu

O mesmo pedido — «Constrói o serviço de avaliação de candidaturas» — depois de acrescentar o CLAUDE.md. O Claude leu primeiro as regras e depois gerou código que seguia a minha estrutura, correspondia exatamente à minha base de dados, etiquetava cada consulta para o multi-tenancy, tratava os erros à minha maneira e punha cada ficheiro no sítio certo. À primeira. Zero correções.

O momento em que percebi que era magia: precisava de uma funcionalidade de correspondência entre mentores — lógica complexa, várias tabelas. Antes do CLAUDE.md, isso significava horas a corrigir o que a IA produzia. Depois, disse «constrói a correspondência de mentores usando os mesmos padrões da avaliação de candidaturas». O Claude leu o livro de regras, estudou a funcionalidade anterior e construiu tudo seguindo cada padrão. Levou 15 minutos e funcionou na perfeição.

Sem o ficheiro, conta com cerca de 30 minutos de correções por cada ficheiro gerado — os padrões errados, as salvaguardas em falta, os ficheiros no sítio errado. Multiplica isso por centenas de ficheiros e o CLAUDE.md é a diferença entre lançar e afogar-te.

Como começar o teu hoje

Não escrevas uma obra-prima. Começa com cinco regras — os cinco erros que a tua IA continua a cometer no teu projeto — mais uma linha a descrever o que estás a construir e a tua stack tecnológica. Mais nada.

Depois trata-o como um documento vivo. Sempre que a IA cometer um erro novo, acrescenta uma regra. Sempre que gerar algo ótimo, copia esse código para a secção de exemplos. O ponto ideal são 200–400 linhas: abaixo de 100 linhas dá pouco contexto; acima de 500, a IA afoga-se nele.

Um limite que vale a pena conhecer: o CLAUDE.md guarda as tuas regras globais, sempre verdadeiras. Para funcionalidades grandes e pontuais vais querer também um briefing específico da tarefa, com os requisitos exatos e o contexto dessa funcionalidade — é uma ferramenta diferente, o método PRP, e as duas trabalham em conjunto: a constituição para todos os dias, a planta para cada construção.

12 semanasA tua carreira corporativa nunca foi o planoCandidata-te ao Solopreneur Accelerator.Candidatar-me →

Perguntas frequentes

O que é um ficheiro CLAUDE.md?

Um ficheiro markdown (texto simples) na raiz do teu projeto que o Claude Code lê antes de cada resposta. Contém as regras do teu projeto, os padrões, a stack tecnológica, exemplos de código reais e antipadrões — para que a IA siga os teus padrões à primeira em vez de ser retreinada em cada conversa.

Preciso de saber programar para escrever um?

Não. O ficheiro escreve-se em linguagem simples: o que é o produto, as regras que têm de se manter sempre, o que nunca pode acontecer. Para a secção de exemplos, colas código que a própria IA gerou quando acertou. Enunciar decisões é o trabalho do fundador; implementá-las é o da IA.

Que tamanho deve ter um ficheiro CLAUDE.md?

Começa hoje com cinco regras. Fá-lo crescer até às 200–400 linhas — o suficiente para conter os teus padrões, curto o suficiente para a IA o usar todo. Abaixo de 100 linhas é pouco; acima de 500, corta. Revê-o todas as semanas: acrescenta padrões novos, apaga regras desatualizadas.

O CLAUDE.md chega sozinho para construir funcionalidades?

Cobre as regras globais — os erros que de outra forma se repetiriam em cada ficheiro. Para uma funcionalidade complexa queres também uma especificação da tarefa com os requisitos exatos, os dados e os passos de validação dessa funcionalidade. Esse é o método PRP; CLAUDE.md mais um PRP é a forma de as funcionalidades saírem bem à primeira.