xxxx2l/design-to-implement

Workflow de Conception et d'Implémentation de Solution

Principe Fondamental

Discuter d'abord, coder ensuite. Ce workflow impose de séparer la « réflexion » de « l'action » :

• Phase de discussion : uniquement des échanges, aucun code. Toutes les conclusions sont consignées dans le document de communication.
• Phase de conception : les consensus sont organisés dans le document de conception, seule source de vérité.
• Phase d'implémentation : un document d'implémentation est généré à partir du document de conception, avec des étapes à suivre.

Tant qu'il n'y a pas de conclusion dans la discussion ou que l'utilisateur n'a pas clairement dit « on peut commencer à implémenter », aucun code n'est touché. Si des questions persistent, la discussion se poursuit jusqu'à satisfaction mutuelle.

Structure du Répertoire de Documents

Stocké de manière fixe dans le répertoire racine du projet sous docs/design/, un sous-dossier indépendant par tâche :

Racine du projet/
└── docs/design/
    ├── README.md              ← Aperçu global des tâches (point d'entrée pour plusieurs tâches, à lire en premier)
    ├── 01-module-auth-utilisateur/
    │   ├── 00-etat-tache.md      ← Point d'ancrage mémoire entre contextes
    │   ├── 01-communication.md
    │   ├── 02-conception.md          ← Contient les critères d'acceptation
    │   ├── 03-implementation.md
    │   └── 04-test.md              ← Ensemble de cas (généré lors de la phase de planification d'implémentation)
    └── 02-refacto-paiement/
        └── ...

Règles de nommage :

• Dossier de tâche : numéro à deux chiffres globalement incrémental + nom de la tâche, ex. 01-module-auth-utilisateur, 02-refacto-paiement. Les numéros sont continus pour garantir l'ordre de création.
• Documents dans la tâche : préfixe de phase fixe : 00-etat-tache / 01-communication / 02-conception / 03-implementation / 04-test. Le préfixe fixe permet de repérer immédiatement le même type de document dans n'importe quelle tâche.

Comment déterminer le numéro lors du premier accès à une tâche : Voir le numéro maximum des dossiers existants sous docs/design/, puis ajouter +1 pour le nouveau numéro de tâche. Si le répertoire n'existe pas, commencer à 01.

Première Étape de Chaque Nouvelle Conversation (Mécanisme de Mémoire Multi-Contextes)

Ce workflow peut s'exécuter sur plusieurs contextes de conversation. Pour éviter de devoir relire massivement le code ou perdre la mémoire à chaque nouvelle conversation, l'ordre suivant est imposé pour restaurer le contexte :

1. Lire docs/design/README.md — Aperçu global des tâches, confirmer les tâches existantes et leur phase respective. Si l'utilisateur a indiqué une tâche, passer directement à celle-ci.
2. Lire 00-etat-tache.md — Point d'ancrage mémoire de la tâche actuelle, confirmer la prochaine étape.
3. Lire le document correspondant à la phase actuelle (par exemple, lire 02-conception.md en phase de conception, 03-implementation.md en phase d'implémentation).
4. Lire le code uniquement pour vérification, et non comme premier moyen de restaurer le contexte.

00-etat-tache.md doit maintenir : un résumé de la tâche en une phrase, la phase actuelle, un résumé des décisions clés, les tâches et questions en suspens, un index des documents, un journal des changements de contexte, et un journal des modifications (couvrant les modifications et les annulations, voir ci-dessous « Modifications pendant l'implémentation »).

Les Quatre Phases du Workflow et Leurs Documents

Phase 1 : Discussion (Sortie → Document de Communication)

Déclencheur : L'utilisateur propose un nouveau besoin, une nouvelle fonctionnalité, un nouveau module, ou a des questions sur une solution existante.

Contraintes de comportement :

• Cette phase consiste uniquement à discuter, pas à écrire de code métier.
• Chaque échange significatif (décision clé, alternative rejetée, consensus atteint) est ajouté à 01-communication.md.
• Suivi des questions en suspens : Maintenir une liste « Questions en suspens » en haut de 01-communication.md. Mettre à jour cette liste à la fin de chaque discussion — quels points d'interrogation restent, lesquels sont nouveaux, lesquels sont résolus. Le critère direct pour passer à la phase de conception est le suivant : cette liste est-elle vide ? Cela rend visible le processus de convergence de la discussion, plutôt que de décider subjectivement que « la discussion est suffisante ».
• La discussion peut s'étendre sur plusieurs tours et plusieurs conversations.
• Lorsque l'utilisateur exprime « ça suffit », « on garde ça », « commençons la conception », et que la liste des questions en suspens est vide, passer à la phase 2.

Quand continuer à discuter plutôt que de passer à la phase suivante : Tant qu'il y a des questions de conception non résolues, des divergences de choix techniques, des limites non clarifiées, continuer à sédimenter dans la phase 1. Mieux vaut un tour de discussion supplémentaire que d'avancer avec des hypothèses floues dans la conception.

Phase 2 : Conception (Sortie → Document de Conception)

Déclencheur : La discussion a abouti à un consensus, la liste des questions en suspens est vide, l'utilisateur accepte de formaliser la solution.

Contraintes de comportement :

• Organiser les conclusions de la communication dans un 02-conception.md structuré. Le document de conception est la seule source de vérité.
• Le document de conception doit être aussi complet que possible : il doit présenter une solution déterminée et exécutable, sans laisser de points « à définir » ou « à voir pendant l'implémentation ». L'exhaustivité est garantie par deux choses : une communication approfondie pour clarifier toutes les questions et la lecture du code existant pour confirmer tous les faits dépendant de l'implémentation existante (formes d'interface, structure de table, méthodes d'appel, etc.). La contrainte « en phase de conception, on ne fait que discuter, pas de code » s'applique au code métier ; la lecture du code existant pour la conception fait partie de la recherche de conception et ne viole pas cette contrainte. Mieux vaut passer plus de temps pendant la phase de conception à peaufiner plutôt que d'entrer dans l'implémentation avec des lacunes — toute lacune se transformera en reprise ou en déviation pendant l'implémentation.
• Les critères d'acceptation font partie de la conception : En plus de décrire « quoi faire et pourquoi », le document de conception doit spécifier « à quel niveau la réponse est-elle considérée comme satisfaisant le besoin » — c'est-à-dire des critères d'acceptation abstraits (au niveau des règles, par exemple « les mots à haut risque doivent être bloqués, l'article n'est pas persisté en base »). Les critères d'acceptation définissent les limites du besoin et constituent le dernier maillon de l'exhaustivité de la conception ; un document de conception sans critères d'acceptation n'a pas de définition objective de « terminé ». Les cas de test spécifiques (au niveau des instances) ne sont pas écrits dans le document de conception mais dans 04-test.md, généré pendant la phase de planification de l'implémentation en transformant les critères d'acceptation en cas.
• Journal des modifications de conception : Maintenir un bloc « Journal des modifications de conception » dans le document de conception. Chaque modification importante est enregistrée sur une ligne (date, quoi, pourquoi). Il est complémentaire à 01-communication.md — la communication est un journal brut, le document de conception est la conclusion, le journal des modifications est l'historique de l'évolution des conclusions. Cela permet de rendre la règle d'airain « les changements de solution modifient le document de conception, pas le document d'implémentation » véritablement exécutable sans perdre l'historique.
• Une fois le document de conception terminé, mettre à jour 00-etat-tache.md pour indiquer « conception terminée, en attente d'implémentation », et synchroniser la mise à jour de docs/design/README.md avec la phase de la tâche.

Phase 3 : Planification de l'Implémentation (Sortie → Document d'Implémentation)

Déclencheur : Le document de conception est finalisé.

Contraintes de comportement :

• Générer 03-implementation.md à partir du document de conception, en décomposant la solution en une liste d'étapes exécutables et cochables.
• En même temps, transformer les « critères d'acceptation » du document de conception en cas de test concrets, générant 04-test.md : Les cas de test sont l'instanciation des critères d'acceptation (par exemple, critère « les mots à haut risque doivent être bloqués » → cas « entrer un texte contenant un mot à haut risque, résultat attendu : retour 40901, article non persisté »). Les cas sont divisés en quatre couches : fonctionnels (T-F), d'exception (T-EX), de régression (T-R) et d'interface (T-API), avec un format de numérotation T-{type}-{numéro à deux chiffres}. Le modèle est dans assets/test.md.
• Le document d'implémentation est « comment faire », le document de test est « quoi tester et quel est le résultat attendu », le document de conception est « quoi faire et pourquoi ». Les trois ont des responsabilités différentes. Ne pas recopier les détails de conception dans le document d'implémentation, ni y inclure des changements de solution.
• Le document d'implémentation est une pure décomposition en étapes, chaque étape consiste uniquement à « implémenter une partie du document de conception », sans assumer la responsabilité de « compléter la conception » . Si, en décomposant, une étape nécessite d'abord de « confirmer la forme de l'interface », de « réécrire la conception » ou de « décider du champ » pour pouvoir agir, cela signifie que la phase de conception n'est pas terminée — il faut alors revenir à la phase 2 pour compléter la conception, plutôt que d'insérer une étape de « complément de conception » dans le document d'implémentation. En résumé : le document d'implémentation ne doit contenir aucune action de type « lire le code pour déterminer la solution », mais seulement des actions de type « implémenter selon la solution définie ».
• Les actions de test dans le document d'implémentation ne font référence qu'aux numéros de cas, sans répéter le contenu des cas. Pour la vérification après chaque étape, écrire « Vérifier selon le cas T-XX-XX », les cas eux-mêmes sont concentrés dans 04-test.md.
• Les étapes d'implémentation sont divisées en grandes étapes et sous-étapes, chacune devant avoir un marqueur d'achèvement indépendant.
• Une fois le document d'implémentation terminé, mettre à jour 00-etat-tache.md pour indiquer « en attente d'implémentation ».

Phase 4 : Implémentation (Exécution des Étapes du Document d'Implémentation)

Déclencheur : L'utilisateur dit « commencer l'implémentation », « on y va », « suivre le document ».

Contraintes de comportement :

• Avancer strictement selon les étapes de 03-implementation.md. À chaque étape terminée, mettre à jour le marqueur dans le document et noter brièvement le résultat.
• Après chaque étape, vérifier selon les cas de test référencés dans 04-test.md pour cette étape ; si un cas échoue, l'étape n'est pas considérée comme terminée. Identifier la cause (est-ce un bug d'implémentation ou un problème de conception / de cas de test lui-même ? Dans ce dernier cas, suivre le mécanisme de modification ou d'annulation). Une fois toutes les étapes terminées, exécuter l'ensemble des cas de régression (T-R).
• En cas de divergence avec le document de conception, s'arrêter : Mettre d'abord à jour 02-conception.md (y compris le journal des modifications), puis réviser 03-implementation.md et 04-test.md (les cas de test changent avec la solution), puis continuer. Ne jamais dévier de la solution en cours de route.
• Les lacunes de conception découvertes pendant l'implémentation, les nouvelles contraintes, les changements d'API sont tous reportés dans le bloc « Journal des modifications de conception » de 02-conception.md, pour que le document de conception reste à jour.
• À chaque changement de phase et à chaque nœud important, mettre à jour 00-etat-tache.md et docs/design/README.md.

Modifications Pendant l'Implémentation : Mécanisme de Modification vs Mécanisme de Retour

Le workflow nominal est discussion → conception → planification d'implémentation → implémentation, mais découvrir pendant l'implémentation que la solution présente des écarts avec le besoin ou la réalité est un phénomène normal et attendu, pas une anomalie — même la conception la plus complète ne peut pas prévoir à 100 % les détails de l'implémentation.

Les écarts sont de deux types, de nature fondamentalement différente, et doivent être traités avec des processus distincts :

	Modification	Retour
Nature	La solution est globalement correcte, il manque des compléments / des oublis	Cette partie de la solution est fondamentalement erronée, doit être reprise de zéro
Solution principale	Inchangée	Reprise
Produits déjà réalisés	Non invalidés	Partiellement invalidés
Fréquence	Normale	Rare
Scénario typique	Champ manquant, branche manquante, valeur de dictionnaire manquante, oubli d'un nouveau point de besoin	Mauvaise direction, hypothèse centrale non valide, non conforme au métier réel

D'abord déterminer de quel type il s'agit (la responsabilité de la détermination est expliquée dans chaque mécanisme), puis suivre le processus correspondant. En cas d'hésitation, tendre à traiter d'abord comme une « modification » et confirmer avec l'utilisateur ; ne passer au « retour » que si l'erreur est clairement fondamentale.

Mécanisme de Modification (Normal, Léger, Incrémental)

Trois conditions pour la qualification (toutes doivent être remplies pour parler de modification) :

• La direction de la solution principale n'est pas mauvaise
• Aucun produit déjà réalisé ne doit être invalidé
• Il s'agit simplement d'un complément / d'un ajustement mineur (ajout de champ, de branche, de valeur de dictionnaire, d'un point de besoin oublié, etc.)

Processus de traitement (ordre strict, non inversable) :

1. Arrêter l'implémentation en cours
2. Mettre d'abord à jour le document de conception : Ajouter le contenu dans le bloc correspondant du document de conception et ajouter une ligne dans le journal des modifications de conception
3. Attendre la confirmation de l'utilisateur pour cette modification (ne pas décider ni implémenter soi-même)
4. Après confirmation de l'utilisateur, réviser le document d'implémentation en synchronisation
5. Puis continuer l'implémentation

Principe clé : Mettre d'abord à jour la conception, puis implémenter — l'ordre ne doit pas être inversé. Il est interdit de « finir l'implémentation puis de mettre à jour le document de conception a posteriori », car cela ferait du document de conception un simple enregistrement après coup plutôt qu'une source de vérité. Même pour l'ajout d'un seul champ, ce processus doit être suivi.

Mécanisme de Retour (Rare, Lourd, Reprise)

Trois conditions pour la qualification (toutes doivent être remplies pour parler de retour) :

• La direction de la solution principale pose problème
• Les produits déjà réalisés doivent être invalidés
• Une nouvelle discussion / conception est nécessaire

Responsabilité de la détermination : La décision finale de retour appartient à l'utilisateur. Si l'IA détecte un problème potentiellement fondamental, elle peut uniquement suggérer un retour possible et en expliquer les raisons ; l'utilisateur prend la décision finale de retour ou non ; l'IA ne peut pas décider elle-même du retour.

Processus de traitement :

1. Arrêter l'implémentation en cours
2. L'IA suggère un retour possible et explique les raisons (quelle partie de la direction est erronée, pourquoi elle n'est pas valide)
3. Attendre la décision finale de l'utilisateur sur le retour ou non
4. Après confirmation du retour par l'utilisateur, noter une ligne dans 00-etat-tache.md : retour de la phase X à la phase Y, raison, quels produits sont invalidés
5. Revenir à la phase de discussion / conception pour réaligner
6. La nouvelle solution générée est sédimentée selon le processus normal : nouvelles questions dans la liste des questions en suspens de 01-communication.md ; changements de solution dans 02-conception.md avec ajout d'une ligne dans le journal des modifications
7. Réviser 03-implementation.md en synchronisation

Règle d'Airain Commune aux Deux Mécanismes

1. Les changements de solution modifient toujours le document de conception, jamais directement le document d'implémentation
2. Mettre d'abord à jour la conception, puis implémenter — l'ordre ne doit pas être inversé (ne pas faire d'abord puis compléter après)
3. Tout changement doit laisser une trace dans le document d'état de la tâche (modification → journal des modifications de conception ; retour → journal de retour supplémentaire)
4. La confirmation de l'utilisateur est un point de passage obligatoire pour tout changement (modification → confirmation du complément de solution ; retour → confirmation de la décision elle-même)

Mentalité : Les écarts ne sont pas graves, ce qui est grave c'est de continuer avec un écart ou de s'écarter silencieusement de la solution. Rendre les « modifications » légères et à faible friction (c'est normal qu'elles soient fluides), rendre les « retours » prudents (la reprise nécessite la décision de l'utilisateur), les deux sont normalisés et tracés, ce qui minimise le coût des reprises.

Norme de Marquage des Étapes du Document d'Implémentation

Les étapes d'implémentation sont divisées en grandes étapes et sous-étapes, chacune doit avoir un marqueur d'achèvement indépendant. Les grandes étapes utilisent des titres avec compteur de progression, les sous-étapes utilisent des cases à cocher à quatre états.

Marqueurs à quatre états :

- [ ]  Non commencé
- [~] En cours
- [x] Terminé
- [!] Bloqué (mentionner la raison après)

Exemple d'organisation :

### 1. Couche Base de Données ✅ 1/3
- [x] 1.1 Créer la table users (y compris le script de migration)
- [~] 1.2 Créer les index
- [ ] 1.3 Écrire les données de seed

### 2. Couche API ⬜ 0/2
- [ ] 2.1 Implémenter POST /api/users
- [ ] 2.2 Intégrer le middleware d'authentification

Symboles pour les grandes étapes :

• ⬜ Non commencé (0/N terminé)
• 🌗 En cours (partiellement terminé)
• ✅ Tout terminé (N/N)

Le format du compteur de progression est uniforme : nombre terminé / total, placé à la fin du titre de la grande étape. Cela permet de voir à la fois la progression globale et de localiser précisément la sous-étape bloquante.

Traitement Spécial pour les Projets Backend

Si le projet actuel est un projet purement backend (pas de code frontend, ou backend et frontend sont dans des dépôts séparés) :

• Le document de conception et le document d'implémentation ne contiennent que le contenu backend, sans impliquer l'implémentation frontend.
• Toute nouvelle interface ou modification d'interface existante (URL, méthode, paramètres d'entrée, paramètres de sortie, codes d'erreur, exigences d'authentification, etc.) doit être listée dans un bloc dédié « Liste des modifications d'interface » dans 02-conception.md.
• Le format de la liste d'interfaces doit permettre à une personne du frontend de l'utiliser directement pour l'intégration. Champs suggérés : chemin de l'interface, méthode de requête, exemple de corps de requête, exemple de réponse réussie, tableau des codes d'erreur, exigences d'authentification, remarques.
• Cette liste d'interfaces est un livrable pour le frontend, elle doit être cohérente et lisible de manière autonome.
• La liste d'interfaces doit donner des conclusions déterminées dès la phase de conception. Il est interdit de reporter la décision à la phase d'implémentation. Tout fait dépendant du code existant (comme « cette interface est-elle nouvelle ou modifiée ? », « le chemin est-il conservé ou changé ? », « les paramètres d'entrée s'alignent sur quelle structure existante ? ») doit être confirmé en lisant le code existant pendant la phase de conception, et la conclusion doit être écrite dans la liste d'interfaces. La contrainte « en phase de conception, on ne fait que discuter, pas de code » s'applique au code métier — lire le code existant pour confirmer la forme de l'interface fait partie de la recherche de conception, pas de l'implémentation, et ne viole pas la contrainte. Le document de conception ne doit pas contenir de formulations vagues comme « dépend du code existant », « à confirmer pendant l'implémentation », ni utiliser d'étiquettes du type « à confirmer pendant l'implémentation » pour légitimer l'incertitude. La liste d'interfaces livrée au frontend doit être complètement déterminée, sinon le frontend ne peut pas faire l'intégration.

Critères d'Acceptation et Tests (Trois Couches de Responsabilités)

Les tests ne sont pas ajoutés à la dernière minute pendant l'implémentation ; ils font partie d'un système qui s'étend de la conception à l'implémentation. Les trois couches de responsabilités sont strictement séparées :

Couche	Support	Contenu	Nature	Phase de production
Règle	02-conception.md	Critères d'acceptation abstraits	« À quel niveau la réponse est-elle considérée comme satisfaisant le besoin ? »	Conception
Instance	04-test.md	Cas de test concrets	« Quelle entrée, quel résultat attendu ? »	Planification de l'implémentation
Action	03-implementation.md	Étapes + Référence aux cas	« Quelle action, contre quel cas vérifier ? »	Planification de l'implémentation

Pourquoi cette séparation ? : Les critères d'acceptation définissent les limites du besoin (appartiennent à la conception), les cas sont l'instanciation de ces limites, et l'implémentation est l'action de mise en œuvre. Les trois couches sont séparées : pour changer une règle, on va dans le document de conception ; pour changer un cas, on va dans le document de test ; pour changer une action, on va dans le document d'implémentation — chaque chose a sa source de vérité, sans contamination mutuelle.

Hiérarchie et numérotation des cas de test :

Préfixe	Type	Utilisation
T-F-	Cas fonctionnels	Flux normaux
T-EX-	Cas d'exception	Flux inverses, cas limites, branches d'erreur
T-R-	Cas de régression	Chemins critiques à tester après modification/retour (sélectionnés parmi F/EX, pour éviter qu'une modification de A ne casse B)
T-API-	Cas d'interface	Correspondant à chaque interface de la « Liste des modifications d'interface » du document de conception

Génération obligatoire de 04-test.md pour toutes les tâches : Ce skill cible les tâches de taille moyenne à grande ; l'utilisateur ne déclenchera pas le skill pour de petites tâches. Par conséquent, aucun jugement de complexité n'est effectué — une fois qu'une tâche entre en phase de planification d'implémentation, le document de test est obligatoire.

Relation entre modification/retour et tests : Après avoir suivi le mécanisme de modification ou de retour, la solution a changé → les cas de test sont mis à jour en conséquence (d'abord modifier les critères d'acceptation de la conception, puis les cas de test), et au moins une exécution complète de l'ensemble des cas de régression (T-R) est effectuée pour éviter qu'une modification locale n'entraîne une régression globale.

Mode Étendu A : Décomposition de Tâches (Tâches Multi-Modules de Grande Envergure)

Quand l'activer : Une tâche de grande envergure contient naturellement plusieurs modules semi-indépendants (par exemple, « système de modération = filtrage de mots sensibles + modération d'images + poste de travail de modération manuelle »), et un seul contexte ne peut pas tout contenir. L'activer lorsque l'utilisateur indique explicitement pendant la phase de discussion qu'il s'agit d'une « tâche de grande envergure, à décomposer en plusieurs modules ». Ne pas juger automatiquement de la taille de la tâche ; l'utilisateur doit explicitement déclencher ce mode.

Mécanisme central : La tâche parente est responsable de la conception globale + de la décomposition en modules + des contrats d'interface entre modules + de l'orchestration. Chaque tâche enfant suit son propre cycle complet en 4 phases, dans les limites définies par la tâche parente.

A.1 Structure Documentaire des Tâches Parente et Enfants (Hiérarchique)

Racine du projet/docs/design/
├── README.md                          ← Aperçu global des tâches
├── 01-systeme-moderation/             ← Tâche parente
│   ├── 00-etat-tache.md               ← Utilise le modèle parent-task-status.md, contient la liste des tâches enfants
│   ├── 01-communication.md            ← Discussion globale au niveau de la tâche parente
│   ├── 02-conception.md               ← Architecture globale + décomposition en modules + contrats d'interface entre modules
│   ├── 03-implementation.md           ← Uniquement orchestration au niveau parent (tests d'intégration, coordination), pas de détails internes des modules
│   ├── 04-test.md                     ← Uniquement tests d'intégration inter-modules
│   └── taches-enfants/
│       ├── 01-1-filtrage-mots-sensibles/ ← Tâche enfant (documents complets en 4 phases, avec modèle standard)
│       ├── 01-2-moderation-images/
│       └── 01-3-poste-travail-moderation-manuelle/
└── 02-autre-tache/

Les tâches enfants utilisent le modèle standard (task-status / communication / design / implementation / test), sans changement. La tâche parente utilise le modèle assets/parent-task-status.md, qui comporte un bloc supplémentaire « Liste des tâches enfants » ; le document de conception de la tâche parente, en plus du modèle de conception standard, doit obligatoirement inclure deux blocs supplémentaires :

• Décomposition en modules : Lister les tâches enfants créées, avec leurs limites de responsabilités respectives
• Contrats d'interface entre modules : Conventions d'interface entre les tâches enfants (signature d'interface, format de données, méthode d'appel, etc.). C'est la clé qui permet aux tâches enfants de travailler en parallèle de manière indépendante, et doit être défini pendant la phase de conception

A.2 Progression des Phases de la Tâche Parente (Strictement Séquentielle)

1. La tâche parente commence par « discussion + conception », doit produire la décomposition en modules + les contrats d'interface entre modules
2. Ce n'est qu'après confirmation de la conception de la tâche parente par l'utilisateur que les tâches enfants peuvent être lancées
3. Lors du lancement des tâches enfants, déterminer l'ordre de lancement en fonction des dépendances : La phase de conception de la tâche parente doit clarifier les dépendances entre les tâches enfants (par exemple, « le poste de travail de modération manuelle dépend de l'interface de filtrage de mots sensibles »), les tâches enfants dont on dépend doivent être terminées avant que les tâches dépendantes puissent être lancées
4. Chaque tâche enfant suit son propre cycle complet en 4 phases (peuvent être parallélisées si les dépendances sont satisfaites). La manière de paralléliser plusieurs tâches enfants dépend du framework d'agent utilisé (généralement via des capacités de tâches en arrière-plan / asynchrones). Pour les détails concrets, voir B.5
5. Une fois toutes les tâches enfants terminées, la tâche parente effectue des « tests d'intégration inter-modules » pour finaliser

Pourquoi les tâches parente et enfants ne peuvent pas être parallélisées : La production centrale de la tâche parente est le contrat d'interface entre modules, qui est la condition préalable à l'indépendance des tâches enfants. Si la conception de la tâche parente n'est pas définie et que les tâches enfants sont lancées, il y aura inévitablement des conflits entre elles.

A.3 Les Tâches Enfants ne Peuvent pas Modifier unilatéralement les Contrats d'Interface Définis par la Tâche Parente

Les contrats d'interface sont un consensus multi-modules. Si une tâche enfant les modifie unilatéralement, cela peut rendre les autres tâches enfants incontrôlables. Si une tâche enfant découvre un problème dans le contrat d'interface de la tâche parente :

• Ne peut pas modifier le contrat d'interface elle-même
• Doit revenir à la tâche parente et suivre le mécanisme de modification : mettre à jour 02-conception.md de la tâche parente (y compris le journal des modifications) → attendre la confirmation de l'utilisateur → notifier toutes les tâches enfants qui dépendent de cette interface → les tâches enfants concernées révisent leurs propres documents de conception / implémentation / test en synchronisation

A.4 Limite de Profondeur d'Emboîtement : Un Seul Niveau

Parent → Enfant, pas d'emboîtement supplémentaire (les tâches enfants ne peuvent pas avoir leurs propres tâches enfants). Raison : Un trop grand nombre de niveaux d'emboîtement rend les relations entre les tâches extrêmement complexes ; si une tâche enfant doit encore être décomposée, cela signifie généralement que la granularité de la décomposition de la tâche n'est pas bonne — elle devrait être replanifiée comme une tâche parente indépendante, plutôt que d'être insérée dans une structure multi-niveaux existante.

A.5 Utilisation du Modèle de Tâche Parente

• Document d'état de la tâche parente : Utiliser assets/parent-task-status.md (ne pas utiliser le modèle standard task-status)
• Autres documents de la tâche parente (communication / conception / implémentation / test) : Utiliser le modèle standard, mais le document de conception doit obligatoirement inclure les deux blocs mentionnés en A.1
• Tous les documents des tâches enfants : Utiliser le modèle standard, sans changement

Mode Étendu B : Implémentation à Deux Agents (Segmentation de l'Implémentation)

Quand l'activer : À l'intérieur d'une seule tâche, les phases d'implémentation et de test cumulées rendent le contexte trop long. L'activer lorsque l'utilisateur indique explicitement, au début de la phase d'implémentation, « utiliser le mode à deux agents pour l'implémentation ». Ne pas juger automatiquement ; l'utilisateur doit explicitement déclencher ce mode.

Mécanisme central : La phase d'implémentation elle-même est divisée en deux étapes séquentielles — l'agent d'implémentation (écrit le code selon 03-implementation.md) + l'agent de test (vérifie selon 04-test.md). Les deux sont physiquement indépendants (deux contextes indépendants), communiquant via le document d'état de la tâche. La valeur fondamentale de B est l'isolation du contexte : l'agent d'implémentation n'a pas le contexte de test, l'agent de test n'a pas les détails de l'implémentation.

B.1 Limites des Responsabilités de l'Implémentation et du Test

• Agent d'implémentation : Effectue uniquement les étapes de 03-implementation.md (écrit le code). Une fois terminé, ne lance pas lui-même les tests, mais déclare dans le bloc « État de la segmentation de l'implémentation » de 00-etat-tache.md : « Implémentation terminée, version X, prête pour les tests »
• Agent de test : Effectue la vérification sur la base du dernier 03-implementation.md + 04-test.md. Sa responsabilité est strictement limitée à « exécuter les cas, déterminer les échecs, faire un rapport », n'est pas responsable de la modification du code (même s'il découvre un bug d'implémentation, il ne le corrige pas lui-même)

B.2 Traitement par l'Agent de Test d'un Échec de Cas

Lorsque l'agent de test exécute un cas et qu'il échoue, il détermine d'abord la cause racine de l'échec (l'agent de test voit le comportement réel, il a le meilleur avantage informationnel pour faire cette première détermination) :

• Diagnostic : bug d'implémentation (le code est mal écrit, la conception est correcte) → Rapporter à l'agent d'implémentation, qui corrige. Après la correction, l'agent de test doit retester le cas pour qu'il soit validé. L'agent d'implémentation ne peut pas clore le cas unilatéralement en déclarant « c'est corrigé »
• Diagnostic : bug de conception (le code a été écrit selon la conception, mais la conception elle-même pose problème) → Ne peut pas modifier la conception de son propre chef. Déclencher le mécanisme de modification : s'arrêter → mettre à jour la conception → attendre la confirmation de l'utilisateur → modifier l'implémentation → modifier les tests → revenir à l'agent de test pour retester

Si le diagnostic est erroné, l'utilisateur le corrige ; mais « modifier la conception » a un large impact et nécessite la décision de l'utilisateur.

B.3 Bloc d'État de la Segmentation de l'Implémentation

Ajouter un bloc optionnel dans 00-etat-tache.md (rempli uniquement lorsque le mode B est activé, laissé vide en mode normal) :

## État de la segmentation de l'implémentation (mode B uniquement, laisser vide en mode normal)

- Étape actuelle : Implémentation / Test
- Version d'implémentation : (incrémentée à chaque achèvement ou correction par l'agent d'implémentation)
- Déclaration d'achèvement de l'implémentation : YYYY-MM-DD, l'agent d'implémentation a déclaré prêt pour les tests
- Progression des tests :
  - Réussis : T-F-01, T-F-02, ...
  - Échecs en attente de correction : T-EX-03 (bug d'implémentation, signalé à l'agent d'implémentation), ...
  - En attente de retest : T-EX-03 (l'agent d'implémentation a corrigé, en attente de retest par l'agent de test)

L'agent d'implémentation et l'agent de test lisent et écrivent tous deux ce bloc. C'est leur seul point de passage pour la communication.

B.4 Combinaison avec A (A+B)

A et B sont orthogonaux et peuvent être combinés : Une tâche de grande envergure est décomposée en tâches enfants selon A, et chaque tâche enfant est décomposée en implémentation + test selon B. Aucun mécanisme supplémentaire n'est nécessaire pour la combinaison — car les tâches enfants sont des tâches standard (A.1 a déjà expliqué que les tâches enfants utilisent le modèle standard), donc chaque tâche enfant supporte naturellement B. Activation : Après la conception de la tâche parente et le lancement des tâches enfants, chaque tâche enfant décide au début de sa phase d'implémentation si elle active B ou non.

B.5 Guide d'Orchestration des Agents

Le mode B nécessite deux agents physiquement indépendants (agent d'implémentation et agent de test), qui communiquent indirectement via le bloc « État de la segmentation de l'implémentation », sans communication directe entre eux. La manière exacte de faire passer le relais dépend du framework d'agent que vous utilisez.

Quel que soit le framework, un modèle d'orchestration générique commun s'applique :

1. Un orchestrateur (qui peut être l'agent principal, un script d'orchestration externe, ou l'utilisateur lui-même) lit le bloc « État de la segmentation de l'implémentation » pour déterminer l'étape actuelle
2. L'orchestrateur lance l'agent d'implémentation, lui transmet les chemins des documents de conception / d'implémentation, lui ordonne de suivre 03-implementation.md et de mettre à jour le bloc d'état après avoir terminé
3. Une fois l'étape d'implémentation terminée, l'orchestrateur lance l'agent de test, lui transmet le chemin du document de test, lui ordonne d'exécuter les cas selon 04-test.md et d'écrire les résultats (y compris le diagnostic d'échec) dans le bloc d'état
4. L'orchestrateur détermine la prochaine étape en fonction des résultats de test dans le bloc d'état : s'il y a un bug d'implémentation, revenir à l'agent d'implémentation pour corriger et retester ; s'il y a un bug de conception, s'arrêter et signaler à l'utilisateur pour suivre le mécanisme de modification ; si tout est réussi, finaliser

Points clés généraux :

• L'agent d'implémentation et l'agent de test établissent chacun leur propre contexte indépendant, sans se polluer mutuellement — c'est le cœur de l'isolation du contexte du mode B
• Les deux agents ne se perçoivent pas directement l'un l'autre, ils communiquent indirectement uniquement via le document partagé « État de la segmentation de l'implémentation »
• L'orchestrateur ne fait que « lire l'état → juger → dispatcher », sans participer à l'implémentation ou au test lui-même

Référence concrète pour les clients : Les capacités de sous-agents, de tâches en arrière-plan et de fenêtres multiples varient d'un framework d'agent à l'autre. Ce document ne verrouille pas une implémentation spécifique. Pour les utilisateurs de ZCode, voir assets/references/zcode-scheduling.md (chargeable à la demande : lire uniquement lorsque le mode B est activé et qu'un guide opérationnel est nécessaire). Les autres clients peuvent s'inspirer de cette approche et l'adapter à leurs propres capacités.

Limite importante : Le skill ne verrouille pas une implémentation d'orchestration spécifique

Le skill définit le protocole de passage de relais (format et sémantique du bloc d'état de la segmentation de l'implémentation) et les responsabilités des rôles (ce que font l'implémentation et le test), mais ne verrouille pas la manière spécifique d'orchestrer. Tout framework capable de « lire un fichier, lancer une sous-tâche, écrire un fichier » peut implémenter le mode B.

Principe de Confirmation pour les Changements de Phase

Le passage d'une phase à l'autre n'est pas automatique ; il nécessite un signal explicite :

Condition d'entrée	Condition satisfaite
Entrer en discussion	(Le skill est activé manuellement)
Discussion → Conception	L'utilisateur accepte explicitement de formaliser la solution, et la liste des questions en suspens est vide
Conception → Planification de l'implémentation	Le document de conception est terminé et approuvé par l'utilisateur
Planification de l'implémentation → Implémentation	L'utilisateur demande explicitement de commencer
Implémentation → Conception (modification)	Pendant l'implémentation, une lacune de solution est découverte, on suit le mécanisme de modification en s'arrêtant, on modifie la conception, on attend la confirmation de l'utilisateur
Implémentation → Discussion/Conception (retour)	Pendant l'implémentation, une erreur fondamentale est découverte, l'IA suggère un retour, l'utilisateur prend la décision finale après

En cas d'incertitude sur le changement, par défaut, rester dans la phase actuelle et continuer à discuter, en demandant activement à l'utilisateur. Ne pas prendre à sa place la décision que « la solution est déjà assez bonne, on peut commencer à écrire ».

Utilisation des Modèles

Lors de la création d'un nouveau document, lire le modèle correspondant dans le répertoire assets/ :

• assets/readme.md → docs/design/README.md (aperçu global des tâches)
• assets/task-status.md → 00-etat-tache.md (tâche standard / tâche enfant)
• assets/parent-task-status.md → 00-etat-tache.md (réservé à la tâche parente, lors de l'activation du mode A)
• assets/communication.md → 01-communication.md
• assets/design.md → 02-conception.md (contient le bloc des critères d'acceptation ; la tâche parente doit en plus inclure les blocs de décomposition en modules + contrats d'interface)
• assets/implementation.md → 03-implementation.md
• assets/test.md → 04-test.md (généré pendant la phase de planification de l'implémentation)

Lire le modèle, remplir le contenu réel, écrire dans le dossier de la tâche. Ne pas inventer de structure de document.

Itération du Skill et Documents de Tâches Anciennes

Le skill évolue continuellement, les modèles et les normes sont mis à jour, mais les documents de tâches anciennes déjà en cours d'utilisation ne migrent pas automatiquement vers les nouvelles normes. C'est intentionnel — pour protéger la mémoire existante de l'utilisateur concernant la structure des documents et maintenir la stabilité du mécanisme de mémoire multi-contextes. La structure des documents est un point d'ancrage mémoriel que l'utilisateur utilise pour se repérer rapidement après avoir changé de contexte ; cet ancrage ne doit pas être fréquemment déformé en raison de mises à jour du skill.

Principes de traitement :

• Ne pas migrer activement : L'IA ne scanne pas de son propre chef les anciennes tâches, ne les aligne pas sur les nouvelles normes, même si elle constate des différences entre les anciens documents et les nouvelles normes (par exemple, un ancien document a un bloc « Journal des retours » alors que la nouvelle norme exige un « Journal des modifications »). Au maximum, mentionner la différence dans une « note pendant l'implémentation » ou dans la conversation, sans intervenir de son propre chef.
• Migrer uniquement sur instruction explicite de l'utilisateur : Agir uniquement lorsque l'utilisateur demande activement « aligner les documents de la tâche X sur les normes actuelles du skill » ou « migrer la tâche X vers le nouveau format ». L'IA ne décide pas à la place de l'utilisateur si une ancienne tâche doit être migrée.
• Priorité au complément incrémental : La migration par défaut consiste à compléter/modifier uniquement les parties qui ne sont pas conformes aux nouvelles normes, en conservant la structure globale et le contenu du document original, sans le réécrire entièrement. Ainsi, lorsque l'utilisateur revient après avoir changé de contexte, il n'a pas besoin de relire et de comprendre l'intégralité du document — la structure n'a pas changé, l'ancrage mémoriel est toujours là.
• Si l'utilisateur demande explicitement une réécriture, la supporter, mais sauvegarder d'abord le fichier original avant de générer le nouveau fichier :
  • Ne pas écraser le fichier original
  • Ajouter un suffixe de date ou de version au fichier de sauvegarde, par exemple 00-etat-tache.md.bak.20260617
  • Le nouveau fichier conserve le nom du fichier original et contient le contenu réécrit
  • Le fichier original est l'ancrage mémoriel historique de l'utilisateur ; même en cas de réécriture, la version originale doit être conservée pour comparaison ou retour en arrière
• Expliquer la portée avant la migration / réécriture : Avant d'agir, dire à l'utilisateur quels endroits seront modifiés (incrémental) ou quels fichiers seront réécrits (complet), et après avoir terminé, résumer brièvement ce qui a été changé, pour rester prévisible.

Anti-patrons (À Éviter)

• ❌ Commencer à écrire du code métier pendant la phase de discussion — mettre la charrue avant les bœufs.
• ❌ Écrire des changements de solution directement dans le document d'implémentation sans mettre à jour le document de conception — ruiner la source de vérité unique.
• ❌ Arriver dans une nouvelle conversation sans lire le document d'état et le README, obligeant l'utilisateur à répéter la progression — gaspiller le contexte.
• ❌ En cas d'écart pendant l'implémentation, modifier discrètement l'implémentation sans la reporter dans la conception — le document de conception se dégrade progressivement.
• ❌ Écrire les détails d'implémentation frontend dans un projet backend, ou ne pas reporter les modifications d'interface dans la liste d'interfaces — le frontend n'a pas de base pour l'intégration.
• ❌ Avancer automatiquement vers la phase suivante sans signal explicite — priver l'utilisateur de son pouvoir de décision.
• ❌ En cas de lacune de solution découverte pendant l'implémentation (champ / branche / valeur de dictionnaire manquants, etc.), modifier directement le document d'implémentation, ne pas le reporter dans le document de conception, ne pas attendre la confirmation de l'utilisateur — doit suivre le mécanisme de modification : s'arrêter → d'abord modifier la conception → attendre la confirmation → modifier l'implémentation → continuer.
• ❌ En cas d'erreur fondamentale découverte pendant l'implémentation, persister à modifier le document d'implémentation, ou laisser l'IA décider elle-même du retour — doit suivre le mécanisme de retour : l'IA peut seulement suggérer, l'utilisateur décide finalement, enregistrer le retour puis revenir en discussion / conception pour réaligner.
• ❌ Cocher une grande étape alors que des sous-étapes sont encore manquantes — les grandes étapes et les sous-étapes doivent toutes avoir des marqueurs indépendants.
• ❌ Discussion qui s'éparpille et ne parvient pas à converger, les questions en suspens étant submergées par de nouveaux sujets — utiliser la liste des questions en suspens pour forcer la convergence.
• ❌ Formulations vagues dans la liste d'interfaces comme « dépend du code existant », « à confirmer pendant l'implémentation », ou utilisation d'étiquettes du type « à confirmer pendant l'implémentation » pour légitimer l'incertitude — les faits dépendant du code existant doivent être confirmés en lisant le code pendant la phase de conception, la liste d'interfaces livrée doit être complètement déterminée, sinon le frontend ne peut pas faire l'intégration.
• ❌ Après une itération du skill, migrer de son propre chef les documents de tâches anciennes, les aligner sur les nouvelles normes — ruiner les ancrages mémoriels de l'utilisateur. Migrer uniquement sur instruction explicite de l'utilisateur ; par défaut, complément incrémental, pas de réécriture complète ; si l'utilisateur demande une réécriture, sauvegarder d'abord le fichier original avant de générer le nouveau fichier.
• ❌ Document de conception qui ne décrit que la solution sans inclure les critères d'acceptation — les critères d'acceptation définissent les limites du besoin, sans eux il n'y a pas de définition objective de « terminé », et la validation pendant l'implémentation ne peut se faire qu'à l'intuition.
• ❌ Dans le document d'implémentation, écrire des actions vagues comme « couvrir XXX avec des tests unitaires » sans référencer des numéros de cas spécifiques — les actions de test doivent pointer vers des cas concrets dans 04-test.md (par exemple, « vérifier selon T-EX-03 »), sinon ce qui est testé et quel est le résultat attendu ne sont pas clairs.
• ❌ Après avoir suivi le mécanisme de modification ou de retour, ne pas réexécuter les cas de régression (T-R) — un changement local peut entraîner une régression globale, les chemins critiques doivent être retestés.
• ❌ Dans le mode A, lancer les tâches enfants alors que la conception de la tâche parente n'est pas définie (décomposition en modules ou contrats d'interface non produits) — il y aura inévitablement des conflits entre les tâches enfants. La conception de la tâche parente doit d'abord être confirmée par l'utilisateur.
• ❌ Dans le mode A, une tâche enfant modifie unilatéralement le contrat d'interface défini par la tâche parente — le contrat d'interface est un consensus multi-modules, doit revenir à la tâche parente pour suivre le mécanisme de modification et notifier toutes les tâches enfants dépendantes de cette interface.
• ❌ Dans le mode A, une tâche enfant emboîte elle-même une autre tâche enfant (plus d'un niveau) — cela signifie généralement que la granularité de la décomposition n'est pas bonne, cette tâche enfant devrait être replanifiée comme une tâche parente indépendante.
• ❌ Dans le mode A, la tâche parente ne définit pas les dépendances entre les tâches enfants et les lance toutes en parallèle — les tâches dépendantes se bloqueront tant que les tâches dont elles dépendent ne sont pas terminées ; les dépendances doivent être définies pendant la phase de conception de la tâche parente.
• ❌ Dans le mode B, l'agent de test corrige lui-même un bug d'implémentation — les responsabilités doivent être séparées : le test ne fait que signaler, la correction revient à l'agent d'implémentation ; et après la correction, l'agent de test doit retester, l'agent d'implémentation ne peut pas unilatéralement déclarer la clôture.
• ❌ Dans le mode B, utiliser le même agent de manière séquentielle pour jouer les deux rôles d'« implémentation » et de « test » — la valeur fondamentale de B est l'isolation du contexte ; les deux doivent être physiquement indépendants, sinon l'isolation du contexte n'a pas lieu et B est équivalent à ne pas être activé.
• ❌ Dans le mode B, l'agent de test, découvrant un bug de conception, modifie la conception de son propre chef — les changements de conception ont un large impact, doivent déclencher le mécanisme de modification et être confirmés par l'utilisateur ; l'agent de test ne peut que diagnostiquer et signaler.