Como configurar o CLAUDE.md em 2026: modelo e 6 regras

Materiais sobre vibe coding: ferramentas, estudos de caso, erros. Guias Ailoot.

Porque precisa do CLAUDE.md e porque é que Claude se esquece do projeto sem ele?#

Na terça-feira, abre o Claude Code e explica: «Estou a trabalhar neste projeto, estas são as ferramentas, não faças isto.» Funciona.

Na quinta-feira, esse mesmo chat já terminou, por isso repete tudo. No sábado, outra vez; na segunda-feira, mais uma vez.

É assim trabalhar com um agente sem CLAUDE.md: cada janela nova é um estagiário sem contexto a quem tem de dizer as mesmas coisas vezes sem conta. Eu costumava passar 5-10 minutos a escrever esta introdução em cada sessão. Os prompts tornavam-se longos porque tinha de transmitir manualmente todo o contexto. E o resultado continuava a ser genérico: o agente não conhecia o meu público, a minha economia nem os meus princípios.

Com um CLAUDE.md atualizado, deixa de ser necessário fazer a introdução. Todas as regras que costumava repetir em cada chat estão num único ficheiro e aparecem automaticamente no início de cada sessão. O prompt fica curto: «faz X», em vez de «estou a trabalhar no projeto Y, as ferramentas são Z, não faças A nem B e, já agora, lembra-te também de C».

Depois, os erros repetidos desaparecem.

Cada erro do agente é um motivo para acrescentar uma linha ao CLAUDE.md. Ao fim de um mês, tem uma «constituição do projeto» viva e Claude deixa de cair nas mesmas armadilhas conhecidas.

E há uma terceira camada: o agente deixa de escrever no vazio. Através do CLAUDE.md, encaminho Claude para pastas com contexto: onde procurar informações sobre o público, os preços e a marca. Sem este encaminhamento, o agente escreve «soluções de alta qualidade» sem conhecer a minha economia, pelo que os resultados são abstratos, formulaicos e «iguais aos de toda a gente».

O que é o CLAUDE.md e por que ordem é que Claude o lê?#

A Anthropic descreve o CLAUDE.md assim na documentação oficial:

Os quatro locais onde o Claude Code procura o CLAUDE.md, por ordem crescente de prioridade:

Os quatro ficheiros são carregados para o contexto ao mesmo tempo. Se as regras entrarem em conflito, a Anthropic afirma diretamente na documentação que não se sabe qual terá precedência; Claude poderá escolher uma delas arbitrariamente. Por isso, é mais simples manter tudo o que é essencial no CLAUDE.md do projeto e evitar duplicados.

Há um pormenor técnico de que quase ninguém fala, mas que explica muitos comportamentos estranhos.

Por outras palavras, o CLAUDE.md não é um «prompt do sistema» em sentido estrito. É a primeira mensagem do utilizador que Claude vê. Portanto, as suas regras são sugestões firmes, não leis. Se uma regra precisar de imposição técnica, use um hook testado para o evento abrangido e permissões ou isolamento do ambiente para o limite mais amplo de acesso. A execução automática de um hook não torna as verificações completas. Explicarei abaixo a fronteira entre hooks e CLAUDE.md.

Como escrever um CLAUDE.md mínimo em 5 minutos (modelo pronto a usar)?#

Segue-se um modelo que testei em dezenas dos meus projetos. Mantém o ficheiro perto de 80-120 linhas, seguindo a recomendação da Anthropic de procurar ficar abaixo de 200 linhas. Com este modelo, o agente dá os resultados mais sensatos.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Para que Claude preencha automaticamente este modelo para o seu projeto, dê-lhe este prompt. Vai ler o contexto e preencher os campos entre parênteses retos:

Cria um ficheiro CLAUDE.md na raiz do projeto usando este modelo:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Segue estes passos:

Lê about-me/INDEX.md e business/INDEX.md para compreender o contexto do projeto e a minha perspetiva enquanto autor.

Preenche todos os campos entre parênteses retos do modelo com base no que encontrares nessas pastas.

Se faltar alguma informação, faz-me perguntas de esclarecimento, uma de cada vez, com 3-4 opções de resposta.

