santa-method

Méthode Santa

Framework de vérification multi-agent adversariale. Faites une liste, vérifiez-la deux fois. Si c'est méchant, corrigez jusqu'à ce que ce soit gentil.

L'idée centrale : un seul agent qui révise sa propre production partage les mêmes biais, lacunes de connaissances et erreurs systématiques qui ont généré cette production. Deux réviseurs indépendants, sans contexte partagé, brisent ce mode de défaillance.

Quand l'activer

Invoquez cette compétence lorsque :

• La sortie sera publiée, déployée ou consommée par des utilisateurs finaux
• Des contraintes de conformité, réglementaires ou de marque doivent être appliquées
• Le code est livré en production sans revue humaine
• L'exactitude du contenu est importante (docs techniques, supports pédagogiques, textes destinés aux clients)
• La génération par lots à grande échelle risque de manquer des motifs systémiques
• Le risque d'hallucination est élevé (affirmations, statistiques, références d'API, langage juridique)

Ne PAS utiliser pour les brouillons internes, la recherche exploratoire ou les tâches à vérification déterministe (utilisez les pipelines de build/test/lint pour celles-ci).

Architecture

┌─────────────┐
│  GÉNÉRATEUR  │  Phase 1 : Faire une liste
│  (Agent A)   │  Produire le livrable
└──────┬───────┘
       │ sortie
       ▼
┌──────────────────────────────┐
│     DOUBLE REVUE INDÉPENDANTE │  Phase 2 : Vérifier deux fois
│                                │
│  ┌───────────┐ ┌───────────┐  │  Deux agents, même grille,
│  │ Relecteur B │ │ Relecteur C │  │  aucun contexte partagé
│  └─────┬─────┘ └─────┬─────┘  │
│        │              │        │
└────────┼──────────────┼────────┘
         │              │
         ▼              ▼
┌──────────────────────────────┐
│       PORTAIL DE VERDICT      │  Phase 3 : Méchant ou gentil
│                                │
│  B valide ET C valide → GENTIL │  Les deux doivent valider.
│  Sinon → MÉCHANT               │  Aucune exception.
└──────┬──────────────┬─────────┘
       │              │
    GENTIL         MÉCHANT
       │              │
       ▼              ▼
   [ EXPÉDIER ]  ┌──────────────────┐
                  │  CYCLE DE CORRECTION│  Phase 4 : Corriger jusqu'à ce que ce soit gentil
                  │                     │
                  │  itération++        │  Collecter tous les drapeaux.
                  │  si i > MAX :       │  Corriger tous les problèmes.
                  │    escalader        │  Relancer les deux relecteurs.
                  │  sinon :            │  Boucler jusqu'à convergence.
                  │    aller à Phase 2  │
                  └─────────────────────┘

Détails des phases

Phase 1 : Faire une liste (Générer)

Exécutez la tâche principale. Aucun changement dans votre flux de travail de génération normal. La méthode Santa est une couche de vérification post-génération, pas une stratégie de génération.

# Le générateur fonctionne normalement
sortie = generer(specification_de_la_tache)

Phase 2 : Vérifier deux fois (Double revue indépendante)

Lancez deux agents de revue en parallèle. Invariants critiques :

1. Isolement du contexte — aucun des relecteurs ne voit l'évaluation de l'autre
2. Même grille d'évaluation — les deux reçoivent les mêmes critères d'évaluation
3. Mêmes entrées — les deux reçoivent la spécification originale ET la sortie générée
4. Sortie structurée — chaque agent renvoie un verdict typé, pas de la prose

PROMPT_RELECTEUR = """
Vous êtes un relecteur qualité indépendant. Vous n'avez PAS vu d'autre relecture de cette sortie.

## Spécification de la tâche
{specification_de_la_tache}

## Sortie à relire
{sortie}

## Grille d'évaluation
{grille}

## Instructions
Évaluez la sortie par rapport à CHAQUE critère de la grille. Pour chacun :
- RÉUSSI : critère pleinement satisfait, aucun problème
- ÉCHEC : problème spécifique trouvé (citez le problème exact)

Retournez votre évaluation sous forme de JSON structuré :
{
  "verdict": "RÉUSSI" | "ÉCHEC",
  "verifications": [
    {"critere": "...", "resultat": "RÉUSSI|ÉCHEC", "detail": "..."}
  ],
  "problemes_critiques": ["..."],   // bloqueurs qui doivent être corrigés
  "suggestions": ["..."]             // améliorations non bloquantes
}

Soyez rigoureux. Votre travail est de trouver des problèmes, pas d'approuver.
"""

# Lancer les relecteurs en parallèle (sous-agents Claude Code)
relecteur_b = Agent(prompt=PROMPT_RELECTEUR.format(...), description="Relecteur Santa B")
relecteur_c = Agent(prompt=PROMPT_RELECTEUR.format(...), description="Relecteur Santa C")

# Les deux s'exécutent en même temps — aucun ne voit l'autre

Conception de la grille d'évaluation

