BLOG

Refatorando com IA em Sistemas Vivos: Como Delegar Sem Perder o Controle da Base de Código

Adriano Santos · 13 de agosto de 2026 · 13 min de leitura

Você pede para a IA “refatorar essa classe para deixar o código mais limpo”. Ela devolve um diff enorme, elegante, com nomes melhores, funções menores, padrões de projeto aplicados com propriedade. Você aprova, faz o merge, sobe para homologação. Duas horas depois, o time de suporte reporta que um relatório financeiro que dependia de um efeito colateral sutil — um campo que era populado como side effect de uma função com nome péssimo, mas comportamento correto — parou de funcionar. A IA não quebrou uma regra de negócio: ela quebrou um contrato implícito que ninguém tinha documentado, porque ninguém sabia que ele existia.

Esse é o risco central de usar IA para refatorar sistemas que já estão em produção, com histórico, dependências cruzadas e comportamentos “acidentais” que se tornaram requisitos ao longo do tempo. A IA é excelente em reescrever código isolado. Ela não tem, por padrão, visão do sistema como um organismo vivo — e é exatamente aí que projetos são quebrados silenciosamente. Neste artigo, vamos tratar refatoração assistida por IA não como “pedir para limpar o código”, mas como um processo de engenharia com escopo definido, rede de segurança e revisão em camadas — a única forma de fazer isso em escala sem introduzir regressões.

Por que refatoração com IA é diferente de geração de código com IA

Gerar código novo é um problema de criação: você define um contrato (assinatura, comportamento esperado) e a IA preenche a implementação. Se ela errar, o pior cenário é reescrever a função. Refatorar é um problema de preservação: existe um comportamento observável hoje, muitas vezes não totalmente especificado, e a tarefa é mudar a estrutura interna sem mudar esse comportamento.

O problema é que “comportamento observável” inclui coisas que raramente estão em nenhum lugar escrito:

Ordem de execução que afeta race conditions em sistemas concorrentes.
Efeitos colaterais em logs, métricas ou eventos que outros sistemas consomem.
Tratamento de exceções que, mesmo “errado”, é o que o resto do sistema espera.
Comportamento de borda (null, string vazia, lista vazia) que ninguém testou explicitamente, mas que existe em produção.

A IA, ao refatorar, tende a “corrigir” essas inconsistências porque elas parecem bugs do ponto de vista da leitura estática do código. Do ponto de vista do sistema em produção, elas são comportamento contratual.

💡 Dica do Mestre: Michael Feathers, no clássico Working Effectively with Legacy Code, define código legado como “código sem testes”. Sob essa definição, praticamente todo código que uma IA vai refatorar em um projeto real é legado — mesmo que tenha sido escrito há um mês. A pergunta certa antes de refatorar não é “esse código é antigo?”, é “esse código tem uma rede de segurança que detecta se eu mudei o comportamento?”.

O framework: escopo, rede de segurança, execução, revisão

Refatoração segura assistida por IA segue quatro etapas que não podem ser puladas. Pular a etapa 2 é a causa mais comum de incidentes.

1. Delimitar o escopo antes de escrever qualquer prompt

O erro mais comum é pedir refatorações amplas demais: “melhora essa classe”, “modulariza esse arquivo”. Isso dá à IA liberdade para tocar em partes do código que você não revisou mentalmente antes de pedir a mudança. Refatoração segura tem escopo de diff pequeno e objetivo nomeado.

Compare os dois pedidos:


❌ "Refatore o arquivo OrderService.java para ficar mais limpo e seguir boas práticas."

✅ "Extraia o método calculateShippingCost() da classe OrderService para uma nova
classe ShippingCalculator. Mantenha a assinatura pública de OrderService.calculateTotal()
idêntica. Não altere nenhuma outra lógica no arquivo. Não altere imports não relacionados
a essa extração."

❌ "Refatore o arquivo OrderService.java para ficar mais limpo e seguir boas práticas."

✅ "Extraia o método calculateShippingCost() da classe OrderService para uma nova

