A Resposta Curta é Não, mas a Resposta Longa Economiza Horas

Uma inspeção Fagan completa precisa de um moderador, um leitor, dois a quatro inspetores e o autor. A equipe gasta duas horas revisando aproximadamente 250 linhas de código a 125 linhas por hora. São oito a doze horas-homem para uma pequena mudança.

Um LLM pode ler 250 linhas em menos de um segundo. Pode executar uma checklist, sinalizar padrões suspeitos e gerar um log de defeitos antes de qualquer humano abrir o arquivo.

Isso não significa que pode substituir a equipe. Significa que a equipe não deve começar a reunião até que o LLM tenha terminado a lição de casa.

O que um LLM Realmente Pode Fazer em uma Inspeção Fagan

Inspeções Fagan têm quatro papéis distintos. Cada papel tem uma tarefa que se mapeia de forma diferente para o que um LLM pode e não pode fazer.

O moderador planeja a inspeção, impõe critérios de entrada e mantém a reunião nos trilhos. Um LLM pode gerar uma checklist, verificar se os testes passam antes da inspeção e estimar o tempo com base na contagem de linhas. Ele não pode dizer se uma sala cheia de engenheiros está derivando para um debate de design. O papel do moderador é social, e LLMs não são sociais.

O leitor parafraseia o código em voz alta durante a reunião para forçar o grupo a processar a lógica na velocidade de compreensão, e não na velocidade de leitura rápida. Um LLM pode resumir código, mas não pode fazer uma sala de humanos desacelerar. O valor real do leitor é a imposição social. O LLM não tem alavancagem.

Os inspetores encontram defeitos examinando o código contra checklists e conhecimento de domínio. É aqui que o LLM é mais útil. Ele pode verificar null dereferences, vazamentos de recursos, caminhos de erro não tratados e erros off-by-one mais rápido que qualquer humano. Ele não fica cansado. Ele não pula as funções utilitárias chatas porque parecem seguras.

O autor responde perguntas e corrige defeitos. O LLM não pode substituir o autor porque não escreveu o código e não pode verificar a intenção.

Então a resposta realista não é substituição. É substituição de papel. O LLM pode servir como um pré-inspetor incansável que lida com as partes mecânicas do papel de inspetor antes dos humanos entrarem na sala.

Onde os LLMs Realmente Ajudam: A Fase de Preparação

A fase mais importante de uma inspeção Fagan é a preparação. Cada inspetor revisa o material sozinho antes da reunião. Estudos mostram que a preparação encontra aproximadamente metade dos defeitos descobertos no processo completo. Se o LLM puder potencializar essa fase, a reunião humana fica mais curta e mais afiada.

Aqui está uma abordagem prática. Alimente o LLM com o código, uma checklist adaptada à sua linguagem e um prompt que force uma saída estruturada. Use a saída do LLM como ponto de partida para inspetores humanos, não como substituto.

O prompt importa mais que o modelo. Um pedido vago como “revisa este código” vai te dar platitudes genéricas. Um prompt estruturado com checklist e formato de saída vai te dar defeitos acionáveis.

Abaixo está um script Python que executa uma pré-inspeção baseada em LLM usando uma API compatível com OpenAI. Ele lê um arquivo fonte, aplica uma checklist no estilo Fagan e gera um log de defeitos estruturado.

#!/usr/bin/env python3
"""
LLM pre-inspection for Fagan-style review.
Produces structured defect log from a checklist.
"""

import argparse
import os
from pathlib import Path


def build_prompt(code: str, filepath: str, language: str) -> str:
    checklist = {
        "python": [
            "Missing null/None checks before dereferencing",
            "Unclosed file handles or missing context managers",
            "Bare except clauses that swallow exceptions",
            "Mutable default arguments in function signatures",
            "Race conditions in shared mutable state",
            "Missing input validation on public functions",
        ],
        "typescript": [
            "Non-null assertions (e.g., !) without justification",
            "Missing await on async calls",
            "Any types that should be narrowed",
            "Unhandled promise rejections",
            "Missing input validation on public functions",
        ],
        "rust": [
            "Unwrap or expect without comment explaining invariants",
            "Missing error propagation where Result is returned",
            "Unsafe blocks without safety comments",
            "Clone on large data structures in hot paths",
            "Missing input validation on public functions",
        ],
    }

    items = checklist.get(language, checklist["python"])
    checklist_text = "\n".join(f"  - {item}" for item in items)

    return (
        "You are a Fagan inspection assistant. Review the following code "
        "against the checklist. For each defect found, output a JSON object "
        "with keys: line, category, severity (minor/major/critical), description. "
        "If no defect is found for a checklist item, omit it. "
        "Be specific about line numbers and exact variable names. "
        "Do not suggest fixes. Fagan inspections only log defects, they do not solve them.\n\n"
        f"File: {filepath}\n"
        f"Language: {language}\n\n"
        "Checklist:\n"
        f"{checklist_text}\n\n"
        "Code:\n```\n"
        f"{code}\n"
        "```\n\n"
        "Output strict JSON array of defects only. No markdown, no preamble."
    )


