Refatorização e Melhoria de Código Existente
Nesta página
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ção | Comando | O que verifica |
|---|---|---|
| Testes unitários | npm run test | Comportamento preservado |
| Tipos | npx tsc --noEmit | Sem erros de tipo |
| Linting | npm run lint | Convenções respeitadas |
| Compilação | npm run build | Pronto 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