santa-method

Método Santa

Estrutura de verificação adversarial multiagente. Faça uma lista, verifique duas vezes. Se estiver 'levando', corrija até ficar 'bonzinho'.

A percepção central: um único agente revisando sua própria saída compartilha os mesmos vieses, lacunas de conhecimento e erros sistemáticos que produziram a saída. Dois revisores independentes, sem contexto compartilhado, quebram esse padrão de falha.

Quando Ativar

Invoque esta habilidade quando:

• A saída for publicada, implantada ou consumida por usuários finais
• Restrições de conformidade, regulatórias ou de marca forem impostas
• Código for enviado para produção sem revisão humana
• A precisão do conteúdo for importante (documentação técnica, material educacional, texto voltado para o cliente)
• Geração em lote em escala, onde a verificação por amostragem perde padrões sistêmicos
• O risco de alucinação for elevado (afirmações, estatísticas, referências de API, linguagem jurídica)

NÃO use para rascunhos internos, pesquisa exploratória ou tarefas com verificação determinística (use pipelines de build/teste/lint para esses casos).

Arquitetura

┌─────────────┐
│  GERADOR    │  Fase 1: Faça uma Lista
│  (Agente A) │  Produza a entrega
└──────┬──────┘
       │ saída
       ▼
┌──────────────────────────────┐
│    REVISÃO DUPLA INDEPENDENTE │  Fase 2: Verifique Duas Vezes
│                                │
│  ┌───────────┐ ┌───────────┐  │  Dois agentes, mesma rubrica,
│  │ Revisor B │ │ Revisor C │  │  sem contexto compartilhado
│  └─────┬─────┘ └─────┬─────┘  │
│        │              │        │
└────────┼──────────────┼────────┘
         │              │
         ▼              ▼
┌──────────────────────────────┐
│      PORTÃO DE VEREDITO       │  Fase 3: Levando ou Bonzinho
│                                │
│  B aprova E C aprova → BONZINHO │  Ambos devem aprovar.
│  Caso contrário → LEVANDO      │  Sem exceções.
└──────┬──────────────┬─────────┘
       │              │
    BONZINHO        LEVANDO
       │              │
       ▼              ▼
   [ ENVIAR ]    ┌─────────────┐
                  │  CICLO DE   │  Fase 4: Corrija Até Ficar Bonzinho
                  │  CORREÇÃO   │
                  │              │
                  │ iteração++  │  Colete todas as bandeiras.
                  │ se i > MAX: │  Corrija todos os problemas.
                  │   escalar   │  Reexecute ambos os revisores.
                  │ senão:      │  Loop até convergência.
                  │   vá p/ F.2 │
                  └──────────────┘

Detalhes das Fases

Fase 1: Faça uma Lista (Gerar)

Execute a tarefa principal. Nenhuma alteração no seu fluxo normal de geração. O Método Santa é uma camada de verificação pós-geração, não uma estratégia de geração.

# O gerador funciona normalmente
saida = gerar(especificacao_tarefa)

Fase 2: Verifique Duas Vezes (Revisão Dupla Independente)

Crie dois agentes revisores em paralelo. Invariantes críticos:

1. Isolamento de contexto — nenhum revisor vê a avaliação do outro
2. Rubrica idêntica — ambos recebem os mesmos critérios de avaliação
3. Mesmas entradas — ambos recebem a especificação original E a saída gerada
4. Saída estruturada — cada um retorna um veredito tipado, não texto corrido

PROMPT_REVISOR = """
Você é um revisor de qualidade independente. Você NÃO viu nenhuma outra revisão desta saída.

## Especificação da Tarefa
{especificacao_tarefa}

## Saída Sob Revisão
{saida}

## Rubrica de Avaliação
{rubrica}

## Instruções
Avalie a saída em relação a CADA critério da rubrica. Para cada:
- APROVADO: critério totalmente atendido, sem problemas
- REPROVADO: problema específico encontrado (cite o problema exato)

Retorne sua avaliação como JSON estruturado:
{
  "veredito": "APROVADO" | "REPROVADO",
  "verificacoes": [
    {"criterio": "...", "resultado": "APROVADO|REPROVADO", "detalhe": "..."}
  ],
  "problemas_criticos": ["..."],   // bloqueadores que devem ser corrigidos
  "sugestoes": ["..."]            // melhorias não bloqueantes
}

Seja rigoroso. Seu trabalho é encontrar problemas, não aprovar.
"""

# Crie revisores em paralelo (subagentes Claude Code)
revisor_b = Agente(prompt=PROMPT_REVISOR.format(...), descricao="Revisor Santa B")
revisor_c = Agente(prompt=PROMPT_REVISOR.format(...), descricao="Revisor Santa C")

