Revisão com IA

A forma de uma revisão

Uma revisão com IA é uma execução do pipeline pr_review predefinido contra uma pull request aberta. O pipeline abre o espaço de revisão da PR, distribui agentes revisores para ler o diff no checkout isolado desse espaço, cada um registra seus achados como nós de revisão estruturados, um agente líder os consolida em um passo a passo e um finalizador calcula um único veredito: Ship, Hold ou Block. O que o pipeline nunca faz é publicar — publicar no GitHub é um passo separado e deliberado que uma pessoa dá.

O restante desta página explica as peças e por que elas têm esse formato.

Um espaço de revisão por PR

O contexto de revisão de uma PR é um espaço de mensagens — modo review, tipo pr — ligado à pull request por uma associação de espaço de revisão. Ele é criado de forma idempotente: a página da PR, o pipeline de revisão e as superfícies de chat resolvem o único espaço de apoio da PR pelo mesmo caminho de código, então um modelo que revisa uma PR e uma pessoa que a abre nunca podem acabar em duas salas diferentes olhando para dois checkouts diferentes.

O worktree isolado do espaço tem a PR em checkout na sua ref de head. Uma sala também significa um checkout: cada revisor trabalha no mesmo espaço, em vez de cada um receber seu próprio clone do espaço de trabalho.

Cada revisor publica em seu próprio fluxo nomeado dentro desse único espaço, e os achados são mensagens review_node, não prosa solta. A coleta em todo o espaço no final é intencional — um veredito calculado a partir dos achados de uma única thread seria, silenciosamente, um veredito sobre um único revisor.

A associação carrega uma escada de status — requested → in progress → awaiting approval → completed — e é ela que condiciona o botão Publicar no GitHub na aba Revisão da PR.

Níveis de revisão

Até onde uma revisão vai é uma política do espaço de trabalho com três níveis, definida em Configurações → Espaço de trabalho → Geral, no cartão Política do espaço de trabalho:

Nível	Revisores distribuídos	Relato
light	Apenas engenheiro	Só o que realmente importa
balanced	Engenheiro, QA, arquiteto (o padrão)	A passagem padrão
thorough	Todos os cinco, incluindo segurança e desempenho	Nada rebaixado

O nível move dois controles ao mesmo tempo: quais revisores são distribuídos, imposto pelos portões de estado runWhen do modelo de pipeline, e não pelo texto do prompt — o texto do prompt pode ser ignorado, um portão não —, e onde os achados abaixo do limite são exibidos. Nenhum dos controles exclui um achado: um nível que relata menos ainda registra exatamente a mesma quantidade e agrupa o restante.

As passagens de segurança e desempenho reutilizam os agentes arquiteto e engenheiro predefinidos, em vez de introduzir novos. A especialidade é o briefing com que o revisor é despachado, não um agente separado por eixo — um agente por eixo seriam cinco linhas a mais em cada espaço de trabalho sem nenhuma capacidade adicional. A seleção de revisores nunca inspeciona o diff em busca de linguagem ou domínio.

Nós de revisão: achados como dados, não como prosa

Um achado registrado com add_review_node se torna um nó de revisão na PR — é o que a aba Revisão exibe, a partir do que o veredito é calculado e o que “Publicar no GitHub” transforma em um comentário em linha. Um revisor que só retorna prosa produz uma execução de pipeline que parece bem-sucedida e uma superfície de revisão vazia; o registro é a parte que sustenta tudo.

Cada nó carrega:

Campo	Valores
Tipo	bug, suggestion, recommendation, question, ticket
Prioridade	P0 (crítico) → P3 (detalhe)
Trio de triagem	categoria (security, stability, …), severidade, esforço
Âncora	Caminho do arquivo, início e fim da linha
Transporte da correção	Linhas de substituição sugeridas, um diff opcional, um prompt de correção opcional
Confiança	Uma pontuação [0, 1]
Raciocínio	A análise, escrita antes do achado

