O que escrever no CLAUDE.md: 7 templates prontos para colar e como criar proibições

“No CLAUDE.md basta colocar a stack, né?”

Eu também pensava assim no começo. Astro, TypeScript e Tailwind — pronto, escrevi. Satisfeito, pedi uma tarefa para o Claude Code e o resultado foi: ele repetiu o mesmo erro três vezes. Pulava os testes toda vez. Mexia num arquivo de configuração que eu não podia perder. Dizia “Corrigido!” enquanto o build nem passava.

Um CLAUDE.md que só lista a stack é como contratar alguém novo, dizer apenas “aqui a gente trabalha com Java” e jogar a pessoa direto na produção. Ela fica sabendo o que você usa, mas não recebe nenhuma pista sobre como deve agir.

Neste artigo eu deixo aqui, prontos para copiar, os 7 templates de CLAUDE.md que uso em projetos reais. Eles não explicam a stack: focam na “ordem de execução” e no “que nunca fazer”.

Pontos principais

• O que realmente funciona num CLAUDE.md não é a stack, e sim duas coisas: regras de trabalho (Working Rules) e proibições (Do Not).
• Preparei 7 templates por caso de uso: app solo, site de conteúdo, API, equipe, código legado, automação e monorepo. Basta escolher o mais parecido com o seu repositório e colar.
• Em todos eles, depois de colar é obrigatório acrescentar três linhas de Do Not próprias. É isso que freia os acidentes.
• “Quanto mais longo, melhor” é um mito. O CLAUDE.md não é um manual, é um arquivo operacional. Regras de ação curtas vencem.
• Se o Claude Code repetir a mesma falha três vezes, desconfie não da IA, mas da granularidade do seu CLAUDE.md.

Pense nesta página como um “catálogo de peças reais” que preenche o espaço entre o Guia de início ao Claude Code e o guia de boas práticas de CLAUDE.md. A teoria está nesses dois; aqui você leva os modelos físicos para casa.

O que um bom CLAUDE.md faz, discretamente

Um CLAUDE.md forte não escreve coisas geniais. Ele apenas elimina, de forma discreta, estes três “acidentes clássicos”:

• A pessoa edita o lugar certo, mas ignora uma convenção específica daquele projeto.
• A correção em si funciona, mas ela pula os testes e as verificações que deviam rodar.
• O escopo do que é “tarefa minha” fica vago, a exploração se espalha demais e o tempo derrete.

Para prevenir esses três, o mínimo que você quer ter é isto:

Item	Função	Eficácia
Stack e comandos principais	Alinhar pré-requisitos	Média
Papel de cada diretório	Reduzir o escopo de busca	Média
Regras específicas do projeto	Fazer respeitar as convenções	Alta
Ordem de trabalho (passos)	Evitar verificações esquecidas	Alta
Proibições (Do Not)	Frear acidentes	Altíssima

Os dois primeiros são bônus; quem realmente funciona são os três últimos. Em especial, no instante em que você escreve a ordem de trabalho e as proibições, o Claude Code fica calmo como se fosse outra pessoa. “Como prosseguir” e “o que não fazer” — no fim, é exatamente o mesmo manual que você entregaria a alguém recém-chegado.

Daqui para frente são modelos reais. Cole o conteúdo de cada bloco de código direto no seu CLAUDE.md.

1. Para app web de desenvolvimento solo

Se você toca sozinho um serviço pequeno, comece por aqui.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

O que mais funciona aqui não é a descrição da stack, e sim as últimas linhas de Working Rules e Do Not. “Não diga que terminou antes de conferir a largura mobile” e “não declare deploy bem-sucedido antes de abrir a URL pública”. Antes de colocar essas duas linhas, mais de uma vez me aconteceu de uma UI estar perfeita no monitor do PC e vazar inteira na tela do celular. Quando você prende a condição de sucesso em texto, esse tipo de coisa desaparece.

2. Para site de conteúdo com artigos, PDF e funil de produto

Este blog é exatamente assim. Sites com funil de receita ficam fracos demais com um template genérico de desenvolvimento.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

