Reduzir dívida técnica com Claude Code: guia seguro para equipes

Toda equipe diz que quer reduzir dívida técnica. Depois o sprint enche de features, any se espalha, dependências envelhecem, a CI falha de vez em quando e TODOs viram arquitetura permanente.

Claude Code não torna refatoração automática livre de risco. O valor prático é outro: ele ajuda a inventariar dívida, anexar evidência, priorizar e dividir o pagamento em PRs pequenos e revisáveis. Isso transforma uma limpeza perigosa em um hábito de engenharia.

Este guia cobre inventário de code smells, dívida de dependências, flaky tests (testes instáveis), lógica duplicada, TODOs perigosos, priorização com ICE/RICE, estratégia de PR pequeno e governança. Como base oficial, veja Common workflows, Memory e Settings. No ClaudeCodeLab, complemente com estratégias de teste, boas práticas de CLAUDE.md e o guia de approval e sandbox.

Transforme dívida em ciclo de pagamento

O erro comum é tratar dívida como uma grande limpeza. A branch cresce, o review fica difícil e ninguém consegue garantir que o comportamento não mudou.

Use um ciclo curto.

flowchart LR
  A["Inventário"] --> B["Evidência"]
  B --> C["Score ICE/RICE"]
  C --> D["PRs pequenos"]
  D --> E["Testes e review"]
  E --> F["Atualizar registro"]
  F --> A

Inventário não é sensação. Colete caminhos de arquivo, linhas, logs de CI, pacotes obsoletos, uso de any, arquivos grandes, lógica duplicada e comentários TODO/FIXME.

Abordagem	Melhor para	Risco	Como Claude Code ajuda
Refatoração grande	Migrações com limites claros	Diff grande demais para review	Pesquisa e plano de migração
PRs pequenos de dívida	Manutenção contínua	Impacto parece invisível	Registro, score e checklist
Sprint de dependências	Segurança e pacotes EOL	Breaking changes escondidos	Resumo de changelog e plano de teste
Limpeza de flaky tests	CI perdeu confiança	Retry esconde bug real	Classificação e reprodução

Caso 1: inventariar code smells

Code smell nem sempre é bug. É um sinal de que mudanças futuras ficarão mais difíceis: funções gigantes, classes com responsabilidades demais, validação duplicada, números mágicos ou escapes do sistema de tipos.

Peça primeiro inspeção, não edição.

claude -p "
Inspecione src/ e tests/ em busca de dívida técnica. Ainda não edite arquivos.

Procure:
- Funções com mais de 80 linhas
- Arquivos com mais de 300 linhas
- Aninhamento com mais de 4 níveis
- Validação, datas ou permissões duplicadas
- TypeScript any, as any e @ts-ignore
- Comentários TODO / FIXME / HACK
- Branches sem testes ou testes que só verificam renderização

Retorne uma tabela Markdown que eu possa colar em docs/tech-debt/register.md.
Colunas: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

A frase “ainda não edite arquivos” evita mudanças especulativas. Deixe Claude Code investigar e classificar; a equipe escolhe a primeira dívida a pagar.

Caso 2: encontrar dívida de dependências

Bibliotecas obsoletas, pacotes sem manutenção, vulnerabilidades e duplicação de libs também são dívida. A contagem do npm audit não basta: avisos ruidosos podem esconder um pacote central perto do fim de vida.

claude -p "
Com package.json, lockfile, npm outdated e npm audit, classifique a dívida de dependências.

Categorias:
1. Correção de segurança necessária
2. Major update com provável breaking change
3. Sem manutenção ou substituição recomendada
4. Bibliotecas duplicadas para a mesma função
5. Seguro adiar

Para cada item, liste área de impacto, changelog a ler primeiro, testes necessários e o menor PR seguro.
Separe mudanças automatizáveis de mudanças que exigem review humano.
"

Dependência não é segura só porque os testes passaram uma vez. Datas, auth, criptografia, roteamento, build tools e test runners merecem branches isoladas e notas de rollback.

Caso 3: pagar flaky tests e lógica duplicada

Flaky tests destroem confiança. Quando a equipe pensa “é só rodar a CI de novo”, a suíte deixa de ser rede de segurança.

