← Voltar ao início

Arquitetura

review-harness

Revisão automática de pull request. Verificações grátis primeiro, IA só onde o risco justifica o custo, e a IA nunca pode aprovar nada.

1. O problema

Agente de IA escreve mais código do que uma pessoa consegue ler linha por linha. Ler tudo não escala. Não ler nada é inseguro.

A solução óbvia, jogar um modelo em cima de todo pull request, tem dois problemas. O primeiro é dinheiro: custa a cada PR, e a maior parte dos PRs não precisa disso. O segundo é mais sério: coloca o componente menos confiável do sistema na posição de decidir o que entra na base de código.

O problema de engenharia é este: decidir quais PRs merecem atenção humana, gastar dinheiro só onde o risco justifica, e garantir que a IA nunca possa aprovar coisa nenhuma.

A base é o processo descrito no artigo da Anthropic sobre como o time do Claude Code faz revisão de código, de outubro de 2026, adaptado para orçamento pequeno.

2. Os números

Contados no próprio funcionamento da ferramenta.

5
etapas em ordem fixa: testes, risco, segurança, IA e decisão
3
dessas etapas não custam nada: testes, risco e segurança
1
etapa custa dinheiro, e vem desligada por padrão
3
resultados possíveis: passou, precisa de humano, falhou
3
rodadas no máximo por PR na etapa de IA
0
arquivos completos lidos pela IA. Só as linhas alteradas
0
chaves entregues a PR vindo de fork
2
permissões no GitHub: ler o código e comentar no PR. Nada mais

3. O desenho

É um funil ordenado por custo. Cada etapa grátis reduz quanto trabalho sobra para a etapa cara, e a etapa cara só recebe o que as grátis já disseram que tem risco.

Pull request aberto1. Testescomandos que você configurousem custo2. Riscoquais arquivos foram alteradossem custo3. Segurançagitleaks · cargo-auditsem custo.review-harness.tomllido da main,nunca do PRSÓ RISCO MÉDIO E ALTO SEGUEM DAQUI4. Revisão por IAdesligada por padrão · só linhas alteradas · 3 rodadasachado fora do PR é descartado · nunca aprovacusta5. Um comentário no PRpassou · precisa de humano · falhou

A configuração entra pela lateral de propósito: ela é lida sempre da branch principal, nunca do PR em revisão. Se o PR pudesse trazer as próprias regras, a primeira coisa que um PR ruim faria era marcar os próprios arquivos como de baixo risco e desligar as verificações.

Os três resultados

O resultado do meio é decisão de produto, não falta de certeza do sistema.

Passou

Testes passaram, nenhum problema de segurança, e só arquivos de baixo risco mudaram.

Pode mesclar.

Precisa de humano

Tudo passou, mas o PR toca arquivo sensível.

Leia com atenção antes de mesclar.

Falhou

Teste quebrou ou apareceu problema de segurança.

Corrija. O merge continua bloqueado.

4. As decisões

Toda decisão tem preço. Abaixo está o que escolhi, o que descartei, por quê, e o que isso custa.

01. Verificação grátis primeiro, IA por último e desligada por padrão

Escolhi
Testes, lista de arquivos alterados e varredura de segurança rodam antes. Só PR de risco médio ou alto chega na IA, e a IA vem desligada.
Em vez de
Mandar todo pull request para um modelo.
Porque
A maior parte dos PRs não precisa de IA para ser julgada. Teste quebrado e lista de arquivo alterado respondem quase tudo sem custo. Colocar a etapa paga por último significa pagar só onde as etapas grátis já apontaram risco.
Preço que pago
A IA nunca vê PR de baixo risco. Um bug sutil num arquivo que ninguém marcou como sensível não vai ser pego por ela.

02. A IA pode apontar problema e nunca pode aprovar

Escolhi
A etapa de IA só reporta. A aprovação é decidida pelas etapas determinísticas.
Em vez de
Deixar o modelo dar o veredicto.
Porque
Aprovar é a única decisão que importa, e um modelo que pode ser conduzido pelo conteúdo que está lendo não pode ter essa caneta. Um PR malicioso que escrevesse instruções no próprio diff estaria instruindo o revisor a aprová-lo.
Preço que pago
Um PR que está realmente correto ainda carrega o que a IA apontou, e alguém precisa descartar manualmente.

03. Achado que aponta para linha fora do PR é descartado

Escolhi
Se o modelo comenta uma linha que não está no diff, o achado é jogado fora.
Em vez de
Mostrar tudo que o modelo falou.
Porque
Modelo lendo diff comenta com confiança sobre código que ele deduziu, não leu. Achado que não ancora em linha alterada é achado que ninguém consegue conferir, e ruído em ferramenta de revisão é o que faz a ferramenta ser desligada em duas semanas.
Preço que pago
Problema real causado pelo PR mas visível só numa linha não alterada é descartado em silêncio.

04. A configuração é lida da branch principal, nunca do PR

Escolhi
O arquivo .review-harness.toml sempre vem da main, independente do que o PR traz.
Em vez de
Ler a configuração da branch em revisão.
Porque
Se o PR trouxesse as próprias regras, bastava ele se declarar de baixo risco para escapar de tudo. Regra precisa morar em lugar que o PR não alcança, senão ela não é regra.
Preço que pago
Mudar as regras exige um PR próprio para a main, revisado sob as regras antigas. Apertar a configuração é mais lento do que parece.

