Modulo 3.1: CLAUDE.md | Claude Code 2026

📋 O que e CLAUDE.md

CLAUDE.md e o arquivo de memoria persistente do seu projeto. Diferente de outros arquivos que Claude le apenas quando solicitado, o CLAUDE.md e carregado automaticamente no inicio de cada sessao, fornecendo contexto imediato sobre arquitetura, convencoes e regras do projeto.

🧠 Como Funciona

Quando voce inicia uma sessao do Claude Code, o sistema automaticamente busca e le o arquivo CLAUDE.md na raiz do projeto. Este conteudo e injetado no contexto antes mesmo do seu primeiro prompt.

• Carregado automaticamente em cada sessao
• Nao precisa ser mencionado no prompt
• Consome tokens do seu contexto de 200K
• Pode ser complementado por arquivos em subpastas

📊 Impacto na Produtividade

60% menos reexplicacoes - Claude ja sabe as regras do projeto
40% menos erros - Convencoes de codigo sao seguidas automaticamente
3x mais rapido - Menos idas e vindas para alinhar contexto

🏗️ Estrutura Ideal

Um CLAUDE.md bem estruturado segue uma ordem logica de prioridade - informacoes mais criticas primeiro, detalhes opcionais depois. Isso garante que mesmo em situacoes de compaction, o essencial seja preservado.

Template Recomendado

# CLAUDE.md

## Visao Geral
Descricao em 2-3 frases do que e o projeto.

## Stack Tecnologico
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Deploy: Vercel + Railway

## Estrutura de Pastas
```
src/
├── components/    # Componentes React
├── hooks/         # Custom hooks
├── services/      # Chamadas API
├── utils/         # Funcoes utilitarias
└── types/         # TypeScript types
```

## Convencoes de Codigo
- Componentes: PascalCase (UserProfile.tsx)
- Hooks: camelCase com 'use' (useAuth.ts)
- Testes: mesmo nome + .test.ts

## Comandos Frequentes
- npm run dev    # Inicia desenvolvimento
- npm run test   # Roda testes
- npm run build  # Build producao

## Regras Importantes
- Sempre usar TypeScript strict
- Commits em portugues
- PR reviews obrigatorios

Secoes Obrigatorias

✓ Visao geral do projeto
✓ Stack tecnologico
✓ Estrutura de pastas
✓ Convencoes de codigo

Secoes Opcionais

○ Arquitetura detalhada
○ Decisoes de design (ADRs)
○ Links para documentacao
○ Changelog recente

⚡ Otimizacao de Tokens

Como CLAUDE.md e carregado em toda requisicao, cada token conta. Um arquivo de 5.000 tokens significa 5.000 tokens a menos para sua tarefa atual. A meta e maximo contexto com minimo de tokens.

🎯 Tecnicas de Compressao

1. Use listas em vez de paragrafos

RUIM - 45 tokens

Este projeto utiliza React para o frontend com TypeScript para tipagem estatica, Node.js no backend com Express como framework...

BOM - 12 tokens

Stack: React/TS, Node/Express, PostgreSQL

2. Tabelas para dados estruturados

| Pasta | Conteudo | |-------|----------| | /src | Codigo fonte | | /tests | Testes automatizados |

3. Referencias em vez de conteudo

Em vez de copiar documentacao, use: "Ver docs/API.md para endpoints"

💡 Regra de Ouro

Mantenha CLAUDE.md abaixo de 2.000 tokens (aproximadamente 500-700 palavras). Use /context para verificar quanto seu arquivo esta consumindo.

📁 Hierarquia de Configuracoes

Em projetos grandes, voce pode ter multiplos arquivos CLAUDE.md em diferentes niveis da arvore de diretorios. Arquivos em subpastas complementam ou sobrescrevem o arquivo raiz.

Exemplo de Hierarquia

projeto/
├── CLAUDE.md              # Contexto global do projeto
├── frontend/
│   └── CLAUDE.md          # Regras especificas de React
├── backend/
│   └── CLAUDE.md          # Regras especificas de Node
└── mobile/
    └── CLAUDE.md          # Regras especificas de React Native