Procura manter o CLAUDE.md resultante abaixo de 200 linhas. Se for mais longo, revê repetições e transfere procedimentos detalhados para ficheiros ligados. Preserva as regras essenciais de planeamento, reflexão e repositório e testa-as depois em tarefas representativas.

Mostra-me o ficheiro final e pergunta-me o que deve ser revisto.

Responde sempre no idioma preferido do utilizador.

Se ainda não tiver as pastas about-me/ e business/, não há problema. Claude fará perguntas de esclarecimento e preparará um CLAUDE.md mínimo com base no que estiver disponível. Pode criar as pastas mais tarde, quando souber o que lá colocar.

Que 6 regras transformam o CLAUDE.md num documento vivo?#

Regra 1. Mantenha-o abaixo de 200 linhas

A Anthropic diz isto sucintamente na documentação oficial:

Um CLAUDE.md longo prejudica-se a si próprio de duas formas. Primeiro, consome tokens. Um ficheiro de instruções com 800 linhas é carregado em todas as janelas e consome vários milhares de tokens do seu orçamento em cada sessão. Com uma subscrição Pro e um limite diário, isso reduz visivelmente o número de sessões disponíveis. Segundo, o modelo começa a ignorar as regras.

A documentação recomenda procurar ficar abaixo de 200 linhas para reduzir o consumo de contexto e melhorar o cumprimento. Não estabelece uma quebra abrupta na linha 201. Examine a relevância, as contradições, o volume de tokens carregado e os resultados reais das tarefas antes de decidir o que transferir para outros ficheiros.

Regra 2. Termine cada sessão com uma reflexão

Escreva no CLAUDE.md: «No final de cada sessão, regista o que fizeste e aprendeste em retrospectives/YYYY-MM-DD_*.md.» Depois de acrescentar esta linha, Claude começa a terminar cada sessão com uma reflexão por iniciativa própria; não precisa de pedir.

Porquê refletir:

• Duas semanas depois, pode abrir uma retrospetiva antiga e recordar porque escolheu aquele caminho.
• Quando regressar ao projeto um mês mais tarde, terá um mapa pronto das decisões recentes.
• Se trabalhar em equipa, um parceiro pode ler a retrospetiva e compreender o estado atual em 2 minutos, sem uma chamada.

Regra 3. Faça commit depois de cada tarefa concluída

O meu CLAUDE.md diz: «Depois de concluir cada tarefa, cria um commit git com uma mensagem significativa.» Claude começa a dividir o trabalho em commits atómicos por iniciativa própria.

Isto dá-lhe duas coisas. Primeiro, se algo falhar, pode reverter uma operação, em vez de «tudo o que fiz hoje». Segundo, o histórico de commits torna-se um registo de trabalho que mostra o que mudou e por que ordem.

Regra 4. Consulte sempre a pasta business/

Em qualquer tarefa que envolva clientes, produtos ou textos, o agente deve abrir primeiro business/INDEX.md e o ficheiro relevante aí indicado. O meu CLAUDE.md diz explicitamente: «Ao trabalhar na UI ou em textos, consulta primeiro business/audience/avatar.md e business/assets/brand-guidelines.md.»

Sem esta regra, Claude escreve textos «no estilo geral de um site de qualidade». Com ela, o texto segue o seu estilo, dirige-se ao seu cliente e evita as palavras proibidas.

Regra 5. Acrescente uma regra depois de cada erro do agente

Esta é a regra principal para manter o CLAUDE.md atualizado.

Exemplos do meu próprio CLAUDE.md que foram acrescentados depois de erros específicos:

• «Nunca faças commit de ficheiros WIP de outra pessoa com git add . - prepara os ficheiros pelo nome.»
• «Antes de fazer push para main, verifica git log origin/main..main --oneline - se não estiver vazio, não faças push.»
• «Não inventes valores - obtém-nos de .env ou do código. Sobretudo URLs, nomes de utilizador e tokens.»

Cada uma destas linhas é o registo de um incidente específico. Uma vez, um agente fez commit de um branch inacabado de um parceiro. Noutra ocasião, incluí commits de outra pessoa que ainda não tinham sido enviados. Uma vez, um agente inventou um URL que não existe. Cada erro torna-se uma regra, e a mesma ferida autoinfligida não volta a acontecer.

Regra 6. Coloque a segurança em .claude/settings.json, não no CLAUDE.md

