🐘🐟 Mode de développement Éléphant et Poisson Rouge
📌 Aperçu
- 🐘 Éléphant (Coordinateur, c'est vous) : a une mémoire globale. Responsable de la communication, de la rédaction des spécifications CUJ, de l'attribution des tâches et de la révision des résultats. N'écrit pas de code, n'exécute pas les tests.
- 🐟 Poisson Rouge (Codeur / Testeur / Relecteur) : sous-agent sans état, sans bagage historique. Exécute uniquement les CUJ, puis disparaît, évitant la contamination du contexte.
🚦 Étape 0 : Déterminez si cette tâche suit ce flux
C'est la première décision, ne la sautez pas.
| Type de tâche | Suit ce flux ? |
|---|---|
| Nouvelle fonctionnalité ou module | ✅ |
| Modification du comportement d'une fonction existante | ✅ |
| Refactorisation impliquant un changement d'interface externe | ✅ |
| Correction de bug nécessitant une modification logique | ✅ |
| Simple mise à jour de documentation (README, commentaires) | ❌ |
| Formatage de code / lint | ❌ |
| Mise à jour de dépendances (aucun changement de comportement) | ❌ |
| Réglage de configuration mineur | ❌ |
| Hotfix urgent (bug critique en production) | ❌ Corrigez directement, puis effectuez une validation Tester |
Par défaut pour les cas ambigus : modification ≤ 10 lignes et ne changeant aucun comportement externe observable → ne pas suivre le flux.
❌ Si non applicable, agissez selon les règles existantes du projet, ne mentionnez pas cette compétence et n'écrivez pas de CUJ pour suivre le flux.
🎯 Principes fondamentaux
- Critère du Poisson Rouge : Un nouveau sous-agent (Poisson Rouge), avec uniquement le document CUJ, doit pouvoir réaliser indépendamment tout le flux explication → implémentation → test. Si ce n'est pas possible, cela signifie que les spécifications ne sont pas assez bonnes, pas que l'IA n'est pas assez intelligente.
- Séparation stricte des rôles : Celui qui écrit le code (Codeur) ne peut pas corriger sa propre copie (Testeur / Relecteur).
- Spécifications + Tests : Le CUJ définit « ce qui est souhaité », les tests prouvent « que c'est atteint ». Les deux sont essentiels ; sans l'un ou l'autre, le CUJ devient un document pour humains, et non un contrat exécutable pour le Poisson Rouge.
- Faites confiance au script, pas seulement au Markdown : Utilisez
scripts/validate_cuj.pypour une vérification objective, ne vous fiez pas à votre ressenti.
🚀 Flux
Étape 1 : Chargez les références selon les besoins
Ne lisez pas tout à la fois. Chargez en fonction des besoins réels du moment : c'est l'essence de la révélation progressive :
| Quand lire | Quel document |
|---|---|
| Avant d'envoyer un Poisson Rouge (obligatoire) | references/dispatch-prompts.md |
| Si vous n'êtes pas sûr qu'un rôle puisse faire quelque chose | references/role-separation.md |
| Si vous n'êtes pas sûr du niveau de détail requis pour un CUJ, ou si la validation échoue | references/cuj-workflow.md |
| Pour commencer à rédiger un CUJ | assets/cuj-template.md (format)assets/cuj-001-user-login.md (exemple de qualité) |
| Si l'outil utilisé n'a pas de mécanisme de sous-agent | Tableau de correspondance multi-outils dans references/role-separation.md |
Étape 2 : Rédigez le CUJ
- Suivez le format du modèle, sauvegardez dans le répertoire
cuj/du projet, nommécuj-XXX-description-courte.md - Le
iddu frontmatter doit correspondre au préfixe du nom de fichier (voir Gotchas) - Si les exigences sont floues, clarifiez avant d'écrire — voir le mécanisme de clarification dans
cuj-workflow.mdétape 2 (en dehors du périmètre de cette compétence)
Étape 3 : Validez le CUJ (étape objective)
python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/
- exit code 0 pour passer à l'étape 4
- Non 0 → Corrigez le CUJ selon le message d'erreur, réexécutez jusqu'à réussite, ne contournez pas
- Après réussite, posez-vous la question du test du Poisson Rouge — le script vérifie la structure, cette question vérifie la convivialité
Étape 4 : Envoyez le Poisson Rouge et convergez
Lisez obligatoirement avant l'envoi la liste « ❌ Ne pas inclure » dans references/dispatch-prompts.md. La séparation des rôles est le plus souvent brisée au moment de l'envoi.
Exécutez dans l'ordre, pas en parallèle, pas de fusion des rôles :
- 4a. Envoyer Codeur — donnez uniquement le chemin du CUJ et du fichier à modifier, pas l'historique de la conversation
- 4b. Envoyer Testeur (sous-agent indépendant) — donnez uniquement les critères d'acceptation et les cas de test du CUJ, pas le contexte d'implémentation ou le résumé de la sortie du Codeur
- 4c. En cas d'échec du test — transmettez le message d'échec à un nouveau Codeur Poisson Rouge pour correction, puis revenez à 4b pour retester. N'utilisez pas le même Codeur pour corriger jusqu'à réussite, cela reviendrait à le laisser corriger sa propre copie
- 4d. Envoyer Relecteur (sous-agent indépendant, optionnel) — donnez uniquement le chemin du code et les critères d'acceptation, pas le résultat du Testeur
- 4e. Coordinateur synthétise — mettez à jour le
statusdu CUJ, rapportez les résultats réels à l'utilisateur
Condition de convergence : Chaque critère d'acceptation a un test correspondant et tous réussissent.
Limite d'échec : Si le cycle 4b ↔ 4c s'exécute 3 fois sans convergence → arrêtez les corrections aveugles,
retournez à l'étape 2 pour examiner le CUJ lui-même (spécifications contradictoires, critères d'acceptation non testables, conditions préalables manquantes).
⚠️ Gotchas
Faits environnementaux à connaître pour ne pas tomber dans les pièges :
iddoit correspondre au préfixe du nom de fichier —id: cuj-001doit correspondre àcuj-001-*.md, sinon échec direct- La recherche par répertoire ne scanne que
cuj-*.md— un nom de fichier mal orthographié (ex.cju-001-x.md) sera listé comme « ignoré » et non comme « échec », vérifiez la liste des ignorés dans la sortie - Le seuil de contenu des sections varie selon la langue — 10 caractères pour les langues CJK, 30 pour le pur occidental, évalué section par section.
Utilisez
--min-section-chars Npour le personnaliser - Le script de validation nécessite Python 3.12+, même si le projet lui-même n'est pas en Python
- « Ignoré » n'est pas égal à « Réussi » — Vérifiez le nombre de
Réussidans la ligne de résumé, ne regardez pas seulement s'il y a un ✅ - Le script ne valide que la structure, pas la sémantique — « Cela devrait fonctionner correctement » est structurellement identique à un critère d'acceptation concret, et peut passer le script. Le script est le plancher, le point de contrôle du test du Poisson Rouge est le plafond
🛑 Anti-Rationalisation & Signaux d'alarme
Périmètre d'application : Les règles suivantes ne s'appliquent que lors du développement de fonctionnalités suivant ce flux, ce ne sont pas des règles absolues en permanence. Pour les tâches d'exploitation, la validation avant déploiement et les hotfix urgents, suivez les règles existantes du projet. En cas de conflit avec les normes existantes du projet lors de l'import, gérez par domaine, ne les écrasez pas mutuellement.
- ❌ Interdiction absolue que le Coordinateur écrive lui-même des modifications de plus de 10 lignes, ou exécute directement des commandes de test.
- ❌ Interdiction absolue de copier le contexte d'implémentation du Codeur au Testeur ; le Testeur doit tester de manière indépendante, dans un contexte propre, en se basant uniquement sur les critères d'acceptation du CUJ.
- ❌ Interdiction absolue de considérer la validation réussie simplement parce que le script imprime ✅ — vérifiez le nombre de
Réussidans la ligne de résumé. - ❌ Interdiction absolue de modifier les tests ou d'assouplir les critères d'acceptation pour les faire réussir. Un échec de test est une information précieuse.
Plus d'excuses courantes et de réfutations dans le tableau Anti-Rationalisation de references/role-separation.md.
🔲 Périmètre de responsabilité
Cette compétence ne couvre que le mécanisme Éléphant et Poisson Rouge lui-même, pas l'ensemble du cycle de vie du développement :
| Phase | Cette compétence | Description |
|---|---|---|
| ① Définir les besoins | Hors périmètre | Responsabilité humaine |
| ② Clarifier les besoins | Hors périmètre (définit le contrat) | Chaque outil s'en charge, voir étape 2 de cuj-workflow.md |
| ③ Générer le CUJ | ✅ Cœur | Modèle CUJ + validate_cuj.py |
| ④ Développement | ✅ Cœur | Séparation des quatre rôles + modèle de prompt d'envoi |
| ⑤ Post-mortem | Hors périmètre | Utilisez les mécanismes natifs des outils (ex. memory de Claude Code) |
Une compétence fait une seule chose. La clarification des besoins et l'apprentissage/décantation peuvent être réalisés avec des compétences indépendantes matures, il est inutile de réinventer la roue.
⚙️ Prérequis
| Élément | Prérequis |
|---|---|
scripts/validate_cuj.py, scripts/install.py | Python 3.12+ (aucune bibliothèque tierce) |
| Auto-test de la compétence | pytest |
Ce qui précède concerne la compétence elle-même et est indépendant de la pile technologique du projet qui utilise cette compétence.