O ponto está na última linha de Do Not: deixar explícito “priorize a qualidade do funil de conversão acima de pageviews”. Sem isso, o Claude Code puxa para fazer “artigos que parecem dar audiência” e produz em massa páginas com CTA fraco justo onde importa. Só por colocar a meta de negócio com prioridade lá no topo, a direção do resultado mudou completamente.

3. Para API de backend

Numa API em que a integridade é vida, eu obrigo “ler antes de corrigir” e “verbalizar depois de corrigir”.

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

A linha de que mais gosto aqui é Summarize risk in plain English — “resuma o risco em linguagem simples”. Com ela, o Claude Code não para em “corrigido”: ele passa a verbalizar sozinho o alcance do impacto, tipo “esta mudança fica perto da fronteira da lógica de cobrança, então pode afetar o processamento mensal em lote”. O primeiro passo da revisão fica muito mais leve.

4. Para desenvolvimento em equipe

O que realmente atrapalha numa equipe não é falta de produtividade, é diff difícil de revisar. O template se antecipa a isso.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make (“não reverta mudanças que não foram você que fez”) parece bobo, mas funciona. A IA tenta “de quebra” deixar o código vizinho “bonitinho” e acaba desfazendo trechos que outra pessoa escreveu de propósito. Sobre como separar fronteiras de aprovação eu escrevi em detalhe no guia de configuração de aprovação e sandbox, então, se for operação em equipe, vale dar uma olhada lá também.

5. Para código legado

Em manutenção de código antigo, “não quebrar” vale mais do que “deixar bonito”.

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance (“prefira compatibilidade a elegância”). Em projetos legados, isso costuma ser o mais importante. Se você deixa solto, o Claude Code, com boa intenção, diz “vou reescrever no estilo mais moderno” — e no legado isso é a porta de entrada do acidente. Coloque Do not rewrite files only to match modern style nas proibições e tampe essa boa intenção.

6. Para scripts de automação e operação

Envio de e-mail, deploy, escrita em API externa — se você vai deixar a IA mexer em scripts com efeitos colaterais, este é o primeiro candidato.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing (“antes de executar, anote o que você pretende fazer”) é a válvula de segurança. Se você obriga a IA a declarar antes “vou enviar 120 e-mails para a produção agora”, a pessoa consegue dar o “espera aí”. Junto com Dry-run whenever the script supports it, garante sempre um respiro antes de operações irreversíveis.

7. Para monorepo

Se vários apps e pacotes compartilhados convivem no mesmo lugar, escreva primeiro “qual pacote é o responsável”.

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Só de escrever Ownership Rules, os acidentes de edição transversal caem bastante. O que era para ser uma correção pequena em apps/web/ acaba, sem ninguém perceber, mexendo num componente compartilhado em packages/ui/, arrasta o apps/admin/ junto e quebra tudo — esse é o acidente típico de monorepo. Faça a IA declarar o escopo logo no início e acrescente uma linha pedindo que ela “explique o impacto downstream” antes de tocar em código compartilhado.

Qual template escolher

Sete opções confundem, então deixo o critério de escolha em uma linha cada:

• UI ou produto no centro → template de app solo
• Tem funil de artigos, PDF e Gumroad → template de site de conteúdo
• Integridade é vida → template de API
• Custo de coordenação alto → template de equipe ou monorepo
• Custo de acidente alto → template legado ou automação

Você não precisa misturar os sete. Pelo contrário: misturar deixa o arquivo longo e reduz a eficácia. Use um como base e acrescente só as regras que mudam o comportamento no seu contexto. Esse é o caminho certo.

4 erros comuns no CLAUDE.md

Compartilho aqui, sem filtro, as minas que eu mesmo pisei.

Erro 1. Escrever longo como se fosse a wiki da empresa. “Quanto mais explicação, melhor” é um mito completo. O CLAUDE.md não é manual, é arquivo operacional. Em vez de longos textos de contexto, regras de ação curtas funcionam várias vezes mais. A gente esquece a premissa de que quem lê não é gente, é a IA.

Erro 2. Escrever só os comandos, sem os passos. Escrever apenas npm run test é muito mais fraco do que se mexer em billing, rode os testes sem falta. O comando só comunica que ele “existe”. O passo comunica até “quando usar”.