Dois detalhes são intencionais. Uma sugestão do GitHub com um clique só é oferecida quando o revisor forneceu linhas de substituição exatas — inferi-las de um diff unificado dá errado em silêncio, e um commit com um clique de uma inferência errada é pior do que nenhum botão. E o esquema de add_review_node apresenta reasoning antes do achado, então um modelo que preenche o objeto na ordem do esquema escreve a análise primeiro. O campo é opcional: omiti-lo não rejeita o nó. Um nó cujo payload está malformado desaparece, em vez de poluir a revisão.

Consenso entre pares

Um nó passa por open → consensus-ready → resolved ou dismissed. A etapa intermediária é o coração do modelo: um achado só progride quando um revisor par o confirma, e um agente nunca pode confirmar seu próprio achado. A ferramenta MCP publish_review_to_github e o padrão do RPC ainda publicam apenas achados confirmados por pares. Já o botão Publicar no GitHub da aba Revisão envia todos os achados abertos restantes.

A regra é aplicada em três lugares independentes — a ferramenta de confirmação, o finalizador e o publicador —, então ela sobrevive a um chamador com bug em qualquer um deles. As mudanças de status passam todas por um único serviço, e é isso que faz um status significar algo: antes disso, dois caminhos pela metade podiam discordar sobre se o mesmo achado havia sido resolvido.

Quando os revisores discordam — mesmo arquivo e linha, prioridades com dois ou mais níveis de diferença, ou um chamando de bug enquanto o outro chama de suggestion —, a discordância é exibida acima da lista de achados. É aí que as opiniões dos revisores divergem e o julgamento humano vale mais.

Descartar um achado também grava um fato de supressão suave no domínio de memória, com baixa confiança — um descarte é uma preferência, não uma regra.

Coortes: em torno do que a revisão é agrupada

A passagem de computação da revisão agrupa os arquivos alterados de uma PR em coortes derivadas do grafo de código: arquivos alterados mapeiam para os símbolos que tocam, símbolos para componentes conectados, e as coortes são classificadas pelo raio de impacto. Uma coorte carrega uma ordem de leitura guiada, diagramas e insights, em vez de ser uma lista simples de arquivos.

Duas regras de honestidade moldam isso. As chaves das coortes derivam do conteúdo e são estáveis entre pushes, então os achados e o progresso da revisão sobrevivem a um rebase ou force-push em vez de ficarem órfãos. E quando o repo não tem índice de código, o agrupamento recorre a caminhos simples e o informa — o mecanismo de fallback nunca finge confiança semântica.

Eixos de revisão e portões

Além dos achados dos revisores, uma revisão acumula resultados de eixos: seis eixos, de dois tipos.

Eixo	Tipo	Origem
correctness, security	Orientado a tokens	Os achados dos próprios revisores
testGap	Orientado a tokens	Os achados dos revisores
visual, apiContract	Determinístico	Calculado sem gastar tokens
performance	Determinístico	Apenas enum — nada no produto calcula um resultado

O veredito de um eixo é pass, warn, fail, partial ou unavailable — e apenas pass ou warn libera um portão. A distinção entre fail, partial e unavailable sustenta tudo: um eixo com portão que não pôde ser concluído ou não pôde rodar de forma alguma mantém o veredito geral, em vez de liberá-lo. A ausência de evidência nunca se converte em um portão verde.

Alguns eixos são apenas consultivos de propósito. O eixo de lacuna de testes derivado das coortes não enxerga cobertura de injeção de dependência ou de fábrica — um repo sem índice com uma suíte completa e um sem nenhum teste parecem idênticos daquela perspectiva, então afirmar qualquer um dos dois seria mentira; ele aparece no painel sem atuar como portão. Os eixos de tokens são consultivos porque as prioridades dos achados já determinam o veredito, e voltar a usá-los como portão contaria em dobro.

O veredito

