O que é clean code na prática e o que uma revisão com IA realmente consegue apontar

Código que passa no teste e código que alguém consegue manter seis meses depois são duas coisas bem diferentes

E é exatamente aí que mora a conversa de clean code, uma expressão tão repetida que quase virou enfeite de bio no LinkedIn

Só que agora entrou uma variável nova no meio: um agente de IA lendo o teu diff e devolvendo um relatório de revisão em segundos

Então bora separar as coisas neste post: o que a expressão significa no dia a dia (nomes, tamanho de função, duplicação, acoplamento), o que a revisão automática realmente enxerga e o que continua dependendo de você 🙂

O que clean code quer dizer no dia a dia: nomes, tamanho de função, duplicação e acoplamento

A expressão ficou popular com o livro Clean Code: A Handbook of Agile Software Craftsmanship, de Robert C. Martin, publicado pela Pearson em 2008 (431 páginas, ISBN 9780132350884)

De lá pra cá o termo virou bandeira, virou briga de internet, virou camiseta

Mas quando tu tira o hype, sobra um punhado de eixos bem concretos, que dá pra olhar agora no arquivo que tu tem aberto

Nomes que dizem a intenção:

Nome bom não é nome bonito, é nome que dispensa a pergunta seguinte

Se pra entender a variável tu precisa subir três linhas e ler a atribuição, o nome falhou

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

// antes
function calc(d, t) {
  return d * t * 0.1
}

// depois
function calcularComissaoDoVendedor(valorDaVenda, taxaDoPlano) {
  return valorDaVenda * taxaDoPlano * PERCENTUAL_DE_COMISSAO
}

Repara que nada mudou na lógica

O que mudou foi o tempo que a próxima pessoa gasta pra confiar nessa função, e essa pessoa provavelmente é você daqui a uns meses

Tamanho de função: quantas coisas ela faz?

O eixo aqui não é contar linha, é contar responsabilidade

Não existe número mágico de linhas por função, e desconfia de quem te vende um

O teste prático é outro: tenta descrever a função em uma frase, sem usar "e"

Se tu precisou de dois "e", provavelmente tem duas funções ali dentro

// antes: valida, salva e notifica
function salvarPedido(pedido) {
  if (!pedido.itens.length) throw new Error('vazio')
  if (!pedido.clienteId) throw new Error('sem cliente')
  db.pedidos.insert(pedido)
  email.enviar(pedido.clienteId, 'Pedido recebido')
}

// depois: cada peça faz a sua parte
function validarPedido(pedido) { /* ... */ }
function persistirPedido(pedido) { /* ... */ }
function notificarCliente(pedido) { /* ... */ }

function salvarPedido(pedido) {
  validarPedido(pedido)
  persistirPedido(pedido)
  notificarCliente(pedido)
}

O ganho real aparece no teste: agora tu consegue testar validação sem tocar em banco nem em email

Duplicação: quando repetir é aceitável?

Aqui tem MUITO desentendimento

Duplicação ruim é quando o mesmo conceito mora em dois lugares e precisa mudar junto

Duplicação aceitável é quando dois trechos só se parecem hoje, por coincidência, e vão evoluir em direções diferentes

Analogia rápida: se você conhece aquele momento de extrair um helper genérico e três semanas depois ele estar cheio de if tipo === 'x', tu já viu de perto a duplicação que era proposital sendo mal resolvida

A pergunta certa não é "esse código é igual?"

É "esses dois trechos representam a MESMA regra?"

Acoplamento: mudar uma coisa e quebrar outra

Acoplamento é o custo escondido do sistema

É quando tu mexe no formato de um objeto no módulo de pagamento e o relatório financeiro para de rodar, sem ninguém ter tocado no relatório

// antes: o consumidor conhece o miolo do outro módulo
const total = carrinho.dados.itens.reduce((a, i) => a + i.preco.valorBruto, 0)

// depois: o módulo expõe o que ele promete
const total = carrinho.calcularTotal()

No primeiro caso, qualquer mudança na estrutura interna do carrinho vaza pra fora

No segundo, tu tem uma fronteira, e fronteira é o que permite trocar o miolo sem quebrar o resto

Esses quatro eixos são a espinha do assunto

Segura eles na cabeça, porque a partir de agora a gente vai testar cada um contra o que uma revisão automática consegue ver

Por que isso ficou mais urgente com IA no fluxo

Agora um contexto de dado, não de opinião

A GitClear analisou 211 milhões de linhas de código e olhou o que aconteceu com a saúde dessas bases durante o período de adoção de assistentes de IA

Os números do estudo:

• blocos com 5 ou mais linhas duplicadas cresceram 8 vezes durante 2024
• linhas copiadas e coladas passaram de 8,3% em 2020 para 12,3% em 2024, uma alta relativa de 48%
• linhas "movidas" (o sinal de refatoração) caíram de 24,1% em 2020 para 9,5% em 2024
• 2024 foi o primeiro ano em que linhas copiadas superaram linhas movidas

Se liga no que isso significa na prática

Dos quatro eixos que a gente acabou de ver, o que mais degradou no período foi justamente duplicação e refatoração

Ou seja: o problema deixou de ser abstrato

A prioridade da revisão muda de lugar, porque não adianta caçar nome de variável enquanto a base acumula bloco copiado que ninguém mais move

O que a revisão com IA aponta bem e o que ainda depende de você

A lógica da coluna da direita é sempre a mesma: o agente lê o diff, não lê o roadmap nem a reunião em que a decisão foi tomada

Como pedir a revisão: /review, /code-review e /security-review no Claude Code

Beleza, e na prática, como se pede isso?

Se você já roda o assistente no dia a dia e conhece o fluxo completo até o deploy, esse pedaço encaixa bem no fim do ciclo, antes de empacotar a mudança

No Claude Code, o comando /review é apelido de /code-review, e ele analisa o diff atual em busca de bugs de correção e de limpezas

/review

Algumas variações que o comando aceita:

• --fix pra aplicar as descobertas
• número de PR, no formato /code-review high 1234
• /code-review ultra, que roda uma revisão multiagente na nuvem

Um detalhe importante de projeto: esse comando roda sob demanda, não automático

A razão é que a checagem é mais longa, então quem decide quando gastar tempo e token é você, e não a ferramenta

Se esse tipo de conta pesa no teu mês, vale entender quanto o Claude Code custa hoje antes de sair rodando revisão profunda em todo commit

E o /security-review, é a mesma coisa?

Não é a mesma coisa, e essa confusão é comum

São duas lentes diferentes: o /code-review olha correção e limpeza do teu diff, o /security-review olha segurança das mudanças pendentes

O /security-review é um slash command incluído por padrão no Claude Code e faz uma revisão de segurança das mudanças pendentes, com foco em coisas como bypass de autorização, IDOR, injeção, SSRF e criptografia fraca

/security-review

Ele inclui filtragem de falso positivo, o que ajuda a não te afogar em alerta genérico

Dá pra customizar também: é só copiar o arquivo security-review.md do repositório claude-code-security-review, mantido pela Anthropic, pra pasta .claude/commands/ do seu projeto

Tome cuidado com isso: revisão de segurança não substitui revisão geral de código

Rodar só a de segurança e achar que o código está revisado é o tipo de conforto que cobra caro depois

Onde a revisão com IA erra: os padrões de falha mais comuns

Sintoma: o relatório traz um achado plausível que não se sustenta

Causa: o problema mais reportado com IA hoje não é o erro escandaloso, é o quase certo

Na pesquisa com desenvolvedores da Stack Overflow de 2025, 66% apontaram "soluções de IA que estão quase certas, mas não totalmente" como problema encontrado, e 45,2% disseram que depurar código gerado por IA consome mais tempo

Como prevenir: trate cada item do relatório como hipótese, não como diagnóstico

Se o achado é real, tu consegue apontar a linha e descrever o comportamento errado em uma frase

Se não consegue, é ruído bem escrito

Sintoma: ele sugere refatorar algo que foi decidido assim de propósito

Causa: o agente vê o diff, não vê a discussão que gerou aquele código

Aquele if feio pode ser um contorno de bug de biblioteca, e ninguém contou isso pra ele

Como prevenir: deixa o porquê no próprio código, curto e no lugar onde a estranheza mora

Um comentário de duas linhas explicando a decisão vale mais que qualquer prompt caprichado

Sintoma: a sensação de velocidade não se confirma no fim do dia

Causa: essa é desconfortável, e vale olhar de frente

Um ensaio controlado randomizado da METR acompanhou 16 desenvolvedores experientes de open source em 246 tarefas de projetos maduros, com Cursor Pro usando Claude 3.5 e 3.7 Sonnet

O tempo de conclusão foi 19% MAIOR quando a IA era permitida (intervalo de confiança de +2% a +39%), e os participantes estimaram depois uma economia de 20%

Ou seja: percepção e cronômetro apontaram pra lados opostos

Justiça seja feita, tem ressalva: em fevereiro de 2026 a METR informou mudança no desenho do experimento, contou que o novo experimento iniciado em agosto de 2025 não gerou sinal confiável por viés de seleção (recusa de participantes em trabalhar sem IA, efeitos de seleção por remuneração menor e medição não confiável de tempo por tarefa), e o achado de 2025 não foi retratado