Erro 3. Não ter proibições. Esse é o mais desperdiçado. Não toque no .env, não diga deploy bem-sucedido sem conferir a URL pública, não faça force push. Uma única frase evita um acidente de uma noite inteira. A seção Do Not não é enfeite, é seguro.

Erro 4. Nunca atualizar. Se o Claude Code repete a mesma falha três vezes, em geral a culpa não é da IA: é a granularidade do CLAUDE.md que está faltando. Nessa hora, em vez de brigar, acrescente uma linha à regra. O CLAUDE.md não termina quando você escreve; é um arquivo que você cultiva.

Perguntas frequentes

P. Onde devo colocar o CLAUDE.md no projeto? R. Se você colocar um arquivo chamado CLAUDE.md na raiz do repositório, o Claude Code o carrega automaticamente. Em monorepo, dá para colocar também na raiz de cada pacote, e o mais próximo tem prioridade. Para colocar na prática e conferir se está funcionando, bastam estes dois comandos:

# Basta colocar na raiz do projeto. O Claude Code carrega na inicialização
cat > CLAUDE.md <<'EOF'
# Project
(cole o template acima aqui)
EOF

# Conferir se funciona: peça que ele repita as regras
claude -p "Liste três Do Not do CLAUDE.md deste projeto"

Para as regras detalhadas de localização, confira a documentação oficial do Claude Code.

P. Funciona direito se eu escrever em português? R. Funciona. Às vezes eu escrevo as proibições e os passos no meu idioma. Mas deixar o template em inglês ajuda a alinhar com pessoas de outros países e com exemplos da comunidade, então neste artigo usei inglês como base. Se o conteúdo for compreendido, qualquer idioma serve.

P. CLAUDE.md longo ou curto, qual é melhor? R. O curto. A referência é caber em uma tela. Quando começa a ficar longo, é sinal de que aquilo deve sair para outro documento. No CLAUDE.md, mantenha só as “regras que mudam o comportamento”.

P. Depois de colar o template, o que devo acrescentar primeiro? R. Três linhas de Do Not para o seu projeto. Uma linha para cada: “arquivo que dá problema se for mexido”, “operação que dá problema se for feita” e “mentira que dá problema se for dita” (ex.: relatar sucesso sem ter conferido). É o acréscimo com o maior retorno.

P. Qual a diferença entre CLAUDE.md e permissions (configuração de permissões)? R. O CLAUDE.md é “pedido e diretriz”; as permissions são uma “lista de permissões com força obrigatória”. Se você quer mesmo fazer as proibições serem respeitadas, use os dois juntos. Falei um pouco sobre como separar permissões no Guia de início ao Claude Code.

O resultado de testar na prática

Na época em que eu só tinha a stack escrita no CLAUDE.md, eu ficava nervoso a cada resultado do Claude Code. “Será que dessa vez ele roda os testes direito?”

Depois que acrescentei Working Rules e Do Not, essa ansiedade quase sumiu. Em especial, a linha “não declare deploy bem-sucedido antes de abrir a URL pública” mostra efeito claro em número. Antes dela, algumas vezes por mês acontecia de virem “deploy concluído” e na verdade ser um 404; depois de colocá-la, virou zero.

A conclusão é simples. O CLAUDE.md não é um arquivo para deixar a IA mais inteligente, é um arquivo para impedir que a IA cause acidentes. Acrescentar três linhas de proibição funciona, na sensação, dez vezes mais do que acrescentar a stack. Comece colando um template, o mais parecido com o seu repositório, e escreva só três linhas de Do Not.

Quem quiser se aprofundar na filosofia de design do CLAUDE.md, veja o guia de boas práticas de CLAUDE.md; para a conversa toda sobre o “andaime” que deixa a IA trabalhar com segurança, veja dizer “faça tudo” para a IA é receita de acidente. Se quiser ter os templates e exemplos de configuração reunidos à mão, ajudam o gratuito Claude Code Quick Reference Cheatsheet e, indo até hooks e permissions, o The Complete Claude Code Setup & Configuration Guide. Para ver todos os materiais, comece pela lista de materiais; para acertar até a padronização de equipe junto comigo, vá para a consultoria de adoção.