eval-harness

Compétence Eval Harness

Un cadre d'évaluation formel pour les sessions Claude Code, implémentant les principes de développement piloté par les évaluations (EDD).

Quand activer

• Mettre en place un développement piloté par les évaluations (EDD) pour les workflows assistés par IA
• Définir des critères de réussite/échec pour l'achèvement des tâches Claude Code
• Mesurer la fiabilité de l'agent avec les métriques pass@k
• Créer des suites de tests de régression pour les changements de prompts ou d'agents
• Évaluer les performances de l'agent entre les versions de modèle

Philosophie

L'Eval-Driven Development considère les évaluations comme les "tests unitaires du développement IA" :

• Définir le comportement attendu AVANT l'implémentation
• Exécuter les évaluations en continu pendant le développement
• Suivre les régressions à chaque changement
• Utiliser les métriques pass@k pour mesurer la fiabilité

Types d'évaluations

Évaluations de capacité

Testent si Claude peut faire quelque chose qu'il ne pouvait pas faire auparavant :

[ÉVALUATION DE CAPACITÉ : nom-fonctionnalité]
Tâche : Description de ce que Claude doit accomplir
Critères de succès :
  - [ ] Critère 1
  - [ ] Critère 2
  - [ ] Critère 3
Sortie attendue : Description du résultat attendu

Évaluations de régression

S'assurent que les changements ne cassent pas les fonctionnalités existantes :

[ÉVALUATION DE RÉGRESSION : nom-fonctionnalité]
RÉFÉRENCE : SHA ou nom de point de contrôle
Tests :
  - test-existant-1 : RÉUSSI/ÉCHEC
  - test-existant-2 : RÉUSSI/ÉCHEC
  - test-existant-3 : RÉUSSI/ÉCHEC
Résultat : X/Y réussi (précédemment Y/Y)

Types de correcteurs

1. Correcteur basé sur du code

Vérifications déterministes à l'aide de code :

# Vérifier si le fichier contient le motif attendu
grep -q "export function handleAuth" src/auth.ts && echo "RÉUSSI" || echo "ÉCHEC"

# Vérifier si les tests passent
npm test -- --testPathPattern="auth" && echo "RÉUSSI" || echo "ÉCHEC"

# Vérifier si la compilation réussit
npm run build && echo "RÉUSSI" || echo "ÉCHEC"

2. Correcteur basé sur modèle

Utiliser Claude pour évaluer des sorties ouvertes :

[PROMPT DU CORRECTEUR MODÈLE]
Évaluer le changement de code suivant :
1. Résout-il le problème énoncé ?
2. Est-il bien structuré ?
3. Les cas limites sont-ils traités ?
4. La gestion des erreurs est-elle appropriée ?

Score : 1-5 (1=mauvais, 5=excellent)
Justification : [explication]

3. Correcteur humain

Marquer pour révision manuelle :

[RÉVISION HUMAINE REQUISE]
Changement : Description de ce qui a changé
Raison : Pourquoi une révision humaine est nécessaire
Niveau de risque : FAIBLE/MOYEN/ÉLEVÉ

Métriques

pass@k

"Au moins un succès en k tentatives"

• pass@1 : Taux de succès à la première tentative
• pass@3 : Succès en 3 tentatives
• Cible typique : pass@3 > 90%

pass^k

"Les k essais réussissent tous"

• Barre plus haute pour la fiabilité
• pass^3 : 3 succès consécutifs
• Utiliser pour les chemins critiques

Workflow d'évaluation

1. Définir (Avant de coder)

## DÉFINITION D'ÉVALUATION : fonctionnalité-xyz

### Évaluations de capacité
1. Peut créer un nouveau compte utilisateur
2. Peut valider le format de l'email
3. Peut hacher le mot de passe de manière sécurisée

### Évaluations de régression
1. La connexion existante fonctionne toujours
2. La gestion de session inchangée
3. Le flux de déconnexion intact

### Métriques de succès
- pass@3 > 90% pour les évaluations de capacité
- pass^3 = 100% pour les évaluations de régression

2. Implémenter

Écrire le code pour réussir les évaluations définies.

3. Évaluer

# Exécuter les évaluations de capacité
[Exécuter chaque évaluation de capacité, enregistrer RÉUSSI/ÉCHEC]

# Exécuter les évaluations de régression
npm test -- --testPathPattern="existant"

# Générer le rapport

4. Rapporter

RAPPORT D'ÉVALUATION : fonctionnalité-xyz
==========================================

Évaluations de capacité :
  créer-utilisateur :     RÉUSSI (pass@1)
  valider-email :        RÉUSSI (pass@2)
  hacher-mot-de-passe :  RÉUSSI (pass@1)
  Total :                3/3 réussi

Évaluations de régression :
  flux-connexion :       RÉUSSI
  gestion-session :      RÉUSSI
  flux-déconnexion :     RÉUSSI
  Total :                3/3 réussi

Métriques :
  pass@1 : 67% (2/3)
  pass@3 : 100% (3/3)

Statut : PRÊT POUR RÉVISION

Modèles d'intégration

Avant implémentation

/eval define nom-fonctionnalité

Crée un fichier de définition d'évaluation dans .claude/evals/nom-fonctionnalité.md

Pendant l'implémentation

/eval check nom-fonctionnalité

Exécute les évaluations actuelles et rapporte l'état

Après implémentation

/eval report nom-fonctionnalité

Génère un rapport d'évaluation complet

Stockage des évaluations

