improve-codebase-architecture (mattpocock/skills)

Avis

Codex CLI 0.166 (gpt-6-astra, low reasoning) sur un PC Windows de test dédié, un projet temporaire neuf et des HOME/TMPDIR/caches temporaires à chaque exécution, skill installé (traitement) ou absent (contrôle) ou absent avec l'exigence centrale du skill compressée en une phrase ajoutée au prompt (groupe « prompt d'une phrase »), 2 exécutions par groupe et par tâche, réseau coupé, écritures dans /tmp bloquées. Les prompts ne mentionnent jamais le skill (sauf la formulation indiquée ci-dessous). Trois tâches sur un petit backend de boutique Python avec des frictions plantées (validateurs/helpers monétaires superficiels, un service d'inventaire qui ne fait que relayer vers son dépôt, un adaptateur de paiement unique, une logique de remise dupliquée dans le panier et les commandes, des tests qui ne couvrent que les helpers) : une revue d'architecture de tout le code écrite dans report.html, la même limitée au paiement et à l'inventaire, et « pourquoi place_order est-il pénible à tester » répondu dans le chat. Les prompts du groupe avec skill commencent par $improve-codebase-architecture (invocation explicite) ; les prompts de contrôle et d'une phrase ne le nomment pas.

Comparaison à trois bras

Mesuré avec Codex CLI sur 18 exécutions, noté par des contrôles basés sur des règles, sans juge LLM. Total 23.0 / 30, verdict Selon les cas.

Verdict : situationnel (23.0 / 30). Source : mattpocock/skills, skills/engineering/improve-codebase-architecture, skills/engineering/codebase-design, épinglé au commit 4ae2317. Installation : npx skills@latest add mattpocock/skills --skill improve-codebase-architecture. Licence : MIT (LICENSE du dépôt).

Ce que c'est

La compétence improve-codebase-architecture de mattpocock/skills. Elle cherche des « occasions d'approfondissement » dans une base de code : modules superficiels dont l'interface est aussi complexe que l'implémentation, couches de simple transit, jointures à adaptateur unique restées hypothétiques, logique dupliquée, comportement testé uniquement via des helpers. Elle produit un rapport HTML avec un avant/après par candidat et une recommandation principale. Elle s'appuie sur une compétence voisine, codebase-design, pour le vocabulaire. Markdown uniquement, aucun script.

Comment nous avons testé

Codex CLI 0.166 (gpt-6-astra, raisonnement faible) sur un PC de test Windows dédié, un projet temporaire neuf et des HOME/TMPDIR/caches temporaires à chaque exécution, compétence installée (avec compétence), absente (témoin) ou absente avec l'exigence essentielle de la compétence condensée en une phrase ajoutée au prompt (groupe prompt d'une phrase), 2 exécutions par groupe et par tâche, réseau désactivé, écritures dans /tmp bloquées. Les prompts ne mentionnent jamais la compétence (sauf la formulation indiquée ci-dessous).

