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 regista as suas constatações como nós de revisão estruturados, um agente líder consolida-as num percurso guiado e um finalizador calcula um único veredicto: Ship, Hold ou Block. O que o pipeline nunca faz é publicar — publicar no GitHub é um passo separado e deliberado que uma pessoa dá.

O resto desta página explica as peças e porque é que têm esta forma.

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. É 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 suporte da PR pelo mesmo caminho de código, por isso um modelo que revê uma PR e uma pessoa que a abre nunca podem acabar em duas salas diferentes a olhar para dois checkouts diferentes.

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

Cada revisor publica no seu próprio fluxo nomeado dentro desse único espaço, e as constatações são mensagens review_node em vez de prosa solta. A recolha que abrange todo o espaço no fim é intencional — um veredicto calculado a partir das constatações de um único fio seria, silenciosamente, um veredicto sobre um único revisor.

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

Níveis de revisão

Até onde vai uma revisão é 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 que são distribuídos	Relato
light	Apenas engenheiro	Só o que importa de facto
balanced	Engenheiro, QA, arquiteto (a predefinição)	A passagem habitual
thorough	Todos os cinco, incluindo segurança e desempenho	Nada rebaixado

O nível move dois controlos 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 as constatações abaixo do limite são apresentadas. Nenhum dos controlos elimina alguma vez uma constatação: um nível que relata menos regista exatamente a mesma quantidade e agrupa o resto.

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

Nós de revisão: constatações como dados, não como prosa

Uma constatação registada com add_review_node torna-se um nó de revisão na PR — é o que o separador Revisão apresenta, aquilo a partir do que o veredicto é calculado e aquilo em que “Publicar no GitHub” se transforma num comentário em linha. Um revisor que só devolve prosa produz uma execução de pipeline que parece bem-sucedida e uma superfície de revisão vazia; o registo é a parte que sustenta tudo.

Cada nó transporta:

Campo	Valores
Tipo	bug, suggestion, recommendation, question, ticket
Prioridade	P0 (crítico) → P3 (pormenor)
Trio de triagem	categoria (security, stability, …), severidade, esforço
Âncora	Caminho do ficheiro, 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 da constatação

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 a partir de um diff unificado corre mal em silêncio, e um commit com um clique de uma inferência errada é pior do que não existir botão nenhum. E o esquema de add_review_node apresenta reasoning antes da constatação, para que um modelo que preenche o objeto pela ordem do esquema escreva primeiro a análise. O campo é opcional: omiti-lo não rejeita o nó. Um nó cujo payload esteja malformado desaparece em vez de poluir a revisão.

Consenso entre pares

Um nó percorre open → consensus-ready → resolved ou dismissed. O passo intermédio é o cerne do modelo: uma constatação só progride quando um revisor par a confirma, e um agente nunca pode confirmar a sua própria constatação. A ferramenta MCP publish_review_to_github e a predefinição do RPC continuam a publicar apenas constatações confirmadas por pares. Já o botão Publicar no GitHub do separador Revisão envia todas as constatações abertas restantes.

A regra é aplicada em três locais independentes — a ferramenta de confirmação, o finalizador e o publicador —, por isso sobrevive a um chamador com bugs em qualquer um deles. As mudanças de estado passam todas por um único serviço, e é isso que faz com que um estado signifique algo: antes disso, dois meios-caminhos podiam discordar sobre se a mesma constatação estava resolvida.

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

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

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

A passagem de computação da revisão agrupa os ficheiros alterados de uma PR em coortes derivadas do grafo de código: os ficheiros alterados mapeiam para os símbolos que tocam, os símbolos para componentes ligados entre si, e as coortes são ordenadas pelo raio de impacto. Uma coorte transporta uma ordem de leitura guiada, diagramas e informações relevantes em vez de ser uma lista simples de ficheiros.

Duas regras de honestidade moldam isto. As chaves das coortes derivam do conteúdo e são estáveis entre pushes, pelo que as constatações 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 di-lo — o mecanismo de recurso nunca simula confiança semântica.

Eixos de revisão e portões

