Verificando acesso...

MÓDULO 4.5 · WALKTHROUGH · ~50 min

🎬 Bug report sexta 23h12 → PR mergeado segunda 8h (sem queimar o fim de semana)

Mariana, plantonista do mês, recebe alerta de um cliente enterprise às 23h12 de sexta. Você acompanha as 4 horas de trabalho dela ao longo do sábado — uso real de plan mode, subagentes especializados, loop de verificação e a coordenação com CTO via PR — e como ela passa o domingo inteiro com a família.

⚠ O ponto desse walkthrough: N4 não é "trabalhar mais" — é "trabalhar com sistema". Mariana resolveu em 4h o que sem Claude Code teria virado fim-de-semana inteiro. Você vê CADA decisão.

⚙

Setup — sexta-feira 23h12

Quem: Mariana, 34, dev sênior numa SaaS B2B de gestão financeira pra empresas médias. 5 anos de casa. É a plantonista do mês (escala rotativa).

O sinal: 23h12 de sexta, pager-duty toca:

"[P1] Cliente Acme Corp (ID 8842) reportou: carregamento do relatório mensal de fluxo de caixa retorna erro 500 desde quinta de manhã. Estão tentando fechar contabilidade — janela termina segunda. Contrato enterprise, conta de R$ 240k/ano."

Mariana abre o laptop: a tentação é resolver agora à noite, 23h. Mas ela conhece a regra do time: "problema P1 não-derruba-tudo na sexta após 22h → confirmar com cliente que estamos cientes, dormir, atacar sábado de manhã descansado."

Ela responde no portal: "Vista. Vamos investigar amanhã 8h e te atualizar até 12h. Janela contábil ainda tem 2 dias úteis." Fecha laptop, dorme.

1

Sábado 8h47 — abrindo o caso

Mariana abre laptop, café na mão. Cria worktree dedicada:

cd ~/work/saas-main claude-worktree hotfix-acme-report-500

Inicia Claude Code com plan mode + Opus Plan:

MARIANA →
[Plan Mode + Opus] Cliente Acme Corp reportou: GET /api/reports/monthly-cashflow retorna 500 desde quinta de manhã. Cliente ID 8842. Antes de qualquer mudança, faça: 1. Reproduza o erro localmente (use o staging dump em /db/dumps/staging-2026-05-09.sql). 2. Lê os logs do Sentry pros últimos 48h filtrando por endpoint e cliente. 3. Cruze com PRs mergeados de quarta+quinta — algum tocou nessa área? 4. Forme hipótese de causa raiz com nível de confiança (%). 5. Volta com plano de fix + plano de teste. NÃO altere código ainda.

9h05 — Claude volta com diagnóstico:

← CLAUDE
**Reprodução confirmada.** Erro 500 ao chamar GET /api/reports/monthly-cashflow?clientId=8842&month=2026-05 com dump de staging. **Logs Sentry (últimas 48h):** - 47 ocorrências do erro, todas após 09h32 de quinta - 100% concentradas em clientes "enterprise" (não afeta plano "growth" ou "starter") - Stack trace aponta pra função `aggregateCashflowByCategory()` em `/lib/reports/cashflow.ts:142` - Erro específico: "TypeError: Cannot read properties of undefined (reading 'subCategories')" **Cruzamento com PRs:** - PR #1224 mergeado quinta 09h12 — "Refactor: separar lógica de subcategorias de categorias" (autor: Felipe) - O PR tocou EXATAMENTE em `cashflow.ts`. Diff relevante linhas 138-156. - 1 teste foi removido nesse PR ("removed test outdated") — pode ser o que cobria esse caminho. **Hipótese de causa raiz (confiança: 92%):** Refactor de PR #1224 assumiu que TODA categoria tem `subCategories` populado. Para clientes enterprise com plano custom de contas, algumas categorias ficam sem subCategories (Postgres retorna null, não array vazio). O acesso direto `.subCategories.map(...)` quebra. **Confirmação rápida (8% de incerteza):** Pra eliminar a dúvida, sugiro: query direto na tabela `cashflow_categories` filtrando WHERE client_id=8842 AND sub_categories IS NULL. Se voltar resultado, confirma 100%. **Plano de fix proposto:** 1. Em `cashflow.ts:142`, adicionar default `?? []` em `category.subCategories ?? []` na linha que itera 2. Adicionar teste explícito: caso com categoria SEM subCategories deve retornar 0 no agregado, não 500 3. Adicionar teste que protege esse cenário em fixtures (cliente enterprise sample) 4. Verificar se há outros lugares no mesmo PR #1224 com mesma assumption **Plano de teste:** - Test unit: `aggregateCashflowByCategory` com input vazio em subCategories - Test integração: endpoint completo com cliente enterprise fixture sem sub-cat - Regressão: rodar suite completa de reports + smoke do endpoint **Risco residual:** - Se outros endpoints assumiram a mesma estrutura, podem ter o mesmo bug latente. Vou auditar antes de PR. Quer que eu execute? Ou prefere validar a hipótese primeiro?