No CLAUDE.md, pode escrever «não mexas no .env», mas isso é um pedido; Claude poderá desrespeitá-lo, porque o CLAUDE.md é carregado como uma mensagem do utilizador, não como uma lei. Para segurança crítica, use .claude/settings.json, onde pode bloquear determinados comandos de forma estrita.

A lista de bloqueio que acrescento a cada projeto novo:

• rm -rf (eliminação recursiva de quaisquer ficheiros).
• Leitura integral de .env (Read .env).
• export e curl no mesmo comando (um padrão para divulgar segredos externamente).
• git push --force sem aprovação explícita.

Encontre outros guias na Ailoot.

Como está estruturado o CLAUDE.md numa empresa ativa (anatomia de um ficheiro com 280 linhas)?#

A maioria dos exemplos de CLAUDE.md disponíveis na Internet são modelos técnicos para programadores: «Usa TypeScript», «Não escrevas testes com mais de 50 linhas». Para um empresário, este tipo de CLAUDE.md é inútil - não abrange a componente empresarial.

Segue-se a estrutura do meu CLAUDE.md de trabalho. Removi as regras e os caminhos específicos porque refletem as minhas operações internas. Mas a estrutura e a lógica das secções podem ser aplicadas a qualquer projeto: adapte-as às suas circunstâncias e terá um ficheiro funcional.

1. Breve descrição do projeto (15 linhas). O que fazemos, quem é o público e que produtos oferecemos. Não é um resumo do site de marketing, mas uma síntese para o agente perceber «para onde vamos».

2. Sobre mim (10 linhas). Uma referência à pasta about-me/ - uma projeção digital da forma como penso. Tom, valores, princípios, palavras proibidas. Quando Claude escreve um texto «como eu», lê primeiro esta pasta para fazer corresponder a voz.

3. Estrutura do repositório (20 linhas). Uma árvore com comentários: onde está o código, onde está o contexto empresarial, onde estão os planos e as reflexões. Sem este mapa, Claude procura ficheiros às cegas de cada vez.

4. Tabela «onde encontrar as coisas» (25 linhas). Encaminhamento de «pergunta → ficheiro». Por exemplo, para uma agência imobiliária, poderia dizer «precisas das condições de crédito à habitação → business/products/mortgage.md» ou «precisas do tom de voz das publicações → business/assets/voice.md». Substitua pelos seus ficheiros. Esta tabela é o coração do CLAUDE.md. Sem ela, o agente tenta adivinhar qual ficheiro contém a resposta. Com ela, vai diretamente à fonte.

5. Princípios fundamentais do projeto (40 linhas, 10-15 itens). Esta secção acumula-se lentamente e exige mais esforço. Cada item regista um erro específico. Por exemplo, as regras para uma loja online poderiam ser «nunca introduzas preços e prazos de entrega diretamente no código», «não publiques um produto sem uma instrução explícita» e «confirma o estilo com o glossário da marca antes de publicares uma ficha de produto». Esta secção é a «constituição do projeto».

6. Planeamento operacional (20 linhas). Uma tabela de acionadores que associa «frase do utilizador → ação». Por exemplo: «Quando eu disser “planeia a semana”, abre ops/monthly.md e cria o ficheiro da semana.» Isto transforma Claude num assistente de operações que compreende o contexto dos comandos.

7. Ferramentas (5 linhas). Tecnologias. De forma breve, sem palha.

8. Publicação (15 linhas). Um processo passo a passo para publicar alterações em produção: que comandos executar, por que ordem e o que verificar. Antes, explicava-o sempre. Agora Claude sabe.

9-12. Segurança (35 linhas). Quatro subseções separadas: regras para trabalhar com .env, acesso à base de dados de produção, comandos seguros para demonstrações (gravações de ecrã, transmissões, capturas de ecrã, para que os tokens não sejam expostos acidentalmente) e regras para rodar segredos.

13. A pasta plans/ (10 linhas). O padrão para os planos: nome de ficheiro, estrutura das fases e o que incluir no bloco de resumo.

14. A pasta retrospectives/ (5 linhas). O padrão para a reflexão: modelo, nome do ficheiro e o que deve conter.