# Ambos executam concorrentemente — nenhum vê o outro

Design da Rubrica

A rubrica é a entrada mais importante. Rubricas vagas produzem revisões vagas. Cada critério deve ter uma condição objetiva de aprovação/reprovação.

Critério	Condição de Aprovação	Sinal de Falha
Precisão factual	Todas as afirmações verificáveis contra material de origem ou conhecimento comum	Estatísticas inventadas, números de versão errados, APIs inexistentes
Livre de alucinação	Nenhuma entidade, citação, URL ou referência fabricada	Links para páginas que não existem, citações atribuídas sem fonte
Completude	Cada requisito da especificação é abordado	Seções ausentes, casos extremos ignorados, cobertura incompleta
Conformidade	Passa em todas as restrições específicas do projeto	Termos proibidos usados, violações de tom, não conformidade regulatória
Consistência interna	Nenhuma contradição dentro da saída	Seção A diz X, seção B diz não-X
Correção técnica	Código compila/executa, algoritmos são sólidos	Erros de sintaxe, bugs de lógica, alegações de complexidade erradas

Extensões de Rubrica Específicas de Domínio

Conteúdo/Marketing:

• Aderência à voz da marca
• Requisitos de SEO atendidos (densidade de palavras-chave, meta tags, estrutura)
• Sem uso indevido de marcas registradas de concorrentes
• CTA presente e vinculada corretamente

Código:

• Segurança de tipos (sem vazamentos de any, tratamento adequado de nulos)
• Cobertura de tratamento de erros
• Segurança (sem segredos no código, validação de entrada, prevenção de injeção)
• Cobertura de testes para novos caminhos

Sensível a Conformidade (regulado, jurídico, financeiro):

• Sem garantias de resultado ou afirmações não fundamentadas
• Isenções de responsabilidade necessárias presentes
• Apenas terminologia aprovada
• Linguagem apropriada para a jurisdição

Fase 3: Levando ou Bonzinho (Portão de Veredito)

def veredito_santa(revisor_b, revisor_c):
    """Ambos os revisores devem aprovar. Sem crédito parcial."""
    if revisor_b.veredito == "APROVADO" and revisor_c.veredito == "APROVADO":
        return "BONZINHO"  # Envie

    # Mescle as bandeiras de ambos os revisores, deduplique
    todos_problemas = deduplicar(revisor_b.problemas_criticos + revisor_c.problemas_criticos)
    todas_sugestoes = deduplicar(revisor_b.sugestoes + revisor_c.sugestoes)

    return "LEVANDO", todos_problemas, todas_sugestoes

Por que ambos devem aprovar: se apenas um revisor detecta um problema, esse problema é real. O ponto cego do outro revisor é exatamente o modo de falha que o Método Santa existe para eliminar.

Fase 4: Corrija Até Ficar Bonzinho (Loop de Convergência)

MAX_ITERACOES = 3

for iteracao in range(MAX_ITERACOES):
    veredito, problemas, sugestoes = veredito_santa(revisor_b, revisor_c)

    if veredito == "BONZINHO":
        registrar_resultado_santa(saida, iteracao, "aprovado")
        return enviar(saida)

    # Corrija todos os problemas críticos (sugestões são opcionais)
    saida = agente_correcao.executar(
        saida=saida,
        problemas=problemas,
        instrucao="Corrija APENAS os problemas sinalizados. Não refatore nem adicione alterações não solicitadas."
    )

    # Reexecute AMBOS os revisores na saída corrigida (agentes novos, sem memória da rodada anterior)
    revisor_b = Agente(prompt=PROMPT_REVISOR.format(saida=saida, ...))
    revisor_c = Agente(prompt=PROMPT_REVISOR.format(saida=saida, ...))

# Iterações esgotadas — escalar
registrar_resultado_santa(saida, MAX_ITERACOES, "escalado")
escalar_para_humano(saida, problemas)

Crítico: cada rodada de revisão usa agentes novos. Os revisores não devem carregar memória de rodadas anteriores, pois o contexto anterior cria viés de ancoragem.

Padrões de Implementação

Padrão A: Subagentes Claude Code (Recomendado)

Subagentes fornecem verdadeiro isolamento de contexto. Cada revisor é um processo separado, sem estado compartilhado.

# Em uma sessão Claude Code, use a ferramenta Agent para criar revisores
# Ambos os agentes executam em paralelo para velocidade

# Pseudocódigo para invocação da ferramenta Agent
revisor_b = Agente(
    descricao="Revisor Santa B",
    prompt=f"Revise esta saída quanto à qualidade...\n\nRUBRICA:\n{rubrica}\n\nSAÍDA:\n{saida}"
)
revisor_c = Agente(
    descricao="Revisor Santa C",
    prompt=f"Revise esta saída quanto à qualidade...\n\nRUBRICA:\n{rubrica}\n\nSAÍDA:\n{saida}"
)