La grille est l'élément le plus important. Des grilles vagues produisent des revues vagues. Chaque critère doit avoir une condition de réussite/échec objective.

Critère	Condition de réussite	Signal d'échec
Exactitude factuelle	Toutes les affirmations vérifiables par rapport à la source ou aux connaissances communes	Statistiques inventées, mauvais numéros de version, APIs inexistantes
Sans hallucination	Aucune entité, citation, URL ou référence fabriquée	Liens vers des pages qui n'existent pas, citations attribuées sans source
Exhaustivité	Chaque exigence de la spécification est couverte	Sections manquantes, cas limites ignorés, couverture incomplète
Conformité	Satisfait toutes les contraintes spécifiques au projet	Termes interdits utilisés, violations de ton, non-conformité réglementaire
Cohérence interne	Aucune contradiction dans la sortie	La section A dit X, la section B dit non-X
Exactitude technique	Le code compile/s'exécute, les algorithmes sont solides	Erreurs de syntaxe, bugs logiques, mauvaises affirmations de complexité

Extensions de grille par domaine

Contenu/Marketing :

• Respect de la voix de la marque
• Exigences SEO satisfaites (densité de mots-clés, balises meta, structure)
• Pas d'utilisation abusive des marques des concurrents
• Appel à l'action présent et correctement lié

Code :