O finalizador calcula o veredito sobre os achados com status open ou consensus-ready:

• qualquer achado P0 com confiança ≥ 0.7 → Block
• caso contrário, qualquer P0 (de baixa confiança) ou qualquer P1 → Hold
• caso contrário → Ship

O veredito carrega uma confiança agregada derivada da dispersão das confianças contribuintes — a concordância a eleva, a divergência a reduz.

A consolidação do agente líder (CEO) é uma passagem editorial, não uma re-listagem: uma segunda cópia escrita à mão dos achados é exatamente o que se desvia da real. Achados duplicados são rebaixados em vez de repetidos — vários revisores apontam para um único diff com escopos deliberadamente sobrepostos, então o mesmo defeito chegando três vezes ao finalizador é o sistema funcionando; publicá-lo três vezes é o sistema vazando sua própria arquitetura para a caixa de entrada do leitor. Em uma nova revisão, os achados recebem impressão digital e são comparados com a rodada anterior, então o delta é o que aparece.

Por fim, os eixos entram em cena, e eles só podem tornar o veredito mais severo: um eixo com portão em falha força Block — ele não pode ser vencido por votos dos achados —, e um eixo com portão que não pôde ser concluído força no mínimo Hold.

A publicação continua com você

O pipeline deliberadamente não publica no GitHub; a publicação depende do usuário, de modo que uma revisão nunca possa publicar em duplicidade. Quando você clica em Publicar no GitHub:

• Uma revisão do GitHub é enviada. Achados já resolvidos ou descartados são ignorados. O botão publica todos os achados abertos restantes (selection: all_open). A ferramenta MCP publish_review_to_github ainda usa por padrão apenas achados confirmados por pares (consensus).
• Achados ancorados a um arquivo e linha viram comentários em linha; todo o resto é incorporado ao corpo do resumo, cada um trazendo um rodapé “— Control Center AI review” para que a origem seja inequívoca.
• As âncoras são reverificadas em relação ao diff atual da PR no momento da publicação. Um comentário sobre código que já foi reescrito é a coisa mais destruidora de confiança que um revisor pode deixar; se o GitHub rejeitar uma âncora em linha mesmo assim, a revisão inteira é reenviada com todos os achados incorporados ao corpo, para que nada seja descartado em silêncio.
• Um veredito Block é enviado como REQUEST_CHANGES; Hold como COMMENT; Ship como APPROVE a partir do botão (approve_on_ship: true). A ferramenta MCP deixa Ship como COMMENT, a menos que você passe approve_on_ship.
• A revisão é publicada sob a identidade do app do servidor. Quem clicou em Publicar fica registrado para o portão de função e o log de auditoria; não é o autor no GitHub.

A publicação declara a classe de ação prPublish, então o ponto de estrangulamento das barreiras a condiciona como qualquer ação mutante — ela solicita confirmação por padrão e, quando nenhum aprovador está conectado, falha fechada. Consulte Barreiras.

O que um revisor pode fazer

Os agentes revisores rodam no modo review: um sandbox somente leitura e uma lista de permissões de ferramentas curada que cobre achados, comentários, tickets e revisão por pares — mas nenhuma mutação. Um revisor não pode corrigir o código que critica; ele pode anexar uma correção sugerida que uma pessoa aplica. A mensagem de recusa do modo diz a um agente que tenta agir mesmo assim para finalizar a revisão e deixar o usuário agir sobre o resumo publicado.

Conceitos relacionados

• Barreiras — o mecanismo de políticas que condiciona a publicação
• Modos — o que o modo review muda para um agente
• Pipelines e automação — o mecanismo sobre o qual a revisão roda
• Ciclo de vida do despacho de agentes — de onde vem o worktree isolado

Guias relacionados

• Usar revisão com IA — execute uma revisão e publique-a
• Despachar agentes revisores — escolha os revisores você mesmo
• Computação de revisão — coortes, eixos e diffs