Como visualizar e reduzir sistematicamente a dívida técnica com Claude Code

“Queremos refatorar mas nunca temos tempo.” “Por onde começamos?” A dívida técnica se acumula silenciosamente. Com Claude Code, você pode expor, priorizar e quitar a dívida sistematicamente por uma fração do custo habitual.

1. Detectar code smells em toda a base de código

Comece com uma varredura completa.

claude -p "
Escaneie src/ em busca de code smells. Verifique:

- Funções com mais de 50 linhas
- Aninhamento profundo (4+ níveis)
- Lógica duplicada
- God Classes (responsabilidades sobrecarregadas)
- Números mágicos
- Exports não utilizados
- Uso do tipo any
- Comentários TODO / FIXME

Saída para docs/tech-debt/smells.md como:
| File | Line | Smell | Severity(1-5) | Suggested fix |
"

Um inventário ordenado por severidade se torna seu ponto de partida.

2. Medir a dívida de dependências

Bibliotecas desatualizadas e vulnerabilidades também são dívida.

claude -p "
Analise package.json junto com npm audit e npm outdated:

1. Bibliotecas que precisam de atualizações major
2. Vulnerabilidades conhecidas
3. Pacotes não mantidos
4. Duplicatas (ex.: moment + date-fns misturados)

Saída para docs/tech-debt/dependencies.md com versão atual, última versão, breaking changes, prioridade de atualização — em formato de tabela.
"

3. Priorizar com ICE Scores

Você não pode consertar tudo. Classifique por Impact × Confidence × Ease.

claude -p "
Usando docs/tech-debt/smells.md e dependencies.md, pontue cada item:

- Impact (I): efeito no negócio/velocidade de dev (1-10)
- Confidence (C): certeza do impacto (1-10)
- Ease (E): esforço para consertar (1-10)

Ordene por Score = I × C × E decrescente.
Saída como docs/tech-debt/backlog.md.
Inclua pessoa-dias estimados para os top 10.
"

Pontuações numéricas tornam o argumento claro para product managers.

4. Gerar automaticamente pequenos PRs de pagamento

Quebre o pagamento em PRs revisáveis.

claude -p "
Para o item nº 1 em docs/tech-debt/backlog.md:

1. Crie a branch: refactor/tech-debt-001
2. Conserte apenas esse problema (sem mudança de comportamento)
3. Verifique que os testes existentes passam
4. Divida em vários commits se for grande
5. Execute gh pr create

O corpo do PR deve incluir:
- Qual era a dívida
- Por que pagá-la agora
- Pontuação ICE
- Raio de impacto em outro código
"

5. Identificar hot spots sem testes

Áreas com baixa cobertura se tornam dívida futura.

npm test -- --coverage --coverageReporters=json

claude -p "
Analise coverage/coverage-summary.json:

- Arquivos com cobertura abaixo de 50%
- Dentre eles, quais contêm lógica de negócio
- Prioridade para adicionar testes

Saída para docs/tech-debt/coverage-gaps.md.
Proponha casos de teste para os 3 arquivos principais.
"

Combine com Geração automática de testes para um impacto cumulativo.

6. Tornar o pagamento visível com relatórios semanais

Sem visibilidade, as equipes desistem.

claude -p "
Relate sobre o pagamento de dívida técnica da última semana:

- Itens resolvidos (verifique docs/tech-debt/backlog.md)
- Nova dívida descoberta
- Itens de severidade 5 ainda abertos
- Progresso das atualizações de dependências

Saída para docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md.
Ajustado para uma leitura de 5 minutos em standup.
"

Agende com cron nas manhãs de segunda-feira para institucionalizar o pagamento.

7. Parar nova dívida na porta

O pagamento é inútil se a entrada continuar. Codifique regras em CLAUDE.md.

## Regras para prevenir nova dívida técnica

### Proibido
- Novos valores tipados como any (use // @ts-expect-error com razão se inevitável)
- Lógica paliativa sem um TODO
- Lógica de negócio sem testes

### Checklist de PR
- [ ] Cobertura do novo código ≥ 80%
- [ ] Zero erros de ESLint
- [ ] Adições de dependências justificadas no PR

### Exceções aceitáveis
- Hotfixes (com ticket de acompanhamento)
- Código POC (deve ser reescrito antes da produção)

Force via pre-commit hooks. Veja o Guia de Hooks.

Anti-padrões

❌ Um PR gigante de refatoração

PRs que “consertam tudo” são irrevisáveis. Um smell = um PR.

❌ Misturar mudanças de comportamento

Nunca combine trabalho de feature com refatoração no mesmo PR. A carga de revisão dobra.

❌ Refatorar sem testes

Se a cobertura for baixa, escreva testes primeiro, depois refatore. Sem rede de segurança, novos bugs aparecem.

Conclusão

• Use Claude Code para expor smells, dívida de dependências e lacunas de cobertura
• Quantifique a prioridade com ICE scoring
• Quebre o pagamento em PRs pequenos
• Publique relatórios semanais de progresso
• Bloqueie nova dívida via regras em CLAUDE.md
• Um smell = um PR

Dívida técnica não é algo para consertar “algum dia”. É algo para quitar um pouco toda semana. Claude Code reduz drasticamente o custo dessa cadência.

Relacionado: Automação de refatoração / Modernização de código legado / Checklist de code review

Documentação oficial: Anthropic Claude Code