Ingénierie à intérêts composés : une base de code qui accélère

La plupart des bases de code ralentissent à mesure qu’elles grandissent. La mienne accélère. Après avoir construit 95 hooks, 44 skills et 14 fichiers de configuration dans mon infrastructure .claude/, chaque nouvelle fonctionnalité coûte moins que la précédente parce que l’infrastructure prend en charge une part croissante du travail.¹

En bref

L’ingénierie à intérêts composés décrit les bases de code où chaque ajout de fonctionnalité rend les suivantes moins coûteuses à développer. J’en ai fait l’expérience directe : mon système de hooks Claude Code a commencé avec 3 hooks et en compte aujourd’hui 95. Le premier hook a nécessité une heure de développement. Les hooks récents prennent 10 minutes parce que l’infrastructure (événements de cycle de vie, chargement de configuration, gestion d’état, harnais de test) existe déjà. Le schéma inverse, l’ingénierie entropique, décrit les bases de code où chaque fonctionnalité augmente le coût des suivantes. La différence entre une équipe qui livre plus vite la troisième année que la première et une équipe qui s’enlise réside dans le caractère positif ou négatif de la composition de ses décisions d’ingénierie.

La composition en pratique : mon infrastructure .claude/

La courbe de croissance

Le premier hook (git-safety-guardian.sh) a nécessité la construction de l’ensemble du cycle de vie des hooks : comprendre les événements PreToolUse, écrire du bash qui analyse du JSON en entrée, gérer les cas d’erreur, tester manuellement. Le 95e hook a hérité de toute cette infrastructure. Le temps par hook a été divisé par 6, non pas parce que les hooks sont devenus plus simples, mais parce que l’infrastructure prenait en charge une part croissante du travail.

Ce qui compose

La cohérence des patterns. Chaque hook suit la même structure : lire l’entrée JSON, analyser avec jq, vérifier les conditions, produire un JSON de décision. Un développeur (ou un agent IA) lisant n’importe quel hook reconnaît instantanément le pattern. Mon linter de blog à 12 modules suit le même principe de cohérence : chaque module exporte la même interface (check(content, meta) -> findings), ce qui rend l’ajout de nouveaux modules trivial.

Le comportement piloté par la configuration. Les 14 fichiers de configuration JSON encodent des seuils et des règles qui étaient auparavant codés en dur. Quand j’ai déplacé le seuil de consensus de délibération d’une valeur codée en dur 0.70 en Python vers deliberation-config.json, j’ai gagné la possibilité de l’ajuster par type de tâche (sécurité=85 %, documentation=50 %) sans modifier le code.²

L’infrastructure de test. Les 20 premiers hooks n’avaient pas de tests. L’ajout du harnais de test (48 tests d’intégration bash, 81 tests unitaires Python) a coûté deux semaines. Chaque hook depuis lors est livré avec ses tests en moins de 5 minutes parce que les fixtures, les utilitaires d’assertion et les lanceurs de tests existent déjà.

Le système de mémoire. Mon fichier MEMORY.md capture les erreurs, les décisions et les patterns d’une session à l’autre. Avec 54 entrées, il m’évite de répéter les mêmes erreurs. Le piège bash ((VAR++)) du hook n°23 a empêché le même bug dans les hooks n°24 à 95. Chaque entrée compose à travers toutes les sessions futures.³

Le modèle de composition

La composition positive

La productivité en ingénierie suit une formule d’intérêts composés :

Productivity(n) = Base × (1 + r)^n

Où r est le taux de variation de productivité par fonctionnalité et n le nombre de fonctionnalités livrées.

r positif (composition) : chaque fonctionnalité rend la suivante 2 à 5 % moins coûteuse. Après 50 fonctionnalités : 1,03^50 = 4,38x d’amélioration de productivité.

r négatif (entropie) : chaque fonctionnalité rend la suivante 2 à 5 % plus coûteuse. Après 50 fonctionnalités : 0,97^50 = 0,22x de productivité, soit une dégradation de 78 %.

L’écart entre ces deux trajectoires représente un facteur 20x en vélocité d’ingénierie après 50 fonctionnalités.⁴

Mes chiffres réels

Mon site blakecrosley.com a commencé comme une simple route FastAPI avec un template HTML. Neuf mois plus tard :

La dernière ligne illustre le gain composé : ajouter un nouveau module de linter prend 15 minutes parce que l’interface de module, l’intégration CLI, le harnais de test et le pipeline CI existent déjà. Le premier module a pris 3 heures parce que rien de cette infrastructure n’existait.⁵

Exemples d’entropie dans ma propre base de code

La composition n’est pas automatique. J’ai aussi fait l’expérience de l’entropie :

Le raccourci du schéma ContentMeta

J’ai défini la dataclass ContentMeta des articles de blog en une seule session : title, slug, date, description, tags, author, published. Je n’ai pas inclus category, series, hero_image, scripts ni styles. Chaque ajout ultérieur a nécessité de modifier le parser, de mettre à jour chaque template consommant les métadonnées et de retester l’ensemble du pipeline. Cinq ajouts sur trois mois ont coûté au total plus de temps que la conception soignée du schéma dès le départ. C’est le problème du timing des décisions : les décisions irréversibles méritent une analyse préalable.