05. O terceiro resultado é "precisa de humano", não um segundo tipo de falha

Escolhi
Três resultados em vez de dois.
Em vez de
Só passou ou falhou.
Porque
Um PR pode estar inteiramente correto e ainda merecer leitura cuidadosa, por causa de onde ele mexe e não do que ele faz. Transformar isso em falha ensina o time a mesclar por cima de falha, e transformar em passou esconde o caso.
Preço que pago
Alguém precisa realmente ler esses. A ferramenta move o trabalho de lugar, ela não elimina o trabalho.

06. Duas permissões: ler o código e comentar

Escolhi
A ferramenta não consegue alterar nada no repositório.
Em vez de
Dar acesso de escrita para ela corrigir ou mesclar sozinha.
Porque
Ferramenta de revisão com acesso de escrita é uma porta nova para dentro do repositório, e ela roda em todo PR, inclusive nos que vêm de desconhecidos. Quem aplica a regra é a proteção de branch do GitHub, não a ferramenta.
Preço que pago
A ferramenta não consegue se impor. Sem o ruleset configurado, tudo que ela diz é opinião e pode ser ignorado, inclusive por um agente fazendo push direto na main.

07. Action fixada em commit, credencial não persistida, nenhuma chave para fork

Escolhi
O checkout é fixado pelo hash do commit em vez da tag, com persist-credentials desligado, e PR vindo de fork nunca recebe a chave de API.
Em vez de
Usar a tag da action e as configurações padrão.
Porque
Tag pode ser movida. Uma action referenciada por tag pode ser trocada por baixo de você, e ela roda dentro de um job que tem token. E PR de fork é escrito por gente que você não conhece: chave entregue a um fork é chave entregue.
Preço que pago
Hash fixado precisa ser atualizado na mão, e um hash desatualizado é um problema de segurança por conta própria.

5. O que quebra

O que está mal resolvido, incluindo o que o próprio README declara.

A ferramenta não consegue se impor

Proteger a branch é passo manual nas configurações do GitHub, e o README diz isso com todas as letras: sem o ruleset, qualquer um, inclusive um agente de IA, faz push direto na main e pula a revisão inteira. A parte mais importante do sistema é a única que ele não controla.

A lista de risco é escrita à mão

Caminho sensível que ninguém listou é caminho de baixo risco. A qualidade da ferramenta inteira depende de uma lista que alguém precisa lembrar de manter atualizada, e lista desatualizada não reclama.

As varreduras pegam o que já é conhecido

O gitleaks acha padrão de segredo conhecido e o cargo-audit acha vulnerabilidade já publicada. Formato de segredo novo e vulnerabilidade ainda não divulgada passam, e o resultado verde não distingue entre não ter problema e não ter encontrado.

O descarte de achado não deixa rastro

Jogar fora achado que aponta para linha fora do PR é o padrão certo e descarta coisa real junto. Como não existe registro do que foi descartado, não dá para saber com que frequência isso acontece nem se o critério está calibrado.

O cargo-audit só serve para Rust

Num projeto que não é Rust, essa etapa não faz nada, e a ferramenta não avisa. O relatório fica com aparência de completo sendo que uma das verificações não rodou de verdade.

PR grande recebe revisão parcial com cara de completa

A etapa de IA tem limite de token e três rodadas. Um PR grande bate no limite, e o comentário final não distingue entre revisão que cobriu tudo e revisão que parou no meio.

Nada garante que o "precisa de humano" foi lido

O resultado do meio só funciona se alguém de fato ler com atenção. A ferramenta não tem como saber se isso aconteceu, e time sob pressão mescla o amarelo do mesmo jeito que mescla o verde.

6. O que eu mudaria em 100x

Cenário: 100 repositórios, centenas de pull requests por dia e vários times usando a mesma instalação.

O que sobrevive sem mudar nada

A ordem das etapas e a proibição da IA aprovar. As duas são regras, não infraestrutura: valem igual com um repositório ou com cem, e são exatamente a parte que impede a conta de explodir e o sistema de ser enganado.

O que quebra primeiro

A lista de risco escrita à mão. Com 100 repositórios são 100 listas, cada uma mantida por quem lembrar, e todas envelhecendo em ritmos diferentes. A ferramenta continua funcionando e passa a julgar errado sem avisar.

Na ordem em que eu mudaria

  1. 1

    Deduzir o risco em vez de declarar. Caminho que já apareceu em incidente, ou do qual muito código depende, é de alto risco esteja ou não escrito na lista. A lista declarada vira exceção, não fonte.

  2. 2

    Centralizar a configuração com exceção por repositório, para uma regra de segurança ser mudada em um lugar em vez de em cem pull requests.

  3. 3

    Orçar a etapa de IA no nível da organização, não por PR. Três rodadas por PR é limite razoável para um repositório e não significa nada em centenas: o controle real é teto de gasto, com a revisão cara indo primeiro para os PRs mais arriscados.

  4. 4

    Medir o que a ferramenta deixa passar. Hoje não existe retorno nenhum: bug que chegou em produção depois de um resultado verde não deixa marca na ferramenta. Ligar o incidente de volta ao PR que o causou é o que transforma a lista de risco de chute em dado.

Esta página descreve o sistema como ele está hoje, incluindo o que ainda não está resolvido. A ferramenta lê o código e comenta no pull request, e não consegue alterar nada no repositório.