🎯 Cases reais de Claude Code
3 cases focados em onde N4 dói mais: claude.md mal feito, refactor caro por skip do plan mode, e coordenação de worktrees paralelas. Cada um com diff antes/depois, custo evitado e padrão pra replicar.
⚠ Esses cases são técnicos. Se você ainda está no N3, salve pra depois. Aqui assumimos familiaridade com git, branches, PRs, testes e prompts complexos. Se algo não fizer sentido, volte pro 4.1.
1
CASE 1
📜 claude.md: a evolução em 4 atualizações reais
Cenário
Lucas é tech lead numa startup B2B SaaS de logística (TypeScript/Next.js + Supabase). Projeto tem 6 devs. Começou com Claude Code há 2 meses. Claude erra coisas básicas — usa enum diferente, ignora convenção de naming, gera teste com mock errado. Lucas atualiza claude.md 1x por semana.
❌ claude.md v1 (semana 1) — "tudo que eu acho importante"
# Projeto Logix
Sistema de gestão de fretes B2B.
## Stack
- Next.js 14 (App Router)
- TypeScript estrito
- Supabase (Postgres)
- Tailwind + shadcn/ui
- Vercel deploy
- Vitest
## Convenções
- Componentes em PascalCase
- Hooks em useXxx
- Pastas em kebab-case
- Imports absolutos com @/
- Estilo: 2 espaços, sem ponto-e-vírgula
- Commits: conventional commits
## Estrutura
- /app — App Router
- /components — shared
- /lib — utilitários
- /hooks — custom hooks
- /db — schemas e migrations
## Como rodar
npm install
npm run dev
## Testes
Vitest. Rodar com npm test.
## Deploy
Push pra main → Vercel deploy.
[mais 130 linhas com detalhes de cada módulo, exemplos de cada hook, lista de todas as tabelas do banco...]
Problemas:
- • 180 linhas — claude.md inflado dispara muitos tokens em toda sessão
- • Conteúdo MISTURA "informação universal" (stack) com "detalhes específicos de módulos"
- • Não diz NUNCA — só "convenções", como se fossem sugestões
- • Falta diretriz sobre tipos repetidos de erro do Claude (não fala de mocks, enums, formas de teste)
🟡 v2 (semana 2) — depois de 3 erros recorrentes
Claude usou Date.now() em 4 lugares diferentes (codebase usa useNow() hook custom). Mockou Supabase de jeitos diferentes em cada teste. Adicionou ponto-e-vírgula em 1 PR.
Lucas adicionou seção "Regras":
## Regras (NUNCA / SEMPRE)
- NUNCA usar Date.now() ou new Date(). SEMPRE useNow() de @/hooks/useNow
- NUNCA mockar Supabase manualmente. SEMPRE mockSupabase() de @/test/utils
- NUNCA adicionar ponto-e-vírgula. Prettier vai reclamar.
- NUNCA criar novo hook sem prefixo use*
- SEMPRE prefixar issue/PR com prefixo do módulo (FREIGHT-, AUTH-, etc.)
Resultado: melhor, mas claude.md já tem 200 linhas. E os 130 linhas de "detalhes de módulos" ainda estão lá inflando contexto.
🟡 v3 (semana 4) — extração via @ pra detalhes longos
Lucas percebe que 70% do claude.md é "info que Claude só precisa quando toca naquele módulo". Cria pasta /docs/claude/ e extrai detalhes:
~/logix/
├── claude.md # 95 linhas — só essencial
├── docs/claude/
│ ├── auth.md # detalhes do módulo de auth
│ ├── freight.md # detalhes do módulo de frete
│ ├── db-schema.md # schema completo do banco
│ ├── testing.md # padrões de teste detalhados
│ └── deploy.md # pipeline de deploy
## em claude.md, referências:
- Pra trabalhar em auth, leia @docs/claude/auth.md primeiro
- Pra mexer em frete, leia @docs/claude/freight.md
- Pra testes, padrão completo em @docs/claude/testing.md
Resultado: claude.md em 95 linhas. Claude lê @docs apenas quando entra no módulo correspondente. Tokens de baseline caíram 65%.
✅ v4 (semana 8) — a versão madura
Após 4 semanas de uso real, Lucas refinou. claude.md final tem 87 linhas. Estrutura que parou de mudar:
# Logix — Claude Code instructions
## Quem sou eu (e quem você tá lidando)
Time de 6 devs sêniors. Sem juniors. Não explique conceitos básicos.
Linguagem técnica direta, sem preâmbulo, sem "ótimo, vou agora...".
## Stack (resumo)
Next.js 14 App Router · TS estrito · Supabase · Tailwind+shadcn · Vitest · Vercel
Detalhes em @docs/claude/stack.md
## Regras NUNCA-SEMPRE (atualizadas conforme Claude erra)
- NUNCA Date.now()/new Date() — SEMPRE useNow() de @/hooks/useNow
- NUNCA mockar Supabase manual — SEMPRE mockSupabase() de @/test/utils
- NUNCA semicolon — Prettier reclama
- NUNCA criar arquivo >500 linhas — splita em sub-arquivos
- NUNCA `any` em TS — se precisar, comente o motivo na linha de cima
- NUNCA push direto em main
- SEMPRE prefixar PR (FREIGHT-, AUTH-, USERS-...)
- SEMPRE testar a função que você adicionou (e a que você alterou se mudou comportamento)
- SEMPRE rodar npm run typecheck antes de pedir review
## Mapa de módulos (leia quando entrar em cada um)
- Auth → @docs/claude/auth.md
- Frete (core) → @docs/claude/freight.md
- Faturamento → @docs/claude/billing.md
- Schema DB → @docs/claude/db-schema.md
- Testes → @docs/claude/testing.md
- Deploy → @docs/claude/deploy.md
## PRs
Template em @docs/claude/pr-template.md
Padrão obrigatório: contexto, plano executado, arquivos com motivo, evidência de teste, riscos.
## Workflow esperado
1. Sempre plan mode antes de mexer em >3 arquivos
2. Sempre subagente "tests" pra rodar e analisar testes
3. Sempre subagente "code-reviewer" antes de eu te chamar
4. Você NÃO mergeia. Eu mergeio.
## Quando errar
Se eu te dizer "atualize o claude.md pra não fazer X de novo", adicione a regra na seção NUNCA-SEMPRE — não na seção de stack ou módulos.
## Quem sou eu (e quem você tá lidando)
Time de 6 devs sêniors. Sem juniors. Não explique conceitos básicos.
Linguagem técnica direta, sem preâmbulo, sem "ótimo, vou agora...".
## Stack (resumo)
Next.js 14 App Router · TS estrito · Supabase · Tailwind+shadcn · Vitest · Vercel
Detalhes em @docs/claude/stack.md
## Regras NUNCA-SEMPRE (atualizadas conforme Claude erra)
- NUNCA Date.now()/new Date() — SEMPRE useNow() de @/hooks/useNow
- NUNCA mockar Supabase manual — SEMPRE mockSupabase() de @/test/utils
- NUNCA semicolon — Prettier reclama
- NUNCA criar arquivo >500 linhas — splita em sub-arquivos
- NUNCA `any` em TS — se precisar, comente o motivo na linha de cima
- NUNCA push direto em main
- SEMPRE prefixar PR (FREIGHT-, AUTH-, USERS-...)
- SEMPRE testar a função que você adicionou (e a que você alterou se mudou comportamento)
- SEMPRE rodar npm run typecheck antes de pedir review
## Mapa de módulos (leia quando entrar em cada um)
- Auth → @docs/claude/auth.md
- Frete (core) → @docs/claude/freight.md
- Faturamento → @docs/claude/billing.md
- Schema DB → @docs/claude/db-schema.md
- Testes → @docs/claude/testing.md
- Deploy → @docs/claude/deploy.md
## PRs
Template em @docs/claude/pr-template.md
Padrão obrigatório: contexto, plano executado, arquivos com motivo, evidência de teste, riscos.
## Workflow esperado
1. Sempre plan mode antes de mexer em >3 arquivos
2. Sempre subagente "tests" pra rodar e analisar testes
3. Sempre subagente "code-reviewer" antes de eu te chamar
4. Você NÃO mergeia. Eu mergeio.
## Quando errar
Se eu te dizer "atualize o claude.md pra não fazer X de novo", adicione a regra na seção NUNCA-SEMPRE — não na seção de stack ou módulos.
🧠 Como evoluir o seu
Princípio 1 — Separe essencial de detalhe: claude.md tem só o que Claude precisa em TODA conversa. Detalhe vai pra @docs/claude/.
Princípio 2 — Regras > convenções: "NUNCA / SEMPRE" é mais forte que "preferimos / costumamos".
Princípio 3 — Evolua reagindo a erro real: não tente prever. Deixe Claude errar. Adicione regra. Repetir.
Princípio 4 — Limite o tamanho: ≤100 linhas é o sweet spot. Acima disso, extraia.
Princípio 5 — Versionar em git: claude.md é código. Reviews de PR podem questionar regra.
📊 Métricas — antes vs depois v4
180→87
linhas no claude.md
-65%
tokens de baseline
4→0
erros recorrentes/semana
+30%
PRs aprovados 1ª revisão
2
CASE 2
📋 Pular Plan Mode custou um dia (e quase a feature)
Cenário
Patrícia (PR Pleno+, 3 anos) precisa implementar feature de "exportação de relatório customizável" — usuário escolhe colunas, filtros, formato (CSV/PDF/XLSX), salva como template. Issue diz "5 dias estimados". Patrícia está confiante: "é só mais uma feature de exportação".
❌ Sem plan mode — terça 9h
Patrícia abre Claude Code direto pelo terminal:
"Implementa a feature de exportação de relatório customizável da issue REPORT-142. Lê o ticket no Jira primeiro."
Claude lê, parte pra ação. Cria componente CustomReportExporter, mexe em 7 arquivos, adiciona endpoint, cria 3 hooks. Testes rodam, passam. PR aberto às 17h.
Revisão do tech lead, manhã seguinte:
"Patrícia, esse novo endpoint/api/reports/exportconflita com o/api/v2/reports/exportque já tava sendo desenhado no PR #882. Você não viu? Estamos migrando pra v2 esse mês. E o CustomReportExporter virou frankenstein — duplica lógica do ExportTrigger que já existe. Vamos ter que refazer."
Custo do erro: 1 dia perdido. Patrícia precisou rebase pesado em PR #882, reescrever de fato, refazer testes. Em vez de 5 dias estimados, gastou 7.
✅ Com plan mode — quarta retomada
Patrícia recomeça. Abre plan mode (Shift+Tab×2 + Opus Plan setting):
[Plan Mode • Opus] "Implementa REPORT-142 (exportação customizável). PRIMEIRO me apresenta plano DETALHADO: arquivos novos, arquivos a alterar, endpoints, conflitos com PRs abertos, riscos. Espera meu OK antes de tocar em qualquer arquivo."
Claude retorna 8 minutos depois:
PLANO REPORT-142
Conflitos detectados (auditei branches ativas):
- PR #882 (em progresso) está desenhando /api/v2/reports/export. SUA feature DEVE usar v2, não criar v1 paralela.
- Já existe ExportTrigger em /components/reports/ — extender em vez de criar CustomReportExporter.
- Tipo ExportFormat já existe em /types/reports/. Não criar enum novo.
Arquivos NOVOS (3):
- /components/reports/ReportColumnPicker.tsx
- /components/reports/ReportFilterBuilder.tsx
- /lib/reports/exportTemplate.ts (salvar/carregar template)
Arquivos a ALTERAR (4):
- /components/reports/ExportTrigger.tsx (adicionar entrada "customizado")
- /api/v2/reports/export/route.ts (adicionar params customizados — coordenar com PR #882)
- /db/migrations/2026_05_xx_report_templates.sql (nova tabela)
- /types/reports/index.ts (estender ExportFormat, adicionar ReportTemplate)
Riscos:
1. PR #882 ainda não mergeou — preciso esperar OU coordenar com Felipe (autor) pra trabalhar em branch encadeada
2. Migration nova requer aprovação do DBA antes de aplicar em staging
3. Performance: customização vai aceitar até X colunas e Y filtros? Sem limite pode gerar queries lentas
Esforço estimado: 4 dias com PR #882 já mergeado. 6 dias se precisar trabalhar em paralelo coordenando.
Aprova plano? Quer ajustar antes de eu começar?
Conflitos detectados (auditei branches ativas):
- PR #882 (em progresso) está desenhando /api/v2/reports/export. SUA feature DEVE usar v2, não criar v1 paralela.
- Já existe ExportTrigger em /components/reports/ — extender em vez de criar CustomReportExporter.
- Tipo ExportFormat já existe em /types/reports/. Não criar enum novo.
Arquivos NOVOS (3):
- /components/reports/ReportColumnPicker.tsx
- /components/reports/ReportFilterBuilder.tsx
- /lib/reports/exportTemplate.ts (salvar/carregar template)
Arquivos a ALTERAR (4):
- /components/reports/ExportTrigger.tsx (adicionar entrada "customizado")
- /api/v2/reports/export/route.ts (adicionar params customizados — coordenar com PR #882)
- /db/migrations/2026_05_xx_report_templates.sql (nova tabela)
- /types/reports/index.ts (estender ExportFormat, adicionar ReportTemplate)
Riscos:
1. PR #882 ainda não mergeou — preciso esperar OU coordenar com Felipe (autor) pra trabalhar em branch encadeada
2. Migration nova requer aprovação do DBA antes de aplicar em staging
3. Performance: customização vai aceitar até X colunas e Y filtros? Sem limite pode gerar queries lentas
Esforço estimado: 4 dias com PR #882 já mergeado. 6 dias se precisar trabalhar em paralelo coordenando.
Aprova plano? Quer ajustar antes de eu começar?
Patrícia coordena com Felipe (15 min de Slack), decide esperar PR #882 mergeer (vai ser amanhã), e começa quinta. Termina sábado 14h, sem dia perdido. Tech lead aprova PR sem refactor pesado.
🔀 Variações testadas pro plan mode
A — Feature pequena (1-2 arquivos): pula plan mode formal, mas pede "me diz quais arquivos vai tocar antes". Versão mini do plano.
B — Refactor amplo (10+ arquivos): plan mode em 2 fases — primeiro "mapeia tudo que precisa mudar", depois "agrupa em commits lógicos".
C — Bug ambíguo (causa raiz desconhecida): plan mode é "primeiro hipóteses de causa raiz, ranking de probabilidade, plano de investigação". Implementação só depois.
D — Migração de stack: plan mode obrigatório de 1 página inteira antes de qualquer linha. Custo de errar aqui é altíssimo.
⚠ Erros ao usar plan mode
- • "Já sei o que fazer, plan mode é overhead" — esse é o pensamento que custou 1 dia da Patrícia. Plan mode em features >3 arquivos é não-negociável.
- • Aprovar plano sem ler direito — se você não absorveu, peça pra Claude resumir em 5 bullets antes.
- • Não auditar conflitos com PRs abertos — peça explicitamente "audite branches ativas e me liste conflitos".
- • Esquecer Opus Plan setting — Opus planeja, Sonnet executa. Custo de Sonnet, qualidade de Opus.
📊 Custo evitado
8 min
tempo do plan mode
1 dia
custo da 1ª tentativa sem plan
~R$ 1.200
custo direto (1 dia de PR)
-50%
conflitos em PRs após adotar
3
CASE 3
🌳 3 worktrees em paralelo — coordenação real
Cenário
Igor, dev sênior. Segunda 9h. Lista do dia: (1) feature de "tags de cliente" (4-6h), (2) bug de timezone no relatório semanal (1-2h), (3) documentação da API pública v2 (2-3h). Total estimado 7-11h. Igor decide rodar paralelo.
✅ Setup das 3 worktrees
# Terminal 1
cd ~/work/saas-main
claude-worktree feature-customer-tags
# abre cd ~/work/.worktrees/feature-customer-tags
# Terminal 2 (outra aba)
cd ~/work/saas-main
claude-worktree bug-timezone-weekly-report
# Terminal 3 (outra aba)
cd ~/work/saas-main
claude-worktree docs-api-public-v2
cd ~/work/saas-main
claude-worktree feature-customer-tags
# abre cd ~/work/.worktrees/feature-customer-tags
# Terminal 2 (outra aba)
cd ~/work/saas-main
claude-worktree bug-timezone-weekly-report
# Terminal 3 (outra aba)
cd ~/work/saas-main
claude-worktree docs-api-public-v2
Cada uma em branch própria, working tree isolada, contexto separado. Claude em cada terminal não vê o que os outros estão fazendo (eles trabalham em arquivos provavelmente diferentes).
⏱ Como o dia rodou na prática
9h00: Igor inicia T1 (tags). Plan mode + Opus Plan. Espera plano enquanto monta T2.
9h08: T1 plano pronto. Igor aprova, T1 começa executar. Vai pra T2 (timezone bug).
9h12: T2: "reproduza o bug primeiro, sem mexer em código. Use o relatório de teste em /fixtures/reports/2026-05-12.json".
9h25: T2 reproduziu, identificou que função formatWeek() não estava usando TZ do usuário. Pergunta confirmação antes de fix.
9h26: Igor (sem sair de T2): "fix com timezone do usuário do contexto. Adiciona teste com 3 timezones diferentes". Volta pra T3.
9h28: T3: "documente endpoints da v2 da API em formato OpenAPI 3.1. Use os tipos existentes em @/types/api/v2/. Pra cada endpoint: descrição, exemplo de req, exemplo de res, códigos de erro possíveis".
9h45: T2 terminou (bug fixed + 3 testes passando). Igor lê código, aprova, /commit-push-pr.
10h12: T1 (tags) volta com pergunta: "essa coluna existing_tags da tabela customer é array de uuid ou JSONB? Verifiquei migration e está como text. Confirma antes de eu alterar". Igor verifica DB, confirma é JSONB. Atualiza T1.
11h30: T1 entrega. 8 arquivos alterados, 6 testes adicionados. Igor revisa em 20 min. Pequenos ajustes, /commit-push-pr.
12h00: T3 entrega doc completa OpenAPI. Igor revisa rápido, ajusta 2 exemplos confusos. PR aberto.
12h22: 3 PRs prontos. Almoço.
🧠 O que tornou paralelo funcional
1. Worktrees isoladas em git: nenhuma colisão de arquivo. Cada Claude tem seu próprio working tree.
2. /focus em cada terminal: Igor não ficava lendo passo a passo. Só intervinha em perguntas.
3. Claude pergunta antes de mexer em coisa ambígua: regra do claude.md ("se schema parecer inconsistente, pergunte antes"). Salvou T1.
4. Plan mode em T1 (a maior): as menores (T2 bug, T3 docs) não precisaram. Plan mode tem custo, use onde paga.
5. Slash /commit-push-pr salvou contexto: Igor não escreve commit message, não digita gh pr create. 1 comando.
⚠ Quando NÃO usar 3 worktrees
- • Mesma área do código: se T1 e T2 mexem nas mesmas pastas, conflito de merge é certo. Sequencial.
- • Você ainda baba cada uma: se não confia em /focus, paralelo vira caos. Domine 1 antes de subir.
- • Pra refactor amplo (1 grande): melhor 1 sessão concentrada que 3 com pedaços.
- • Sweet spot é 3-4: 5+ vira gerenciamento manual. Bori Cherny diz 5, mas ele é o criador. Comece em 3.
📊 Métricas do dia
3h22
tempo total
(9h → 12h22)
(9h → 12h22)
~9h
se sequencial
3 PRs
aprovados na mesma manhã
~45 min
de Igor envolvido
(resto Claude trabalha sozinho)
(resto Claude trabalha sozinho)
★
🧠 O padrão N4 dos 3 cases
- 1. claude.md evolui REAGINDO a erro, não previsão. Cada erro recorrente → 1 linha de NUNCA-SEMPRE.
- 2. Plan mode em features >3 arquivos é não-negociável. O custo de 8min de plan ≠ o custo de 1 dia de refactor.
- 3. Worktrees isoladas + /focus + slash commands customizados = você opera time de 3-4 sem virar babá.
- 4. Claude DEVE perguntar quando algo é ambíguo (schema inconsistente, contexto incerto). Coloca isso no claude.md.
- 5. Você NÃO mergeia. Claude entrega PR. Você revisa. Você mergeia. Regra explícita evita acidente.
🎓 Resumo do Módulo
✓
claude.md evolui v1 (inflado) → v4 (87 linhas focadas + @docs). -65% tokens baseline.
✓
Plan mode em features >3 arquivos. 8min de plan poupa 1 dia de refactor.
✓
3 worktrees paralelas = 9h sequencial em 3h22.
✓
Claude pergunta antes de mexer em coisa ambígua — regra do claude.md.
✓
Você revisa e mergeia — Claude entrega PR.
Próximo Módulo:
4.5 — Walkthrough: bug report sexta 23h ao PR mergeado segunda 8h, sem queimar fim de semana.