claude -p "
Leia os últimos 20 logs de falha da CI e classifique possíveis flaky tests.

Classifique por:
- Dependência de horário, timezone ou dados aleatórios
- Dependência de rede ou API externa
- Estado compartilhado vazando entre testes
- Espera assíncrona instável
- Provável bug de produto que não deve ser tratado como flaky

Para cada candidato, forneça comando de reprodução, correção mínima e assertion a adicionar.
"

Para lógica duplicada, o primeiro PR deve ser simples. Se permissões estão copiadas em quatro arquivos, extraia um helper puro e trave o comportamento com testes. Troque cada call site em PRs seguintes.

Scanner copiável

Claude Code ajuda na análise, mas marcadores mecânicos devem ser repetíveis. Salve como scripts/debt-scan.mjs e execute node scripts/debt-scan.mjs src.

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

Ele não entende arquitetura nem acha toda duplicação. Mesmo assim, dá uma base semanal estável para TODO, FIXME, any e arquivos grandes.

Template de registro de dívida

Antes de abrir issues, consolide os achados em um registro.

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE é rápido para ordenar. RICE é melhor quando alcance e esforço precisam ficar explícitos. Nenhum deles é verdade absoluta; são ferramentas de conversa.

Prompt para plano de refatoração segura

Depois de escolher o item, peça um plano antes de editar.

claude -p "
Crie um plano seguro para pagar TD-001. Ainda não edite arquivos.

Escopo:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Restrições:
- Não alterar comportamento de API externa
- Inspecionar testes existentes primeiro
- Se faltar cobertura de comportamento, adicionar characterization tests antes da refatoração
- Mirar um PR com menos de 300 linhas alteradas
- Incluir riscos, rollback e pontos de atenção para reviewers

Saída:
1. Resumo do comportamento atual
2. Non-goals explícitos
3. Plano do primeiro PR
4. Comandos de teste
5. Texto de pedido de review
"

Non-goals evitam crescimento de escopo. Claude Code pode ajudar além do necessário se o limite do PR não estiver claro.

Checklist de PR de refactor

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

Use no corpo do PR que Claude Code redigir. Isso transforma “é só refactor” em evidência revisável.

Armadilhas concretas

Confiar demais na automação Tipos passando não bastam. Autorização, cobrança, datas, async e migrações exigem testes de caracterização e review humano.

Apagar todos os TODOs Alguns TODOs bloqueiam release, outros são notas. Priorize remove before release, bypass auth, temporary token e FIXME.

Agrupar atualizações de dependências Dez major updates em um PR dificultam isolar falhas. Separe build tools, UI, auth e test runners.

Usar score como política ICE/RICE deve carregar evidência: caminhos, runs de CI, incidentes e suposições de esforço.

Não registrar a memória do time Regras como “código de permissão exige approval” e “refactors abaixo de 300 linhas” devem ficar em CLAUDE.md ou settings. Memory e Settings reduzem prompts repetidos.

Governança para equipes

Uma cadência prática é review de dívida de 30 minutos por semana:

1. Ler o scanner e o inventário do Claude Code.
2. Atualizar ICE/RICE só dos 10 primeiros.
3. Escolher um PR de pagamento para o próximo sprint.
4. Priorizar flaky tests e dependências de segurança.
5. Registrar o que ficou mais fácil após o PR.

ClaudeCodeLab ajuda a transformar isso em sistema: registro de dívida, checklists de PR, settings e regras iniciais de CLAUDE.md. Para adaptar ao seu repositório e cultura de review, veja treinamento, templates e consultoria Claude Code.

Resumo

Reduzir dívida técnica com Claude Code de forma segura não é pedir “refatore tudo”. É coletar evidência, pontuar o trabalho e pagar uma dívida pequena por PR. Code smells, dependências, flaky tests, lógica duplicada e TODOs perigosos cabem no mesmo ciclo.

Ao testar este fluxo em projetos pequenos do Masa, o maior ganho foi separar dívida urgente de dívida que só precisava ser registrada. Dividir limpeza de any e remoção de TODOs antigos em PRs pequenos reduziu risco sem aumentar muito o review. Major updates de dependências foram mais pesados que o esperado; por isso foi mais seguro adicionar testes e notas de release antes de pedir ao Claude Code para rascunhar as mudanças.