classe ShippingCalculator. Mantenha a assinatura pública de OrderService.calculateTotal()

idêntica. Não altere nenhuma outra lógica no arquivo. Não altere imports não relacionados

a essa extração."

O segundo prompt tem um objetivo único, um limite explícito (“não altere nenhuma outra lógica”) e preserva um contrato público que outras partes do sistema dependem. Isso reduz drasticamente a superfície de erro e — igualmente importante — reduz a superfície que você precisa revisar com atenção.

2. Construir a rede de segurança: testes de caracterização antes de tocar no código

Se o código não tem testes, escrever testes de comportamento (não de implementação) antes de refatorar é obrigatório — e a IA pode ajudar exatamente nisso, de forma segura, porque gerar testes que capturam comportamento atual não corre o risco de “melhorar” nada.

Testes de caracterização registram o que o código faz hoje, certo ou errado, para que qualquer refatoração subsequente seja validada contra esse baseline.


import pytest
from decimal import Decimal
from order_service import OrderService

# Teste de caracterização: captura o comportamento ATUAL,
# incluindo casos de borda estranhos que existem em produção.

def test_calculate_total_com_desconto_e_frete_gratis():
    service = OrderService()
    resultado = service.calculate_total(
        items=[{"price": Decimal("100.00"), "qty": 2}],
        coupon="FRETEGRATIS10",
        region="SP"
    )
    # Este valor foi capturado rodando o código atual, não deduzido
    # da regra de negócio documentada — a documentação está desatualizada.
    assert resultado == Decimal("189.00")

def test_calculate_total_com_lista_vazia_retorna_zero_sem_exception():
    service = OrderService()
    resultado = service.calculate_total(items=[], coupon=None, region="RJ")
    assert resultado == Decimal("0.00")

def test_calculate_total_com_regiao_invalida_nao_lanca_mas_ignora_frete():
    # Comportamento "estranho" mas que o time de vendas descobriu que
    # é usado deliberadamente para pedidos internacionais.
    service = OrderService()
    resultado = service.calculate_total(
        items=[{"price": Decimal("50.00"), "qty": 1}],
        coupon=None,
        region="XX"
    )
    assert resultado == Decimal("50.00")

import pytest

from decimal import Decimal

from order_service import OrderService

# Teste de caracterização: captura o comportamento ATUAL,

# incluindo casos de borda estranhos que existem em produção.

def test_calculate_total_com_desconto_e_frete_gratis():

service = OrderService()

resultado = service.calculate_total(

items=[{"price": Decimal("100.00"), "qty": 2}],

coupon="FRETEGRATIS10",

region="SP"

)

# Este valor foi capturado rodando o código atual, não deduzido

# da regra de negócio documentada — a documentação está desatualizada.

assert resultado == Decimal("189.00")

def test_calculate_total_com_lista_vazia_retorna_zero_sem_exception():

service = OrderService()

resultado = service.calculate_total(items=[], coupon=None, region="RJ")

assert resultado == Decimal("0.00")

def test_calculate_total_com_regiao_invalida_nao_lanca_mas_ignora_frete():

# Comportamento "estranho" mas que o time de vendas descobriu que

# é usado deliberadamente para pedidos internacionais.

service = OrderService()

resultado = service.calculate_total(

items=[{"price": Decimal("50.00"), "qty": 1}],

coupon=None,

region="XX"

)

assert resultado == Decimal("50.00")

Peça à IA para gerar esses testes observando o código-fonte e, quando possível, executando-o com dados reais anonimizados. O prompt certo aqui é: “gere testes que capturem o comportamento atual desta função para todos os caminhos de execução visíveis, incluindo casos de borda; não corrija nada que pareça um bug, apenas documente o comportamento existente”.

💡 Dica do Mestre: Ferramentas de mutation testing como o PIT (Java), o mutmut (Python) ou o Stryker (JS/TS/.NET) ajudam a validar se seus testes de caracterização realmente pegam mudanças de comportamento, e não só cobrem linhas. Cobertura de linha alta com testes fracos é a ilusão de segurança mais perigosa antes de uma refatoração.