✅ Mariana valida em 4 minutos

Roda o query sugerido. Volta com resultados — confirma: 23 categorias do Acme Corp sem subCategories. Hipótese 100% certa. Aprova o plano.

2

9h22 — fix + auditoria com subagentes

Mariana usa 2 subagentes em paralelo:

Subagente "fix": implementa o fix do plano.

"Aplique o fix do plano. Não toque em mais nada além do necessário. Cada arquivo alterado: comente em 1 linha o porquê da mudança."

Subagente "audit-similar": caça padrões similares no codebase.

"Audite o PR #1224 inteiro + funções relacionadas a relatório. Procure padrão similar: acesso direto a array assumindo que existe (sem optional chaining ou default). Liste arquivos, linhas, severidade (1-5). Não corrija — só liste."

9h41 — saídas dos subagentes:

Subagente fix: aplicou correção em cashflow.ts:142 + 1 lugar similar em cashflow.ts:198. Adicionou 3 testes (1 unitário, 2 integração). Total: 2 arquivos código + 1 arquivo teste alterados.

Subagente audit-similar: encontrou 2 lugares com mesmo padrão arriscado:

  • • /lib/reports/balance.ts:87 — severidade 3 (afeta só plano starter, baixa probabilidade)
  • • /lib/reports/forecast.ts:213 — severidade 4 (afeta enterprise, mesma classe de bug)

Mariana decide: fix imediato cobre só o reportado. Os 2 outros viram ticket separado pra próxima semana (não bloqueia Acme).

3

9h47 — loop de verificação

Antes de chamar review, Mariana ativa loop de verificação:

MARIANA →
Antes de chamar PR, valide tudo: 1. Rode `npm run test -- reports` — todos passando? 2. Rode `npm run typecheck` — sem erros? 3. Inicie servidor local, chame `GET /api/reports/monthly-cashflow?clientId=8842&month=2026-05`. Deve retornar 200 com dados. 4. Repita 3 com clientes growth e starter. Deve manter funcionando. 5. Tire screenshot da response (use a extensão de browser) — quero ver o JSON. 6. SE ALGO FALHAR, NÃO ME CHAME — analise, ajuste, repete até PASS.

10h18 — Claude volta:

← CLAUDE
Loop de verificação completo: ✓ npm run test -- reports: 47/47 passando ✓ npm run typecheck: 0 erros ✓ GET /api/reports/monthly-cashflow?clientId=8842 (enterprise): retornou 200, payload válido, 23 categorias sem sub-cat tratadas como [] (resultado correto) ✓ GET /api/reports/monthly-cashflow?clientId=1142 (growth): 200, regressão OK ✓ GET /api/reports/monthly-cashflow?clientId=552 (starter): 200, regressão OK ✓ Screenshot do payload em /screenshots/verify-acme-fix.png Tudo verde. Pronto pra PR. Devo abrir?
4

10h31 — PR via slash command