def inspect_file(filepath: str, api_key: str, base_url: str) -> list:
    """Run LLM pre-inspection and return parsed defect list."""
    from openai import OpenAI

    path = Path(filepath)
    code = path.read_text()

    # Infer language from extension
    ext_map = {
        ".py": "python",
        ".ts": "typescript",
        ".tsx": "typescript",
        ".rs": "rust",
    }
    language = ext_map.get(path.suffix, "python")

    client = OpenAI(api_key=api_key, base_url=base_url)
    response = client.chat.completions.create(
        model=os.environ.get("INSPECTION_MODEL", "gpt-4.1-mini"),
        messages=[
            {"role": "system", "content": "You are a precise code inspection tool."},
            {"role": "user", "content": build_prompt(code, filepath, language)},
        ],
        temperature=0.2,
        max_tokens=2048,
    )

    raw = response.choices[0].message.content.strip()

    # Some models wrap JSON in markdown fences. Strip them.
    if raw.startswith("```json"):
        raw = raw[7:]
    if raw.startswith("```"):
        raw = raw[3:]
    if raw.endswith("```"):
        raw = raw[:-3]
    raw = raw.strip()

    import json
    try:
        defects = json.loads(raw)
        if not isinstance(defects, list):
            return []
        return defects
    except json.JSONDecodeError:
        print("Warning: LLM returned non-JSON output:")
        print(raw[:500])
        return []


def main():
    parser = argparse.ArgumentParser(description="LLM pre-inspection for Fagan review")
    parser.add_argument("files", nargs="+", help="Source files to pre-inspect")
    parser.add_argument("--api-key", default=os.environ.get("OPENAI_API_KEY"))
    parser.add_argument(
        "--base-url",
        default=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
    )
    args = parser.parse_args()

    if not args.api_key:
        raise SystemExit("Error: set OPENAI_API_KEY or pass --api-key")

    all_defects = []
    for f in args.files:
        defects = inspect_file(f, args.api_key, args.base_url)
        all_defects.extend({"file": f, **d} for d in defects)

    if not all_defects:
        print("No defects flagged by LLM pre-inspection.")
        return

    print(f"LLM pre-inspection found {len(all_defects)} defect(s):\n")
    for d in all_defects:
        print(
            f"[{d['severity'].upper()}] {d['file']}:{d.get('line', '?')} "
            f"({d['category']}) {d['description']}"
        )


if __name__ == "__main__":
    main()

Instale o SDK da OpenAI com pip install openai, configure sua chave de API e execute python inspect.py src/auth.py. O script produz um log de defeitos estruturado que inspetores humanos podem usar como sua checklist inicial.

Isso não é a inspeção. É a preparação. Os defeitos ainda precisam de julgamento humano.

O que os LLMs Perdem: Os Defeitos que Custam Dinheiro Real

Os defeitos mais caros não são erros de sintaxe. São suposições erradas.

Um LLM vai pegar o null check faltante. Ele não vai perceber que o caso null nunca deveria acontecer porque o serviço upstream garante o campo, e o bug real é que sua equipe mudou o contrato três semanas atrás e esqueceu de atualizar o código downstream.

Um LLM vai sinalizar uma exceção não tratada. Ele não vai notar que o handler de exceção está faltando porque o autor assumiu que a transaction do banco de dados faria rollback automaticamente, e essa suposição é falsa para o nível de isolamento específico que sua equipe usa.

Esses são defeitos em nível de intenção. Eles exigem conhecimento de domínio, contexto histórico e a capacidade de perguntar “o que o autor assumiu que não é verdade?” Um LLM não tem acesso às suposições não documentadas da sua equipe. Não tem memória da decisão de arquitetura do trimestre passado. Não pode olhar um documento de requisitos e notar que o código implementa o requisito errado.

Inspeções Fagan foram projetadas para pegar exatamente esses defeitos. Os inspetores humanos trazem modelos mentais e contextos diferentes. Quando eles discordam sobre o que o código deveria fazer, a lacuna entre suas suposições é onde os bugs reais moram.

Um LLM tem um único modelo mental, e ele é treinado em código público, não na sua codebase.

A Troca Real: Cobertura vs. Compreensão