3. Executar a refatoração em passos pequenos e reversíveis

Depois de ter a rede de segurança, a execução deve seguir os passos clássicos de refatoração (extrair método, mover classe, inverter dependência) um por vez, rodando os testes entre cada passo. Isso vale tanto para refatoração manual quanto assistida por IA — a diferença é que, com IA, cada passo pode ser um prompt isolado e revisável.


# Fluxo de execução, um commit por passo

git checkout -b refactor/extract-shipping-calculator

# Passo 1: extrair a interface, sem mudar comportamento
# (prompt específico, diff pequeno, testes passam)
git commit -m "extract: cria interface ShippingCalculator sem alterar comportamento"

# Passo 2: mover a implementação
git commit -m "extract: move calculateShippingCost para ShippingCalculator"

# Passo 3: atualizar OrderService para usar a nova classe via injeção
git commit -m "refactor: OrderService passa a depender de ShippingCalculator"

# Testes de caracterização executam depois de CADA commit, não só no final

# Fluxo de execução, um commit por passo

git checkout -b refactor/extract-shipping-calculator

# Passo 1: extrair a interface, sem mudar comportamento

# (prompt específico, diff pequeno, testes passam)

git commit -m "extract: cria interface ShippingCalculator sem alterar comportamento"

# Passo 2: mover a implementação

git commit -m "extract: move calculateShippingCost para ShippingCalculator"

# Passo 3: atualizar OrderService para usar a nova classe via injeção

git commit -m "refactor: OrderService passa a depender de ShippingCalculator"

# Testes de caracterização executam depois de CADA commit, não só no final

Se em algum passo os testes de caracterização falharem, o problema está isolado naquele commit específico — você não precisa investigar um diff gigante para descobrir onde o comportamento mudou. Essa granularidade é o que torna o processo auditável e reversível com git revert pontual, sem precisar descartar todo o trabalho.

4. Revisão em camadas: sintática, semântica e sistêmica

Revisar um diff gerado por IA linha a linha, procurando erros de sintaxe, é a camada mais fácil e a menos importante — compiladores e linters já fazem isso. As camadas que exigem julgamento humano são outras duas:

Revisão semântica: o comportamento da função mudou? Use os testes de caracterização como evidência objetiva, não a leitura do código.
Revisão sistêmica: quem mais chama esse código? Uma mudança de assinatura, mesmo compatível, afeta contratos com outros serviços, filas de mensagens, serialização de cache, ou testes de integração em outros repositórios?

Um checklist prático para revisão sistêmica antes de aprovar um PR de refatoração gerado com IA:


[ ] Assinaturas públicas alteradas? Se sim, quem consome esse método/endpoint?
[ ] Ordem de campos em serialização (JSON, protobuf) foi preservada?
[ ] Exceções lançadas mudaram de tipo? Algum catch específico depende disso?
[ ] Logs ou métricas emitidos foram removidos ou tiveram formato alterado?
[ ] Há testes de integração/E2E cobrindo o fluxo completo, não só a unidade?
[ ] O diff toca em arquivos fora do escopo pedido no prompt?

[ ] Assinaturas públicas alteradas? Se sim, quem consome esse método/endpoint?

[ ] Ordem de campos em serialização (JSON, protobuf) foi preservada?

[ ] Exceções lançadas mudaram de tipo? Algum catch específico depende disso?

[ ] Logs ou métricas emitidos foram removidos ou tiveram formato alterado?

[ ] Há testes de integração/E2E cobrindo o fluxo completo, não só a unidade?

[ ] O diff toca em arquivos fora do escopo pedido no prompt?