Mariana invoca slash command custom /hotfix-pr (versão pra hotfixes urgentes que pula etapas opcionais):

MARIANA →
/hotfix-pr Contexto: cliente Acme Corp P1, erro 500 em relatório mensal causado por PR #1224 (refactor que não tratou subCategories null em enterprise). Linkar issues: ACME-001 (ticket interno do plantão). Marcar autores: @felipe (autor do PR #1224, pra ele saber), @cto (review urgente). Tag: hotfix, priority/p1.

10h35 — PR aberto:

🚨 hotfix: trata subCategories nullable em cashflow report

Contexto

Cliente Acme Corp (enterprise) reportou erro 500 em GET /api/reports/monthly-cashflow desde quinta 09h32. Causa raiz: refactor do PR #1224 assumiu subCategories sempre populado, mas categorias custom de planos enterprise podem retornar null do banco.

Plano executado

  • cashflow.ts:142 e :198 → adicionado ?? [] no acesso a subCategories
  • 3 testes adicionados (1 unit, 2 integração) cobrindo categoria sem sub-cat
  • Fixture de cliente enterprise sample agora inclui caso sem sub-cat (proteção contra regressão)

Evidência de teste

  • npm run test -- reports: 47/47 ✓
  • npm run typecheck: 0 erros
  • Reprodução local com cliente 8842: 200 OK (antes 500)
  • Regressão com growth/starter: 200 OK
  • Screenshot do payload em /screenshots/verify-acme-fix.png

Riscos

  • Mudança defensiva, baixo risco. Aplica default vazio em vez de quebrar.
  • Audit identificou 2 lugares similares (balance.ts, forecast.ts) — abri ticket separado #ACME-002 pra próxima sprint, NÃO bloqueia este PR.

Deploy

Sugiro merge + deploy em janela suave (domingo > 21h). Cliente já comunicado que correção sai até segunda.

10h42 — Mariana ping pessoal no CTO via Slack: "PR de hotfix Acme: [link]. Pode revisar entre 21-22h domingo pra deploy noturno? Já testei tudo, baixo risco."

✓

10h47 — comunicar cliente e fechar laptop

Mariana manda atualização pro Acme no portal:

"Atualização: identificamos a causa raiz (assumption indevida sobre estrutura de dados em planos enterprise customizados) e implementamos a correção. Já validamos em ambiente de pré-produção que o problema está resolvido pro seu cenário. Deploy em produção: domingo 22h. Confirmaremos por aqui assim que estiver no ar. Janela contábil de vocês não é afetada — fechamento segue normalmente segunda."

11h00 — Mariana fecha o laptop. Total de tempo trabalhado: 2h13. Vai pra feira com a filha.

5

Domingo 21h47 — CTO revisa e aprova pelo celular

CTO abre o PR pelo celular. Lê o contexto, plano executado, evidência. Examina o diff (4 arquivos, mudanças cirúrgicas). Aprova com comentário: "Limpo. Mereceu fim de semana decente. Mergeio agora."

21h52 — CI roda. Verde. Merge. Pipeline de deploy automático dispara.

22h17 — Deploy completo. Smoke tests automáticos validam endpoint. Verde.

22h21 — Hook no projeto envia mensagem automática pro Slack #deploys: "🟢 PR #1287 merged + deployed. Endpoint /reports/monthly-cashflow: 200 OK em smoke."

✓

Segunda 8h02 — feedback do cliente

Mariana abre o portal antes do café:

"Mariana, bom dia. Acabei de rodar o relatório, voltou perfeito. Janela contábil mantida. Obrigado pela rapidez e pela comunicação clara durante o processo — você nos atualizou ANTES de eu cobrar, isso fez muita diferença. — Carlos, CFO Acme Corp"

Mariana arquiva o ticket. PR está mergeado. Bug resolvido. Domingo intocado. Cliente impressionado.

⏱

Timeline completa

