8.6 KiB
Plan de review des agents — conditions réelles
⚠️ Ce fichier concerne la qualité des AGENTS, pas les tests du code applicatif. Tests code → Jest/Vitest dans chaque projet.
La boucle en une phrase
Lancer → Capturer → Évaluer → Patcher → Documenter.
Chaque review laisse l'agent meilleur qu'avant et le brain plus riche qu'à son départ.
Phrases d'invocation — copier-coller direct
1. Lancer la review (session projet)
Charge l'agent <nom>.
<Cas concret — voir "Use cases concrets" ci-dessous>
Exemple réel :
Charge l'agent monitoring.
Audite la couverture de surveillance actuelle sur Uptime Kuma.
Identifie ce qui manque et propose les sondes à créer.
2. Patcher avec le recruiter (après évaluation)
Charge l'agent recruiter.
Lis brain/agents/reviews/<Projet>/<agent>-v1.md.
Améliore l'agent <nom> en intégrant les gaps identifiés.
3. Fermer la boucle avec le scribe (fin de session)
Charge l'agent scribe.
On vient de faire la review de <agent> — mets le brain à jour.
Phrase complète — session de review dédiée
On review l'agent <nom>.
Projet de test : <projet>.
Cas soumis : <description courte du problème à lui soumettre>.
Prépare le template, lance-le, évalue, patche avec recruiter, scribe en fin.
Philosophie — progression hexagonale
Comme en architecture hexagonale : chaque couche doit être solide avant d'en ajouter une autre.
Review 1 (security) → identifie les patterns manquants
Review 2 (code-review) → confirme le pattern → correction systématique
Review 3 (testing) → le pattern est acquis, on cherche d'autres gaps
...
Review N (scribe) → le scribe lui-même est reviewé avec les mêmes critères
Ce que chaque review apporte :
- Un agent testé en conditions réelles (pas en théorie)
- Un gap documenté = une règle qui ne sera plus oubliée
- Un pattern transversal détecté = tous les agents suivants en bénéficient
- Un changelog qui raconte l'histoire des améliorations
Signal de progression réelle : quand les gaps trouvés en v1 disparaissent en v2. Pas parce qu'on les a ignorés — parce que l'agent a vraiment appris.
Procédure complète — step by step
Étape 1 — Préparer le fichier de capture
cp brain/agents/reviews/_template.md brain/agents/reviews/<Projet>/<agent>-v1.md
Remplir l'en-tête : agent reviewé, date, projet, cas soumis.
Étape 2 — Lancer l'agent dans une session Claude Code
Ouvrir une session dans le projet concerné, charger l'agent, lui soumettre le cas. → Voir "Phrases d'invocation" + "Use cases concrets" ci-dessous.
Étape 3 — Capturer l'output
Copier-coller l'intégralité de la réponse de l'agent dans reviews/<Projet>/<agent>-v1.md.
Section "Output brut de l'agent" du template.
Étape 4 — Évaluer
Remplir les sections ✅ ❌ ⚠️ 📐 du template. Identifier les gaps concrets : qu'est-ce qui manquait ? qu'a-t-il inventé ? a-t-il débordé ?
Étape 5 — Améliorer l'agent (si gaps)
Charge l'agent recruiter.
Lis brain/agents/reviews/<Projet>/<agent>-v1.md.
Améliore l'agent <nom> en intégrant les gaps identifiés.
Étape 6 — Scribe + re-tester
Charge l'agent scribe.
On vient de faire la review de <agent> — mets le brain à jour.
Répéter étapes 2-4 → sauvegarder dans <agent>-v2.md.
Comparer v1 / v2 — noter dans le changelog de l'agent.
Use cases concrets — prompts exacts
orchestrator — "Je ne sais pas par où commencer"
Charge l'agent orchestrator.
Je veux préparer Super-OAuth pour un déploiement en production.
Je ne sais pas par où commencer ni quels agents charger.
Dis-moi ce qui doit être fait et dans quel ordre.
Ce qu'on vérifie : identifie-t-il les bons domaines ? Propose-t-il un ordre logique ? Reste-t-il coordinateur (ne code pas, ne déploie pas) ? Statut : ✅ Testé 2026-03-12 — RÉUSSI
security — Audit avant prod
Charge l'agent security.
Audite la branche feature/security-hardening de Super-OAuth.
Focus sur : JWT blacklist Redis, CSRF, CSP nonce, device fingerprinting.
Dis-moi si l'implémentation est correcte et ce qui manque.
Ce qu'on vérifie : connaît-il les mécanismes déjà en place (ne les re-propose pas) ? Trouve-t-il de vrais gaps ? Respecte-t-il les priorités d'audit dans l'ordre ?
code-review — Review d'un fichier
Charge l'agent code-review.
Review ce fichier : [coller le contenu ou donner le chemin]
Projet : Super-OAuth, architecture DDD.
Ce qu'on vérifie : format adapté (inline si court, rapport si long) ? Explique-t-il le pourquoi de chaque finding ? Respecte-t-il le périmètre ?
testing — Stratégie coverage
Charge l'agent testing.
Analyse la couverture actuelle de Super-OAuth.
Identifie les zones critiques non couvertes (priorité : couches DDD auth flows).
Propose une stratégie pour atteindre une couverture suffisante avant prod.
Ce qu'on vérifie : connaît-il la structure DDD par couche ? Distingue-t-il les tests unitaires des tests d'intégration ? Propose-t-il TDD ou rétroactif selon le contexte ?
debug — Diagnostic d'une erreur
Charge l'agent debug.
J'ai cette erreur : [coller la stack trace ou décrire le symptôme]
Projet : Super-OAuth, stack Express + TypeORM + Redis.
Aide-moi à isoler la cause.
Ce qu'on vérifie : suit-il la méthode en 5 étapes (reproduire → isoler → hypothèses → vérifier → corriger) ? Formule-t-il des hypothèses ordonnées par probabilité ?
ci-cd — Créer un pipeline
Charge l'agent ci-cd.
Je veux créer le pipeline de déploiement prod pour Super-OAuth.
CI actuel : tests seulement (ci.yml). À ajouter : build + SSH deploy + migration TypeORM.
Stack : Node.js 22, TypeScript, Docker.
Ce qu'on vérifie : adapte-t-il au type de projet (Node.js + Docker) ? Connaît-il les secrets VPS ? Propose-t-il d'ajouter le template dans toolkit/ ?
monitoring — Audit couverture Kuma
Charge l'agent monitoring.
Audite la couverture de surveillance actuelle sur Uptime Kuma.
Identifie ce qui manque et propose les sondes à créer.
Ce qu'on vérifie : connaît-il l'infra réelle (containers, sous-domaines, monitoring.md) ? Détecte-t-il les gaps entre ce qui est surveillé et ce qui devrait l'être ?
scribe — Bilan de session
Charge l'agent scribe.
Fais le bilan de cette session et mets le brain à jour.
Ce qu'on vérifie : identifie-t-il les bons fichiers à mettre à jour ? Propose-t-il validation avant les changements importants ?
mentor — Interpréter un plan
Charge l'agent mentor.
L'orchestrator vient de proposer ce plan : [coller l'output].
Explique-moi pourquoi security passe avant code-review.
Vérifie que j'ai bien compris la logique avant qu'on continue.
Ce qu'on vérifie : explique-t-il le pourquoi (pas juste le quoi) ? Pose-t-il une question de vérification sans surcharger ?
refacto — Audit dette technique
Charge l'agent refacto.
Audite OriginsDigital — identifie la dette technique principale.
Propose un plan de refacto en étapes atomiques.
Règle absolue : aucune logique métier ne doit disparaître.
Ce qu'on vérifie : produit-il un plan en étapes, du moins risqué au plus risqué ? Demande-t-il validation avant de passer à l'exécution ?
Ordre recommandé
| # | Agent | Projet | Statut |
|---|---|---|---|
| 1 | orchestrator |
Super-OAuth | ✅ 2026-03-12 |
| 2 | security |
Super-OAuth | ✅ 2026-03-12 |
| 3 | code-review |
Super-OAuth | ✅ 2026-03-12 |
| 4 | testing |
Super-OAuth | ✅ 2026-03-12 |
| 5 | debug |
Super-OAuth | ✅ 2026-03-12 |
| 6 | ci-cd |
Super-OAuth | ✅ 2026-03-12 |
| 7 | monitoring |
Infra | ✅ 2026-03-12 |
| 8 | scribe |
Brain | ✅ 2026-03-12 |
| 9 | mentor |
Super-OAuth | ✅ 2026-03-12 |
| 10 | optimizer-db |
Super-OAuth | ✅ 2026-03-12 |
| 11 | refacto |
Super-OAuth | ✅ 2026-03-12 |
| 12 | optimizer-backend |
Super-OAuth | ✅ 2026-03-12 |
| 13 | optimizer-frontend |
Portfolio | ✅ 2026-03-12 |
Critères de validation d'un agent
- ✅ Output utile et ancré dans la réalité (pas d'invention)
- ✅ Anti-hallucination : dit "Information manquante" quand nécessaire
- ✅ Périmètre respecté : ne déborde pas, délègue ce qui ne le concerne pas
- ✅ Format adapté au cas soumis
Notation changelog après review
| 2026-XX-XX | Review réelle — <Projet> : ✅ <ce qui a marché> / ❌ <gap identifié> / 🔧 <correction appliquée> |