Esse último ponto é crítico. Ferramentas como o Claude Code e outros agentes de terminal frequentemente “aproveitam” a tarefa para corrigir imports, formatação ou pequenos “bugs” adjacentes que não foram pedidos. Isso pode ser bem-vindo em código isolado, mas em sistemas com múltiplos mantenedores é fonte de conflitos e regressões não relacionadas ao objetivo do PR. Vale configurar instruções de projeto — em um CLAUDE.md, por exemplo — explicitando que alterações fora do escopo pedido devem ser reportadas, não aplicadas silenciosamente.

Exemplo prático: refatorando um trecho legado em múltiplas linguagens

Para ilustrar que o princípio é generalista e não depende de stack, veja o mesmo padrão de refatoração — extrair uma responsabilidade misturada em uma função grande — em três contextos diferentes.

TypeScript: separando validação de persistência


// Antes: validação e persistência misturadas
async function createUser(data: UserInput): Promise {
  if (!data.email || !data.email.includes("@")) {
    throw new Error("Email inválido");
  }
  if (data.age &lt; 18) {
    throw new Error(&quot;Usuário menor de idade&quot;);
  }
  const hashed = await bcrypt.hash(data.password, 10);
  const user = await db.users.insert({ ...data, password: hashed });
  await emailService.sendWelcome(user.email);
  return user;
}

// Prompt usado: &quot;Extraia a validação de UserInput para uma função pura
// validateUserInput() que retorna um array de erros. Não altere a ordem
// de execução do restante da função. Mantenha createUser com a mesma
// assinatura e mesmo comportamento de exceção.&quot;

function validateUserInput(data: UserInput): string[] {
  const errors: string[] = [];
  if (!data.email || !data.email.includes(&quot;@&quot;)) errors.push(&quot;Email inválido&quot;);
  if (data.age &lt; 18) errors.push(&quot;Usuário menor de idade&quot;);
  return errors;
}

async function createUser(data: UserInput): Promise {
  const errors = validateUserInput(data);
  if (errors.length &gt; 0) throw new Error(errors[0]); // preserva comportamento: só o 1º erro
  const hashed = await bcrypt.hash(data.password, 10);
  const user = await db.users.insert({ ...data, password: hashed });
  await emailService.sendWelcome(user.email);
  return user;
}

// Antes: validação e persistência misturadas

async function createUser(data: UserInput): Promise {

if (!data.email || !data.email.includes("@")) {

throw new Error("Email inválido");

}

if (data.age < 18) {

throw new Error("Usuário menor de idade");

}

const hashed = await bcrypt.hash(data.password, 10);

const user = await db.users.insert({ ...data, password: hashed });

await emailService.sendWelcome(user.email);

return user;

}

// Prompt usado: "Extraia a validação de UserInput para uma função pura

// validateUserInput() que retorna um array de erros. Não altere a ordem

// de execução do restante da função. Mantenha createUser com a mesma

// assinatura e mesmo comportamento de exceção."

function validateUserInput(data: UserInput): string[] {

const errors: string[] = [];

if (!data.email || !data.email.includes("@")) errors.push("Email inválido");

if (data.age < 18) errors.push("Usuário menor de idade");

return errors;

}

async function createUser(data: UserInput): Promise {

const errors = validateUserInput(data);

if (errors.length > 0) throw new Error(errors[0]); // preserva comportamento: só o 1º erro

const hashed = await bcrypt.hash(data.password, 10);

const user = await db.users.insert({ ...data, password: hashed });

await emailService.sendWelcome(user.email);

return user;

}

Note o detalhe: o comportamento original lançava só o primeiro erro encontrado, não todos. Um refatoramento “ingênuo” para validateUserInput retornando todos os erros e um throw new Error(errors.join(", ")) pareceria melhor, mas mudaria o contrato de erro que talvez algum front-end esteja fazendo parsing de string para exibir mensagem específica. Isso só se detecta com teste de caracterização cobrindo múltiplos erros simultâneos.

Delphi: isolando regra de negócio de acesso a dados


// Antes: regra de negócio e SQL na mesma unit
function TPedidoService.CalcularDesconto(APedido: TPedido): Currency;
var
  Query: TFDQuery;