Sexta 23h12 — alerta P1 do Acme Corp. Mariana confirma recebimento, comunica plano (sábado 8h investigar, atualização até 12h). Fecha laptop.
Sábado 8h47 — worktree criada, Claude Code aberto em plan mode.
9h05 — diagnóstico com 92% de confiança, hipótese de causa raiz, plano de fix completo.
9h09 — Mariana valida hipótese com 1 query. 100% confirmado.
9h22-9h41 — 2 subagentes em paralelo: fix + audit-similar.
9h47-10h18 — loop de verificação. Testes, typecheck, smoke local, screenshot.
10h31-10h35 — /hotfix-pr slash command. PR aberto com contexto completo.
10h47 — comunicação proativa ao cliente.
11h00 — laptop fechado. Total trabalhado: 2h13.
Domingo — Mariana descansa. CTO está livre.
Domingo 21h47-22h21 — CTO aprova pelo celular. CI verde. Deploy automático. Smoke OK.
Segunda 8h02 — feedback positivo do cliente. Janela contábil mantida.
★

Lições da jornada

1. Plantão sexta-noite = "confirmar e dormir"

Bug P1 fora de janela "derruba-tudo" não exige trabalho às 23h. Confirme recebimento, comunique plano, descanse. Decisão clara EVITA mau-julgamento por sono.

2. Plan mode em bug ambíguo = investigar com método

Mariana não pediu "fix the bug". Pediu "reproduza, leia logs, cruze com PRs, forme hipótese com %, plano de fix, plano de teste". 18 minutos depois ela tinha mapa completo.

3. Subagentes paralelos = audit e fix simultâneos

"audit-similar" descobriu 2 bugs latentes que Mariana NÃO planejava procurar. Viraram ticket separado, pré-emptivo. Cliente fica protegido sem PR inchado.

4. Loop de verificação tira você do "espero-CI"

Claude validou tudo antes do PR. Quando CTO abriu pelo celular, viu PR com evidência inline — não precisou esperar CI rodar. Aprovação em 5 minutos.

5. Comunicação proativa > correção rápida

Feedback do CFO Acme cita "comunicação ANTES de eu cobrar". 3 mensagens curtas (sexta, sábado, domingo) custaram 5 minutos no total — transformaram a percepção do incidente.

⚙

Adaptações pro seu contexto

🔥 P0 que derruba TUDO em produção

Mesma estrutura mas sem "dormir": Claude opera enquanto você comunica stakeholders. Plan mode mais rápido (5min, não 18). Verification loop é mais curto também.

🐛 Bug de "comportamento estranho" sem stack trace

Plan mode investiga: "use feature flag de log verbose, reproduza, junte logs, identifique linha". Sem stack o trabalho de hipótese é maior.

🚀 Feature de cliente premium urgente

Plan mode mais elaborado (incluir conflito com PRs em vôo). Verification loop com browser automation pra UX. Slash command de PR com formato "premium feature".

🔁 Refactor que afeta 20+ arquivos

Plan mode em 2 etapas: 1) mapeia tudo afetado 2) agrupa em commits lógicos. Subagente "consistency-check" depois de cada commit.

📊

Métricas reais

2h13
tempo total da Mariana
~6-8h
se sem Claude Code
100%
domingo da Mariana
fora do trabalho
+1
cliente encantado pela
comunicação proativa

🎓 Resumo do Módulo

✓
P1 sexta noite = confirmar + comunicar plano + dormir.
✓
Plan mode com investigação metodológica: reproduzir + logs + cruzar PRs + hipótese com %.
✓
Subagentes paralelos — fix e audit-similar simultaneamente.
✓
Loop de verificação OBRIGATÓRIO antes de PR.
✓
/hotfix-pr slash command — PR com evidência inline, CTO aprova pelo celular em 5min.
✓
3 comunicações curtas = cliente encantado pela transparência.

Próxima Trilha:

Trilha 5 — Arquiteto. Claude rodando 24/7, hook que salva de drop table acidental, routines, SDK pra construir produto.

← Voltar para Trilha Próxima Trilha →