• Sécurité des types (pas de fuite any, gestion correcte des nulls)
• Couverture de la gestion d'erreurs
• Sécurité (pas de secrets dans le code, validation des entrées, prévention d'injection)
• Couverture de test pour les nouveaux chemins

Sensible à la conformité (réglementé, juridique, financier) :

• Pas de garanties de résultat ni d'affirmations non étayées
• Avertissements requis présents
• Terminologie approuvée uniquement
• Langage adapté à la juridiction

Phase 3 : Méchant ou gentil (Portail de verdict)

def verdict_santa(relecture_b, relecture_c):
    """Les deux relecteurs doivent valider. Pas de demi-mesure."""
    if relecture_b.verdict == "RÉUSSI" and relecture_c.verdict == "RÉUSSI":
        return "GENTIL"  # Expédier

    # Fusionner les drapeaux des deux relecteurs, dédoublonner
    tous_problemes = dedupe(relecture_b.problemes_critiques + relecture_c.problemes_critiques)
    toutes_suggestions = dedupe(relecture_b.suggestions + relecture_c.suggestions)

    return "MÉCHANT", tous_problemes, toutes_suggestions

Pourquoi les deux doivent valider : si un seul relecteur détecte un problème, ce problème est réel. L'angle mort de l'autre relecteur est exactement le mode de défaillance que la méthode Santa vise à éliminer.

Phase 4 : Corriger jusqu'à ce que ce soit gentil (Boucle de convergence)

MAX_ITERATIONS = 3

for iteration in range(MAX_ITERATIONS):
    verdict, problemes, suggestions = verdict_santa(relecteur_b, relecteur_c)

    if verdict == "GENTIL":
        log_santa_resultat(sortie, iteration, "réussi")
        return expedier(sortie)

    # Corriger TOUS les problèmes critiques (les suggestions sont optionnelles)
    sortie = agent_correction.executer(
        sortie=sortie,
        problemes=problemes,
        instruction="Corrigez UNIQUEMENT les problèmes signalés. Ne refactorez pas et n'ajoutez pas de changements non demandés."
    )

    # Relancer les DEUX relecteurs sur la sortie corrigée (nouveaux agents, pas de mémoire du tour précédent)
    relecteur_b = Agent(prompt=PROMPT_RELECTEUR.format(sortie=sortie, ...))
    relecteur_c = Agent(prompt=PROMPT_RELECTEUR.format(sortie=sortie, ...))

# Itérations épuisées — escalader
log_santa_resultat(sortie, MAX_ITERATIONS, "escaladé")
escalader_a_humain(sortie, problemes)

Critique : chaque cycle de relecture utilise des agents frais. Les relecteurs ne doivent pas conserver de mémoire des cycles précédents, car le contexte antérieur crée un biais d'ancrage.

Patterns d'implémentation

Pattern A : Sous-agents Claude Code (Recommandé)

Les sous-agents offrent un véritable isolement du contexte. Chaque relecteur est un processus séparé sans état partagé.

# Dans une session Claude Code, utilisez l'outil Agent pour lancer les relecteurs
# Les deux agents s'exécutent en parallèle pour plus de rapidité

# Pseudo-code pour l'invocation de l'outil Agent
relecteur_b = Agent(
    description="Relecteur Santa B",
    prompt=f"Relisez cette sortie pour la qualité...\n\nGRILLE :\n{grille}\n\nSORTIE :\n{sortie}"
)
relecteur_c = Agent(
    description="Relecteur Santa C",
    prompt=f"Relisez cette sortie pour la qualité...\n\nGRILLE :\n{grille}\n\nSORTIE :\n{sortie}"
)

Pattern B : Séquentiel en ligne (solution de repli)

Lorsque les sous-agents ne sont pas disponibles, simulez l'isolement avec des réinitialisations explicites du contexte :

1. Générer la sortie
2. Nouveau contexte : "Vous êtes le Relecteur 1. Évaluez UNIQUEMENT par rapport à cette grille. Trouvez des problèmes."
3. Enregistrer les résultats textuellement
4. Effacer complètement le contexte
5. Nouveau contexte : "Vous êtes le Relecteur 2. Évaluez UNIQUEMENT par rapport à cette grille. Trouvez des problèmes."
6. Comparer les deux revues, corriger, répéter

Le pattern des sous-agents est strictement supérieur — la simulation en ligne risque un mélange de contexte entre les relecteurs.

Pattern C : Échantillonnage par lots

Pour les grands lots (100+ éléments), appliquer Santa à chaque élément est trop coûteux. Utilisez un échantillonnage stratifié :

1. Exécutez Santa sur un échantillon aléatoire (10-15 % du lot, minimum 5 éléments)
2. Catégorisez les échecs par type (hallucination, conformité, exhaustivité, etc.)
3. Si des motifs systématiques apparaissent, appliquez des corrections ciblées à l'ensemble du lot
4. Rééchantillonnez et revérifiez le lot corrigé
5. Continuez jusqu'à ce qu'un échantillon propre réussisse

import random

def santa_lot(elements, grille, taux_echantillonnage=0.15):
    echantillon = random.sample(elements, max(5, int(len(elements) * taux_echantillonnage)))

    for element in echantillon:
        resultat = santa_complet(element, grille)
        if resultat.verdict == "MÉCHANT":
            motif = classifier_echec(resultat.problemes)
            elements = correction_lot(elements, motif)  # Corriger tous les éléments correspondant au motif
            return santa_lot(elements, grille)            # Rééchantillonner

    return elements  # Échantillon propre → expédier le lot

Modes de défaillance et mesures de correction

Mode de défaillance	Symptôme	Mesure correctrice
Boucle infinie	Les relecteurs trouvent continuellement de nouveaux problèmes après corrections	Plafond d'itérations (3). Escalader.
Validation automatique	Les deux relecteurs approuvent tout	Prompt adversaire : "Votre travail est de trouver des problèmes, pas d'approuver."
Dérive subjective	Les relecteurs signalent des préférences de style, pas des erreurs	Grille serrée avec critères objectifs de réussite/échec uniquement
Régression de correction	Corriger le problème A introduit le problème B	Nouveaux relecteurs à chaque cycle pour détecter les régressions
Biais d'accord des relecteurs	Les deux relecteurs manquent la même chose	Atténué par l'indépendance, mais pas éliminé. Pour une sortie critique, ajouter un troisième relecteur ou un contrôle humain ponctuel.
Explosion des coûts	Trop d'itérations sur de grandes sorties	Pattern d'échantillonnage par lots. Plafonds budgétaires par cycle de vérification.

Intégration avec d'autres compétences

Compétence	Relation
Boucle de vérification	À utiliser pour les vérifications déterministes (build, lint, test). Santa pour les vérifications sémantiques (exactitude, hallucinations). Exécutez la boucle de vérification d'abord, Santa ensuite.
Harness d'évaluation	Les résultats de la méthode Santa alimentent les métriques d'évaluation. Suivez le pass@k sur les exécutions Santa pour mesurer la qualité du générateur au fil du temps.
Apprentissage continu v2	Les conclusions de Santa deviennent des instincts. Des échecs répétés sur le même critère → comportement appris pour éviter le motif.
Compact stratégique	Exécutez Santa AVANT de compacter. Ne perdez pas le contexte de revue en pleine vérification.

Métriques

Suivez celles-ci pour mesurer l'efficacité de la méthode Santa :

• Taux de première réussite : % de sorties qui réussissent Santa au premier tour (objectif : >70 %)
• Nombre moyen d'itérations jusqu'à convergence : tours moyens jusqu'à GENTIL (objectif : <1,5)
• Taxonomie des problèmes : distribution des types d'échec (hallucination vs. exhaustivité vs. conformité)
• Accord des relecteurs : % de problèmes signalés par les deux relecteurs vs. un seul (faible accord = la grille doit être resserrée)
• Taux d'évasion : problèmes trouvés après l'expédition que Santa aurait dû détecter (objectif : 0)

Analyse des coûts

La méthode Santa coûte environ 2 à 3 fois le coût des tokens de la génération seule par cycle de vérification. Pour la plupart des sorties à enjeux élevés, c'est une aubaine :

Coût de Santa = (tokens de génération) + 2×(tokens de relecture par tour) × (nombre moyen de tours)
Coût de PAS Santa = (atteinte à la réputation) + (effort de correction) + (érosion de la confiance)

Pour les opérations par lots, le pattern d'échantillonnage réduit le coût à environ 15-20 % de la vérification complète tout en détectant >90 % des problèmes systématiques.