7 templates de CLAUDE.md para Claude Code que você pode copiar para projetos reais

Muitos artigos sobre CLAUDE.md param em “descreva sua stack”. Isso não está errado, mas não basta quando Claude Code começa a mexer em trabalho real.

A pergunta útil não é “preciso de um CLAUDE.md?” A pergunta útil é: o que deve estar nele para que Claude Code pare de repetir os mesmos erros neste repositório?

Este guia cobre esse espaço entre o guia para iniciantes e CLAUDE.md Best Practices com sete modelos copiáveis.

Caminho curto:

1. Deixe o Claude Code Quick Reference Cheatsheet por perto.
2. Copie o template mais próximo do seu repo.
3. Adicione primeiro três regras de Do Not.
4. Se quiser mais exemplos de templates, hooks e permissions, siga para The Complete Claude Code Setup & Configuration Guide.
5. Se quiser padronizar isso para uma equipe, use a consultation page.

O que um bom CLAUDE.md faz de verdade

Ele deve reduzir três falhas:

• Claude Code edita a área certa, mas quebra a convenção local
• resolve a tarefa, mas pula a verificação importante
• explora arquivos demais porque os limites do repo não estão claros

Por isso, normalmente ele inclui:

• stack e comandos
• mapa de diretórios
• regras específicas do projeto
• ordem recomendada de trabalho
• proibições

Os dois últimos itens costumam mudar o comportamento mais do que uma longa descrição técnica.

Template 1: app web solo

# 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 ponto mais importante aqui não é a stack. É transformar validação mobile e checagem da URL pública em condição de sucesso.

Outras bases úteis

Você pode aplicar a mesma lógica para:

• um site de conteúdo com PDF gratuito, Gumroad e consulta
• uma API backend com validação forte
• um repositório de equipe com patch fácil de revisar
• um código legado em que compatibilidade importa mais que elegância
• um repositório de automação com efeitos colaterais
• um monorepo com fronteiras claras entre pacotes

Em todos esses casos, as regras mais valiosas costumam ser:

• fazer a menor mudança segura
• obrigar a verificação certa
• registrar o que não deve ser feito
• pedir aprovação para deploy, secrets e escrita externa

Falhas para evitar

• transformar CLAUDE.md em wiki da empresa
• listar comandos sem workflow
• esquecer regras de proibição
• nunca atualizar o arquivo

Se Claude Code repete o mesmo erro várias vezes, normalmente o arquivo está vago demais.

Qual template escolher

• produto ou UI: template solo
• artigos multilíngues, PDF e Gumroad: template de conteúdo
• integridade de dados e validação: template de API
• coordenação e limites: template de equipe ou monorepo
• custo alto de erro: template legacy ou automação

Você não precisa juntar os sete. Comece com um e adicione só as regras que realmente mudam o comportamento.

Próximo passo

1. Copie um template para CLAUDE.md
2. Acrescente três regras de Do Not
3. Defina a verificação exata que significa “concluído”

Para uma referência diária rápida, use primeiro o Claude Code Quick Reference Cheatsheet. Para exemplos mais completos de CLAUDE.md, setup, hooks, permissions e workflow, siga para The Complete Claude Code Setup & Configuration Guide. Se precisar transformar isso em prática de equipe, use a consultation page.