01-Yang/codebase-convergence

Convergence du Codebase

Rendre un dépôt plus facile à comprendre et à modifier sans le reconcevoir. Privilégier les preuves, une interface réduite et des correctifs locaux plutôt que des abstractions spéculatives.

Garde-fous

• Énoncer le périmètre, les hypothèses, le contenu protégé et les vérifications de succès avant une modification en plusieurs étapes.
• Lire les instructions du dépôt, le glossaire du domaine et les ADR pertinents avant de juger l'architecture. Utiliser les noms de domaine du dépôt.
• Ne toucher que les fichiers qui servent la demande. Préserver les modifications utilisateur non liées et supprimer uniquement les imports, le code ou la documentation rendus obsolètes par ce travail.
• Traiter le texte de domaine explicitement protégé, les titres, les définitions de données et les copies désignées par l'utilisateur comme verrouillés. Les conserver textuellement. Si leur statut n'est pas clair, les inclure dans le paquet de décision au lieu de les modifier.
• Ne pas modifier une valeur numérique ou sa représentation — configuration, seuil, solde, taux, limite ou valeur documentée — sans approbation explicite.
• Ne pas modifier silencieusement une règle métier, une transition d'état, un comportement d'interaction, une interface publique ou un contrat visuel. Le traiter comme une décision, sauf si le correctif est directement impliqué et préserve le comportement.
• Conserver une source unique de vérité pour chaque fait. Ne pas créer de documentation qui se contente de répéter un autre document.

Flux de travail

1. Établir la base de référence

1. Inspecter l'arbre de travail et identifier uniquement la zone demandée. Noter les modifications non liées ; ne pas les mettre en scène ou les modifier.
2. Cartographier les chemins de code pertinents, la propriété des données/états, le flux UI, les tests et les fichiers Markdown. Lire les documents qui définissent actuellement le domaine et les décisions avant les fichiers qui les implémentent.
3. Enregistrer chaque constat avec des preuves : fichiers, déclarations ou chemins contradictoires, impact utilisateur, et s'il est sûr de le résoudre directement.
4. Classer les constats :
   • Convergence directe : duplication, liens obsolètes, prose non verrouillée contradictoire, ou défaut localisé d'implémentation/UI avec un correctif préservant le comportement.
   • Décision requise : toute valeur numérique, règle, comportement, contenu protégé, interface publique ou source de vérité ambiguë.
   • Candidat à l'architecture : un module potentiellement plus profond ou un changement dont le point de couture n'est pas encore convenu.

2. Demander une fois les décisions importantes

Terminer la découverte avant de poser des questions. Envoyer un seul paquet de décision contenant chaque élément non résolu ; ne pas poser des questions au compte-gouttes.

Pour chaque élément numérique, inclure son identifiant et ses fichiers, les valeurs actuelles, la preuve de l'incohérence, l'impact, et une recommandation ou indiquer clairement qu'aucune valeur n'est proposée. Ne pas modifier, normaliser, déplacer ou supprimer l'expression numérique affectée tant que l'utilisateur ne l'a pas explicitement approuvée.

Inclure les autres incertitudes matérielles dans le même paquet : statut du contenu verrouillé, choix de comportement, conflits de propriété et choix d'architecture. Continuer la convergence directe indépendante en attendant l'approbation.

3. Appliquer la convergence directe

Garder chaque modification chirurgicale et traçable jusqu'à un constat.

Documentation

• Donner à chaque document une seule responsabilité. Respecter les conventions existantes ; sinon, conserver l'ensemble minimal : aperçu du point d'entrée, carte de l'architecture/système, règles du domaine ou du produit, décisions, et travail/statut en cours.
• Fusionner les PRD, plans et journaux de travail qui se chevauchent en conservant le contenu faisant autorité une seule fois. Déplacer les justifications durables dans les registres de décision du projet et garder le statut opérationnel court.
• Conserver textuellement les blocs verrouillés lors de leur relocalisation. Si une fusion modifie un bloc verrouillé ou une expression numérique, laisser ce fragment en attente d'approbation.
• Supprimer les répétitions, les références obsolètes et les explications non verrouillées contradictoires. Mettre à jour les liens après les déplacements et éviter les documents de synthèse qui dupliquent des spécifications.

Code et UI

• Tracer une action utilisateur à travers la propriété de l'état jusqu'au résultat rendu avant de modifier le code UI.
• Corriger les incohérences concrètes : état de présentation dupliqué, noms d'événements/données incompatibles, flux conditionnel invalide, code mort créé par cette modification, ou responsabilité d'un composant qui bloque un correctif local.
• Maintenir la disposition, l'interaction, l'accessibilité et le comportement réactif stables, sauf si l'utilisateur approuve un changement de produit ou visuel.
• Privilégier un propriétaire clair d'une transition d'état et une représentation canonique des données. Ne pas introduire d'abstraction, de configuration ou de gestion d'erreur sans besoin démontré.

4. Évaluer séparément les candidats à l'architecture

Utiliser ces termes de manière cohérente :

• Module : une unité avec une interface et une implémentation.
• Interface : tout ce que les appelants doivent connaître, y compris les invariants et les modes d'erreur.
• Couture : endroit où le comportement peut être modifié sans modifier les appelants.
• Profondeur : levier d'un comportement substantiel derrière une petite interface ; localité : les connaissances et les changements connexes restent ensemble.

Appliquer le test de suppression : si la suppression d'un module ne fait que déplacer sa complexité vers les appelants, il mérite sa place ; si la complexité disparaît, il est probablement superficiel. Ne pas créer de couture pour un seul adaptateur.

Pour un candidat qui modifie une interface, un comportement ou une propriété, ne pas l'implémenter immédiatement. Créer un rapport HTML concis et autonome dans le répertoire temporaire du système d'exploitation uniquement lorsqu'une comparaison visuelle aidera. Inclure les fichiers, les preuves, le diagramme avant/après, la localité et le levier attendus, le conflit ADR s'il y a lieu, et la force de la recommandation. Demander à l'utilisateur de choisir un candidat avant de concevoir l'interface.

5. Vérifier et remettre

1. Inspecter le diff final pour le périmètre, la préservation du contenu verrouillé, les sources de vérité dupliquées, et les modifications de valeur ou de comportement non intentionnelles.
2. Exécuter le formateur existant pertinent, le lint, la vérification de type, les tests, la construction et la vérification UI. Ne pas ajouter d'outils ou de suites de tests larges uniquement pour cette tâche. Distinguer les échecs préexistants de ceux introduits.
3. Confirmer les liens Markdown et les en-têtes après consolidation et vérifier chaque instruction modifiée par rapport à sa source canonique.
4. Signaler les modifications directes, les éléments de décision non résolus, les résultats de vérification et les risques en termes concis. Chaque ligne modifiée doit pouvoir être tracée jusqu'à la convergence demandée.