Cycle de développement assisté par IA

Medusa utilise un cycle de développement traçable pour éviter qu’une demande soit implémentée sans connaissance de l’existant ou sans arbitrage humain. Pour une idée encore incertaine, un Software Design Document (SDD) versionné stabilise d’abord le besoin et les décisions. Le plan reste le livrable obligatoire qui autorise ensuite l’implémentation après validation humaine.

Parcours attendu

flowchart LR
  P[Prompt] --> D[Découverte de l'existant]
  D --> Q{Discussion SDD utile ?}
  Q -->|non, demande claire| PL[Plan détaillé]
  Q -->|oui| S[Discussion et SDD]
  S --> SV{Validation humaine du SDD}
  SV -->|révision| S
  SV -->|approbation| PL
  PL --> R[Revue humaine assistée]
  R -->|modifications| PL
  R --> V{Validation humaine}
  V -->|refus| PL
  V -->|approbation explicite| I[Implémentation IA]
  I --> T[Vérifications et documentation]
  T --> A[Archive du plan]

1. Demande

La demande décrit le résultat attendu, les acteurs et les contraintes connues. L’IA commence par retrouver les fonctionnalités, interfaces, permissions et conventions déjà présentes. Elle ne suppose pas qu’une nouvelle route, ressource ou permission est nécessaire avant cette découverte.

2. Discussion de conception optionnelle

La discussion SDD est déclenchée lorsque le demandeur la souhaite. Elle est aussi recommandée pour une nouvelle capacité ambiguë, transverse, persistante, sensible aux permissions/sécurité, coûteuse ou difficile à inverser. Une correction petite et déjà définie peut aller directement au plan.

L’IA inspecte d’abord l’existant, puis conduit de courts rounds de questions. Elle distingue les faits vérifiés, exigences du demandeur, hypothèses, inférences, décisions et questions ouvertes. Elle challenge les contradictions, termes vagues, acteurs oubliés et cas limites pertinents, et formule une recommandation avec ses conséquences lorsqu’un arbitrage est requis.

Le SDD contient des exigences stables FR-*/NFR-* et des critères AC-*. Il n’est approuvable qu’après suppression des placeholders et résolution de toutes les questions bloquantes. Une personne valide explicitement le document final. Cette validation permet seulement de préparer le plan.

Tous les SDD partagent le même socle, défini uniquement dans .agents/sdds/TEMPLATE.md. L’IA les crée obligatoirement avec la commande du workflow : elle ne copie pas un ancien document et n’invente pas une structure différente. Le contenu et les sous-rubriques propres au domaine peuvent varier, mais les rubriques canoniques, leur ordre et la version du template restent identiques jusqu’à la revue et l’approbation.

La création et les gates du workflow acceptent indifféremment les fichiers Markdown en LF ou avec les fins de ligne Windows CRLF. Cette compatibilité de lecture ne modifie ni le modèle commun, ni sa version, ni les validations appliquées aux SDD.

3. Plan détaillé

L’IA crée un fichier sous .agents/plans/active/ à partir du modèle commun. Le plan contient au minimum : périmètre, critères d’acceptation, existant réutilisé, contrats impactés, conception, étapes par fichier, sécurité, données, interface, documentation, tests, déploiement, retour arrière et risques.

Le plan passe au statut in_review. À cette étape, aucun code produit n’est modifié.

Un plan peut référencer un SDD approuvé ou archivé et sa révision. Il traduit alors ses exigences en étapes et tests sans réinventer ou supprimer silencieusement les décisions déjà validées.

4. Revue et validation

Une personne relit le plan. Elle peut demander à l’IA d’analyser les risques ou d’intégrer ses commentaires. Toute modification d’un plan déjà approuvé annule l’approbation précédente.

La validation doit être explicite et porte sur la version finale visible du plan. Le nom du validateur et la preuve de validation sont enregistrés. L’IA ne peut jamais se valider elle-même.

La validation du SDD et celle du plan sont deux gates séparés : aucune des deux ne peut être déduite du silence ou effectuée par l’IA.

5. Implémentation et clôture

L’IA n’implémente qu’un plan approved. Elle met à jour le journal d’implémentation, les trois volets documentaires Medusa et exécute les contrôles prévus. Une décision nouvelle ou un élargissement du périmètre renvoie le plan en revue.

Une fois les critères satisfaits, le plan est archivé par année et mois. L’index permet de retrouver la demande, les décisions, la validation et les preuves de vérification.

Utilisation avec Codex

Les skills peuvent être choisis explicitement ou détectés à partir de la demande :

• $medusa-project-context pour cartographier une fonctionnalité existante ;
• $medusa-sdd-discovery pour discuter, challenger et formaliser une idée avant le plan ;
• $medusa-change-plan pour créer, revoir ou faire évoluer un plan ;
• $medusa-implement-plan pour exécuter un plan humainement approuvé.

Exemple de première demande :

Utilise $medusa-change-plan pour préparer l’ajout d’un garage persistant. Ne commence pas l’implémentation.

Pour une idée moins stabilisée :

Utilise $medusa-sdd-discovery pour discuter cette capacité, éliminer les incertitudes et produire un SDD que je pourrai valider avant la planification.

Après revue, une personne peut demander l’enregistrement de son approbation, puis lancer explicitement l’implémentation du plan approuvé.

Sélection du contexte par domaine

Avant de préparer un plan, l’IA choisit le plus petit contexte utile. Elle annonce un domaine principal, puis ajoute au maximum deux domaines secondaires si le parcours traverse réellement leurs frontières. Les neuf domaines actuels sont :

Domaine	Besoins couverts
Accès et administration	Authentification Discord, whitelist, permissions, modération, audits et surfaces admin
Personnages et apparence	Sélection/spawn, personnalisation, vêtements, tenues, vestiaires et tatouages
Banque	Comptes, soldes, ledger, espèces, cartes/PIN, PNJ bancaires, distributeurs et administration financière
Objets et inventaires	Catalogue d’objets, inventaires personnels, drops, stockages, slots et poids
Monde et interactions	Interactions, placement/sélection d’entités, props, MLO et outils World Edit
Groupes	Propriété, membres, invitations, rangs et permissions propres à un groupe
Compétences	Arbre, branches/nœuds, prérequis, XP, niveaux, points, déblocages et flags accordés
Simulation et HUD	Buffs, temps, météo, HUD, horloge et minimap
Plateforme et exploitation	API, données, Docker, Portainer, démarrage, volumes, santé et logs

Cette sélection ne remplace pas la lecture du code : le pack indique où regarder et quels invariants vérifier. Le plan conserve la trace des domaines chargés et des passages de frontière afin que le relecteur humain puisse contrôler que l’existant pertinent a bien été pris en compte.

Exemples :

• modifier les caméras d’un magasin de vêtements sélectionne uniquement Personnages et apparence ;
• modifier les cartes, PIN ou écritures du ledger sélectionne Banque ;
• modifier la courbe de niveau ou les prérequis d’un nœud sélectionne Compétences ;
• ajouter un stockage matérialisé par un prop sélectionne Objets et inventaires, puis Monde et interactions ;
• ajouter une action inventaire dans les deux administrations sélectionne Objets et inventaires, puis Accès et administration ;
• corriger le téléchargement des mappings au démarrage sélectionne Plateforme et exploitation, puis Monde et interactions.

Responsabilités

Acteur	Responsabilité
Demandeur	Exprime le besoin et les contraintes métier
IA de découverte SDD	Inspecte l’existant, conduit la discussion et formalise les décisions sans planifier ni coder
Validateur SDD humain	Confirme explicitement que la conception finale peut sourcer un plan
IA planificatrice	Découvre l’existant et produit un plan vérifiable sans coder
Relecteur humain	Arbitre les choix, le périmètre, les risques et les questions ouvertes
Validateur humain	Approuve explicitement la version finale du plan
IA d’implémentation	Exécute le périmètre approuvé, vérifie et documente

Maintenance du contexte projet

Chaque nouveau plan évalue séparément le catalogue généré, la carte projet, les packs de domaine, le manifeste de routage et les références de skills. Pour chaque catégorie, le plan cite les fichiers à mettre à jour ou justifie explicitement qu'aucune mise à jour n'est nécessaire. À la clôture, l'implémentation compare cette évaluation avec le diff réel, actualise les connaissances réutilisables et consigne les choix dans son journal avant archivage.