15. Dados da base de dados em tempo real (15 linhas). Uma regra para assinalar «dados recentes»: quando um ficheiro indica que os números têm de estar atualizados, o agente obtém-nos na fonte em vez de usar valores antigos. Isto elimina o risco de Claude usar os números de ontem.

16. Idioma (3 linhas). «Responde sempre no idioma preferido do utilizador. Usa apenas hífenes, não travessões.»

Cerca de 280 linhas no total. Ultrapassa o objetivo de concisão, mas não invalida o ficheiro. Neste exemplo, continuou a ser útil; a decisão de o manter deve depender do contexto efetivamente usado e de testes de tarefas representativas. As tabelas não são automaticamente mais económicas em tokens do que a prosa.

O que faz o comando /init e porque não é suficiente?#

A Anthropic descreve o comando assim na documentação:

O que /init faz bem:

• Identifica as ferramentas através de package.json, Cargo.toml e pyproject.toml.
• Enumera os comandos de compilação e teste.
• Deteta convenções em ficheiros existentes (.eslintrc, .prettierrc).
• Identifica regras existentes do Cursor (.cursorrules, .cursor/rules/) e do Copilot, e incorpora as partes relevantes. Deteta AGENTS.md no modo CLAUDE_CODE_NEW_INIT=1.

O que /init não faz:

• Não saberá quem é o seu cliente.
• Não incluirá as palavras proibidas para os textos.
• Não acrescentará regras sobre erros do agente (porque ainda não houve nenhum).
• Não criará uma tabela «onde encontrar as coisas» para a estrutura da sua empresa.

Assim, o fluxo de trabalho correto é:

1. Execute /init no Claude Code

   Terá um CLAUDE.md inicial com 30-50 linhas, ferramentas e comandos. Essa é a base técnica.

2. Acrescente o modelo deste artigo

   Use a secção «Um CLAUDE.md mínimo em 5 minutos». Acrescente secções sobre navegação, encaminhamento e princípios.

3. Preencha os campos entre parênteses retos

   Dê a Claude o prompt «lê o meu projeto e preenche o modelo». Se ainda não existirem as pastas business/ e about-me/, Claude fará perguntas de esclarecimento.

4. Faça um teste de esforço

   Diga a Claude: «Lê o meu CLAUDE.md e encontra 10 ambiguidades que poderiam levar-te, enquanto agente, a interpretá-lo mal.» Receberá uma lista de correções.

5. Depois, use o ficheiro no dia a dia

   Acrescente uma linha depois de cada erro do agente. Ao fim de um mês, terá um CLAUDE.md vivo, adaptado à sua empresa.

Prompt para o quarto passo:

Tenho um CLAUDE.md. Amanhã vou desenvolver uma funcionalidade com base nele.

A tua tarefa é submetê-lo a um teste de esforço. Encontra 10 motivos pelos quais poderíamos falhar:

onde o CLAUDE.md é ambíguo e tu, enquanto agente, poderias interpretá-lo mal

onde existem lacunas que te obrigariam a inventar informações

onde as regras se contradizem

onde sobrestimo o que é possível fazer num dia

onde subestimo as coisas (isto é ainda pior)

Não te contenhas. Critica-o sem rodeios. Quero encontrar estes problemas agora, não em produção.
No final, dá-me uma lista de alterações específicas: o que mudar e como, para evitar que estes problemas aconteçam.

CLAUDE.md vs AGENTS.md vs MEMORY.md: quem lê o quê em 2026?#

A principal pergunta que confunde os recém-chegados é: o Claude Code lê AGENTS.md? Antes de setembro de 2026, a resposta era «não»: a documentação da Anthropic recomendava criar um CLAUDE.md que importasse o AGENTS.md. Desde a versão 2.1.277 (lançada a 18 de setembro de 2026), o Claude Code lê o AGENTS.md diretamente, mas apenas se não existir CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md na pasta de trabalho ou em qualquer pasta acima dela.

Se o projeto tiver um CLAUDE.md, o Claude Code lê apenas esse ficheiro por predefinição e ignora o AGENTS.md. Pode alterar esta opção em /config, em Project instructions: por exemplo, a definição claude-md-and-agents-md faz com que leia ambos os ficheiros. Há outra forma que funciona em qualquer versão: acrescentar uma importação ao CLAUDE.md:

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

