Auditoria de código com Claude Opus 5.5: valide cada achado antes do merge

Você deixa o Claude Opus 5.5 analisando um repositório por horas e recebe dezenas de achados “críticos”, talvez acompanhados por um patch enorme. A parte difícil começa agora: descobrir quais defeitos são reais, quais mudanças respeitam a arquitetura e quais correções podem entrar com segurança.

Este processo trata a saída do modelo como hipóteses de auditoria, não como conclusões. Primeiro você congela uma linha de base reproduzível; depois, cada achado precisa passar por portões de reprodução, risco, arquitetura, correção e regressão.

Use o Opus 5.5 para ampliar a auditoria, não para aprovar o merge

O modelo é uma escolha plausível para auditorias amplas e longas, mas não é um revisor independente. No anúncio de 22 de setembro de 2026, a Anthropic destacou migrações e auditorias em toda a base de código e apresentou resultados internos e de usuários iniciais. Esses dados do fornecedor não garantem o mesmo resultado no seu repositório. Leia o anúncio do Opus 5.5.

Kent C. Dodds também publicou um prompt cobrindo segurança, desempenho, acessibilidade, manutenibilidade, escalabilidade, arquitetura, documentação, testes e automação. Segundo ele, o Opus 5.5 encontrou um problema de segurança relevante que outros modelos não perceberam. A publicação, porém, não revela a falha, a reprodução nem uma comparação controlada. Isso justifica testar o fluxo, não dispensar a validação. Veja a publicação.

Portanto, a meta é produzir achados reproduzíveis, classificados e revisáveis de forma independente, e não maximizar a quantidade de alertas.

Transforme o critério de sucesso em comandos antes de começar

Sem uma linha de base limpa, você não saberá se uma falha já existia ou foi introduzida durante a auditoria. Registre o SHA atual, o ambiente, as versões relevantes, cada comando e seu código de saída.

Troque os marcadores pelos comandos reais do projeto. Quando um portão não se aplicar, marque “não aplicável” em vez de inventar uma verificação.

git status --short
<install-command>
<lint-command>
<type-check-command>
<unit-test-command>
<integration-test-command>
<build-command>

Registre pelo menos:

• SHA do commit, runtime, gerenciador de pacotes e versões importantes;
• comando, diretório de trabalho, código de saída e resumo da falha;
• falhas conhecidas, testes instáveis e exceções temporárias;
• diretórios no escopo e arquivos proibidos, como código gerado, migrações antigas, lockfiles e código de terceiros;
• fluxos críticos: autenticação, autorização, cobrança, migração de dados e contratos de API.

Se a linha de base já falhar, corrija, isole ou documente antes da auditoria. Um problema antigo não pode aparecer como uma descoberta nova do modelo.

Na primeira rodada, peça auditoria sem alterar arquivos

Investigação e correção precisam ser fases separadas. Se o modelo editar enquanto investiga, uma nova falha pode vir do código original, do primeiro patch ou da interação entre vários patches.

Use este prompt inicial e acrescente as regras do repositório:

Faça uma auditoria longa deste repositório. Nesta fase, apenas investigue e apresente resultados; não modifique arquivos.

Escopo: <diretórios, serviços, linguagens e fluxos críticos>
Exclusões: <arquivos gerados, código externo, migrações históricas e sistemas inacessíveis>
Linha de base: <comandos executados, códigos de saída e falhas conhecidas>

Revise:
1. segurança e limites de autorização;
2. correção, concorrência, transações e tratamento de erros;
3. desempenho e uso de recursos;
4. acessibilidade quando aplicável;
5. manutenibilidade e escalabilidade;
6. arquitetura e limites de módulos;
7. lacunas de documentação, testes e automação.

Para cada achado, informe:
- ID único e título curto;
- severidade e justificativa do impacto;
- arquivos, símbolos e linhas exatas;
- condição de disparo, comportamento esperado e observado;
- comando reproduzível ou teste mínimo;
- resumo da saída e código de término;
- possível explicação de falso positivo;
- menor direção de correção;
- verificações obrigatórias após a correção;
- confiança alta, média ou baixa.