A par das constatações dos revisores, uma revisão acumula resultados de eixos: seis eixos, de dois tipos.

Eixo	Tipo	Origem
correctness, security	Orientado por tokens	As próprias constatações dos revisores
testGap	Orientado por tokens	As constatações dos revisores
visual, apiContract	Determinístico	Calculado sem gastar tokens
performance	Determinístico	Apenas enum — nada no produto calcula um resultado

O veredicto de um eixo é pass, warn, fail, partial ou unavailable — e só pass ou warn abre um portão. A distinção entre fail, partial e unavailable é essencial: um eixo com portão que não conseguiu concluir-se ou que não conseguiu sequer ser executado retém o veredicto global em vez de o libertar. A ausência de provas nunca se converte num portão verde.

Alguns eixos são consultivos de propósito. O eixo de lacunas de testes derivado das coortes não consegue ver cobertura de injeção de dependências ou de fábricas — um repo sem índice com um conjunto de testes completo e outro sem teste nenhum parecem idênticos daquela perspetiva, por isso afirmar qualquer delas seria uma mentira; aparece no painel sem funcionar como portão. Os eixos de tokens são consultivos porque as prioridades das constatações já determinam o veredicto, e voltar a usá-los como portão contaria em dobro.

O veredicto

O finalizador calcula o veredicto sobre as constatações com estado open ou consensus-ready:

• qualquer constatação 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 veredicto transporta uma confiança agregada derivada da dispersão das confianças que contribuem — a concordância aumenta-a, a divergência reduz-lhe.

A consolidação do agente líder (CEO) é uma passagem editorial, não uma nova listagem: uma segunda cópia das constatações escrita à mão é exatamente aquilo que se desvia da verdadeira. As constatações duplicadas são rebaixadas em vez de repetidas — vários revisores são apontados a um único diff com âmbitos deliberadamente sobrepostos, por isso o mesmo defeito a chegar três vezes ao finalizador é o sistema a funcionar; publicá-lo três vezes é o sistema a deixar escapar a sua própria arquitetura para a caixa de entrada de quem lê. Numa nova revisão, as constatações recebem uma impressão digital e são comparadas com a ronda anterior, pelo que o que aparece é o delta.

Por fim, os eixos entram em jogo, e só podem tornar o veredicto mais severo: um eixo com portão em falha força Block — não pode ser derrotado por votos das constatações —, e um eixo com portão que não conseguiu concluir-se força, no mínimo, Hold.

A publicação continua nas tuas mãos

O pipeline não publica deliberadamente no GitHub; a publicação depende do utilizador, para que uma revisão nunca possa publicar em duplicado. Quando primes Publicar no GitHub:

• É submetida uma revisão do GitHub. As constatações já resolvidas ou descartadas são ignoradas. O botão publica todas as constatações abertas restantes (selection: all_open). A ferramenta MCP publish_review_to_github continua a usar por predefinição apenas constatações confirmadas por pares (consensus).
• As constatações ancoradas a um ficheiro e a uma linha tornam-se comentários em linha; tudo o resto é integrado no corpo do resumo, transportando cada uma 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 que mais destrói a confiança que um revisor pode deixar; se, mesmo assim, o GitHub rejeitar uma âncora em linha, toda a revisão é reenviada com cada constatação integrada no corpo, para que nada seja descartado em silêncio.
• Um veredicto Block é submetido 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 passes approve_on_ship.
• A revisão é publicada sob a identidade da aplicação do servidor. Quem premiu Publicar é registado para o portão de funções e o registo de auditoria; não é o autor no GitHub.

A publicação declara a classe de ação prPublish, por isso o ponto de estrangulamento das barreiras condiciona-a como qualquer ação mutável — pede confirmação por predefinição e falha em modo fechado quando não há nenhum aprovador ligado. Ver Barreiras.

O que um revisor pode fazer

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

Conceitos relacionados

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

Guias relacionados

• Usar revisão com IA — executa uma revisão e publica-a
• Despachar agentes revisores — escolhe tu os revisores
• Computação de revisão — coortes, eixos e diffs