Há uma pergunta que separa quem aproveita o Claude de quem luta com ele: explicas-lhe o teu projeto sempre que abres uma sessão? Se a resposta for sim, estás a deixar metade do valor em cima da mesa. O truque não é escrever melhores prompts. É escrever um ficheiro, uma única vez, que o Claude leia automaticamente sempre que começa: o CLAUDE.md.
É a mudança mais barata e mais rentável que podes fazer. Quatro linhas bem postas e deixas de te repetir para sempre. Este guia é sobre o que meter ali, o que deixar de fora e como o estruturar para que funcione a sério.
Nota
O CLAUDE.md não é um prompt nem uma documentação. É contexto permanente: as regras e os dados que se aplicam a todas as tuas sessões nesse projeto. O Claude carrega-o sozinho ao abrir a pasta, sem que tenhas de o colar no chat.
O que é o CLAUDE.md e porque multiplica o Claude
É um ficheiro de texto em formato Markdown que pões na pasta do teu projeto. Nada mais: texto simples. O que o torna especial é que o Claude o lê automaticamente ao arrancar cada sessão e trata o seu conteúdo como instruções de cabeçalho.
A diferença face a um chat normal é brutal. Sem CLAUDE.md, cada conversa começa do zero: o Claude não sabe o que é o teu projeto, que stack usas, como gostas que escreva nem que ficheiros são intocáveis. És tu que preenches esse vazio à mão, uma e outra vez, gastando o teu tempo e a atenção dele. Com CLAUDE.md, esse contexto já está carregado antes de escreveres uma palavra.
É por isso que «multiplica»: não torna o Claude mais inteligente, torna-o mais teu. Deixa de adivinhar e começa alinhado com a forma como trabalhas. A primeira resposta de cada sessão já é a boa, não a terceira.
O que pôr (e o que deixar de fora)
Aqui está o erro mais comum: tratar o CLAUDE.md como uma gaveta onde se mete tudo o que se sabe do projeto. Mal. Tudo o que escreves ali ocupa contexto em cada sessão e compete pela atenção do modelo. Um ficheiro enorme dilui as instruções que de facto importam.
A regra mental é simples: instruções operativas e estáveis, não documentação. Se algo é estável (aplica-se sempre) e operativo (muda a forma como o Claude trabalha), entra. Se muda todas as semanas ou só serve para uma tarefa de hoje, vai para o chat.
O que VAI dentro:
- O que é o projeto numa ou duas frases. O para quê, não a história.
- Como queres que trabalhe: tom, idioma, nível de detalhe, se deve pedir permissão antes de mudanças grandes.
- Convenções: stack e comandos (projetos de código), estrutura de pastas, nomenclatura, formato de saída.
- Proibições explícitas: que ficheiros ou áreas nunca deve tocar. É a secção que mais erros evita e a que quase todos esquecem.
- Atalhos: comandos ou fluxos que repetes muito («para publicar usa-se X»).
O que NÃO vai dentro:
- O histórico do projeto ou decisões já fechadas que não afetam o trabalho de hoje.
- Documentação longa que já vive noutro sítio (melhor: liga-a ou diz onde está).
- Instruções de uma só tarefa («hoje corrige este bug»): isso é um prompt.
- Segredos, chaves ou palavras-passe. Nunca.
Atenção
A secção das proibições é a mais importante e a mais ignorada. «NÃO modifiques a pasta de produção», «NUNCA apagues dados sem me mostrares o plano antes», «não toques nos ficheiros de configuração». Escrever o que NÃO deve acontecer evita 90 % dos sustos.
Uma estrutura recomendada
Não há um formato obrigatório, mas esta estrutura funciona porque vai do geral ao específico e põe as regras duras onde o Claude as vê. Quatro blocos:
- Sobre o projeto — o que é e para quê, em poucas frases.
- Como trabalhar — tom, idioma, fluxo de aprovação, nível de detalhe.
- Convenções — stack, estrutura, comandos, formato. O concreto.
- Não tocar — as proibições explícitas, bem visíveis.
Mantém cada bloco curto e em listas. O Claude lê melhor cinco pontos claros do que um parágrafo denso. E se o teu projeto crescer, divide: um CLAUDE.md geral com as tuas preferências globais e um por subprojeto com os seus detalhes. Os específicos somam-se aos gerais, por isso não te repitas: no da marca pões o tom, no de cada projeto só o que muda.
Modelo copiável
Este é o modelo base. Copia-o, apaga o que não se aplica e preenche os parênteses. Em dois minutos tens um CLAUDE.md melhor do que 95 % dos que existem.
# [Nome do projeto]
## Sobre o projeto
[O que é, em 1-2 frases.] Uso-o para [objetivo principal].
Público / contexto: [quem o usa ou para quem é].
## Como quero que trabalhes
- Fala comigo em português, direto e sem rodeios.
- Antes de mudanças grandes ou irreversíveis, mostra-me o plano e espera o meu OK.
- Por defeito, tarefas pequenas e reversíveis.
- Se algo não estiver claro, pergunta antes de assumir.
## Convenções
- Stack / ferramentas: [linguagem, framework, apps].
- Estrutura: [onde vive cada coisa].
- Comandos-chave: [build / test / deploy se aplicável].
- Formato de saída: [como queres as respostas].
## NÃO tocar (importante)
- [ficheiros, pastas ou áreas intocáveis].
- Nunca apagues nem sobrescrevas [X] sem avisar primeiro.
- Não incluas segredos, chaves nem dados sensíveis.Três exemplos consoante o teu caso
O modelo é o mesmo; o que muda é o preenchimento. Três casos reais.
Projeto de código. Aqui o valor está nas convenções técnicas. Stack e versões, comando de build e de testes, estrutura de pastas, estilo de código («usa TypeScript estrito, sem any») e as proibições críticas («não toques em migrations/, não faças push direto para main»). O Claude deixa de inventar comandos e respeita a tua arquitetura desde a primeira mensagem.
Marca ou negócio. Aqui o que importa é a voz. Tom («direto, prático, sem enchimento, sem emojis»), que palavras usar e quais evitar, formato dos textos, idioma e regras de estilo («nunca prometas resultados garantidos»). O que em código são convenções técnicas, na marca são convenções de voz. O resultado: tudo o que o Claude escreve soa a ti, não a IA genérica.
Uso não técnico. Organizar documentos, planear, redigir e-mails. Não é preciso saber programar. Pões como trabalhas («ordena-me sempre por data», «os resumos em pontos de no máximo cinco»), as tuas pastas habituais e o que não tocar («não mexas em nada da pasta Importante sem me mostrares antes o que vais fazer»). Mesmo ficheiro, mesmo efeito: deixas de explicar o óbvio em cada sessão.
O erro que arruína um bom CLAUDE.md
Escrevê-lo e esquecê-lo. Um CLAUDE.md é um documento vivo: quando notares que repetes uma instrução no chat duas ou três vezes, essa instrução pertence ao ficheiro. Acrescenta-a. E ao contrário: se uma regra já não se aplica, apaga-a, porque o lixo acumulado também pesa.
Trata-o pelo que é: o contrato de trabalho entre ti e o Claude. Quanto mais claro e atualizado, melhor trabalha. A diferença entre quem luta com a ferramenta e quem a aproveita reduz-se quase sempre a isto: o segundo escreveu as suas regras uma vez, num ficheiro, e deixou de as repetir para sempre.
Abre o teu projeto, cria um CLAUDE.md com o modelo de cima e preenche os quatro blocos. É o mais rentável que farás hoje com o Claude.