Stocker les évaluations dans le projet :

.claude/
  evals/
    fonctionnalité-xyz.md      # Définition d'évaluation
    fonctionnalité-xyz.log     # Historique des exécutions
    baseline.json              # Références de régression

Bonnes pratiques

1. Définir les évaluations AVANT de coder - Oblige à réfléchir clairement aux critères de succès
2. Exécuter les évaluations fréquemment - Détecter les régressions tôt
3. Suivre le pass@k dans le temps - Surveiller les tendances de fiabilité
4. Utiliser des correcteurs par code quand possible - Déterministe > probabiliste
5. Révision humaine pour la sécurité - Ne jamais automatiser entièrement les vérifications de sécurité
6. Garder les évaluations rapides - Les évaluations lentes ne sont pas exécutées
7. Versionner les évaluations avec le code - Les évaluations sont des artefacts de première classe

Exemple : Ajout d'authentification

## ÉVALUATION : ajouter-authentification

### Phase 1 : Définir (10 min)
Évaluations de capacité :
- [ ] L'utilisateur peut s'inscrire avec email/mot de passe
- [ ] L'utilisateur peut se connecter avec des identifiants valides
- [ ] Les identifiants invalides sont rejetés avec une erreur appropriée
- [ ] Les sessions persistent après rechargement de page
- [ ] La déconnexion efface la session

Évaluations de régression :
- [ ] Les routes publiques restent accessibles
- [ ] Les réponses API inchangées
- [ ] Le schéma de base de données compatible

### Phase 2 : Implémenter (variable)
[Écrire le code]

### Phase 3 : Évaluer
Exécuter : /eval check ajouter-authentification

### Phase 4 : Rapporter
RAPPORT D'ÉVALUATION : ajouter-authentification
================================================
Capacité : 5/5 réussi (pass@3 : 100%)
Régression : 3/3 réussi (pass^3 : 100%)
Statut : À LIVRER

Utilitaires locaux du cadre

Les utilitaires mécaniques sont livrés dans scripts/lib/eval-harness/ :

node scripts/eval-harness.js example

• Capsule : journal lié par hachage avec cinq lignées et vérifications d'intégrité locales.
• Inspection : condensés de source, chemins de variantes validés et avertissements syntaxiques.
• Relecture : outils déclarés et fixtures adressées par contenu. Les fixtures manquantes échouent en mode fermé ; SE3 et supérieur est refusé en relecture. Le mode d'enregistrement invoque l'implémentation enregistrée, donc n'enregistrer que des fonctions de confiance.
• Reçu : vérification hors ligne des octets de capsule et d'artefact, avec vérifications nommées.
• Préparation rétrospective : node scripts/eval-harness.js capsule group <dossier> [<dossier> ...] groupe 1 à 100 instantanés de capsule explicitement sélectionnés et vérifiés localement d'une famille de tâches par version de cadre déclarée. Les instantanés répétés comptent une fois ; les identités conflictuelles ou les capsules invalides rejettent l'ensemble du rapport. Ceci est un comptage d'enregistrements en lecture seule, sans nouveau déploiement, score ou promotion. Utiliser des capsules petites et quiescentes. Les charges utiles, arguments de dossier et identifiants bruts d'exécution/capsule sont omis, mais les étiquettes famille-tâche/version sont textuelles et les références de condensé sont liables ; les réviser avant de partager. La validation opérationnelle reste en attente.

L'exécution de candidats est désactivée sur tous les OS car aucun backend de confinement OS vérifié n'est implémenté. gate run, runGate, runVariant, le lancement direct d'enfant, et le préchargement d'effet retiré refusent avec gate.isolation_required. Aucun indicateur de confiance ou exécuteur fourni par l'appelant ne peut contourner le refus. L'exemple enregistre ce refus et inspecte la source sans l'exécuter ni la noter.

Ne pas présenter d'avertissements statiques, de reçu de capsule ou de tests utilitaires réussis comme preuve de confinement de candidat ou de promotion. Une future porte nécessite une frontière OS examinée indépendamment, un vérificateur protégé et des canaux d'audit, et un rejet de référence fatal. Voir docs/architecture/eval-harness-frameworks.md.

Évaluations produit (v1.8)

Utiliser les évaluations produit lorsque la qualité du comportement ne peut pas être capturée par les tests unitaires seuls.

Types de correcteurs

1. Correcteur de code (assertions déterministes)
2. Correcteur de règles (contraintes regex/schéma)
3. Correcteur de modèle (grille LLM-en-tant-que-juge)
4. Correcteur humain (adjudication manuelle pour les sorties ambiguës)

Guide pass@k

• pass@1 : fiabilité directe
• pass@3 : fiabilité pratique sous tentatives contrôlées
• pass^3 : test de stabilité (les 3 exécutions doivent réussir)

Seuils recommandés :

• Évaluations de capacité : pass@3 >= 0.90
• Évaluations de régression : pass^3 = 1.00 pour les chemins critiques de version

Anti-patrons d'évaluation

• Surapprentissage des prompts sur des exemples d'évaluation connus
• Mesurer uniquement les sorties de chemin heureux
• Ignorer la dérive de coût et de latence tout en poursuivant les taux de réussite
• Autoriser des correcteurs instables dans les portes de version

Disposition minimale d'artefact d'évaluation

• Définition .claude/evals/<fonctionnalité>.md
• Historique .claude/evals/<fonctionnalité>.log
• Instantané de version docs/releases/<version>/eval-summary.md