Domínio 4 — Prompt Engineering & Structured Output · Lição 2 de 7

Critérios explícitos e redução de falsos positivos

Objetivos de aprendizagem

• Explicar por que critérios categóricos específicos vencem instruções como "seja conservador" ou "reporte só achados de alta confiança" (task statement 4.1).
• Descrever o impacto de falsos positivos na confiança do desenvolvedor no sistema de revisão.
• Aplicar a tática de desabilitar temporariamente categorias com alta taxa de falso positivo.
• Definir critérios de severidade com exemplos de código concretos para classificação consistente.

O problema: precisão em revisão automatizada

No cenário de CI/CD do exame, Claude Code revisa pull requests automaticamente. O risco número um desses sistemas não é deixar passar bugs — é reportar coisas demais. Um revisor automático que comenta 15 itens por PR, dos quais 12 são irrelevantes, treina os desenvolvedores a ignorar todos os comentários, inclusive os 3 verdadeiros. Falsos positivos em uma categoria minam a confiança nas categorias que funcionam bem.

Por que "seja conservador" não funciona

Instruções de calibração genérica — "seja conservador", "reporte apenas achados de alta confiança", "evite falsos positivos" — pedem que o modelo aplique um filtro interno de confiança que ele não calibra bem. A auto-confiança reportada por um LLM não é um proxy confiável da correção do achado (o mesmo motivo pelo qual escalonamento por confiança auto-reportada falha, no Domínio 5). O resultado prático é pouca ou nenhuma mudança na taxa de falsos positivos.

O que funciona é substituir o filtro subjetivo por critérios categóricos, que o modelo consegue aplicar de forma binária:

Categorias com alta taxa de falso positivo: desabilite temporariamente

Quando a telemetria mostra que uma categoria específica (ex.: "problemas de performance") tem taxa de falso positivo alta enquanto outras (ex.: "segurança") vão bem, a ação recomendada é desabilitar temporariamente a categoria ruim — removê-la do prompt de revisão — enquanto seus critérios são refinados offline. Isso restaura imediatamente a confiança dos desenvolvedores nas categorias que funcionam, em vez de deixar o ruído contaminar o sistema inteiro. Depois de melhorar os critérios (e validar em amostra), a categoria volta.

Critérios de severidade com exemplos concretos

Se o prompt pede para classificar achados em critical / major / minor sem definir cada nível, a classificação varia entre execuções. A correção é definir cada severidade com critérios objetivos e exemplos de código concretos para cada nível — um mini few-shot de severidade (a Lição 3 aprofunda few-shot).

import anthropic

client = anthropic.Anthropic()

REVIEW_SYSTEM = """Você é um revisor de código automatizado em um pipeline de CI.

REPORTE apenas estas categorias:
- bug: lógica incorreta demonstrável no diff (ex.: off-by-one, null deref).
- security: vulnerabilidade concreta (ex.: SQL injection, segredo hardcoded).

NÃO REPORTE:
- estilo, formatação, nomenclatura;
- padrões já usados de forma consistente no arquivo;
- sugestões de refatoração sem bug associado.

SEVERIDADE (com exemplos):
- critical: perda de dados, execução remota, credencial exposta.
  Exemplo: query montada com concatenação de input do usuário.
- major: comportamento incorreto em fluxo principal.
  Exemplo: condição invertida que pula a validação de saldo.
- minor: comportamento incorreto em caso-limite raro.
  Exemplo: mensagem de erro trocada em branch de exceção.

Formato de cada achado: arquivo, linha, categoria, severidade,
descrição em 1 frase, correção sugerida."""

def review_diff(diff_text: str):
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        system=REVIEW_SYSTEM,
        messages=[{
            "role": "user",
            "content": "<diff>\n" + diff_text + "\n</diff>\n\nRevise o diff acima.",
        }],
    )
    return next(b.text for b in response.content if b.type == "text")

print(review_diff("--- a/billing.py\n+++ b/billing.py\n+    total = price * qty"))

Ciclo de melhoria orientado a dados

Para melhorar precisão de forma sistemática, o sistema precisa saber por que os desenvolvedores descartam achados. Incluir um campo detected_pattern na saída estruturada (qual construção de código disparou o achado) permite agrupar os descartes e descobrir padrões de falso positivo — tema da Lição 5.

flowchart TD
    A[Revisão automática gera achados] --> B[Dev aceita ou descarta cada achado]
    B --> C[Análise dos descartes por detected_pattern]
    C --> D{Categoria com FP alto?}
    D -->|Sim| E[Desabilitar categoria temporariamente]
    E --> F[Refinar critérios + exemplos e validar em amostra]
    F --> G[Reabilitar categoria]
    D -->|Não| A
  

Pegadinhas da prova

• Distrator típico: "adicione 'reporte apenas achados de alta confiança' ao prompt". Confiança auto-reportada de LLM é mal calibrada; a resposta certa define categorias explícitas de incluir/excluir.
• Distrator típico: "peça um score de confiança e filtre por threshold" como primeira resposta para falsos positivos. Sem calibração com dados rotulados, o threshold é arbitrário — critérios categóricos vêm primeiro.
• Distrator típico: diante de uma categoria ruidosa, "desligar a revisão automática inteira" ou "manter tudo ligado e pedir desculpas no onboarding". A ação proporcional é desabilitar somente a categoria problemática enquanto ela é refinada.
• Distrator típico: tratar severidade inconsistente com "use bom senso para classificar" — a correção é definir cada nível com critérios e exemplos concretos de código.

Resumo em 5 linhas

Documentação oficial

• Be clear and direct
• Prompt engineering overview
• Claude Code em CI (GitHub Actions)

Questões de fixação