Améliorer l'architecture du code

Identifier les frictions architecturales et proposer des opportunités d'approfondissement — des refactorisations qui transforment des modules superficiels en modules profonds. L'objectif est la testabilité et la navigabilité pour l'IA.

Glossaire

Utilise ces termes exactement dans chaque suggestion. Le langage cohérent est l'essentiel — ne dérives pas vers « composant », « service », « API » ou « limite ». Définitions complètes dans LANGUAGE.md.

• Module — tout ce qui a une interface et une implémentation (fonction, classe, package, slice).
• Interface — tout ce qu'un appelant doit savoir pour utiliser le module : types, invariants, modes d'erreur, ordre, config. Pas seulement la signature de type.
• Implémentation — le code à l'intérieur.
• Profondeur — levier au niveau de l'interface : beaucoup de comportement derrière une petite interface. Profond = levier élevé. Superficiel = interface presque aussi complexe que l'implémentation.
• Seam — où vit une interface ; un endroit où le comportement peut être altéré sans édition sur place. (Utilise ceci, pas « limite ».)
• Adapter — une chose concrète qui satisfait une interface au niveau d'un seam.
• Levier — ce que les appelants gagnent de la profondeur.
• Localité — ce que les mainteneurs gagnent de la profondeur : les changements, les bugs, la connaissance concentrés dans un seul endroit.

Principes clés (voir LANGUAGE.md pour la liste complète) :

• Test de suppression : imagine supprimer le module. Si la complexité disparaît, c'était un relais. Si la complexité réapparaît sur N appelants, il gagnait son maintien.
• L'interface est la surface de test.
• Un adapter = seam hypothétique. Deux adapters = vrai seam.

Cette compétence est informée par le modèle de domaine du projet — CONTEXT.md et tout docs/adr/. Le langage du domaine donne des noms aux bons seams ; les ADRs enregistrent les décisions que la compétence ne doit pas relitigater. Voir CONTEXT-FORMAT.md et ADR-FORMAT.md.

Processus

1. Explorer

Lis d'abord la documentation existante :

• CONTEXT.md (ou CONTEXT-MAP.md + chaque CONTEXT.md dans un repo multi-contexte)
• ADRs pertinents dans docs/adr/ (et tout répertoire docs/adr/ scoped au contexte)

Si l'un de ces fichiers n'existe pas, continue silencieusement — ne signale pas son absence et ne suggère pas de le créer d'entrée de jeu.

Utilise ensuite l'outil Agent avec subagent_type=Explore pour parcourir le code. Ne suis pas des heuristiques rigides — explore organiquement et note où tu expérimentes de la friction :

• Où comprendre un concept exige-t-il de rebondir entre de nombreux petits modules ?
• Où les modules sont-ils superficiels — interface presque aussi complexe que l'implémentation ?
• Où des fonctions pures ont-elles été extraites juste pour la testabilité, mais les vrais bugs se cachent dans la façon dont elles sont appelées (pas de localité) ?
• Où les modules fortement couplés fuient-ils au-delà de leurs seams ?
• Quelles parties du code ne sont pas testées, ou difficiles à tester via leur interface actuelle ?

Applique le test de suppression à tout ce que tu suspectes d'être superficiel : le supprimer concentrerait-il la complexité, ou l'avancerait-il seulement ? Un « oui, concentre » est le signal que tu cherches.

2. Présenter les candidats

Présente une liste numérotée d'opportunités d'approfondissement. Pour chaque candidat :

• Fichiers — quels fichiers/modules sont impliqués
• Problème — pourquoi l'architecture actuelle cause de la friction
• Solution — description en langage simple de ce qui changerait
• Bénéfices — expliqués en termes de localité et de levier, et aussi en comment les tests s'amélioreraient

Utilise le vocabulaire CONTEXT.md pour le domaine, et le vocabulaire LANGUAGE.md pour l'architecture. Si CONTEXT.md définit « Order », parle du « module d'intake Order » — pas du « FooBarHandler », et pas du « service Order ».

Conflits ADR : si un candidat contredit un ADR existant, ne le surface que si la friction est assez réelle pour justifier de revisiter l'ADR. Marque-le clairement (ex. « contredit ADR-0007 — mais vaut le coup de rouvrir parce que… »). Ne liste pas chaque refactor théorique qu'un ADR interdit.

NE propose PAS d'interfaces pour l'instant. Demande à l'utilisateur : « Lequel de ceux-ci aimerais-tu explorer ? »

3. Boucle de grilling

Une fois que l'utilisateur choisit un candidat, entre dans une conversation de grilling. Parcourez ensemble l'arbre de conception — contraintes, dépendances, la forme du module approfondi, ce qui se cache derrière le seam, quels tests survivent.

Les effets secondaires se produisent en ligne à mesure que les décisions se cristallisent :

• Nommer un module approfondi après un concept absents de CONTEXT.md ? Ajoute le terme à CONTEXT.md — même discipline que /domain-model (voir CONTEXT-FORMAT.md). Crée le fichier paresseusement s'il n'existe pas.
• Affiner un terme flou pendant la conversation ? Mets à jour CONTEXT.md sur le champ.
• L'utilisateur rejette le candidat avec une raison structurante ? Offre un ADR, présenté ainsi : « Veux-tu que j'enregistre ceci comme un ADR pour que les futures revues d'architecture ne le re-suggèrent pas ? » Propose-le uniquement quand la raison serait vraiment utile à un futur explorateur pour éviter de re-suggérer la même chose — ignore les raisons éphémères (« pas intéressant en ce moment ») et les évidentes. Voir ADR-FORMAT.md.
• Veux explorer des interfaces alternatives pour le module approfondi ? Voir INTERFACE-DESIGN.md.