Padrão B: Sequencial Inline (Fallback)

Quando subagentes não estiverem disponíveis, simule o isolamento com redefinições explícitas de contexto:

1. Gere a saída
2. Novo contexto: "Você é o Revisor 1. Avalie SOMENTE contra esta rubrica. Encontre problemas."
3. Registre as descobertas textualmente
4. Limpe o contexto completamente
5. Novo contexto: "Você é o Revisor 2. Avalie SOMENTE contra esta rubrica. Encontre problemas."
6. Compare ambas as revisões, corrija, repita

O padrão de subagentes é estritamente superior — a simulação inline corre o risco de vazamento de contexto entre revisores.

Padrão C: Amostragem em Lote

Para lotes grandes (100+ itens), executar o Santa completo em cada item é proibitivo em custo. Use amostragem estratificada:

1. Execute o Santa em uma amostra aleatória (10-15% do lote, mínimo 5 itens)
2. Categorize as falhas por tipo (alucinação, conformidade, completude, etc.)
3. Se padrões sistemáticos surgirem, aplique correções direcionadas a todo o lote
4. Re-amostre e re-verifique o lote corrigido
5. Continue até que uma amostra limpa seja aprovada

import random

def santa_lote(itens, rubrica, taxa_amostragem=0.15):
    amostra = random.sample(itens, max(5, int(len(itens) * taxa_amostragem)))

    for item in amostra:
        resultado = santa_completo(item, rubrica)
        if resultado.veredito == "LEVANDO":
            padrao = classificar_falha(resultado.problemas)
            itens = correcao_lote(itens, padrao)  # Corrija todos os itens que correspondem ao padrão
            return santa_lote(itens, rubrica)       # Re-amostre

    return itens  # Amostra limpa → envie o lote

Modos de Falha e Mitigações

Modo de Falha	Sintoma	Mitigação
Loop infinito	Revisores continuam encontrando novos problemas após correções	Limite máximo de iterações (3). Escalar.
Carimbo	Ambos os revisores aprovam tudo	Prompt adversarial: "Seu trabalho é encontrar problemas, não aprovar."
Deriva subjetiva	Revisores sinalizam preferências de estilo, não erros	Rubrica restrita com critérios objetivos de aprovação/reprovação apenas
Regressão de correção	Corrigir problema A introduz problema B	Revisores novos a cada rodada detectam regressões
Viés de concordância entre revisores	Ambos os revisores perdem a mesma coisa	Mitigado pela independência, não eliminado. Para saída crítica, adicione um terceiro revisor ou verificação humana por amostragem.
Explosão de custos	Muitas iterações em saídas grandes	Padrão de amostragem em lote. Limites de orçamento por ciclo de verificação.

Integração com Outras Habilidades

Habilidade	Relacionamento
Loop de Verificação	Use para verificações determinísticas (build, lint, teste). Santa para verificações semânticas (precisão, alucinações). Execute o loop de verificação primeiro, Santa depois.
Eval Harness	Os resultados do Método Santa alimentam métricas de avaliação. Acompanhe pass@k nas execuções Santa para medir a qualidade do gerador ao longo do tempo.
Aprendizado Contínuo v2	As descobertas do Santa tornam-se intuições. Falhas repetidas no mesmo critério → comportamento aprendido para evitar o padrão.
Pacote Estratégico	Execute Santa ANTES de compactar. Não perca o contexto de revisão no meio da verificação.

Métricas

Acompanhe estas métricas para medir a eficácia do Método Santa:

• Taxa de primeira aprovação: % de saídas que aprovam o Santa na rodada 1 (alvo: >70%)
• Média de iterações até convergência: média de rodadas até BONZINHO (alvo: <1,5)
• Taxonomia de problemas: distribuição dos tipos de falha (alucinação vs. completude vs. conformidade)
• Concordância entre revisores: % de problemas sinalizados por ambos os revisores vs. apenas um (baixa concordância = rubrica precisa ser apertada)
• Taxa de escape: problemas encontrados após o envio que o Santa deveria ter pegado (alvo: 0)

Análise de Custo

O Método Santa custa aproximadamente 2-3x o custo de tokens da geração sozinha por ciclo de verificação. Para a maioria das saídas de alto risco, isso é um bom negócio:

Custo do Santa = (tokens de geração) + 2×(tokens de revisão por rodada) × (média de rodadas)
Custo de NÃO usar Santa = (dano à reputação) + (esforço de correção) + (erosão da confiança)

Para operações em lote, o padrão de amostragem reduz o custo para ~15-20% da verificação completa, enquanto detecta >90% dos problemas sistemáticos.