Boas práticas de CLAUDE.md: template prático para projetos reais

CLAUDE.md evita repetir a arquitetura, os comandos e as regras do projeto em toda sessão. Ele não é uma política de segurança nem um lugar para colar toda a documentação.

Regras de equipe devem ser curtas e verificáveis; preferências pessoais ficam locais; restrições fortes devem usar permissions e hooks. Este artigo mostra o que deve ficar no CLAUDE.md e o que deve ficar fora, em formato prático para iniciantes.

O objetivo é começar com um template copiável e permitir que a equipe revise sem transformar o arquivo em uma enciclopédia.

Core idea: CLAUDE.md is guidance, not enforcement

Regras de equipe devem ser curtas e verificáveis; preferências pessoais ficam locais; restrições fortes devem usar permissions e hooks. Pela documentação oficial, CLAUDE.md é orientação contextual, Auto memory guarda aprendizados locais, settings configuram o cliente e hooks executam comandos em eventos.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code lê CLAUDE.md e CLAUDE.local.md do diretório de trabalho para cima. Regras da raiz entram no início; regras aninhadas entram quando arquivos relacionados são lidos.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

Mantenha comandos de build, testes, limites de arquitetura, nomes, padrões proibidos e gates de revisão. Deixe fora secrets, logs longos, atas, planos únicos e pesquisas extensas.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

O template abaixo é curto para não pesar no contexto. Adapte ao projeto e mantenha cada regra verificável.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

Imports @path ajudam a organizar, mas não economizam tokens. Conteúdo importado também entra no contexto. Em projetos grandes, apague conteúdo velho e mova regras por caminho para .claude/rules/.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. Os casos mais úteis são onboarding, correção de bugs e produção de conteúdo com links internos consistentes. No onboarding, escreva primeiro o mapa do projeto e os comandos de verificação.
2. Em bugs, inclua comando de reprodução, local dos logs e teste mínimo.
3. Em conteúdo, coloque tom, links internos e quality gates no CLAUDE.md; notas longas ficam no Obsidian ou docs.

Failure cases and pitfalls

1. Falhas comuns são importar todo README, escrever regras vagas e confiar em CLAUDE.md para segurança. Mantenha apenas regras sempre necessárias.
2. Troque “deixe limpo” por comandos exatos e limites de arquivos.
3. Segurança forte exige permissions e PreToolUse hooks; CLAUDE.md sozinho não basta.

Team maintenance rule

Atualize CLAUDE.md quando um erro se repetir, um review repetir comentário, ou comando e limite de arquitetura mudarem.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

Para o fluxo completo, combine com Obsidian, otimização de tokens e a página de consultoria. O workflow completo combina com Obsidian, otimização de tokens e página de consultoria. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

Esta atualização segue as páginas oficiais memory, context window, settings e commands. Official references: memory, context window, settings, and commands.