Maturité du code
Votre agent de codage IA n'est aussi bon que le harnais de votre base de code. L'IA amplifie la structure déjà en place : une base de code disciplinée livre plus vite, une base de code indisciplinée livre du code confidemment erroné plus vite. Le harnais (Fowler : Agent = Modèle + Harnais) est ce que cette page vous aide à mesurer.
Un diagnostic à neuf dimensions avec un barème de 1 à 5 par dimension. Trois sont bloquantes : un faible score compromet fondamentalement le travail des agents et ne peut pas être compensé par de bons scores ailleurs. Les six autres sont contraignantes. Évaluez n'importe quel dépôt en une commande avec la compétence Claude Code libre et open-source.
Les cinq niveaux de maturité
Chaque niveau est défini par le mécanisme de rétroaction qu'il ajoute. On ne peut pas sauter de niveaux : ce qui déverrouille le niveau suivant est toujours une nouvelle boucle de rétroaction, pas un nouvel outil.
| Niveau | Nom | Ce qui est présent | Ce que les agents peuvent faire |
|---|---|---|---|
| 0 | Opaque | Pas de types appliqués. Couverture de tests quasi nulle. IC absente ou peu fiable. Docs obsolètes. Frontières de modules floues. | Suggestions isolées sur une seule fonction. Au-delà, le code produit est halluciné sans signal correcteur. |
| 1 | Instrumenté | Types appliqués à la compilation. Quelques tests existent. L'IC retourne un résultat en quelques minutes. | Génération sur une seule fonction avec une confiance de base. Refactorisations à portée étroite. Le signal est faible mais présent. |
| 2 | Validé | Couverture significative sur les chemins de code qui changent. IC sous 30 min (sous 5 min c'est mieux). Au moins un parcours d'intégration de bout en bout. | Refactorisations multi-fichiers dans une portée délimitée. Corrections de bogues validées par les tests existants. Niveau minimum pour l'Échelon 3 (développement dirigé). |
| 3 | Lisible | Frontières de modules claires. Nommage cohérent. Architecture documentée. Contrats comportementaux déclarés aux frontières d'interface. | Travail inter-modules avec des résultats prévisibles. Les agents peuvent raisonner sur la base de code sans visite guidée. |
| 4 | Spécifié | L'intention est capturée dans des spécifications, pas seulement dans le code. Le nouveau travail est spécification-d'abord. Les décisions passées sont documentées. | Génération autonome de fonctionnalités à partir de spécifications (Échelon 4). L'humain spécifie; l'agent construit et teste. |
| 5 | Gouverné par scénarios | Les scénarios de bout en bout couvrent les chemins critiques. Les métriques de satisfaction remplacent le binaire réussite/échec. Observabilité complète. | Production autonome complète (Échelon 5). Le modèle opérationnel du Lab devient viable. |
Fowler nomme les propriétés structurelles du Niveau 3 et au-delà affordances ambiantes : des propriétés qui rendent une base de code lisible pour un agent sans instruction supplémentaire. Leur absence force l'agent à inventer une structure.
Le Modèle de maturité des bases de code IA, validé sur un vrai projet à 91 % de couverture et des cycles bogue-correction sous 30 minutes, a énoncé le constat de fond sans détour : « L'intelligence d'un système de développement piloté par l'IA ne réside pas dans le modèle IA lui-même, mais dans l'infrastructure d'instructions, de tests, de métriques et de boucles de rétroaction qui l'entoure. »
La règle de plafond
La pratique d'ingénierie (les Échelons 0 à 5 du cadre) concerne comment l'équipe travaille. La maturité du code (Niveaux 0 à 5) concerne ce que le code supporte. Ils sont liés :
Le niveau de maturité d'une base de code est le plafond de l'échelon d'ingénierie qui peut y opérer de façon fiable.
Une équipe à l'Échelon 5 qui déploie des agents sur une base de code de Niveau 2 obtiendra les mêmes bris qu'une équipe à l'Échelon 2, mais plus vite. Les boucles de rétroaction qui maintiennent l'Échelon 5 honnête n'existent pas. C'est le mode de défaillance le plus courant dans l'adoption IA brownfield : les équipes voient des démos de l'Échelon 5 sur des dépôts greenfield et supposent que le modèle fonctionnel se transpose. Ce ne sera pas le cas tant que le harnais n'est pas construit.
La Grille de maturité du code (Codebase Readiness Grid)
Neuf dimensions. Chacune répond à une question. Notez chaque dimension de 1 à 5. Le score le plus bas est le plafond du niveau de maturité auquel vous pouvez opérer de façon fiable ; votre dimension la plus faible est là où les agents échoueront en premier.
La Grille de maturité du code, sous forme de compétence Claude Code. Fonctionne sur n'importe quel dépôt, collecte des signaux par dimension, produit un tableau de bord avec une recommandation de chemin vers le Niveau 5. Open source, licence MIT.
| # | Dimension | Type | Question à laquelle elle répond | Barème (1 à 5) |
|---|---|---|---|---|
| 1 | Couverture de tests et latence de rétroaction | bloquante | Y a-t-il une couverture significative sur les chemins de code qui changent le plus souvent ? Quelle est la vitesse de l'IC ? | 1 = pas de tests ou tests morts. 2 = faible couverture, IC lente. 3 = couverture significative sur les chemins chauds, IC sous 30 min. 4 = seuil appliqué, IC sous 5 min, les échecs se localisent. 5 = scénarios comportementaux sur les chemins critiques, IC rapide et verte comme porte de déploiement. |
| 2 | Rigueur des types | bloquante | Les types sont-ils appliqués à la compilation ? any est-il rare ou omniprésent ? | 1 = non typé ou types désactivés. 2 = types optionnels, any partout. 3 = types appliqués, quelques échappatoires. 4 = mode strict activé, any rare et justifié. 5 = mode strict en IC, zéro any, contrats à chaque frontière. |
| 3 | Taille des fichiers et lisibilité du contexte | contraignante | Un agent peut-il raisonner sur un fichier sans charger tout le reste du système ? | 1 = fichiers dieux (2000+ lignes), responsabilités mélangées. 2 = nombreux fichiers de 1000+ lignes, enchevêtrés. 3 = la plupart des fichiers sous 500 lignes, quelques cas extrêmes. 4 = la plupart sous 300 lignes, exceptions rares et justifiées. 5 = chaque fichier dimensionné à une responsabilité. |
| 4 | Clarté des frontières de modules | contraignante | Un nouvel ingénieur (ou un agent) peut-il décrire le graphe de modules après 30 minutes ? Les frontières sont-elles appliquées ? | 1 = pas de structure modulaire. 2 = structure sur le papier, violée en pratique. 3 = modules de haut niveau clairs, fuites occasionnelles. 4 = frontières appliquées, contrats stables. 5 = le graphe de modules est une carte navigable; architecture documentée et à jour. |
| 5 | Directness des API | bloquante | L'appel HTTP/RPC est-il visible au site d'appel, ou caché derrière des couches d'abstraction ? | 1 = accès via des abstractions opaques (Factory, dispatch dynamique, ORM avec requêtes invisibles). 2 = abstraction significative, traçable avec effort. 3 = mélange de direct et d'abstrait. 4 = appels principalement directs avec réponses typées. 5 = les sites d'appel montrent ce qui se passe; pas d'opérations réseau ou base de données cachées. |
| 6 | Intention documentée | contraignante | Le pourquoi est-il documenté séparément du comment ? Les décisions d'architecture sont-elles consignées ? | 1 = pas de docs d'intention; le code est la seule vérité. 2 = docs éparpillées, souvent obsolètes. 3 = READMEs de modules, quelques ADR. 4 = journal d'ADR à jour, modules critiques documentés, CLAUDE.md / AGENTS.md en place. 5 = chaque décision non triviale a une spec ou un ADR; contexte historique préservé. |
| 7 | Observabilité | contraignante | Peut-on dire ce que le système a fait pour une requête donnée ? Les défaillances produisent-elles des cas de test reproductibles ? | 1 = pas de logs structurés, pas de traces, pas de métriques, pas de suivi d'erreurs. 2 = quelques logs, pas de traçage. 3 = logs structurés et métriques de base; suivi d'erreurs en place. 4 = télémétrie complète avec accès aux requêtes. 5 = production entièrement observable; les erreurs produisent des cas de test reproductibles. |
| 8 | Simplicité du développement et du déploiement | contraignante | Peut-on configurer l'environnement de développement en une commande ? Déployer en une (ou automatiquement) ? | 1 = la mise en place du développement prend des jours ou un savoir tribal; déploiements manuels et fragiles. 2 = scripté mais fragile; déploiements nécessitent un runbook. 3 = commandes documentées, déploiement fiable. 4 = mise en place en une commande; déploiement en une commande (ou automatique). 5 = développement, IC, production architecturalement identiques. |
| 9 | Actualité des dépendances et du runtime | contraignante | Le runtime est-il supporté ? Les frameworks sont-ils à 1 à 2 versions majeures du courant ? Des bibliothèques abandonnées ? | 1 = runtime en fin de vie, framework 2+ versions majeures derrière, bibliothèques abandonnées, paradigmes mélangés. 2 = runtime courant mais nombreuses dépendances 1+ versions majeures derrière. 3 = runtime courant, la plupart des dépendances à 1 version majeure, patron legacy occasionnel documenté. 4 = paradigmes modernes cohérents. 5 = hygiène de dépendances agressive; conventions alignées sur les standards actuels de la communauté. |
Notes sur les dimensions moins évidentes. D1 : l'IC lente est le déficit brownfield le plus courant : une suite de tests de 72 heures n'est pas un capteur, c'est un rapport. D3 : les petits fichiers ne sont pas une préférence de style, c'est une discipline de fenêtre de contexte; un agent qui a besoin de trois fichiers pour comprendre une fonction hallucine les parties manquantes. D5 : les abstractions opaques ne font pas que cacher des détails, elles produisent du code confidemment erroné quand l'agent devine ce que UserFactory.resolve() fait. D6 : le code se documente lui-même; l'intention ne se documente pas. C'est le déficit le plus difficile à réparer rapidement. D9 : les agents sont entraînés sur les versions et idiomes courants des bibliothèques; une base de code utilisant des patrons vieux de 2 à 3 ans reçoit du code qui contredit ses propres conventions.
Comment fonctionne le barème
Quatre règles régissent la lecture du tableau de bord. Elles se combinent : les quatre s'appliquent simultanément.
1. Le plafond est le score le plus bas. Votre dimension la plus faible fixe votre niveau de maturité. Une base de code avec huit 5 et un 1 est au Niveau 0, pas au Niveau 4. Les agents échouent au maillon le plus faible.
2. Trois dimensions sont bloquantes; six sont contraignantes.
- Bloquantes (D1, D2, D5) : un faible score compromet fondamentalement le travail des agents. Sans tests, les agents sont aveugles. Sans types, ils hallucinent des formes. Avec des API opaques, ils produisent du code confidemment erroné. Ces dimensions ne peuvent pas être compensées par de bons scores ailleurs.
- Contraignantes (D3, D4, D6, D7, D8, D9) : un faible score dégrade la qualité mais les agents peuvent encore produire de la valeur. Plus de révision humaine par changement, plus de nettoyage, plus de friction.
Quand deux dimensions sont à égalité à un faible score, relevez d'abord la bloquante. La règle de plafond s'applique toujours; cette classification affine seulement la priorité de remédiation.
3. Crédit de report : un report intentionnel et documenté vaut un niveau de plus que le même écart non documenté. Si l'observabilité n'est pas câblée, mais que la spécification du projet reporte cette décision à une phase GA-Prêt avec une date et des critères, notez-la 2 au lieu de 1. Le report est une décision; un écart inattentif ne l'est pas. Les affirmations verbales ne comptent pas : le report doit figurer dans le dépôt.
4. Ne résumez jamais le tableau de bord avec une moyenne. Le tableau de bord est un vecteur, pas un scalaire. Deux bases de code avec une moyenne de 3,0 peuvent être dans des situations radicalement différentes : l'une avec D1 à 1 est aveugle; l'autre avec D7 à 1 est opérationnellement immature mais utilisable. Les moyennes cachent cette distinction.
Le tableau de bord est un instantané. Relancez-le chaque trimestre : les bases de code évoluent dans les deux sens.
À quoi ressemble une base de code de Niveau 5
Une référence concrète, généralisée à partir de patrons observés. Une base de code qui obtient 5 dans les neuf dimensions tend à partager ces traits :
- Spécification-d'abord pour le travail non trivial. Contrats API vérifiés, scénarios d'acceptation définis, décisions documentées avant le code.
- Typage strict appliqué à la compilation. Zéro
any. Les violations de types font échouer l'IC. - Fichiers petits et focalisés. La plupart sous quelques centaines de lignes. Les plus grands sont des exceptions intentionnelles, pas des accumulations accidentelles.
- Accès direct aux API et aux données. Les sites d'appel montrent ce qui est appelé. Pas de factories opaques, pas de dispatchers génériques.
- Dépendances minimales. Peu de paquets, chacun justifié.
- Conventions explicites. Structure de fichiers et nommage documentés. En-tête
ABOUTME:sur chaque fichier.AGENTS.mdouCLAUDE.mdavec les règles pour les agents. - Pas de savoir implicite. La base de code est lisible parce qu'elle dit ce qu'elle veut dire, pas parce que l'équipe s'en souvient.
- Tests comme contrats. Mocks simples, assertions comportementales, noms lisibles.
- Construction en une commande, déploiement en une commande. Pas de combat avec l'infrastructure pour livrer.
- Dépendances à jour, runtime supporté. Pas de runtimes en fin de vie, pas de bibliothèques abandonnées.
Ce ne sont pas des préférences de style. Ce sont les propriétés structurelles qui permettent aux agents de produire un travail fiable, et ce sont les mêmes propriétés qui rendent les humains productifs. Les deux ne sont pas séparés.
Stratégie de construction du harnais
Quand la maturité est inférieure à ce dont votre équipe a besoin pour travailler, séquencez l'investissement dans cet ordre. Sauter des étapes produit de la vitesse sans confiance.
Le harnais a deux parties : les capteurs (tests, IC, observabilité) vérifient la production des agents; les guides (types, conventions, docs d'architecture, intention documentée) spécifient ce qu'il faut produire. Les bases de code brownfield ont typiquement les guides mais manquent de capteurs : c'est la configuration qui livre du code confidemment erroné.
Étape 1 : installez d'abord les capteurs rapides. Tests utiles et IC rapide (latence de rétroaction sous 30 minutes est la porte d'entrée). Sans capteurs, chaque changement en aval est une supposition et on ne peut pas vérifier que le travail de harnais ultérieur porte ses fruits.
Étape 2 : rendez le code lisible. Nommage cohérent, types appliqués, frontières de modules claires, préoccupations transversales centralisées, suppression des chemins morts. La lisibilité est ce qui permet aux agents de travailler entre modules sans halluciner une structure.
Étape 3 : capturez l'intention. Documentez les décisions d'architecture. Déclarez les contrats comportementaux aux frontières d'interface. Pour les modules les plus critiques, extrayez la spécification implicite : les milliers de décisions qui se sont accumulées au fil des années de correctifs. Les agents peuvent documenter ce que le système fait; distinguer le comportement intentionnel de l'accident historique reste une tâche humaine. Voir la séquence brownfield du Lab IA pour la version disciplinée.
Étape 4 : gouvernez avec des scénarios. Convertissez l'intention en scénarios de bout en bout. Les scénarios sont plus difficiles à contourner pour les agents que les tests unitaires. Le mode de travail de l'Échelon 5 devient viable à ce stade.
Patrons de Paul Duvall AI Development Patterns qui s'inscrivent dans cette séquence : Readiness Assessment (Foundation), Observable Development, Guided Refactoring.
Que faire quand le score est bas
Quatre modes s'appliquent, couverts en détail dans la Stratégie brownfield : remédier sur place, migration strangler-fig, reconstruction complète, ou isoler et contourner. Le bon mode dépend de la solidité architecturale de la base de code, de la disponibilité de coutures et de la valeur métier résiduelle, pas de la capacité de l'équipe ou des priorités stratégiques, qui se situent en dehors de cette évaluation.
Miroir : maturité et non-fiabilité
L'ingénierie de la fiabilité traite de la production IA comme intrant pour les systèmes. La maturité du code traite l'inverse : la base de code comme intrant pour les agents IA. Même incertitude, reflétée.
En lien
- Stratégie brownfield : les quatre modes pour les bases de code à faible maturité
- Le Lab IA : le mode de travail de l'Échelon 5 qu'une base de code de Niveau 5 supporte
- L'ingénierie de la fiabilité : le problème miroir
- Standards d'exécution IA et Guide de spécification : l'ingénierie de spécification
Sources
- Mahiou et al. (2026). « AI Codebase Maturity Model (ACMM). » arXiv. arxiv.org/abs/2604.09388
- Fowler, M. (2026). « Harness Engineering for Coding Agent Users. » martinfowler.com
- Duvall, P. (2026). « AI Development Patterns. » github.com/PaulDuvall/ai-development-patterns
- Google Cloud (2025). « DORA 2025 State of AI-assisted Software Development. » dora.dev
- « A Maturity Model for AI-Native Development. » (2025). Transcode. blog.transcode.be
- « The State of Generative AI in Software Development. » (2026). arXiv. arxiv.org/abs/2603.16975
← Retour à l'accueil · Stratégie brownfield · Le Lab IA · L'ingénierie de la fiabilité · Glossaire