A sintaxe @filename importa outro ficheiro. Claude lê-o e carrega-o para o contexto juntamente com o CLAUDE.md. A importação não faz com que o ficheiro seja lido duas vezes, mesmo que o Claude Code consiga ler o AGENTS.md por si só.

Quando precisa de AGENTS.md. Se trabalhar em paralelo com Claude Code e Codex CLI, Cursor ou Copilot, crie um AGENTS.md como fonte única da verdade, coloque @AGENTS.md no CLAUDE.md e acrescente por cima quaisquer regras específicas do Claude. Se não tiver regras desse tipo, não precisa de criar CLAUDE.md: desde a versão 2.1.277, o Claude Code lê o AGENTS.md por si só. Se trabalhar apenas com Claude Code, não precisa de AGENTS.md; use apenas um CLAUDE.md. Para ver todas as opções passo a passo, consulte o guia para usar AGENTS.md e CLAUDE.md no mesmo projeto.

O que é MEMORY.md? Desde uma atualização recente, o Claude Code guarda automaticamente notas sobre si em ~/.claude/projects/<project-name>/memory/MEMORY.md. Estas incluem hábitos de conversação («o utilizador prefere respostas curtas»), expressões recorrentes («proibiu emojis no código») e observações comportamentais («trabalha em macOS, usa zsh»).

Este é um sistema de memória separado, não é o CLAUDE.md. Não o escreve à mão; Claude cria-o com base nas suas conversas. Se o MEMORY.md contiver algo que deva tornar-se uma regra, transfira-o para o CLAUDE.md. Se contiver algo desnecessário ou incorreto, pode apagá-lo manualmente; é um ficheiro de texto.

Que tamanho é útil para o CLAUDE.md e como rever um ficheiro longo?#

Em cada janela do Claude Code, são carregadas várias camadas para o contexto: o prompt do sistema da Anthropic (estimado em dezenas de milhares de tokens), o seu CLAUDE.md, os ficheiros importados com @, o MEMORY.md, o histórico do chat atual e o conteúdo dos ficheiros que Claude abre. Tudo isto tem de caber na janela de contexto do modelo (200K tokens para Sonnet, 1M para Opus).

Quanto maior for o CLAUDE.md, menos espaço sobra para o trabalho atual. Um ficheiro com 1,000 linhas tem cerca de 8,000 tokens e é repetido em todas as sessões. Numa subscrição Pro (na minha experiência, cerca de 10-12 prompts «pesados» por dia), isso reduz a sua capacidade em um quarto.

O custo é apenas uma preocupação. O cumprimento pode degradar-se quando as instruções são longas, irrelevantes ou contraditórias; não existe um número universal de instruções seguidas de forma fiável. Teste algumas tarefas representativas que exerçam as regras críticas, registe as falhas e compare o comportamento depois de uma edição focada.

Eis uma regra prática para o tamanho:

• 80-120 linhas - um intervalo inicial prático para um mapa conciso do projeto, sem pontuação garantida de cumprimento.
• 150-200 linhas - um bom momento para rever a relevância e transferir procedimentos detalhados para ficheiros ligados.
• 200-300 linhas - examine o volume de tokens, as repetições e os resultados das tarefas; o exemplo empresarial de 280 linhas acima pode continuar a funcionar bem.
• 400+ linhas - um forte motivo para uma revisão focada, não prova de inutilidade. Preserve os limites essenciais e só transfira pormenores depois de verificar que as ligações e as regras continuam a funcionar.

A contagem de linhas, por si só, não prova sucesso nem falha. Depois de editar, repita as mesmas tarefas representativas e verifique as regras importantes, em vez de atribuir uma percentagem de cumprimento inventada.

A Anthropic apresenta um teste direto na documentação:

Aplique este teste a cada linha. Se a resposta for «continuaria a acertar», remova a linha. O CLAUDE.md não é o lugar para documentação, histórico de decisões ou filosofia. Serve apenas para as regras de que o agente precisa para evitar erros.

Que 7 erros tornam o CLAUDE.md inútil?#

Erro 1. «Sê um bom engenheiro»

O erro mais comum. As pessoas escrevem desejos genéricos no CLAUDE.md: «escreve código limpo», «usa boas práticas», «pensa como um engenheiro sénior».