Trois tâches sur un petit backend de boutique en Python avec des frictions implantées (validators et helpers monétaires superficiels, un service d'inventaire qui ne fait que relayer vers son dépôt, un adaptateur de paiement unique, une logique de remise dupliquée dans le panier et les commandes, des tests qui ne couvrent que les helpers) : une revue d'architecture de toute la base de code rédigée dans report.html, la même limitée au paiement et à l'inventaire, et « pourquoi place_order est-il pénible à tester » répondue dans le chat. Les prompts du groupe avec compétence commencent par $improve-codebase-architecture (invocation explicite) ; ceux des groupes témoin et prompt d'une phrase ne la nomment pas.

1. Analyse d'architecture de tout le dépôt — Analyse ce petit backend de boutique pour des améliorations d'architecture : où une restructuration rendrait-elle le code plus facile à modifier et à tester ? Rédige tes conclusions dans un rapport HTML autonome nommé report.html dans ce dossier (n'ouvre pas de navigateur et ne lance pas de se…
2. Paiement et inventaire uniquement — Examine uniquement les parties paiement et inventaire de ce backend et dis-moi quelles restructurations seraient rentables. Rédige tes conclusions dans un rapport HTML autonome nommé report.html dans ce dossier (n'ouvre pas de navigateur et ne lance pas de serveur) et ne modifie aucun co…
3. Pourquoi place_order est-il difficile à tester ? — Il me semble pénible d'écrire un vrai test pour place_order dans ce backend. Pourquoi, et quelle restructuration y remédierait ? Ne modifie aucun fichier ; réponds dans ton message final.

Le score est calculé de manière programmatique (tests masqués / détection des problèmes implantés / vérifications de contraintes / rendu + OCR le cas échéant), avec une note de 0–5 par exécution. Aucun juge LLM n'a attribué de score.

Résultats

Le prompt d'une phrase fourni au troisième groupe : « Cherche les occasions d'approfondissement : modules superficiels dont l'interface est aussi complexe que l'implémentation (applique le test de suppression : supprimer ce module concentrerait-il la complexité ou la déplacerait-il simplement ?), couches de simple transit, jointures à adaptateur unique restées hypothétiques, logique dupliquée entre modules, et logique testée uniquement via des helpers plutôt que via la vraie interface ; présente chaque candidat avec les fichiers, le problème, la solution, les bénéfices, un avant/après, et nomme une recommandation principale. »

Score moyen : 3.2 sans contre 4.12 avec la compétence (écart +0.92). Tokens par exécution : 115k contre 208k (1.80x) ; temps 112s contre 135s. Groupe prompt d'une phrase : 3.91 (gain de la compétence par rapport au prompt d'une phrase : +0.2 ; gain propre du prompt d'une phrase par rapport à l'absence de compétence : +0.72) ; tokens du prompt d'une phrase : 120k par exécution, la compétence coûte donc 1.73x le prompt d'une phrase.

Ce qui s'est passé

• C'est sur la revue de toute la base de code que la différence apparaît : la compétence et la version en une phrase ont trouvé 6/6 points implantés, avec le vocabulaire d'architecture, un avant/après et une recommandation principale aux quatre exécutions ; Codex seul en a trouvé 2/6 dans une exécution et 5 contrôles sur 6 dans l'autre, et aucune des deux n'avait de « recommandation principale » claire.
• La revue ciblée (paiement et inventaire uniquement) est difficile pour tout le monde : le meilleur groupe a trouvé en moyenne un des deux points implantés. Témoin 2/4 contrôles, prompt d'une phrase 3/4, compétence 3/4. La compétence n'a pas fait mieux que la phrase.
• Sur « pourquoi place_order est-il difficile à tester », les trois groupes ont trouvé les causes implantées (PaymentAdapter caché, stock partagé au niveau du module, logique de remise dupliquée, tests qui s'arrêtent aux helpers). La réponse de la compétence utilisait son vocabulaire (« interface », « localité ») ; celle du témoin était tout aussi correcte en mots simples.
• Score moyen 3.20 pour le témoin, 3.91 pour le prompt d'une phrase, 4.12 pour la compétence. La compétence apporte 0.21 de plus que la phrase en consommant 1.7x les tokens (208k contre 120k par exécution), car elle lit aussi la compétence voisine ; le groupe prompt d'une phrase coûte autant que le témoin (115k).
• Comme la compétence installe deux dossiers de compétences, les exécutions avec compétence créaient des fichiers supplémentaires dans le dossier .agents du projet ; ils ont été exclus du contrôle « aucun fichier de code modifié » (une première passe les avait à tort mis en échec, et un bug propre à Windows dans le contrôle a été corrigé avant les chiffres finaux).

Scores par dimension

Limites de ce test

• Un petit jeu de données Python avec des problèmes implantés classiques ; l'utilité du rapport sur un gros dépôt réel n'est pas mesurée.
• La qualité du rapport, les faux positifs et le style HTML (il charge Tailwind et Mermaid depuis des CDN à l'ouverture dans un navigateur) n'ont pas été notés ; le comportement de sous-agent décrit par la compétence n'a pas été exercé.
• Le prompt d'une phrase reformule la checklist de la compétence : c'est donc une borne haute pour un prompt court.
• n = 2 par groupe et par tâche : les écarts inférieurs à environ 1 point relèvent du bruit.
• Le score basé sur des règles mesure ce que les contrôles peuvent voir ; il ne peut juger du goût ni du caractère optimal d'un résultat.

Sécurité

Voir security.md. Analyse : 0 CRITICAL / 0 HIGH / 0 MEDIUM. Verdict : sûr à exécuter (sandbox sans réseau). Une analyse propre ne prouve pas qu'une compétence est sûre.

En bref

Par rapport à l'absence de compétence, celle-ci améliore nettement une revue de toute la base de code, surtout en imposant la structure et le vocabulaire du rapport, en consommant 1.8x les tokens. Une seule phrase listant les mêmes symptômes obtient l'essentiel du gain : elle vaut donc surtout la peine si vous voulez retrouver à chaque fois le même format de rapport.