Regras:
- Marque como NÃO EXECUTADO qualquer comando que você não tenha rodado.
- Se não conseguir reproduzir, marque como NÃO VERIFICADO.
- Não apague, pule nem enfraqueça testes para obter verde.
- Pare e liste credenciais, serviços ou dependências ausentes.
- Atualize a tabela de status ao final de cada fase e aguarde revisão.

O prompt não garante disciplina. Revise o histórico do terminal, o diff e a saída real. A função dele é impedir que uma observação vaga vá direto para a fila de correções.

Divida a tarefa longa em quatro fases controladas

Execução prolongada não deve significar escopo e permissões ilimitados. Pare no fim de cada fase e valide as evidências.

Fase 1: mapa do sistema

O modelo lê código, configuração, testes e documentos. O resultado deve mostrar pontos de entrada, limites de confiança, fluxos de dados, dependências externas e caminhos de alto impacto. Não há meta de quantidade de bugs nem alterações de arquivos.

Fase 2: achados candidatos

Cada candidato aponta para código e condição concreta. Uma recomendação geral sem local e gatilho vai para uma lista de melhorias, não para a contagem de defeitos.

Fase 3: reprodução individual

Comece pelos itens de alto impacto e baixo custo de verificação. Um experimento testa uma hipótese. Guarde a saída bruta e os dados do ambiente.

Fase 4: plano de correção

Apenas defeitos reproduzidos entram no plano. Para cada um, exija mudança mínima, impacto de compatibilidade, risco de migração, rollback e portões de teste. Questões arquiteturais vão primeiro ao responsável pelo código.

Controle o estado em audit-plan.md ou em tickets:

ID	Status	Risco	Evidência	Decisão arquitetural	Branch	Aprovador
AUD-001	Aguardando reprodução	Alto	Ainda não há	Não revisada	—	—

O caminho deve ser explícito: candidato → aguardando reprodução → reproduzido → arquitetura revisada → corrigido → aceito. A confiança da redação do modelo não altera o estado.

Portão de risco: separe severidade de confiança

Severidade mede o dano possível; confiança mede a qualidade das evidências. Um possível bypass de autorização pode ser grave e ter baixa confiança. Um erro pequeno em log pode ter baixa severidade e alta confiança.

Severidade	Quando usar	Evidência mínima antes de corrigir
Crítica	Escalada ampla de privilégio, exposição de dados sensíveis, corrupção irreversível ou falha do serviço central	Reprodução controlada, alcance claro e revisão imediata do responsável
Alta	Afeta fluxo essencial ou entrada realista dispara a falha de forma estável	Reprodução mínima, teste falhando ou saída de comando e confirmação do responsável
Média	Impacto limitado, há contorno ou são necessárias condições incomuns	Evidência repetível e decisão de prioridade
Baixa	Qualidade local, documentação, manutenção ou desempenho não crítico	Código concreto e benefício maior que o risco de regressão

O modelo consegue seguir caminhos do código, mas não conhece automaticamente a sensibilidade dos dados, compromissos com clientes ou tolerância a indisponibilidade. Isso exige decisão humana responsável.

Portão de reprodução: converta cada achado em uma verificação que falha

Código suspeito não basta. Você precisa de uma verificação que falhe antes da correção e passe depois. Para cada achado, responda:

1. Em qual commit e ambiente ele aparece?
2. Qual é a menor entrada que o dispara?
3. O comportamento esperado vem de teste, especificação, contrato ou regra de negócio?
4. Qual foi o resultado real e onde está a saída original?
5. Por que os testes existentes não detectaram?
6. Uma decisão válida de design ou diferença de ambiente pode explicar o comportamento?

A melhor evidência é um teste de regressão mínimo. Quando não for possível automatizar, documente passos manuais determinísticos, observações esperadas e limpeza. Reproduza questões de segurança apenas em sistemas próprios ou autorizados, preferencialmente locais, isolados ou de pré-produção.

Se o modelo disser que rodou um comando, exija comando completo, diretório, código de saída e trechos relevantes. Um resumo em texto não prova execução.

