Revisão de Código

Um pull request no order muda o checkout para que ele confirme a reserva do assento com um único comando SQL, em vez de uma chamada HTTP ao inventory — "é mais rápido". O código compila, os testes passam e o revisor, às 18h40 de uma sexta-feira, aprova. Três semanas depois, durante uma abertura de vendas, o inventory muda sua tabela de reservas e o checkout quebra. A regra violada — um schema por serviço — estava escrita numa página da wiki que ninguém abria. Um revisor que tivesse lido essa página, toda vez, em todo PR, teria pegado o problema.

Essa é a promessa da revisão de código por IA: um revisor que lê cada diff em minutos, nunca se cansa e pode ser informado das regras do time. Esta página trata de transformar essa promessa em uma ferramenta em que as pessoas realmente confiem.

Por que revisão de código, e para que ela serve

A revisão de código moderna — uma revisão leve, apoiada em ferramentas, de cada mudança antes do merge — é praticamente universal na indústria. Estudos na Microsoft e no Google concluíram que seus principais resultados não são apenas encontrar defeitos, mas transferência de conhecimento, propriedade coletiva do código e consistência; no Google, a latência mediana da revisão era menor que um dia, e a maioria das mudanças era pequena¹². Duas consequências para a revisão por IA:

• Um revisor de IA pode assumir parte do trabalho de encontrar defeitos e de consistência, mas não a transferência de conhecimento: um humano ainda precisa ler o código para aprendê-lo.
• A latência da revisão importa. O primeiro olhar humano costuma esperar horas; uma revisão por IA em dois minutos dá ao autor algo para corrigir antes de o humano chegar, e a revisão humana fica mais curta.

Em que a revisão por IA é boa e em que é ruim

Duas fraquezas sistemáticas merecem nome. Credulidade: o modelo lê texto escrito pelo autor — descrição do PR, comentários no código — e pode ser conduzido por ele ("isto foi aprovado pela segurança"); veja prompt injection. Ruído plausível: um modelo que recebe o pedido de revisar vai encontrar alguma coisa; sem permissão explícita para não retornar nada, ele enche a revisão com observações de estilo e repetições do código.

Anatomia de um revisor de IA

sequenceDiagram
    autonumber
    participant GH as Host Git
    participant R as Job do revisor
    participant Ctx as Montador de contexto
    participant GW as LLM gateway
    participant Post as Publicador
    GH->>R: PR aberto / novo push
    R->>Ctx: diff + metadados do PR
    Ctx->>Ctx: numera linhas, filtra arquivos, orça tokens
    Ctx->>Ctx: adiciona convenções, ADRs, responsáveis, código relacionado
    Ctx->>GW: system (estável, em cache) + user (dados não confiáveis)
    GW-->>R: achados em JSON (validados pelo schema)
    R->>R: filtro: linhas alteradas, severidade, confiança, dedup, teto
    R->>Post: achados a publicar
    Post->>GH: uma revisão com comentários inline
    Post->>GH: métricas: tokens, US$, mantidos vs. descartados

O modelo é uma caixa entre oito. A maior parte da engenharia — e a maior parte da qualidade — está no montador de contexto e no filtro.

Engenharia de contexto

Um modelo só consegue revisar contra aquilo que recebe. Engenharia de contexto é decidir o que entra na janela de contexto, limitada e paga, e em que ordem.

Três regras práticas:

1. Ordene pensando no cache. Coloque o conteúdo estável primeiro (instruções, convenções, ADRs) e o conteúdo de cada execução por último (diff). O prompt caching é uma correspondência de prefixo: se a parte estável for idêntica byte a byte, as revisões repetidas a leem por uma fração do preço (LLM gateway).
2. Orce, não trunque. Um PR de 5.000 linhas não cabe — e não deveria ser revisado como um único bloco. Mantenha arquivos inteiros por prioridade (código de produção antes de testes, antes de configuração), liste na revisão os arquivos pulados, ou divida: uma chamada por arquivo ou por serviço (map) e depois uma chamada para juntar e deduplicar (reduce). Cortar um diff no meio produz absurdos confiantes sobre código que o modelo nunca viu.
3. Escreva as convenções primeiro para humanos. Se uma regra não é clara para um engenheiro novo, não é clara para o modelo. Uma regra que precisa de um parágrafo de nuances costuma funcionar melhor como verificação determinística (abaixo).