Estas palavras não significam nada. Claude já escreve «código limpo» em termos gerais. Estas linhas ocupam contexto sem afetar nenhuma decisão.

Substitua «escreve código limpo» por «usa indentação de 2 espaços», «não uses any em TypeScript» ou «as funções não podem ter mais de 30 linhas». São indicações específicas e verificáveis.

Erro 2. Repetir o que Claude já sabe

Descrições de convenções linguísticas comuns («em JavaScript, as funções são cidadãos de primeira classe», «TypeScript tem tipagem estática»). Explicações sobre o funcionamento de npm, git ou docker.

Claude aprendeu tudo isto durante o treino. Repeti-lo no CLAUDE.md não acrescenta nada; apenas ocupa espaço no contexto.

Erro 3. Instruções longas, passo a passo, dentro do CLAUDE.md

Instruções longas sobre «como implementar o projeto», «como escrever uma migração de base de dados» ou «como configurar um componente novo». Dezenas de linhas com instruções passo a passo.

Este não é o lugar para instruções longas, passo a passo. É para regras de uma linha. Coloque as instruções longas em skills/ (um mecanismo separado do Claude Code, carregado a pedido) ou em docs/. No CLAUDE.md, use uma ligação de uma linha: «Ao criar uma migração, abre docs/migrations.md.»

Erro 4. Regras já verificadas por um analisador automático de código

«Usa ponto e vírgula», «não deixes importações não utilizadas», «não uses var». O ESLint, o Prettier e o Biome detetam tudo isto - são linters (ferramentas automáticas de verificação de código).

Um linter é determinístico: é executado, encontra um erro e corrige-o. Uma regra no CLAUDE.md é probabilística; o agente pode esquecê-la. Não há motivo para a duplicar - é mais fácil configurar o linter.

Erro 5. Segredos no CLAUDE.md

Já vi palavras-passe de contas de teste, tokens de API de sandbox e ligações para painéis de administração autenticados. Estava tudo num ficheiro guardado no git e carregado para o contexto do modelo da Anthropic.

Nunca. Os segredos pertencem ao .env, que está no .gitignore. No máximo, o CLAUDE.md deve dizer: «Não leias o .env completo; usa grep para uma variável específica.»

Erro 6. Um depósito com 500+ linhas que não é limpo há seis meses

O CLAUDE.md cresceu, duplica metade de docs/, contradiz-se em vários pontos e ninguém se lembra do que lá está. O agente começa a ignorar a maior parte. A equipa queixa-se de que «Claude não segue as instruções» e acrescenta mais regras, piorando a situação.

Sinais de que um CLAUDE.md foi negligenciado: mais de 300 linhas, regras repetidas em secções diferentes, ligações desatualizadas para ficheiros que já não existem e notas «históricas» como «em 2024 decidimos fazer assim, mas depois mudámos de ideias».

A solução: de duas em duas semanas, peça a Claude que o reveja com o teste da Anthropic: «Se esta linha fosse removida, o agente cometeria um erro?». Apague tudo aquilo para que a resposta seja «não».

Erro 7. Criar o CLAUDE.md e esquecê-lo

É o oposto do erro anterior. O ficheiro foi preparado uma vez, há dois meses, e nunca mais foi alterado. Entretanto, as ferramentas mudaram, foram acrescentadas novas pastas e surgiram novos erros do agente. O CLAUDE.md não sabe nada disto porque ninguém o atualizou.

Um sinal revelador: repete a mesma instrução em cada sessão. «Não faças X», «não toques em Y», «lembra-te de Z». Se já a repetiu mais de duas vezes, a regra pertence ao CLAUDE.md, não à sua cabeça.

Como tornar o CLAUDE.md autodidático com uma regra de «atualização no fim da sessão»?#

O meu CLAUDE.md tem uma secção curta:

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Depois de acrescentar esta secção ao CLAUDE.md, Claude começou a perguntar no final de cada sessão: «Houve alguma coisa nova que valha a pena registar?» Se sim, sugeria uma regra preliminar, eu clarificava-a e era criado um ficheiro.

Depois de dois meses a trabalhar desta forma, tenho mais de duas dúzias de ficheiros em about-me/feedback/ - regras aprendidas com erros específicos. Cada ficheiro é uma página no formato Regra → Porquê → Como. A pasta tornou-se uma «segunda memória» que regista as minhas preferências pessoais e os meus tabus.