Portão de arquitetura: descubra por que o código atual existe

Uma solução aparentemente mais limpa pode quebrar compatibilidade, ordem de deploy ou uma fronteira intencional. Antes de aceitar refatoração ampla, revise ADRs, documentos de design, contratos de API, restrições de migração e histórico.

Quando o histórico Git estiver disponível:

git log -- <path>
git blame -L <start>,<end> <file>
git show <commit> -- <path>

Exija respostas objetivas:

• Qual restrição o desenho atual preserva?
• Quais consumidores, formatos e etapas de deploy dependem dele?
• A proposta corrige um defeito ou muda o produto?
• Uma mudança local menor resolve o problema?
• O rollback exige restaurar código, configuração ou dados?

O histórico oferece indícios, não uma leitura perfeita da intenção. Se não houver justificativa, marque “intenção arquitetural desconhecida” e consulte um mantenedor.

Portão de correção: um defeito reproduzido por patch pequeno

Não aceite um megapatch com muitos assuntos. Primeiro adicione um teste que falhe no código anterior; depois faça a menor correção capaz de passá-lo.

Portão	Requisito	Se falhar
Escopo	O diff cobre apenas o achado aprovado	Separe mudanças não relacionadas
Regressão	Falha antes e passa depois	Corrija o teste ou reavalie o achado
Estática	Formatação, lint e tipos passam	Não esconda erros com exceções globais
Projeto	Testes unitários, integração e build relevantes passam	Investigue a primeira falha nova antes de empilhar patches
Arquitetura	O responsável confirma limites e compatibilidade	Reduza o escopo ou abra revisão de design
Revisão humana	Erros, permissões, dados e remoções são inspecionados	Explique cada trecho suspeito

Rejeite falsos verdes: apagar asserts, pular testes, engolir exceções, enfraquecer validação, aumentar retries para esconder corrida ou refatorar tanto que a origem do defeito desapareça.

Portão de regressão: rode as verificações definidas pelo projeto

A aceitação final deve usar scripts existentes ou CI, não apenas testes escolhidos pelo modelo. Compare o conjunto completo antes e depois e confirme que o novo teste falha na revisão sem o patch.

Revise lockfiles, migrações, APIs públicas e padrões de configuração. Uma alegação de desempenho só vale com o mesmo ambiente e entrada. Para testes instáveis, não repita até ficar verde: registre o padrão, isole a causa e veja se o patch piorou a variabilidade.

Rejeite o resultado quando aparecer qualquer um destes sinais

• Não há local exato, gatilho ou evidência inspecionável.
• Um comando não executado aparece como aprovado.
• A severidade não apresenta caminho de impacto.
• O patch ultrapassa o escopo ou redesenha a arquitetura sem autorização.
• Testes são apagados, pulados ou enfraquecidos, ou erros são silenciados.
• A mudança conflita com ADR, contrato ou migração sem aprovação.
• Só existe um resumo final, sem comandos e diff revisável.
• Uma afirmação de segurança depende apenas de outro modelo concordar.

Um segundo modelo pode procurar contraexemplos, mas consenso entre modelos não é evidência independente. Validação real vem de testes, execução, histórico, especificações e responsáveis humanos.

Checklist final antes do merge

• Escopo, exclusões e commit base estão congelados.
• Comandos da linha de base e códigos de saída foram preservados.
• Cada achado aceito tem ID e local exato.
• Severidade e confiança estão separadas.
• O defeito foi reproduzido por teste ou procedimento determinístico.
• Intenção arquitetural, compatibilidade e rollback foram revisados.
• Cada achado corresponde a um patch pequeno e revisável.
• O teste de regressão falha antes e passa depois.
• Todos os portões rodam por scripts existentes ou CI.
• Um responsável revisa o diff final e aprova explicitamente.

Os relatos públicos tornam o Opus 5.5 um candidato confiável para auditorias extensas e sugerem que ele pode encontrar problemas ignorados em outras revisões. Eles não eliminam a verificação. O próximo passo mínimo é salvar uma linha de base limpa e iniciar uma fase “somente auditoria, sem modificações”.