Toda a gente que usa IA com regularidade conhece a sensação: cada conversa começa do zero. Volta a explicar quem é o cliente, que tom usar, que palavras evitar, onde estão os ficheiros. E mesmo assim, uma semana depois, o resultado sai com outro estilo.
No Claude Code, a resposta a esse problema é um ficheiro de texto chamado CLAUDE.md. É lido automaticamente no início de cada sessão e funciona como o “manual de acolhimento” que daria a um novo colaborador. Bem escrito, é a diferença entre uma IA que adivinha e uma IA que segue as regras da casa.
Este guia é pensado para quem usa o Claude Code em projetos de marketing, conteúdo e gestão, não apenas em programação.
Termos usados neste artigo
- Claude Code: a versão do Claude que trabalha em ficheiros e pastas do seu computador, através do terminal ou da app de desktop.
- CLAUDE.md: ficheiro de instruções em Markdown que o Claude Code carrega automaticamente em cada sessão.
- Markdown: formato de texto simples com marcações leves (
#para títulos, para listas).- Contexto: toda a informação que o modelo tem “à frente” numa conversa. Tem um limite, e tudo o que lá está compete pela atenção do modelo.
- Git: sistema de controlo de versões usado para partilhar ficheiros de um projeto numa equipa.
O que é e porque importa
O CLAUDE.md é um ficheiro onde escreve, em linguagem simples, o que o Claude precisa de saber para trabalhar bem num projeto: o objetivo, a estrutura de pastas, as regras, o tom, os erros a evitar e o que nunca deve fazer sem perguntar.
Sem ele, o Claude toma decisões razoáveis, mas suas. Com ele, toma as decisões que a sua equipa tomaria.
Segundo a documentação oficial, o Claude trata estas instruções como contexto, não como regras impostas: quanto mais específicas e concisas, mais consistentemente são seguidas.
Onde fica o ficheiro (e o que cada um faz)
| Local | Âmbito | Para quê |
|---|---|---|
~/.claude/CLAUDE.md | Todos os seus projetos | Preferências pessoais: língua, tom, formato das respostas |
./CLAUDE.md (raiz do projeto) | Este projeto, para toda a equipa | Regras do projeto. Se usam Git, é partilhado com todos |
./CLAUDE.local.md | Este projeto, só para si | Notas pessoais. Adicione ao .gitignore para não ser partilhado |
.claude/rules/*.md | Este projeto, por tema | Regras divididas em ficheiros (por exemplo tom-de-voz.md, seo.md) |
| Ficheiro gerido pela organização | Todos os utilizadores da empresa | Políticas definidas pela equipa de TI (segurança, conformidade) |
Pontos práticos:
- Os ficheiros somam-se, não se substituem. O Claude lê o global, o do projeto e o local, por esta ordem. O mais próximo da pasta onde trabalha é lido por último.
- Ficheiros em subpastas carregam quando são necessários, ou seja, quando o Claude trabalha nessa subpasta. Útil para ter regras próprias numa pasta
artigos/e outras numa pastaanuncios/. - Pode importar outros ficheiros com a sintaxe
@caminho/ficheiro.md. Por exemplo,@marca/tom-de-voz.md. Ajuda a organizar, mas não poupa espaço: o ficheiro importado também é carregado.
Comandos úteis
/init: gera um primeiroCLAUDE.mda partir do que encontra no projeto. Se já existir um, sugere melhorias em vez de o substituir./memory: abre e edita os ficheiros de instruções./context: mostra o que está carregado na sessão, para confirmar que as regras estão a ser lidas.
O Claude Code tem também uma memória automática, onde regista por iniciativa própria aprendizagens a partir das suas correções. Complementa o CLAUDE.md, mas não o substitui: as regras importantes devem estar escritas por si.
Tamanho: menos é mais
A documentação recomenda menos de 200 linhas por ficheiro. Ficheiros mais longos ocupam mais contexto e reduzem a adesão às regras.
O meu conselho para começar: 20 a 30 linhas que segue de facto. Depois, sempre que corrigir a mesma coisa duas vezes, essa correção passa a ser uma linha do ficheiro.
Modelo para um projeto de marketing e conteúdo
# Projeto: Blog e redes sociais da [Empresa]
Produção de artigos, posts e newsletters para [empresa], que vende [produto/serviço] a [público].
## Mapa
- artigos/ → rascunhos e versões finais dos artigos do blog
- redes/ → posts para LinkedIn e Instagram
- marca/ → manual de marca, tom de voz, glossário
- dados/ → estudos e números que podemos citar (com fonte)
## Regras que não se quebram
- Escrever sempre em português de Portugal, com o Acordo Ortográfico em vigor. O nosso público é português.
- Nunca inventar números, estudos, clientes ou testemunhos. Sem fonte em dados/, não se publica.
- Preços de ferramentas: confirmar sempre na página oficial e indicar a data. Os preços mudam.
- Explicar sempre siglas técnicas (SEO, GEO, CRM) na primeira utilização. O leitor é gestor, não técnico.
## Tom
- Profissional mas acessível. Frases curtas. Sem jargão de agência.
- Ver @marca/tom-de-voz.md para exemplos do que dizer e do que evitar.
## Erros que já cometemos
- Usar termos do português do Brasil ("tela", "time", "planilha", "pauta"). Usar "ecrã", "equipa", "folha de cálculo", "tema".
- Títulos com mais de 60 caracteres cortam no Google.
- Chamadas para ação genéricas ("saiba mais"). Usar sempre a CTA definida em @marca/cta.md.
## Formato de entrega
- Artigos em Markdown, com meta title (≤60 caracteres) e meta description (≤155) num comentário no topo.
- Rodapé: "Artigo publicado em [seu site]".
## Antes de dizer que terminou
- Contar os caracteres das metas.
- Verificar que todas as afirmações com números têm fonte.
## Não fazer sem me perguntar
- Publicar, enviar emails ou alterar ficheiros em marca/.
- Apagar qualquer ficheiro.
Repare em três detalhes:
- Cada regra tem o porquê. “Escrever em português de Portugal porque o nosso público é português“. Regras com motivo são seguidas com mais consistência e aplicadas com melhor critério em casos novos.
- A secção “Erros que já cometemos” é a mais valiosa. Regista os problemas que não se veem à primeira e que se repetem.
- “Não fazer sem me perguntar” protege o que é caro ou irreversível.
Deixar o Claude entrevistá-lo
Se não sabe por onde começar, peça ao Claude que faça as perguntas:
Quero criar o CLAUDE.md deste projeto. Entrevista-me, uma pergunta de cada vez, sobre:
o objetivo do projeto, o público, a estrutura de pastas, o tom de voz, as regras que não se podem quebrar,
os erros que já cometemos e o que nunca deves fazer sem me perguntar.
No fim, escreve o ficheiro na raiz do projeto com no máximo 100 linhas,
com o motivo de cada regra, e diz-me quais são as 3 linhas mais fracas.
Um mês depois, faça uma revisão:
Revê o CLAUDE.md deste projeto. Diz-me que regras não estou a seguir,
quais se contradizem, quais estão desatualizadas e quais não mudam nenhuma decisão. Propõe cortes.
O Claude Code tem também uma auditoria própria aos ficheiros de instruções, acessível através do comando /doctor.
O que nunca colocar no CLAUDE.md
- Palavras-passe, chaves de API ou dados de acesso. O ficheiro é lido em todas as sessões e, num projeto partilhado, fica visível para toda a equipa.
- Dados pessoais de clientes. Se precisa de os usar, ficam em ficheiros próprios, com acesso controlado.
- Regras que não segue. Ensinam o modelo a ignorar o ficheiro.
- Instruções que se contradizem. Se duas regras chocam, o Claude pode escolher uma ao acaso.
- Texto motivacional ou descrições genéricas (“somos uma empresa inovadora e focada no cliente”). Não mudam nenhuma decisão e ocupam espaço.
- Histórico de alterações. Isso pertence ao Git ou a um registo próprio.
E se não usa o Claude Code?
O princípio é o mesmo noutras ferramentas:
- No claude.ai: as instruções de um Projeto fazem o papel do
CLAUDE.mddo projeto; o campo “Instructions for Claude” nas definições faz o papel do ficheiro global. - No ChatGPT: as instruções de um projeto ou de um GPT personalizado.
- Noutros agentes de programação: muitos leem um ficheiro
AGENTS.md. O Claude Code também consegue ler umAGENTS.mdexistente quando não háCLAUDE.md.
O formato muda, a lógica não: escreva uma vez o que a IA precisa de saber, mantenha-o curto e atualize-o sempre que corrigir a mesma coisa duas vezes.
Quer configurar a IA para trabalhar com as regras da sua marca? Marque uma análise rápida ao seu negócio em contacto e vemos juntos marketing, vendas, tecnologia e IA.
Informação verificada em outubro de 2026 na documentação oficial do Claude Code. Comandos e comportamentos podem mudar entre versões.
