eval-harness

Skill Eval Harness

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

Quand l'activer

• Mise en place du développement piloté par les évaluations (EDD) pour les workflows assistés par IA
• Définition des critères de réussite/échec pour l'achèvement de tâches Claude Code
• Mesure de la fiabilité de l'agent avec les métriques pass@k
• Création de suites de tests de régression pour les modifications de prompts ou d'agents
• Évaluation comparative des performances de l'agent entre versions de modèles

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 accomplir 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
Résultat attendu : 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 : SUCCÈS/ÉCHEC
  - test-existant-2 : SUCCÈS/ÉCHEC
  - test-existant-3 : SUCCÈS/ÉCHEC
Résultat : X/Y réussis (auparavant Y/Y)

Types de correcteurs

1. Correcteur basé sur le code

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

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

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

# Vérifier si la construction réussit
npm run build && echo "SUCCÈS" || echo "ÉCHEC"

2. Correcteur basé sur un modèle

Utiliser Claude pour évaluer les résultats ouverts :

[PROMPT DU CORRECTEUR MODÈLE]
Évaluez la modification de code suivante :
1. Résout-elle le problème énoncé ?
2. Est-elle bien structurée ?
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]
Modification : 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 dès la première tentative
• pass@3 : Succès en 3 tentatives maximum
• Objectif typique : pass@3 > 90 %

pass^k

"Les k tentatives réussissent toutes"

• 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 le codage)

## 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 des sessions 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 SUCCÈS/ÉCHEC]

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

# Générer le rapport

4. Rapporter

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

Évaluations de capacité :
  créer-utilisateur :     SUCCÈS (pass@1)
  valider-email :         SUCCÈS (pass@2)
  hacher-mot-de-passe :   SUCCÈS (pass@1)
  Total :                 3/3 réussis

Évaluations de régression :
  flux-connexion :        SUCCÈS
  gestion-session :       SUCCÈS
  flux-déconnexion :      SUCCÈS
  Total :                 3/3 réussis

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

Statut : PRÊT POUR RÉVISION

Modèles d'intégration

Pré-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

Post-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 d'évaluation
    baseline.json              # Références pour les régressions

Bonnes pratiques

1. Définir les évaluations AVANT le codage - Force une réflexion claire sur les critères de succès
2. Exécuter les évaluations fréquemment - Détecter les régressions tôt
3. Suivre pass@k dans le temps - Surveiller les tendances de fiabilité
4. Utiliser des correcteurs basés sur le code quand c'est 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 sont toujours 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éussis (pass@3 : 100 %)
Régression : 3/3 réussis (pass^3 : 100 %)
Statut : PRÊT À LIVRER

Utilitaires du cadre local

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

node scripts/eval-harness.js exemple

• 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.
• Rejeu : outils déclarés et accessoires adressés par contenu. Les accessoires manquants échouent en mode sécurité ; SE3 et supérieur sont refusés en rejeu. Le mode enregistrement invoque l'implémentation enregistrée, donc n'enregistrez 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 de 1 à 100 instantanés de capsule locaux explicitement sélectionnés et vérifiés d'une même famille de tâches par version de harness déclarée. Les instantanés répétés comptent une seule fois ; les identités conflictuelles ou les capsules invalides rejettent le rapport entier. Il s'agit d'un comptage de relevés en lecture seule, sans nouveau déploiement, score ou promotion. Utilisez des capsules petites et au repos. Les charges utiles, les arguments de dossier et les 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 ; révisez-les avant de les partager. La validation opérationnelle reste en attente.

L'exécution de candidat 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 présentez pas d'avertissements statiques, de reçu de capsule ou de tests utilitaires réussis comme preuve de confinement ou de promotion de candidat. Une future passerelle nécessite une frontière OS révisée indépendamment, des canaux de vérification et d'audit protégés, et un rejet fatal de référence. Voir docs/architecture/eval-harness-frameworks.md.

Évaluations de produit (v1.8)

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

Types de correcteurs

1. Correcteur basé sur le code (assertions déterministes)
2. Correcteur basé sur des règles (contraintes regex/schéma)
3. Correcteur basé sur un modèle (grille LLM-en-tant-que-juge)
4. Correcteur humain (arbitrage manuel 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 en version

Anti-patrons d'évaluation

• Surapprentissage des prompts sur des exemples d'évaluation connus
• Mesure uniquement des sorties de scénarios heureux
• Ignorer la dérive des coûts et de la latence en poursuivant les taux de réussite
• Autoriser des correcteurs instables dans les passerelles de version

Structure minimale d'artefact d'évaluation

• .claude/evals/<fonctionnalité>.md définition
• .claude/evals/<fonctionnalité>.log historique des exécutions
• docs/releases/<version>/eval-summary.md instantané de version