Como prevenir: não use "me senti mais rápido" como métrica de qualidade de revisão

Sintoma: o time adota, mas ninguém confia de verdade

Causa: isso não é problema seu, é estado da indústria

O relatório DORA de 2025 aponta 90% de adoção de IA entre profissionais de desenvolvimento (alta de 14 pontos em relação ao ano anterior), com 24% relatando muita ou bastante confiança e 30% confiando pouco ou nada

Como prevenir: desenhe o fluxo assumindo a desconfiança, com verificação humana no meio

É mais honesto que fingir uma confiança que os dados não mostram

O que checar na mão depois do relatório

Relatório pronto na tela, e agora?

Esse é o checklist que separa revisão útil de carimbo automático:

1. Valide cada achado contra o comportamento esperado antes de aceitar. Leia o trecho apontado e pergunte o que deveria acontecer ali, não o que a ferramenta disse. O erro comum: aceitar em lote porque o texto do relatório soa seguro

2. Decida se a duplicação apontada é acidental ou proposital. Se os dois trechos representam a mesma regra, unifica; se só parecem iguais hoje, deixa quieto. O erro comum: extrair helper genérico às pressas e criar acoplamento onde não tinha

3. Confira se o nome sugerido bate com o vocabulário do domínio. O agente propõe nome tecnicamente correto, mas quem sabe se o time chama aquilo de "assinatura" ou de "contrato" é você. O erro comum: renomear pro nome bonito e criar dois vocabulários na mesma base

4. Revise se a refatoração proposta não move a fronteira do módulo sem razão. Mudança de fronteira é decisão de arquitetura, não limpeza. O erro comum: aprovar um "extrai isso pra um serviço" que vira dependência nova sem ninguém ter discutido

5. Rode os testes e leia o diff final você mesmo, principalmente se usou --fix. Aplicar automático é cômodo, e é exatamente por isso que passa batido

git diff

O erro comum: confiar que o que foi aplicado é idêntico ao que estava descrito no relatório

6. Registre a decisão de manter algo "sujo" de propósito. Um comentário curto no código, ou uma linha no PR, evita que a mesma sugestão volte na próxima revisão e roube teu tempo de novo. O erro comum: rejeitar o achado em silêncio e reviver a discussão daqui a três semanas

Onde encaixar revisão automática no fluxo de time

Três cenários que funcionam bem, e são bem diferentes entre si:

Revisão local antes de abrir o PR. Tu roda no terminal, no diff que ainda está na tua máquina, e chega no PR com o sinal mecânico já limpo

É o melhor uso, porque o barulho morre antes de virar comentário público

Revisão no PR. Aqui a lógica é outra: cobertura automática de tudo que entra, sem depender de alguém lembrar de rodar

Revisão de segurança em mudança sensível. Mexeu em autenticação, permissão, upload ou integração externa? É onde a lente de segurança paga o próprio custo

O critério de escolha é bem direto: sob demanda no terminal, quando tu quer controlar quando a revisão roda, versus revisão automática no PR, quando tu quer cobertura sem depender de disciplina do time

Dá pra usar os dois, e em time grande normalmente é isso que acontece mesmo

Veredito: a revisão com IA é um primeiro leitor, não o revisor final

Minha posição, sem enfeite

Vale muito como varredura rápida de sinal mecânico: nome ruim, função inchada, catch vazio, trecho repetido dentro do diff

Vale como rede de segurança em mudança sensível, principalmente com a lente de segurança rodando junto

Não vale como aprovação

Os três dados do post apontam pro mesmo lugar: a confiança relatada no DORA 2025 é baixa (24% com muita ou bastante confiança, 30% com pouca ou nenhuma), o problema campeão na Stack Overflow de 2025 é o quase certo (66%), e a GitClear mostra duplicação subindo enquanto refatoração cai

E tem o limite estrutural, que nenhum modelo melhor resolve sozinho: o agente lê o diff, não lê o produto

Regra de negócio, decisão intencional e fronteira de módulo não estão no arquivo, estão na cabeça de quem construiu

Conclusão

Clean code, quando tu tira o jargão, é aquilo: nome que diz a intenção, função que faz uma coisa, duplicação sob controle e acoplamento baixo

A divisão de trabalho ficou clara: a máquina cuida bem do sinal local, dentro do diff, e você cuida do julgamento, que é o que exige contexto

Próximo passo concreto pra hoje: roda /review no diff atual, abre o relatório com a tabela deste post do lado e separa o que tu aceita do que tu ignora, anotando a razão de cada ignorada

Esse pequeno hábito de registrar o porquê é o que impede a mesma discussão de voltar todo mês 😀

até o próximo post!