Saída estruturada, publicada como comentários de revisão

Texto livre é para humanos; o pipeline precisa de dados. Peça um JSON que seja validado contra um schema — no Claude, as structured outputs restringem a resposta ao schema; em outros provedores, modo JSON mais validação e uma tentativa de reparo:

{
  "summary": "Adds direct SQL access from order to the inventory schema.",
  "findings": [
    {
      "file": "services/order/src/main/java/boxoffice/order/OrderService.java",
      "line": 21,
      "severity": "blocker",
      "category": "architecture",
      "confidence": "high",
      "title": "order writes to the inventory schema",
      "explanation": "CONVENTIONS.md: a service reads and writes only its own schema. This UPDATE couples order to inventory's table layout and bypasses inventory's locking, so a hold can be confirmed after it expired.",
      "suggestion": "Call InventoryClient.confirmHold(holdId) and handle 409 Conflict."
    }
  ]
}

No GitHub, todos os achados de uma execução vão para uma revisão (POST /repos/{owner}/{repo}/pulls/{number}/reviews com um array comments de path, line, side), de modo que o autor recebe uma notificação, e não doze³. Um evento de revisão COMMENT mantém o bot consultivo; é o código — não o modelo — que escolhe esse evento.

Controle de ruído

Cada comentário gasta a atenção de um desenvolvedor. Um revisor é julgado pelos seus piores comentários: depois de alguns inúteis, as pessoas param de ler — inclusive os úteis. Os controles, na ordem em que atuam:

Os limiares trocam precisão (a fração dos comentários publicados que são úteis) por recall (a fração dos problemas reais encontrados). A tabela usa uma amostra rotulada ilustrativa de 100 PRs — o modelo emitiu 60 achados de confiança alta, 90 de média e 150 de baixa, dos quais 48, 45 e 30 eram problemas reais, de um total de 150 problemas reais:

Publicar tudo encontra a maior parte dos problemas e é ignorado por todo mundo (3 comentários por PR, 4 em cada 10 úteis). Publicar só os de confiança alta gera confiança e deixa passar dois terços dos problemas. A maioria dos times começa com alta + média para severidades ≥ minor, mede e ajusta por categoria: segredos e SQL injection podem ficar em média; estilo nunca é publicado.

def review(diff: str, title: str, body: str, root: Path = Path(".")):
    """Review a diff: (summary, kept findings, dropped [(finding, why)], usage, skipped files)."""
    files = diffutil.split_files(diff)
    files, skipped = diffutil.budget(files, MAX_DIFF_LINES)
    if not files:
        return "No reviewable changes.", [], [], Usage(model()), skipped
    numbered = "\n\n".join(diffutil.numbered(p, lines) for p, lines in files.items())
    user = (f"<untrusted_pr_title>\n{title}\n</untrusted_pr_title>\n"
            f"<untrusted_pr_description>\n{body[:4000]}\n</untrusted_pr_description>\n"
            f"<untrusted_diff>\n{numbered}\n</untrusted_diff>")
    data, usage = complete_json(load_context(root), user, SCHEMA, effort="medium")

    kept, dropped = [], []
    added = {p: diffutil.added_lines(lines) for p, lines in files.items()}
    for f in data["findings"]:
        if f["line"] not in added.get(f["file"], set()):
            dropped.append((f, "not an added line"))
        elif SEVERITIES.index(f["severity"]) < SEVERITIES.index(MIN_SEVERITY):
            dropped.append((f, f"below {MIN_SEVERITY}"))
        elif f["confidence"] == "low":
            dropped.append((f, "low confidence"))
        else:
            f["fp"] = fingerprint(f)
            kept.append(f)
    kept.sort(key=lambda f: (-SEVERITIES.index(f["severity"]), f["confidence"] != "high"))
    for f in kept[MAX_COMMENTS:]:
        dropped.append((f, f"over the limit of {MAX_COMMENTS} comments"))
    return data["summary"], kept[:MAX_COMMENTS], dropped, usage, skipped
    try:
        summary, kept, dropped, usage, skipped = review(diff, title, body)
    except LLMError as err:
        step_summary(f"### AI review skipped\n\n{err}")
        return 0                      # fail open: an AI outage must not block merges