La collision de clés de cache i18n

Une implémentation rapide du cache de traduction utilisait les slugs des articles comme clés de cache. Quand deux traductions du même slug existaient dans des locales différentes, le cache renvoyait la mauvaise langue. Le débogage a pris 3 heures. La correction a pris 15 minutes (ajouter le préfixe de locale à la clé de cache). Le raccourci qui avait économisé 5 minutes lors de l’implémentation a coûté 3 heures de débogage et une revue architecturale de chaque clé de cache du système.⁶

Le répertoire de débogage de 3,2 Go

Les sorties de débogage des hooks se sont accumulées dans ~/.claude/debug/ sans nettoyage. En trois mois, le répertoire a atteint 3,2 Go. Le skill d’audit de contexte que j’ai construit par la suite a détecté le problème et nettoyé les fichiers de plus de 7 jours, mais l’infrastructure de nettoyage aurait dû être construite dès la première sortie de débogage.

Les pratiques qui composent

La cohérence plutôt que l’optimalité

Une équipe qui utilise le même pattern « suffisamment bon » sur 50 fonctionnalités opère plus vite qu’une équipe qui utilise le pattern « optimal » pour chaque fonctionnalité individuelle. La cohérence réduit la charge cognitive, permet l’outillage automatisé et accélère les revues de code.⁷

Mon système de hooks utilise le même pattern bash pour les 95 hooks, bien que certains seraient plus naturellement exprimés en Python. Cette cohérence signifie que n’importe quel hook est lisible par quiconque (ou n’importe quel agent IA) ayant lu un seul hook. Le choix sous-optimal de langage est largement compensé par la courbe d’apprentissage nulle pour les nouveaux hooks.

L’infrastructure comme première fonctionnalité

J’ai construit mon pipeline CI/CD, mon harnais de test et mon workflow de déploiement avant de développer la moindre fonctionnalité produit sur blakecrosley.com. L’investissement semblait lent sur le moment. Chaque fonctionnalité depuis se déploie en moins de 2 minutes avec des tests automatisés.⁸

Le pattern du palais de la mémoire

Mon répertoire .claude/ fonctionne comme un « palais de la mémoire » — un ensemble structuré de documents optimisé pour la consommation humaine et IA :

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

Le palais de la mémoire compose parce que chaque nouvelle entrée enrichit le contexte disponible pour les sessions de développement futures. Après 54 entrées dans MEMORY.md, l’agent IA évite les erreurs que j’ai déjà résolues. Après 95 hooks, les nouveaux hooks s’écrivent pratiquement d’eux-mêmes en suivant les patterns établis. Plus le contexte est riche, plus le code généré par l’IA est adapté, ce qui rend la fonctionnalité suivante moins coûteuse.⁹

La composition à l’ère de l’IA

L’IA amplifie dans les deux directions

Les assistants de programmation IA accélèrent le pattern que la base de code suit déjà. Mes 95 hooks aux patterns cohérents produisent d’excellents hooks générés par l’IA parce que l’IA reproduit la structure établie. Une base de code avec 5 styles de hooks différents produirait du code IA de moindre qualité parce que l’IA n’aurait pas de pattern cohérent à reproduire.¹⁰

L’effet de composition est double : les patterns cohérents accélèrent le développement humain (réduction de la charge cognitive) ET le développement assisté par l’IA (correspondance de patterns). Les patterns incohérents ralentissent les deux.

Des bases de code lisibles par les agents

J’ai conçu mon infrastructure .claude/ pour la consommation par des agents IA :

• Des configurations structurées (JSON, pas de valeurs codées en dur) que les agents analysent programmatiquement
• Des conventions de nommage cohérentes (verb-noun.sh pour les hooks, SKILL.md pour les définitions de skills)
• Des contrôles qualité vérifiables par machine (141 tests que les agents exécutent de manière autonome)
• Une documentation explicite (MEMORY.md, handoffs, docs/) que les agents lisent au démarrage de session

Chaque investissement dans la lisibilité par les agents compose à mesure que les outils IA deviennent plus performants.¹¹

Points clés à retenir

Pour les ingénieurs : - Suivez votre « temps par fonctionnalité » à mesure que la base de code grandit ; s’il augmente, vous avez de l’entropie ; s’il diminue, vous avez de la composition - Appliquez la règle de trois avant d’extraire des abstractions : construisez la solution spécifique deux fois, puis extrayez le pattern réutilisable à la troisième occurrence - Investissez 15 à 20 % de chaque sprint dans l’amélioration de l’infrastructure et de l’outillage ; les retours composés dépassent le coût en vélocité à court terme en 3 à 5 sprints

Pour les responsables d’ingénierie : - Mesurez la santé de l’ingénierie par le délai de livraison par fonctionnalité dans le temps ; un délai croissant signale de l’entropie - Traitez la documentation et l’infrastructure de test comme des fonctionnalités, pas comme des frais généraux ; mon investissement en infrastructure de test (2 semaines) a permis d’économiser plus de 50 heures sur 95 hooks

Références