begin
  Query := TFDQuery.Create(nil);
  try
    Query.Connection := FConexao;
    Query.SQL.Text := 'SELECT percentual FROM regras_desconto WHERE cliente_id = :id';
    Query.ParamByName('id').AsInteger := APedido.ClienteId;
    Query.Open;
    if Query.RecordCount &gt; 0 then
      Result := APedido.Total * (Query.FieldByName('percentual').AsFloat / 100)
    else
      Result := 0;
  finally
    Query.Free;
  end;
end;

// Prompt: "Extraia a regra de cálculo do desconto para uma função pura que
// receba o percentual já obtido, e isole o acesso a dados em um método
// separado chamado ObterPercentualDesconto. Não altere o tratamento de
// RecordCount = 0."

function TPedidoService.ObterPercentualDesconto(AClienteId: Integer): Double;
var
  Query: TFDQuery;
begin
  Query := TFDQuery.Create(nil);
  try
    Query.Connection := FConexao;
    Query.SQL.Text := 'SELECT percentual FROM regras_desconto WHERE cliente_id = :id';
    Query.ParamByName('id').AsInteger := AClienteId;
    Query.Open;
    if Query.RecordCount &gt; 0 then
      Result := Query.FieldByName('percentual').AsFloat
    else
      Result := 0;
  finally
    Query.Free;
  end;
end;

function TPedidoService.CalcularDesconto(APedido: TPedido): Currency;
var
  Percentual: Double;
begin
  Percentual := ObterPercentualDesconto(APedido.ClienteId);
  Result := APedido.Total * (Percentual / 100);
end;

// Antes: regra de negócio e SQL na mesma unit

function TPedidoService.CalcularDesconto(APedido: TPedido): Currency;

var

Query: TFDQuery;

begin

Query := TFDQuery.Create(nil);

try

Query.Connection := FConexao;

Query.SQL.Text := 'SELECT percentual FROM regras_desconto WHERE cliente_id = :id';

Query.ParamByName('id').AsInteger := APedido.ClienteId;

Query.Open;

if Query.RecordCount > 0 then

Result := APedido.Total * (Query.FieldByName('percentual').AsFloat / 100)

else

Result := 0;

finally

Query.Free;

end;

// Prompt: "Extraia a regra de cálculo do desconto para uma função pura que

// receba o percentual já obtido, e isole o acesso a dados em um método

// separado chamado ObterPercentualDesconto. Não altere o tratamento de

// RecordCount = 0."

function TPedidoService.ObterPercentualDesconto(AClienteId: Integer): Double;

var

Query: TFDQuery;

begin

Query := TFDQuery.Create(nil);

try

Query.Connection := FConexao;

Query.SQL.Text := 'SELECT percentual FROM regras_desconto WHERE cliente_id = :id';

Query.ParamByName('id').AsInteger := AClienteId;

Query.Open;

if Query.RecordCount > 0 then

Result := Query.FieldByName('percentual').AsFloat

else

Result := 0;

finally

Query.Free;

end;

function TPedidoService.CalcularDesconto(APedido: TPedido): Currency;

var

Percentual: Double;

begin

Percentual := ObterPercentualDesconto(APedido.ClienteId);

Result := APedido.Total * (Percentual / 100);

end;

Aqui a extração permite testar CalcularDesconto com um percentual mockado, sem precisar de banco de dados no teste — um ganho real de testabilidade, mas obtido com uma mudança estrutural mínima e sem alterar a regra de “sem registro, desconto zero”.

Quando a IA erra: padrões de falha que você precisa reconhecer

Depois de revisar dezenas de refatorações geradas por IA em projetos reais, alguns padrões de erro se repetem com frequência suficiente para merecer atenção específica:

