Como Automatizar Refatoração com o Claude Code

Por Que Refatorar com o Claude Code?

Todo mundo sabe que refatoração é importante, mas fazer manualmente é tedioso e frequentemente fica para depois. O Claude Code entende todo o seu projeto e pode executar refatoração de forma autônoma em múltiplos arquivos.

Padrão 1: Melhorar a Segurança de Tipos

Eliminando Tipos any

> Pesquise no projeto todos os tipos any e substitua-os por tipos adequados.
> Após as alterações, verifique que npx tsc --noEmit passa.

Veja como o Claude Code procede:

1. Pesquisa arquivos contendo tipos any
2. Infere tipos apropriados a partir do código ao redor
3. Cria arquivos de definição de tipos se necessário
4. Executa o verificador de tipos para confirmar que tudo compila

Antes e Depois

// Antes
function processData(data: any): any {
  return data.items.map((item: any) => item.name);
}

// Depois
interface DataPayload {
  items: Array<{ name: string; id: number }>;
}

function processData(data: DataPayload): string[] {
  return data.items.map((item) => item.name);
}

Padrão 2: Dividir Funções e Clarificar Responsabilidades

Quebrar funções grandes demais é algo que o Claude Code faz excepcionalmente bem.

> A função createOrder em src/services/orderService.ts tem mais de 200 linhas.
> Divida-a em funções menores seguindo o princípio da responsabilidade única.
> Certifique-se de que os testes existentes continuem passando.

Prompt para Divisão

> Divida a função usando estas diretrizes:
> - Cada função deve ter no máximo 30 linhas
> - Separe validação, lógica de negócios e persistência
> - Adicione comentários JSDoc a cada função
> - Divida os testes para corresponder aos novos limites das funções

Padrão 3: Padronizar Tratamento de Erros

Unifique padrões de tratamento de erros em todo o projeto.

> Padronize o tratamento de erros em todo o projeto:
> - Use uma classe de erro personalizada (AppError)
> - Defina códigos de erro como constantes
> - Sempre inclua logging nos blocos try-catch

Veja um exemplo do que o Claude Code gera:

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly statusCode: number = 500,
    public readonly cause?: Error
  ) {
    super(message);
    this.name = 'AppError';
  }
}

// Constantes de códigos de erro
export const ErrorCodes = {
  USER_NOT_FOUND: 'USER_NOT_FOUND',
  INVALID_INPUT: 'INVALID_INPUT',
  DB_CONNECTION_ERROR: 'DB_CONNECTION_ERROR',
} as const;

Padrão 4: Adicionar e Melhorar Testes

Adicione testes onde a cobertura está baixa.

# Use relatórios de cobertura para guiar as adições de testes
npx vitest run --coverage | claude -p "Identifique arquivos com baixa cobertura e adicione os casos de teste faltantes"

> Eleve a cobertura de testes para tudo em src/services/ para pelo menos 80%.
> Cubra não apenas os caminhos felizes, mas também casos extremos e cenários de erro.

Padrão 5: Padronizar Formatos de Resposta da API

> Padronize todas as respostas dos endpoints de API neste formato:
>
> Sucesso: { success: true, data: T }
> Falha: { success: false, error: { code: string, message: string } }
>
> Atualize o código do frontend para corresponder ao novo formato.

Dicas para Refatoração Segura

1. Verifique os Testes Primeiro

> Execute npm test primeiro e certifique-se de que todos os testes existentes passem.
> Se algum teste estiver falhando, reporte antes de fazer alterações.

2. Trabalhe Incrementalmente

Refatore módulo por módulo em vez de tudo de uma vez.

> Comece refatorando apenas src/services/userService.ts.
> Verifique que os testes passam após as alterações antes de prosseguir.

3. Revise o Diff

> Me mostre o git diff. Se for muito grande, resuma as alterações por arquivo.

4. Use um Branch Separado

git checkout -b refactor/error-handling
claude
> Inicie a refatoração do tratamento de erros...

Exemplo Real: Modernizando Código Legado

Veja como modernizar uma base de código mais antiga de forma incremental:

> Modernize este projeto com as seguintes alterações:
> 1. Substitua var por const/let
> 2. Converta funções com callback para async/await
> 3. Converta require para import
> 4. Verifique que os testes passam após cada alteração
> 5. Prossiga uma etapa por vez e reporte os resultados em cada fase

Conclusão

Com o Claude Code, refatorações que antes levavam dias podem ser feitas em horas. As chaves são: fornecer regras específicas, trabalhar incrementalmente e sempre validar com testes. Comece com um módulo pequeno e veja os resultados por si mesmo.