Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Refatorização e Melhoria de Código Existente

Aula 6 de 20 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Transformar Código Legado em Código Moderno
  2. Refatorização Estrutural
  3. Modernização do Código
  4. Melhoria da Qualidade
  5. Refatorização Baseada em Padrões
  6. Verificar a Refatorização
  7. Pontos-chave

Transformar Código Legado em Código Moderno

A refatorização é uma das tarefas mais demoradas no desenvolvimento e, raramente, a mais recompensada: ninguém o felicita por dividir um ficheiro de 800 linhas. É exatamente por isso que ela se acumula, sprint após sprint, até se tornar a verdadeira causa da sua lentidão. O Codex reduz horas de trabalho manual a minutos, preservando o comportamento existente — a única coisa que realmente importa numa refatorização.

Refatorização Estrutural

O caso mais comum é o ficheiro «catch-all» que ninguém ousa tocar porque é importado em toda a parte.

"Refactor src/utils/helpers.ts: this file is 800 lines long. 
Split it into thematic modules in src/utils/ (string.ts, 
date.ts, validation.ts, formatting.ts). Update all imports 
across the project."

O Codex lida excecionalmente bem com este tipo de tarefas: identifica as funções, agrupa-as por tema, cria os novos ficheiros e, em seguida, atualiza todas as importações no projeto. Esse último passo é geralmente o que desencoraja a refatorização manual — quarenta ficheiros para corrigir, uma importação esquecida, e a compilação falha no pior momento possível. E o resultado é objetivamente verificável: se os testes passavam antes e continuam a passar, a divisão está correta.

Modernização do Código

O outro grande caso é a atualização para padrões modernos, onde a transformação é mecânica, mas tão repetitiva que continua a ser adiada para o backlog.

"Migrate all callbacks in src/lib/database.ts to 
async/await. Preserve existing error handling."

O ponto de partida é o JavaScript baseado em callbacks com o seu tratamento de erros em cascata:

function getUser(id, callback) {
  db.query("SELECT * FROM users WHERE id = ?", [id], 
    (err, rows) => {
      if (err) return callback(err);
      callback(null, rows[0]);
    });
}

Eis o que o Codex produz:

async function getUser(id: string): Promise<User> {
  const rows = await db.query(
    "SELECT * FROM users WHERE id = ?", 
    [id]
  );
  return rows[0];
}

Três coisas aconteceram numa única passagem: surgiram os tipos TypeScript, as callbacks deram lugar ao async/await e o tratamento de erros simplificou-se, uma vez que as exceções agora se propagam naturalmente. A lógica de negócio permanece idêntica — e é exatamente isso que deve verificar na revisão, não a elegância do resultado.

Melhoria da Qualidade

Pode também visar uma dimensão específica de qualidade em vez de uma transformação sintática, desde que enumere os requisitos.

"In src/api/, improve error handling:
- Replace generic try/catch blocks with typed errors
- Add appropriate HTTP error codes
- Add logging with request context
- Ensure Prisma errors are mapped correctly"

Formulada desta forma, o pedido torna-se verificável ponto por ponto durante a revisão. Um prompt isolado «melhorar o tratamento de erros» produziria algo plausível, mas inutilizável, porque nem si nem o agente saberiam quando o objetivo foi alcançado.

Refatorização Baseada em Padrões

A variante mais poderosa consiste em designar um ficheiro já conforme e solicitar a sua generalização.

"All React components in src/components/ that use 
useState for forms must migrate to react-hook-form. 
Apply the same pattern as src/components/LoginForm.tsx, 
which is already migrated."

O Codex lê o componente de referência, extrai o padrão e aplica-o aos componentes alvo, lidando com casos extremos — validação personalizada, efeitos secundários — em vez de realizar uma substituição cega. A implicação prática é interessante: o primeiro componente, aquele que migra manualmente, paga todos os outros. Invista cuidado neste ficheiro modelo; vale tanto como uma especificação.

Verificar a Refatorização

O Codex executa testes após cada refatorização, mas uma refatorização que passa nos testes não é necessariamente pronta para produção. Quatro verificações constituem o mínimo, e cada uma aborda um risco diferente.

VerificaçãoComandoO que verifica
Testes unitáriosnpm run testComportamento preservado
Tiposnpx tsc --noEmitSem erros de tipo
Lintingnpm run lintConvenções respeitadas
Compilaçãonpm run buildPronto para produção

O caso típico que justifica esta lista: mover ficheiros mantém os testes verdes porque estes importam de um ficheiro «barrel», mas quebra a compilação de produção devido a uma importação circular que mais nada revela. Adicione estes quatro comandos ao seu ficheiro AGENTS.md e o Codex executá-los-á após cada alteração, sem que tenha de pensar nisso ou de lho lembrar.

Pontos-chave

  • A refatorização é a tarefa onde o Codex oferece a maior poupança de tempo
  • Referencie um ficheiro modelo para guiar o padrão de refatorização
  • O Codex atualiza importações e referências em todo o projeto
  • Verifique sempre com testes, verificação de tipos e compilação após a refatorização
  • Documente os comandos de verificação no AGENTS.md