Cada erro deixa de se repetir porque se transforma numa regra, e as regras acumulam-se e reforçam-se mutuamente. Ao fim de seis meses, Claude conhece melhor o meu projeto do que eu próprio me lembro dele depois de uma pausa de um mês.

Como acrescentar regras jurídicas, marketing e operações ao CLAUDE.md?#

Para a maioria das equipas, o CLAUDE.md é um documento puramente técnico: ferramentas, comandos de compilação, convenções de programação. É útil, mas representa apenas um terço do valor.

Quando um empresário mantém o CLAUDE.md, faz sentido acrescentar secções de negócio. Há três particularmente importantes:

Regras jurídicas (para mercados regulados)

Se publicar textos num setor regulado (finanças, medicina, publicidade de medicamentos, produtos para crianças), as palavras proibidas têm força legal e devem constar explicitamente do CLAUDE.md. Não na cabeça de alguém, nem numa captura de ecrã do editor - num ficheiro que o agente vê em cada sessão.

Exemplo para um projeto fintech sem licença bancária:

Nota editorial: O exemplo seguinte mostra o formato de uma regra interna para um projeto específico. Não constitui uma autorização universal para usar os termos indicados: a aceitabilidade de uma afirmação depende da legislação aplicável e da situação da empresa.

🚨 CRÍTICO - é proibido usar formulações financeiras. Em materiais dirigidos a clientes, não use: «depósito», «rentabilidade garantida» ou «produto de investimento». Use: «conta poupança», «rentabilidade esperada» e «produto de taxa variável». O motivo são os requisitos legais aplicáveis à publicidade de serviços financeiros neste projeto.

Este bloco no CLAUDE.md faz algo simples: sempre que pede a Claude que escreva um texto dirigido a clientes, o agente verifica-o tendo em conta estas proibições. Sem a regra, as palavras proibidas aparecem em cada terceira campanha. Com ela, esquece-se de que existem.

A mesma abordagem funciona para:

• Projetos médicos (sem alegações de que algo «trata» ou «cura»).
• Publicidade de medicamentos (sem alegações de «mais eficaz»; avisos obrigatórios).
• Qualquer setor regulado com regras próprias de publicidade.

Estilo de marketing e formato dos textos

Se publica textos regularmente (redes sociais, newsletters, sites), vale a pena documentar o formato num parágrafo do CLAUDE.md. Eis um exemplo do que um influenciador ou uma agência responsável por um canal de mensagens poderia escrever:

Ao escrever publicações para o canal, consulta style/posts.md. Usa os marcadores de formatação permitidos pelo canal e evita caracteres especiais «perigosos». Termina com uma CTA que tenha uma etiqueta UTM segundo esta convenção: utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Antes, Claude escrevia publicações «no estilo geral de um site de marketing». Agora segue o seu formato, usa as suas UTM e não deixa transparecer que o texto foi escrito por IA.

Hábitos operacionais

Tabelas de acionadores. Quando diz uma frase específica, o agente sabe que ficheiros abrir e que ações executar. Eis um exemplo para uma equipa que planeia por semanas:

«Planeia a semana» → abre ops/monthly.md, cria YYYY-WNN.md na mesma pasta e distribui as tarefas de ops/backlog.md pelos dias adequados. «O que está na lista de pendências?» → lê ops/backlog.md e apresenta-o como lista. «Fecha a semana» → preenche a secção «Resumo da semana» no ficheiro da semana atual.

Com tabelas como estas, Claude deixa de ser um «assistente que escreve código» e passa a ser um «operador» que conhece a rotina da sua empresa. Todas as segundas-feiras digo «vamos planear a semana» e Claude abre os ficheiros certos, lê os objetivos mensais e sugere como dividir o trabalho.

Como verificar o CLAUDE.md com uma lista de verificação de 12 pontos em 5 minutos?#

