Revisão de Código com Harness Engineering

💡 Nota: Ato 1: Projeto — primeiro, capturar a visão geral. Que tipo de sistema vamos construir e por que essa estrutura.

O modelo de seis camadas do harness

Harness Engineering projeta o ambiente em que o agente de IA opera em seis camadas.

Revisão de código é o núcleo da ③ camada de verificação de qualidade.

Pense em uma casa: ① é a planta, ② é o procedimento de obra, ③ é a inspeção predial. Ninguém quer morar numa casa erguida sem inspeção.

As três subcamadas da verificação de qualidade

Decompondo a camada de verificação de qualidade, surgem três subcamadas.

Subcamada	Responsável	Velocidade	Precisão
Portão automático	hooks / CI	segundos	exatidão mecânica
Revisão por IA	CodeRabbit / Copilot	minutos	reconhecimento de padrões
Revisão humana	membros do time	horas	decisão de design e direção

De baixo para cima, a velocidade diminui, mas a qualidade do julgamento aumenta. É a mesma lógica de uma cozinha de restaurante. A lava-louças (portão automático) é a mais rápida, o sous-chef (IA) checa a qualidade, e o chef-executivo (humano) define a direção do sabor.

”Quase sempre” vs “sem exceção, sempre”

Um post da SmartScope vai direto ao ponto.

Escrever “execute o linter” no CLAUDE.md e forçar a execução do linter por Hook é a diferença entre “quase sempre” e “sem exceção, sempre.”

Entre “quase sempre” e “sem exceção, sempre” há um abismo maior do que parece. Uma taxa de adesão de 90% significa “1 em 10 vezes passa código quebrado.” Em 100 PRs por mês, 10 vão para produção sem inspeção.

A mesma coisa vale para revisão de código.

Método	Taxa de execução
Escrever “escreva testes antes do PR” no AGENTS.md	80-90%
Forçar execução de testes em pre-commit hook	100%
Escrever “use Conventional Comments” no AGENTS.md	50-70%
Lembrete de label no template de PR	70-80%

A força impositiva sobe na ordem: pedido → template → hook → CI. Neste livro, vamos definir o que impor e o que deixar opcional em cada camada.

Por que não impor tudo?

Você pode pensar: “por que não impor tudo pelo CI?”. Mas, ao impor tudo, a velocidade de desenvolvimento despenca.

Assim como o mundo da segurança tem o trade-off “conveniência vs segurança”, revisão tem o trade-off “força impositiva vs velocidade de desenvolvimento”. O importante é onde traçar a linha entre o que é obrigatório e o que é apenas recomendado.

A abordagem deste livro:

• Obrigatório: formato, linter, checagem de tipos, testes → o que dá para julgar mecanicamente
• Recomendado: labels de Conventional Comments, limite de tamanho de PR → o que depende de julgamento humano

Visão geral da estrutura de arquivos

A estrutura de arquivos do sistema de revisão com harness que vamos construir:

A partir do próximo capítulo, vamos projetar as três subcamadas em ordem.

Continue este capítulo no Kindle →

No capítulo anterior, ficou claro que revisão de código fica na ③ camada de verificação de qualidade do harness. Neste capítulo, vamos decompor essa camada em três subcamadas. Essa é a espinha dorsal do livro.

Dividir papéis em três camadas

O maior problema de revisão de código é tentar fazer tudo com humano.

Checagem de estilo, violação de linter, erro de tipo, presença de testes, vulnerabilidade de segurança, decisão de design, discussão de direção. Se um revisor faz tudo isso em um PR, fadiga de revisão é consequência natural.

O modelo de três camadas divide esse trabalho.

Primeira camada: portão automático (sem humano envolvido)

O que é barrado aqui nem chega ao PR. É resolvido antes de entrar no campo de visão do revisor.

Princípio: o que dá para julgar mecanicamente, deixe para a máquina.

Segunda camada: revisão por IA (reconhecimento de padrões)

O que a IA consegue encontrar:

• Problema N+1
• Risco de SQL injection
• Imports e variáveis não usados
• Cobertura de testes insuficiente
• Violação de convenção de nomenclatura

Princípio: o que dá para detectar por padrão, deixe para a IA.

Terceira camada: revisão humana (julgamento e direção)

Princípio: só o humano faz o que exige julgamento.

O efeito das três camadas

Como o humano pode focar em julgamento, a qualidade também sobe.

Fronteiras de responsabilidade entre as camadas

Tipo de problema	1ª (automática)	2ª (IA)	3ª (humana)
Formato	○
Violação de linter	○
Erro de tipo	○
Falha de teste	○
Problema N+1		○
Vulnerabilidade de segurança		○
Melhoria de nomenclatura		○
Decisão de design			○
Regra de negócio			○
Edição de direção			○

Com a fronteira clara, cada camada consegue focar no próprio trabalho.

Quando a revisão humana não é necessária

Aqui tem um ponto importante. Nem todo PR precisa chegar à terceira camada.

PRs que não exigem decisão de design ou validação de regra de negócio — correção de bug, atualização de dependências, ticket simples — podem se resolver só com a primeira camada (portão automático) e a segunda (revisão por IA).

Tipo de PR	Camadas necessárias
Correção de formato	só 1ª
Atualização de dependências (Dependabot)	1ª + 2ª
Correção de bug (causa clara)	1ª + 2ª
Refatoração (pequena)	1ª + 2ª
Nova funcionalidade	1ª + 2ª + 3ª
Mudança arquitetural	1ª + 2ª + 3ª
Introdução de novo padrão	1ª + 2ª + 3ª

A revisão humana só é necessária em PRs que envolvem “julgamento”. Sem deixar isso claro, vai exigir revisão humana em todo PR e, no fim, a revisão volta a ser o gargalo.

Continue este capítulo no Kindle →