Consultivo ou gate?

Uma implantação segura: sombra (achados registrados, não publicados; compare com o que os humanos encontraram) → consultivo para times voluntários → gate por categoria quando a precisão estiver comprovada. Mesmo como gate, uma verificação de IA é um status check obrigatório — nunca uma aprovação. A aprovação continua humana, imposta pela proteção de branch.

Medindo o revisor

Não dá para ajustar o que não se mede, e "o time gosta" não é uma medida.

Um LLM também pode julgar comentários ("este comentário estava correto?"), o que é mais barato que rótulos humanos — mas o LLM como juiz tem vieses (tende a concordar com textos confiantes, e consigo mesmo). Use-o para triagem e calibre-o contra uma amostra rotulada por humanos.

Conformidade com a arquitetura

A história do início — o order escrevendo no schema de inventory — é uma regra de arquitetura. Essas regras são o que de mais valioso um revisor automatizado pode verificar, porque humanos as esquecem e as violações custam caro depois. Mas muitas delas não precisam de modelo algum.

@AnalyzeClasses(packages = "boxoffice.order")
class ArchitectureTest {

    @ArchTest
    static final ArchRule no_direct_kafka_outside_outbox =
        noClasses().that().resideOutsideOfPackage("..outbox..")
            .should().dependOnClassesThat().haveSimpleName("KafkaTemplate")
            .because("ADR-0004: events are published through the transactional outbox");
}

O melhor projeto combina os dois: regras determinísticas bloqueiam, porque são exatas; o revisor de IA explica e pega o que as regras não conseguem expressar, e seus achados recorrentes viram candidatos a novas regras determinísticas. De novo, defesa em profundidade — e o usuário de banco do order sem grants em inventory.* é a última camada, que não depende de revisor nenhum.

Como se conecta

flowchart LR
    PR["pull request event"] --> CTX["context: diff, conventions,<br/>ADRs, symbol search"]
    CTX --> RET["retrieval<br/>→ AI systems RAG & Memory"]
    CTX --> LLM["model call<br/>→ LLM gateway, prefix cache"]
    LLM --> OUT["structured findings<br/>(JSON schema)"]
    OUT --> NOISE["noise control: changed lines,<br/>confidence, dedup, cap"]
    NOISE --> GATE{"advisory<br/>or gate?"}
    GATE --> PREC["precision + golden set<br/>→ AI systems safety & evals"]
    ARCH["architecture rules:<br/>deterministic checks first"] --> OUT
    PR --> INJ["PR text is untrusted<br/>→ Security & governance"]

Componentes da paleta: orchestrator (o job do revisor em volta do modelo) · llmgw (roteamento, cotas, prefixo em cache com convenções e ADRs) · memory (o contexto montado para cada diff) · safety (texto do PR não confiável, saída validada) · metrics (precisão e comentários por PR). Cenários: nenhum específico. Continua em: Sistemas de IA — RAG e memória, Sistemas de IA — LLM Gateway, Sistemas de IA — segurança e avaliações, Segurança e governança, Hands-on 13 — o revisor.