🔄 Regras de Merge

1. Claude le primeiro o CLAUDE.md da raiz
2. Depois le CLAUDE.md do diretorio atual (se existir)
3. Informacoes do arquivo mais proximo tem prioridade
4. Use para isolar contexto de equipes ou modulos

⚠️ Cuidado

Multiplos CLAUDE.md aumentam o consumo de tokens. Use com moderacao e apenas quando contextos muito diferentes justificarem a separacao.

🔄 Manutencao e Versionamento

Um CLAUDE.md desatualizado pode ser pior que nenhum - Claude tomara decisoes baseadas em informacoes obsoletas. Implemente processos para manter o arquivo sincronizado com a evolucao do projeto.

Revisao em Pull Requests

Adicione ao checklist de PR

Sempre que mudar arquitetura, adicionar dependencia ou criar convencao nova, inclua atualizacao do CLAUDE.md no mesmo PR.

Git Hook Pre-commit

Automacao leve

# .husky/pre-commit
if git diff --cached --name-only | grep -E "^(src/|package.json)"; then
echo "Lembre de atualizar CLAUDE.md se necessario"
fi

Revisao Mensal

Calendario recorrente

Agende uma revisao mensal do CLAUDE.md junto com outras housekeeping tasks. Remova informacoes obsoletas e adicione novos padroes estabelecidos.

💡 Dica Pro

Adicione um campo "Ultima atualizacao: YYYY-MM-DD" no final do CLAUDE.md. Isso ajuda a identificar quando o arquivo pode estar desatualizado.

💼 Exemplos Empresariais

Veja exemplos reais de CLAUDE.md usados em diferentes tipos de projetos. Adapte o que fizer sentido para sua realidade.

Projeto SaaS B2B

# CLAUDE.md - SaaS Dashboard

## Sobre
Dashboard multi-tenant para gestao empresarial.

## Stack
Frontend: Next.js 14, Tailwind, Zustand
Backend: tRPC, Prisma, PostgreSQL
Auth: NextAuth + RBAC customizado

## Regras de Negocio Criticas
- Tenant isolation obrigatoria em TODAS queries
- PII deve ser criptografada (ver utils/crypto)
- Audit log para acoes destrutivas

## Padroes
- Server Components por padrao
- Client Components apenas quando necessario interatividade
- Todas APIs tipadas via tRPC

Atualizado: 2026-01-15

Biblioteca Open Source

# CLAUDE.md - UI Components Library

## Sobre
Biblioteca de componentes React acessiveis.

## Requisitos
- WCAG 2.1 AA compliance obrigatorio
- Suporte SSR (Next.js, Remix)
- Bundle size < 5kb per component

## Estrutura
/src/components/[Name]/
  ├── index.ts       # Export publico
  ├── [Name].tsx     # Implementacao
  ├── [Name].test.tsx
  └── [Name].stories.tsx

## Antes de PR
- npm run test (100% coverage)
- npm run a11y (sem violacoes)
- npm run build (sem erros TS)

Atualizado: 2026-01-20

Gerando seu CLAUDE.md

Use o comando /init para Claude analisar seu projeto e gerar um CLAUDE.md inicial. Depois, refine manualmente.

$ claude
> /init
# Claude analisa a estrutura e gera CLAUDE.md

📋 Resumo do Modulo

✓

CLAUDE.md e memoria persistente - carregado automaticamente em cada sessao

✓

Estrutura importa - informacoes criticas primeiro, detalhes depois

✓

Otimize tokens - mantenha abaixo de 2.000 tokens (~700 palavras)

✓

Use hierarquia - CLAUDE.md em subpastas para contextos especificos

✓

Mantenha atualizado - revise em PRs e mensalmente

Proximo Modulo:

3.2 - Skills: Criando Fluxos Sob Demanda - comandos customizados para automatizar tarefas

← Voltar para Trilha Proximo Modulo →