Améliorer l'architecture de la base de code
Explorez une base de code comme le ferait une IA, détectez les frictions architecturales, découvrez les opportunités d'amélioration de la testabilité, et proposez des refactorisations d'approfondissement de modules sous forme d'issues RFC GitHub.
Un module profond (John Ousterhout, "A Philosophy of Software Design") possède une petite interface qui masque une grande implémentation. Les modules profonds sont plus testables, plus navigables par l'IA, et permettent de tester à la frontière plutôt qu'à l'intérieur.
Processus
1. Explorer la base de code
Utilisez l'outil Agent avec subagent_type=Explore pour naviguer naturellement dans la base de code. Ne suivez PAS d'heuristiques rigides — explorez de manière organique et notez les endroits où vous ressentez une friction :
- Où la compréhension d'un concept nécessite de passer d'un fichier à l'autre entre de nombreux petits fichiers ?
- Où les modules sont si peu profonds que l'interface est presque aussi complexe que l'implémentation ?
- Où des fonctions pures ont été extraites uniquement pour la testabilité, mais où les vrais bugs se cachent dans la manière dont elles sont appelées ?
- Où des modules fortement couplés créent des risques d'intégration dans les jointures entre eux ?
- Quelles parties de la base de code ne sont pas testées, ou difficiles à tester ?
La friction que vous ressentez EST le signal.
2. Présenter les candidats
Présentez une liste numérotée des opportunités d'approfondissement. Pour chaque candidat, montrez :
- Cluster : Quels modules/concepts sont impliqués
- Pourquoi ils sont couplés : Types partagés, schémas d'appel, co-propriété d'un concept
- Catégorie de dépendance : Voir REFERENCE.md pour les quatre catégories
- Impact sur les tests : Quels tests existants seraient remplacés par des tests de frontière
Ne proposez PAS encore d'interfaces. Demandez à l'utilisateur : "Lequel de ceux-ci souhaitez-vous explorer ?"
3. L'utilisateur choisit un candidat
4. Cadrer l'espace problème
Avant de lancer des sous-agents, rédigez une explication destinée à l'utilisateur de l'espace problème pour le candidat choisi :
- Les contraintes que toute nouvelle interface devrait satisfaire
- Les dépendances sur lesquelles elle devrait s'appuyer
- Un croquis de code illustratif approximatif pour rendre les contraintes concrètes — ce n'est pas une proposition, juste un moyen de matérialiser les contraintes
Montrez cela à l'utilisateur, puis passez immédiatement à l'étape 5. L'utilisateur lit et réfléchit au problème pendant que les sous-agents travaillent en parallèle.
5. Concevoir plusieurs interfaces
Lancez 3 sous-agents ou plus en parallèle à l'aide de l'outil Agent. Chacun doit produire une interface radicalement différente pour le module approfondi.
Donnez à chaque sous-agent un brief technique séparé (chemins de fichiers, détails du couplage, catégorie de dépendance, ce qui est masqué). Ce brief est indépendant de l'explication destinée à l'utilisateur de l'étape 4. Donnez à chaque agent une contrainte de conception différente :
- Agent 1 : "Minimiser l'interface — viser 1 à 3 points d'entrée maximum"
- Agent 2 : "Maximiser la flexibilité — supporter de nombreux cas d'usage et extensions"
- Agent 3 : "Optimiser pour l'appelant le plus courant — rendre le cas par défaut trivial"
- Agent 4 (si applicable) : "Concevoir selon le pattern ports & adaptateurs pour les dépendances transfrontalières"
Chaque sous-agent produit :
- Signature de l'interface (types, méthodes, paramètres)
- Exemple d'utilisation montrant comment les appelants l'utilisent
- Quelle complexité il masque en interne
- Stratégie de dépendance (comment les dépendances sont gérées — voir REFERENCE.md)
- Compromis
Présentez les conceptions séquentiellement, puis comparez-les en prose.
Après la comparaison, donnez votre propre recommandation : quelle conception vous semble la plus solide et pourquoi. Si des éléments de différentes conceptions se combinent bien, proposez un hybride. Soyez tranché — l'utilisateur veut une opinion forte, pas seulement un menu.
6. L'utilisateur choisit une interface (ou accepte la recommandation)
7. Créer une issue GitHub
Créez une RFC de refactoring sous forme d'issue GitHub en utilisant gh issue create. Utilisez le template dans REFERENCE.md. Ne demandez PAS à l'utilisateur de relire avant de créer — créez-la simplement et partagez l'URL.