XeroBis/website

Planifier et documenter

Pourquoi

Les demandes comme « portage des cartes » ou « ajouter des tags au portfolio » ressemblent à des décisions finales, mais cachent généralement des choix non résolus : combien construire maintenant, quoi supprimer ou modifier de l'ancien dépôt, quel schéma possède les données, ce qui va dans @shared. Construire immédiatement risque de faire la mauvaise chose, de la refaire, ou de s'écarter d'un choix déjà enregistré dans documentation/decisions.md. Poser des questions d'abord permet aux docs — et ensuite au code — de rester un reflet précis de ce que l'utilisateur veut réellement.

Quand cela s'applique

Toute demande qui modifierait ce que documentation/ suit : une fonctionnalité ou un comportement visible par l'utilisateur, un schéma/table/colonne/règle métier, un choix technique ou de bibliothèque, la structure des dossiers/architecture, ou une étape de migration-plan.md. Les petites modifications entièrement spécifiées (corriger cette faute de frappe, renommer ce libellé exactement en X) ne nécessitent pas l'entretien — utilisez votre jugement pour déterminer ce qui est réellement ambigu.

Étapes

1. Lire avant de demander. Parcourez les sections documentation/*.md qui concernent la demande (et le code pertinent). Lors d'un portage, lisez aussi les docs de l'ancien dépôt (../<repo>/documentation/, ../<repo>/CLAUDE.md) et le code porté. Ne posez pas de question à laquelle on a déjà répondu. Utilisez-les comme base pour vos questions.

2. Poser des questions de clarification avec AskUserQuestion. Préférez plusieurs petites questions concrètes à une seule question large. Pour ce dépôt, les bons sujets sont :

   • combien construire maintenant vs. plus tard ;
   • lors d'un portage : quoi conserver tel quel, modifier ou supprimer de l'ancienne app (l'ancien comportement n'est pas automatiquement souhaité) ;
   • quel schéma possède les nouvelles tables (propre à une app, ou core si chaque app en a besoin) ;
   • si un élément appartient à une app ou à @shared / un module backend partagé ;
   • les détails UX que features.md devrait enregistrer, et la forme des nouvelles données.

   Donnez à chaque question une valeur par défaut recommandée pour que l'utilisateur puisse avancer rapidement.

3. Respecter exactement le périmètre que l'utilisateur vous donne. S'il le réduit à « docs uniquement » ou « juste X, pas Y », n'en faites pas plus sans confirmation — confirmez à nouveau avant d'élargir le périmètre plus tard.

4. Mettre à jour les docs dans la même étape que la décision, en utilisant le tableau de CLAUDE.md :

   • Structure des dossiers, environnements, ports, flux de requêtes → architecture.md
   • Schémas, tables, colonnes, relations, règles métier → data-model.md, dans la section de ce schéma
   • Choix technique/bibliothèque/architecture → decisions.md : une entrée datée indiquant ce qui a été choisi, sur quoi, et pourquoi, en respectant le style du fichier
   • Comportement visible par l'utilisateur, règles de validation → features.md, dans la section de cette app
   • Tout ce qui est différé, exclu ou encore une simple possibilité → ideas.md
   • Progression du portage → colonne d'état de migration-plan.md
   • Modifications du runbook de production → deployment.md

5. Déplacer les idées résolues hors de ideas.md. Si une modification transforme une entrée de ideas.md en décision réelle, supprimez ou réécrivez cette entrée plutôt que de laisser un doublon obsolète.