“Correção” silenciosa de bugs conhecidos-mas-necessários: a IA identifica que um comportamento é inconsistente e o “corrige” sem avisar, mesmo quando o prompt não pediu correção de bugs.
Perda de comportamento assíncrono/concorrente: ao extrair métodos, ordens de await ou locks podem ser sutilmente reordenadas, introduzindo race conditions que só aparecem sob carga.
Generalização excessiva: transformar um caso específico em uma abstração genérica “para o futuro”, aumentando a complexidade sem necessidade imediata — o clássico over-engineering, agora automatizado.
Confiança excessiva em nomes: a IA às vezes assume o que uma função faz pelo nome, sem ler a implementação completa, especialmente em bases de código grandes onde o contexto foi truncado.

💡 Dica do Mestre: Martin Fowler, em Refactoring: Improving the Design of Existing Code, é enfático em um princípio que se aplica perfeitamente à era da IA: cada refatoração deve ser pequena o suficiente para ser revertida trivialmente. Se você não consegue explicar em uma frase o que um diff de refatoração muda, ele está grande demais para revisar com segurança — independentemente de quem o escreveu.

Integrando ao fluxo de CI: gates automáticos para refatoração

Para dar escala a esse processo sem depender só de disciplina humana, vale configurar gates automáticos que bloqueiem merges de refatoração sem evidência de preservação de comportamento:

Delphi/Pascal

# .github/workflows/refactor-check.yml name: Refactor Safety Check on: pull_request: branches: [main] jobs: characterization-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Roda testes de caracterização run: npm run test:characterization - name: Verifica cobertura de mutação mínima nos arquivos alterados run: npx stryker run --mutate "$(git diff --name-only origin/main...HEAD)" - name: Bloqueia se assinatura pública mudou sem label 'breaking-change' run: node scripts/check-public-api-diff.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# .github/workflows/refactor-check.yml
name: Refactor Safety Check

on:
  pull_request:
    branches: [main]

jobs:
  characterization-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Roda testes de caracterização
        run: npm run test:characterization
      - name: Verifica cobertura de mutação mínima nos arquivos alterados
        run: npx stryker run --mutate "$(git diff --name-only origin/main...HEAD)"
      - name: Bloqueia se assinatura pública mudou sem label 'breaking-change'
        run: node scripts/check-public-api-diff.js

O terceiro passo — verificação de API pública — pode ser implementado com ferramentas de diff de tipos (como API Extractor no TypeScript, ou análises de compatibilidade em Go) que comparam a superfície pública antes e depois do PR, alertando automaticamente quando uma refatoração — humana ou de IA — expõe uma mudança de contrato não sinalizada.

Participe da Comunidade Dev’s AI

Refatoração assistida por IA é um dos temas em que a diferença entre “economizar horas” e “criar um incidente em produção” está inteiramente no processo, não na ferramenta. Se você quer trocar experiências reais sobre como outros times estruturam esse fluxo, comparar workflows de agentes e discutir armadilhas específicas de cada stack, venha para a Comunidade Dev’s AI. É um espaço de desenvolvedores que aplicam IA no dia a dia de engenharia de software, com discussões práticas sobre agentes, automações, revisão de código e tudo que envolve manter qualidade em projetos reais.

Conclusão

A IA não torna a refatoração mais arriscada por si só — ela torna visível uma verdade que já era verdadeira antes: refatorar código sem rede de segurança sempre foi um jogo de sorte, humano ou automatizado. O que muda é a velocidade com que erros podem ser introduzidos e a facilidade com que diffs grandes e aparentemente elegantes passam por revisão superficial simplesmente porque “o código parece mais limpo”.

O caminho seguro não é desconfiar da IA a ponto de não usá-la para refatoração — é justamente o oposto: delegar refatorações com escopo estreito, protegidas por testes de caracterização, executadas em passos pequenos e revisadas em camadas que vão além da sintaxe. Feito assim, a refatoração assistida por IA deixa de ser uma aposta e se torna o que sempre deveria ter sido: uma técnica de engenharia disciplinada, só que mais rápida.

Leave a Reply Cancelar resposta
O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *
Comentário *
Nome *

E-mail *

Salvar meus dados neste navegador para a próxima vez que eu comentar.

Δ