A pré-inspeção com LLM te dá cobertura. Ele lê cada linha, verifica cada função e nunca se distrai com uma notificação do Slack. É o inspetor estreito perfeito.

A inspeção humana te dá compreensão. Ela conecta o código à especificação, a especificação ao esquema do banco de dados e o esquema à regra de negócio que mudou na última reunião de sprint planning. É a única forma de encontrar defeitos que vivem fora do código.

A troca não é humano versus máquina. É profundo versus amplo.

Se você substituir sua equipe de inspeção por um LLM, vai encontrar mais defeitos em nível de sintaxe e perder mais defeitos em nível de intenção. O resultado líquido depende de que tipo de bugs estão te matando. Se seus incidents de produção são principalmente null dereferences e vazamentos de recursos, um LLM vai ajudar. Se seus incidents são principalmente lógica de negócio errada e casos edge perdidos, um LLM vai te dar falsa confiança.

Como Executar uma Inspeção Híbrida na Prática

Aqui está um workflow prático que usa o LLM para o que ele faz bem e preserva a equipe humana para o que só humanos podem fazer.

Antes da reunião, execute o script de pré-inspeção com LLM no código. Dê a cada inspetor humano a saída mais o código original. Exija que eles verifiquem ou descartem cada achado do LLM durante sua preparação individual. Isso os força a examinar linhas que teriam passado batido.

Durante a reunião, o leitor ainda parafraseia o código em voz alta. Os inspetores ainda levantam problemas. Mas agora eles partem de uma lista curada de defeitos mecânicos já triados. O tempo de reunião pode cair de duas horas para noventa minutos, ou a equipe pode revisar mais código na mesma janela de tempo.

O moderador ganha uma nova responsabilidade: rastrear a precisão do LLM. Registre quantos defeitos sinalizados pelo LLM eram reais, quantos eram falsos positivos e quantos defeitos exclusivamente humanos o LLM perdeu. Depois de três ou quatro inspeções, você vai saber se seu prompt de checklist precisa de ajustes.

Esse é o mesmo processo que a NASA usou quando experimentou inspeção assistida por ferramentas nos anos 1990. Verificadores automatizados encontraram os defeitos fáceis e deixaram os difíceis para os humanos. Os humanos se saíram melhor porque não estavam mentalmente exaustos de encontrar os fáceis.

A Conclusão

Um LLM não pode substituir uma equipe de inspeção completa porque inspeção não é apenas ler código. É um processo social estruturado projetado para expor lacunas entre o que o autor assumiu e o que o código realmente faz.

O que um LLM pode fazer é tornar a equipe humana mais efetiva removendo a carga mecânica. Ele pode desempenhar um quinto papel: o pré-inspetor incansável que prepara o campo de batalha antes dos humanos chegarem.

Se você está pulando inspeções porque são caras demais, um LLM não as torna gratuitas. As torna mais curtas. Isso costuma ser o suficiente.

FAQ

O que é uma inspeção Fagan?

Um processo de revisão estruturado em seis fases inventado por Michael Fagan na IBM em 1976. Usa papéis definidos (moderador, leitor, inspetores, autor), preparação individual obrigatória e reuniões com tempo limitado para encontrar defeitos antes dos testes. Relata consistentemente taxas de remoção de defeitos de 60 a 90 por cento.

Um LLM pode substituir um revisor de código humano?

Não para os defeitos que mais importam. Um LLM pega problemas mecânicos como null checks faltantes e vazamentos de recursos. Perde defeitos em nível de intenção como suposições erradas sobre contratos upstream, lógica de negócio faltante e divergências entre código e requisitos.

Como integrar um LLM em uma inspeção Fagan?

Use o LLM durante a fase de preparação. Execute-o contra uma checklist, alimente sua saída aos inspetores humanos antes da reunião e exija que verifiquem cada achado. Isso encurta a reunião e melhora o foco humano sem remover o julgamento humano.

O que torna um prompt de checklist para LLM efetivo?

Especificidade. Prompts genéricos produzem saída genérica. Prompts efetivos nomeiam categorias exatas de defeitos, exigem saída JSON estruturada, proíbem propostas de solução e pedem números de linha exatos e nomes de variáveis. A checklist deve combinar com sua linguagem e os defeitos mais comuns que sua equipe deixa escapar.

Experimente em Um Arquivo

Escolha um arquivo que causou um incident de produção no último mês. Escreva uma checklist com cinco tipos específicos de defeitos que importam para sua equipe. Execute o script acima com essa checklist. Dê a saída para dois engenheiros que não escreveram o arquivo.

Compare os achados do LLM com os achados humanos. Conte a sobreposição. Conte o que cada lado perdeu. Essa lacuna é sua resposta.