CLAUDE.md: a memória que se compõe

O problema da sessão em branco

A cada nova sessão, o Claude recomeça do zero. Voltas a explicar o projeto, as convenções, onde estão os ficheiros, como referenciar a chave API… É uma perda de tempo repetida, mas é pior do que isso: é uma perda de fiabilidade. Um dia esqueces-te de mencionar uma convenção, e o Claude mostra uma chave API em claro num comando ou arruma um ficheiro no sítio errado. A qualidade do teu sistema passa a depender da tua memória do momento — exatamente o que procuramos eliminar desde o início do curso.

A solução chama-se CLAUDE.md. É um ficheiro na raiz do teu projeto que o Claude Code lê no arranque de cada sessão, antes mesmo da tua primeira mensagem. Tudo o que lá puseres torna-se contexto persistente: o Claude conhece-o antes de falares. É a diferença entre um trabalhador temporário a quem se faz um briefing todas as manhãs e um colaborador que conhece a casa.

Uma memória com vários andares

O CLAUDE.md não existe apenas na raiz do projeto. O Claude Code lê na realidade uma hierarquia de ficheiros de memória, do mais geral ao mais específico: o teu ficheiro pessoal ~/.claude/CLAUDE.md (as tuas preferências válidas em todos os teus projetos — língua, estilo de resposta, convenções pessoais), o CLAUDE.md do projeto (versionado no Git, partilhado com a equipa), e eventuais CLAUDE.md em subpastas para as regras próprias de uma parte do projeto.

• ~/.claude/CLAUDE.md — as tuas preferências pessoais, em todos os projetos.
• CLAUDE.md na raiz do projeto — convenções e contexto do projeto, partilhados via Git.
• subpasta/CLAUDE.md — regras específicas de uma zona, carregadas quando o Claude lá trabalha.

Esta hierarquia responde à pergunta «onde pôr o quê». A regra é a mesma do capítulo 3 para os skills: o que é pessoal vai para a tua pasta, o que pertence ao projeto vai para o projeto. «Responde-me sempre em português» → pessoal. «A chave API referencia-se via o ficheiro .env, nunca em claro» → projeto.

Criar o teu CLAUDE.md

Dois caminhos possíveis. O primeiro: o comando /init, que analisa o teu projeto e gera um primeiro CLAUDE.md — é o bom reflexo num projeto existente que o Claude não conhece. O segundo, mais preciso para o nosso caso: pedir ao Claude para codificar o que construíram juntos, já que ele tem todo o contexto. Cola este prompt:

cria um ficheiro CLAUDE.md que codifica tudo o que construímos neste projeto:
- link para a doc da API utilizada
- onde se encontra a chave API e como a referenciar nos comandos
- convenções de comandos (sempre inline, etc.)
- link para o ficheiro de voz de marca
- link para a configuração do quality gate
- link para o registo dos posts
- qualquer outro padrão que tenhamos estabelecido

O Claude percorre o projeto, reúne os padrões recorrentes que funcionaram bem e codifica-os. A partir de agora cada sessão arranca com todo o contexto: a estrutura do projeto da Lea, as suas convenções, as suas salvaguardas. Abre o ficheiro gerado e lê-o — é a fotografia de tudo o que aprendeste neste curso.

O que vai para o CLAUDE.md (e o que não vai)

A tentação, uma vez compreendido o mecanismo, é pôr lá tudo. Erro: o CLAUDE.md é carregado no contexto de cada sessão, cada palavra tem portanto um custo permanente. Um ficheiro de 400 linhas atravanca todas as tuas conversas com detalhes inúteis 95% do tempo — exatamente o ruído que combatemos desde o capítulo 2. O alvo: um ficheiro curto e denso, em que cada linha merece ser lida a cada sessão.

O atalho #: memorizar no momento

Manter esta memória não deve ser uma tarefa penosa, senão não o farás. O Claude Code tem um atalho dedicado: começa uma mensagem por # e o que escreves é proposto para adição à memória, sem interromper o teu trabalho. Em plena sessão, reparas que o Claude voltou a usar um formato de data que te desagrada? Escreve # as datas são sempre no formato DD/MM/AAAA — a regra é capturada, a sessão continua.

O outro mecanismo de manutenção, mais estrutural: no fim de uma sessão de trabalho rica, pede «relê a nossa conversa e atualiza o CLAUDE.md com os padrões que estabelecemos». O Claude extrai as decisões duradouras da conversa e funde-as na memória. É o equivalente da ata de reunião — dez segundos a pedir, e nada se perde.

O conhecimento que se compõe

Tal como os teus skills, o teu CLAUDE.md evolui continuamente — e é este ciclo que muda tudo. Cada sessão constrói sobre a anterior em vez de recomeçar do zero: é assim que a tua expertise se compõe ao longo do tempo, no sentido dos juros compostos. A maioria das pessoas usa a IA de forma linear: 100 sessões, 100 vezes o mesmo nível. Com uma memória mantida, a tua sessão 100 arranca com o condensado das 99 anteriores.

flowchart LR
  S["Sessão de trabalho"] --> U["«atualiza o CLAUDE.md»"]
  U --> M["CLAUDE.md enriquecido"]
  M -->|"Lido no arranque"| N["Nova sessão"]
  N --> S

E o ciclo fecha-se com o capítulo 2: podes agora fazer /clear sem remorsos. O ruído conversacional desaparece, o essencial volta pelo CLAUDE.md. Contexto limpo e memória duradoura — as duas exigências que pareciam contraditórias no início do curso estão reconciliadas.

E agora?

Faz o balanço do sistema da Lea: um skill /post multi-plataforma com a sua voz de marca, um quality gate que torna os erros públicos impossíveis, subagents que publicam em paralelo, um comando /plan-week que orquestra a semana, e uma memória de projeto que faz com que tudo se mantenha ao longo do tempo. A Lea escreve uma frase; o sistema faz o resto, sob o seu controlo.

Para ir mais longe, três direções naturais: ligar mais ferramentas externas via MCP (CRM, analytics, calendários — o comando claude mcp add é o teu ponto de entrada), explorar o modo navegador para que o Claude teste ele próprio o que publica, e sobretudo: repetir o método deste curso noutro processo da tua vida profissional. O método — skill, salvaguarda, paralelização, validação, memória — é o verdadeiro produto deste curso. A Lea era apenas o pretexto.