Auto-évaluation de l'agent
Après avoir terminé une tâche complexe, l'agent fait une pause pour évaluer sa propre sortie selon une grille structurée à 5 axes. Ce n'est PAS un portail de validation — c'est une étape de réflexion délibérée qui permet de détecter les omissions, de signaler les excès de confiance et de mettre en évidence les domaines d'amélioration avant que l'utilisateur n'ait à le faire.
Quand activer
- Après avoir écrit du code qui s'étend sur 3+ fichiers ou 50+ lignes
- Après avoir terminé un workflow en plusieurs étapes (implémenter → tester → réviser)
- Après une session de débogage qui a impliqué 3+ tentatives
- Après avoir produit un document de conception, une décision d'architecture ou une analyse écrite
- Lorsque l'utilisateur demande « c'était comment? » ou « note-toi »
- À la fin de tout crochet de session Stop (si configuré — voir
references/hook-integration.md)
Concepts de base
Les 5 axes d'évaluation
| Axe | Question | Ce qu'il détecte |
|---|---|---|
| Exactitude | Les faits, affirmations et résultats sont-ils corrects? | Hallucinations, noms d'API erronés, syntaxe incorrecte, fausses déclarations |
| Exhaustivité | Tout ce que l'utilisateur a demandé a-t-il été couvert? | Cas limites manqués, chemins d'erreur non traités, exigences oubliées, sous-tâches ignorées |
| Clarté | L'explication est-elle compréhensible et bien structurée? | Explications confuses, jargon sans définition, contexte manquant, digressions |
| Caractère actionnable | L'utilisateur peut-il agir immédiatement sur la sortie? | Suggestions vagues, étapes manquantes, « vous devriez X » sans montrer comment, absence de chemin de vérification |
| Concision | La sortie utilise-t-elle le minimum de mots/tokens nécessaire? | Redondance, sur-explication, répétition textuelle de la question de l'utilisateur, contenu de remplissage |
Échelle de notation
5 — Exceptionnel : aucune amélioration raisonnable possible
4 — Bon : seulement des broutilles mineures, pas de lacunes substantielles
3 — Correct : répond à la demande mais présente une faiblesse notable sur au moins un axe
2 — Faible : présente une lacune évidente qui affecte la facilité d'utilisation ou la correction
1 — Médiocre : ne répond pas fondamentalement à la demande ou contient des erreurs significatives
La règle de la preuve
Tout score inférieur à 5 DOIT citer des preuves spécifiques. Un score de 3 ne peut pas simplement dire « pourrait être mieux » — il doit dire exactement ce qui manque ou ce qui ne va pas. Le mantra : « Montre la lacune, ne te contente pas de la nommer. »
Workflow
Étape 1 : Collecter le matériel brut
Rassemblez ce que vous allez évaluer :
- La demande originale de l'utilisateur (relire à partir de la conversation)
- Votre réponse/sortie finale (le livrable)
- Toutes les sorties d'outils qui vérifient l'exactitude (résultats de tests, codes de sortie, sortie de lint)
- Tous les retours utilisateur reçus pendant la tâche (corrections, « réessaye », « ce n'est pas correct »)
Étape 2 : Noter chaque axe indépendamment
Parcourez les 5 axes un par un. Pour chacun :
- Lisez la question de l'axe
- Trouvez des preuves (ou l'absence de preuves) dans la sortie
- Attribuez un score de 1 à 5
- Si le score est < 5, rédigez une note d'amélioration d'une phrase citant la lacune
Ne faites PAS la moyenne des scores dans votre tête en premier et ne travaillez pas à rebours. Notez chaque axe à partir de zéro.
Étape 3 : Produire le rapport d'évaluation
Utilisez le modèle de templates/evaluation-report.md. Le rapport doit inclure :
- Résumé en une ligne
- Tableau de bord à 5 axes (score + preuve par axe)
- Score global (moyenne simple, arrondie à 1 décimale)
- 1 à 3 améliorations spécifiques classées par impact
- Auto-vérification : « L'utilisateur serait-il d'accord avec cette évaluation? »
Étape 4 : Appliquer l'amélioration
Si un axe a obtenu un score de 3 ou moins :
- Indiquez ce que vous feriez différemment
- Si la lacune peut être corrigée en moins de 30 secondes (lien manquant, formulation peu claire), corrigez-la maintenant
- Si la lacune nécessite une refonte, signalez-la explicitement : « Cet axe a obtenu un score de [raison] parce que [preuve]. Recommencer avec [correction spécifique] le porterait probablement à [score]. »
Exemples de code
Exemple : Bonne évaluation (Score 4+)
Tâche : Ajouter une logique de réessai au client HTTP
Tableau de bord :
Exactitude : 5 — Tous les appels API corrects. Vérifié : les réessais
utilisent un backoff exponentiel. Aucune méthode hallucinée.
Exhaustivité : 4 — Chemin heureux + 3 cas d'erreur couverts. Manquant :
gestion des délais d'attente pour les connexions bloquées.
Clarté : 5 — Les commentaires de code expliquent la formule de backoff.
La description de la PR renvoie à l'incident qui a motivé cela.
Caractère actionnable :5 — Une seule fusion. Aucune tâche de suivi. Les tests passent.
Concision : 4 — 47 lignes au total. La boucle de réessai pourrait être extraite
dans une aide pour réduire d'environ 8 lignes.
Score global : 4.6 — Une lacune (gestion des délais d'attente). Corriger avant la fusion.
Exemple : Évaluation faible (Score 2-3)
Tâche : Ajouter une logique de réessai au client HTTP
Tableau de bord :
Exactitude : 2 — Utilisation d'urllib3 qui ne correspond pas à notre
base de code basée sur httpx. Mauvaise bibliothèque.
Exhaustivité : 3 — Fonctionne pour GET. POST/PUT non traités (l'utilisateur
a dit « toutes les requêtes HTTP »).
Clarté : 4 — Code lisible. Bons noms de variables.
Caractère actionnable :2 — « Ajouter des tests » mentionné mais aucun fichier de test créé.
L'utilisateur doit écrire les tests avant la fusion.
Concision : 3 — 120 lignes. La configuration de réessai est dupliquée dans
3 endroits au lieu d'un objet RetryConfig partagé.
Score global : 2.8 — Mauvaise bibliothèque utilisée. Nécessite une réécriture en httpx.
Corriger d'abord l'exactitude (passer à httpx), puis étendre à toutes les
méthodes HTTP, puis consolider la configuration.
Anti-patrons
« Tout est un 5 »
ÉCHEC : Exactitude : 5 — Tout va bien.
Exhaustivité : 5 — Tout couvert.
Clarté : 5 — Clair.
Aucune preuve citée. C'est de l'auto-congratulation, pas une évaluation. Un vrai 5 nécessite de prouver qu'il n'y a rien à améliorer.
Pénalisation excessive pour l'élargissement de la portée
ÉCHEC : Exhaustivité : 2 — N'a pas géré les connexions WebSocket ni
le streaming gRPC (l'utilisateur n'a pas demandé cela)
Évaluez uniquement ce que l'utilisateur a réellement demandé, pas ce que vous auriez pu construire en plus.
Utiliser l'évaluation pour re-contester
ÉCHEC : « Comme je l'ai dit plus tôt, cette approche est erronée. Score : 1 »
L'évaluation porte sur la sortie livrée, pas sur le fait de re-discuter des décisions de conception déjà prises. Si l'approche était erronée, cela aurait dû être détecté avant la livraison.
Mélanger préférence personnelle et lacunes objectives
ÉCHEC : « Score : 3. Je n'aime pas les décorateurs Python. »
« Je n'aime pas » n'est pas une preuve. Citez un problème concret de lisibilité, de testabilité ou de correction, ou laissez le score à 4+.
Bonnes pratiques
- Évaluez la sortie, pas le processus. L'utilisateur se soucie de ce que vous avez livré, pas du nombre d'itérations que vous avez effectuées.
- Une amélioration par axe faible. Ne listez pas 5 choses pour un axe — choisissez la lacune ayant le plus grand impact.
- Lie les améliorations à l'impact utilisateur. « La gestion d'erreur manquante signifie que l'appel API de l'utilisateur plantera silencieusement » est mieux que « ajouter la gestion d'erreur. »
- Soyez précis sur ce à quoi ressemble « corrigé ». « Relancer avec un transport httpx configuré pour les réessais » est mieux que « corriger le problème de bibliothèque. »
- Utilisez les sorties d'outils comme preuves. Si les tests passent, citez-les. Si le lint est propre, citez-le. Ne devinez pas — cherchez la preuve.
- Si vous ne trouvez aucune lacune, essayez plus fort. Un score parfait sur les 5 axes est rare. Demandez : « Si j'étais l'utilisateur, qu'est-ce qui m'agacerait dans cette sortie ? »
Compétences associées
agent-eval— Comparaison tête-à-tête de différents agents de codage sur des tâches de référenceverification-loop— Vérification systématique des sorties par rapport aux résultats attendussecurity-review— Liste de contrôle de révision de code axée sur la sécurité