1. Tamanho. É conciso, usando cerca de 200 linhas como referência para revisão, em vez de um limite de aprovação ou reprovação?
2. Nome. Chama-se exatamente CLAUDE.md, com letras maiúsculas, e não claude.md?
3. Localização. Está na raiz do projeto ou em ./.claude/CLAUDE.md?
4. Descrição do projeto. As primeiras 5 linhas deixam claro o que é o projeto e para quem se destina?
5. Ferramentas. As tecnologias estão explicitamente indicadas e sem palha?
6. Estrutura. Há um diagrama do repositório com explicações?
7. Encaminhamento. Existe uma tabela «pergunta → ficheiro» que indica onde encontrar respostas?
8. Princípios. Há uma secção com regras que começam por «nunca» e «sempre»?
9. Especificidade. Todas as regras são verificáveis? («Usa 2 espaços», não «escreve de forma bonita».)
10. Atualização automática. Há uma regra para «verificar o que acrescentar no final da sessão»?
11. Reflexão. Há uma regra para «registar o resumo da sessão em retrospectives/»?
12. Segurança. As proibições críticas (.env, rm -rf) também estão incluídas em .claude/settings.json?

Se tiver mais de cinco respostas «não», abra Claude e dê-lhe este prompt:

Lê o meu CLAUDE.md e compara-o com a lista de verificação abaixo. Para cada item, indica: sim / não / parcialmente, e o que corrigir concretamente.

Lista de verificação:

Suficientemente compacto para a tarefa; rever perto das 200 linhas sem tratar esse valor como limite rígido

Descrição do projeto nas primeiras 5 linhas

Ferramentas indicadas explicitamente

Diagrama da estrutura do repositório incluído

Tabela «Pergunta → ficheiro» incluída

Secção de princípios com regras incluída

Todas as regras são específicas e verificáveis

Regra «Atualizar no final da sessão» incluída

Regra «Refletir no final da sessão» incluída

Proibições críticas incluídas em .claude/settings.json

Sem duplicados da mesma regra em secções diferentes

Sem ligações sem destino para ficheiros que já não existem

Depois da auditoria, dá-me uma lista de alterações específicas que tornarão o ficheiro num documento vivo.

O que usar depois do CLAUDE.md: Plan Mode, Skills ou sub-agentes?#

O CLAUDE.md é a base. Quando estiver a funcionar, pode acrescentar três mecanismos do Claude Code que se reforçam mutuamente.

Plan Mode. Um modo em que Claude cria primeiro um plano de alterações, aguarda a sua aprovação e só depois começa a trabalhar. Ative-o com Shift+Tab ou com o comando /plan. Resolve o principal problema do vibe coding: «Pedi a Claude que corrigisse uma coisa e ele reescreveu metade do projeto.» Isso não acontecerá no Plan Mode - verá o plano antes de o agente tocar em quaisquer ficheiros.

Skills. Ficheiros .md separados na pasta .claude/skills/ com conhecimentos para um tipo específico de tarefa. Por exemplo, uma skill sobre «como escrever uma migração de base de dados» contém um procedimento específico, um modelo e exemplos. Esse conhecimento não está no CLAUDE.md porque é demasiado extenso. Mas, quando Claude encontra uma tarefa como «escreve uma migração», carrega a skill relevante e segue-a.

Sub-agentes. Quando uma tarefa precisa de muito contexto (por exemplo, rever uma funcionalidade grande), Claude pode iniciar um sub-agente separado, com o seu próprio contexto limpo. O sub-agente faz o trabalho e devolve o resultado sem sobrecarregar o contexto do chat principal.

Os três mecanismos usam o CLAUDE.md como ponto de entrada: leem-no no início do trabalho para compreender o contexto do projeto. Por isso, estas funcionalidades também funcionam mal sem um CLAUDE.md atualizado. Primeiro a base; depois as camadas adicionais.

Próximo passo. Crie um ficheiro CLAUDE.md na raiz do projeto, copie o modelo do início deste artigo e preencha os campos entre parênteses retos usando o prompt auxiliar. Depois, trabalhe com o ficheiro: transforme cada erro do agente numa nova linha. Ao fim de duas ou três semanas, o CLAUDE.md deixa de ser «um documento que escrevemos e esquecemos» e passa a ser algo que Claude consulta efetivamente em cada sessão.

Se quiser criar um enquadramento completo em torno do CLAUDE.md - uma pasta business/ para um segundo cérebro, uma pasta about-me/ para uma projeção digital de si, skills básicas e um Plan Mode configurado - use os passos e exemplos deste artigo. Guias Ailoot.

Continue com a Ailoot.