Détection du drift d'architecture : gardez votre code aligné avec le design
Quelque part dans votre organisation, il y a un diagramme d'architecture qui est faux. Peut-être qu'il montre un microservice qui a été fusionné dans un autre il y a six mois. Peut-être qu'il liste Redis comme couche de cache alors que l'équipe est passée à Memcached lors d'un incident de production. Peut-être qu'il décrit une architecture hexagonale propre dans un service qui a accumulé suffisamment de raccourcis et de contournements pour ressembler à du spaghetti.
C'est le drift d'architecture : la divergence graduelle et silencieuse entre la documentation de votre système et son fonctionnement réel. Contrairement aux bugs, le drift ne déclenche pas d'alertes. Contrairement aux régressions de performance, il n'apparaît pas dans le monitoring. Il reste tranquillement en place jusqu'à ce que quelqu'un prenne une décision basée sur une documentation obsolète -- et que cette décision s'avère être fausse.
Le drift d'architecture est universel. Chaque équipe en fait l'expérience. La question n'est pas de savoir si votre documentation va dériver, mais à quelle vitesse vous le détecterez et ce que vous ferez à ce sujet.
Les conseils ne manquent pas sur la seconde moitié de cette question. Gardez les docs à côté du code. Relisez-les dans la même pull request. Faites-en une partie de la definition of done. Ce sont de bons conseils, on en retrouve la plupart plus bas dans cette page, et ils partagent tous le même angle mort : ils vous disent quoi faire, pas si ça a fonctionné. Ce qui ressemble le plus à une vérification dans les recommandations courantes, c'est une date de dernière modification, qui vous dit quand quelqu'un a touché le fichier plutôt que si le fichier dit vrai.
Détecter le drift, c'est la moitié qu'on saute. Ce guide couvre le problème, les cinq familles de méthodes de détection, et ce que chacune peut voir ou ne peut pas voir. Deux articles compagnons approfondissent chacun un point : comment un score de drift est calculé et ce que ce chiffre signifie, et les pratiques qui gardent un modèle juste une fois que vous en avez un.
Qu'est-ce que le drift d'architecture ?
Le drift d'architecture survient quand l'implémentation réelle d'un système logiciel diverge de son architecture documentée ou prévue. Perry et Wolf ont nommé le problème dans Foundations for the Study of Software Architecture (ACM SIGSOFT Software Engineering Notes, 1992), où ils distinguaient l'erosion (érosion), qui provient de la violation de l'architecture, du drift, qui provient de l'insensibilité à celle-ci. L'usage courant a évolué depuis : la plupart des ingénieurs disent aujourd'hui "drift" pour tout écart entre la documentation et le code, et c'est dans ce sens que ce guide l'emploie. La distinction mérite d'être conservée, et une section y est consacrée plus bas.
Le drift se manifeste à tous les niveaux de la documentation architecturale :
Drift structurel
La structure documentée ne correspond plus à la codebase :
- Un service documenté comme un container autonome a été absorbé dans un monolithe
- Un component a été renommé mais le diagramme montre toujours l'ancien nom
- Un nouveau service a été créé mais jamais ajouté au modèle d'architecture
- Une base de données a été migrée de MySQL à PostgreSQL mais le diagramme de containers dit toujours MySQL
Drift comportemental
Le comportement documenté ne correspond plus à la réalité :
- Un appel API synchrone a été remplacé par un message asynchrone, mais la relation dit toujours "REST/HTTP"
- Un flux de données a été modifié pour passer par un API gateway, mais le diagramme montre une communication directe service-à-service
- Une étape d'authentification a été ajoutée qui n'est pas reflétée dans le diagramme de contexte système
Drift de dépendances
Les dépendances documentées ne correspondent plus aux intégrations réelles :
- Une API tierce a été remplacée par une solution interne
- Une nouvelle dépendance externe a été ajoutée (fournisseur de paiement, service de monitoring) mais pas documentée
- Une intégration a été décommissionnée mais apparaît toujours dans le diagramme de contexte système
Drift de décisions
Les décisions architecturales documentées ne sont plus suivies :
- Un ADR dit "utiliser PostgreSQL pour tout le stockage persistant" mais une équipe a commencé à utiliser MongoDB
- Les règles de conformité disent "pas d'accès direct à la base de données depuis le frontend" mais quelqu'un a ajouté une intégration Supabase côté client
- L'architecture de déploiement dit "région unique" mais des services ont été déployés dans plusieurs régions
Pourquoi le drift d'architecture se produit
Comprendre les causes du drift est essentiel pour le prévenir. Le drift n'est généralement ni malveillant ni même négligent -- c'est une conséquence naturelle de la façon dont le logiciel est développé.
La vitesse avant la documentation
Quand il faut livrer une feature pour vendredi, mettre à jour le diagramme d'architecture est la première chose qui saute. Le changement de code est le livrable. La mise à jour de documentation est du overhead. C'est un comportement rationnel à court terme et dévastateur à long terme.
De nombreux petits changements
Le drift survient rarement en un moment dramatique. Il s'accumule à travers des centaines de petits changements, chacun trop mineur pour justifier une mise à jour de documentation :
- Renommer un fichier
- Ajouter un package utilitaire
- Changer une dépendance de bibliothèque
- Extraire une fonction dans un module séparé
Aucun changement individuel n'est suffisamment significatif pour déclencher une mise à jour de documentation. Ensemble, ils transforment l'architecture.
Turnover de l'équipe
Quand les ingénieurs partent, ils emportent le savoir implicite avec eux. La nouvelle équipe hérite de la codebase mais pas de la compréhension de pourquoi elle est structurée ainsi. Ils font des changements basés sur ce qu'ils voient dans le code, pas sur ce que dit la documentation, élargissant le drift.
Absence de boucles de feedback
Si personne ne vérifie si la documentation correspond à la réalité, le drift est invisible. Sans mécanisme de détection, la seule façon de découvrir le drift est pendant un incident, un audit, ou quand un nouvel ingénieur fait remarquer que le diagramme ne correspond pas au code. À ce stade, le drift peut être considérable.
Changements d'urgence
Les incidents de production nécessitent souvent des raccourcis architecturaux : une connexion directe à la base de données au lieu de passer par la couche API, une configuration codée en dur au lieu d'utiliser le service de config, un cache temporaire qui devient permanent. Ces changements contournent les processus normaux de revue et sont rarement documentés.
Le coût du drift d'architecture
Le drift n'est pas juste un problème esthétique. Il a des coûts concrets et mesurables.
Mauvaises décisions
Quand les architectes prennent des décisions basées sur une documentation obsolète, ces décisions peuvent être fausses. "Ce service a peu de trafic, donc on peut se permettre une dépendance synchrone" -- sauf que la documentation est obsolète et que le service gère en réalité 10x la charge documentée.
Onboarding lent
Les nouveaux ingénieurs s'appuient sur la documentation d'architecture pour construire leur modèle mental. Si la documentation est fausse, ils construisent des modèles mentaux faux. Ils écrivent du code qui ne correspond pas à l'architecture réelle. Ils posent des questions qui révèlent leur confusion, consommant le temps des ingénieurs seniors.
Réponse aux incidents
Pendant un incident de production, les diagrammes d'architecture devraient aider les équipes à comprendre le rayon d'impact et les dépendances. Si ces diagrammes sont faux, les équipes perdent des minutes précieuses à tracer les mauvaises chaînes de dépendances ou à manquer des systèmes amont critiques.
Échecs de conformité et d'audit
Dans les industries réglementées, la documentation d'architecture est souvent requise pour la conformité (SOC 2, ISO 27001, HIPAA). Si les auditeurs trouvent que la documentation ne correspond pas à la réalité, c'est une constatation -- potentiellement sérieuse.
Confusion des agents IA
À mesure que les agents de codage IA deviennent plus répandus, ils s'appuient de plus en plus sur la documentation d'architecture pour le contexte. Un agent qui lit un modèle C4 obsolète générera du code qui correspond à l'architecture documentée, pas à la réelle. Cela amplifie le drift au lieu de le corriger.
Comment détecter le drift d'architecture
Cinq approches sont couramment utilisées, et elles répondent à des questions différentes. La revue manuelle demande si le diagramme semble encore juste aux personnes présentes dans la pièce. Les fonctions de fitness et l'analyse statique demandent si des règles précises sont enfreintes. L'évaluation par LLM demande si le code se lit comme le design qu'il prétend implémenter. Le scoring de drift demande quelle part du modèle documenté existe encore. Choisissez en fonction de la question qui vous coûte le plus cher.
Revue manuelle (approche traditionnelle)
L'approche la plus simple est la revue manuelle périodique : réunissez l'équipe, parcourez les diagrammes d'architecture, et vérifiez s'ils correspondent encore à la réalité.
Quand ça fonctionne : Petites équipes, architectures simples, cadence trimestrielle.
Quand ça échoue : Systèmes larges, équipes qui avancent vite, ou quand les personnes qui connaissent le mieux le code n'ont pas le temps pour des réunions de revue. La revue manuelle souffre aussi du biais de confirmation -- les gens ont tendance à voir ce qu'ils s'attendent à voir.
Fonctions de fitness d'architecture
Les fonctions de fitness, popularisées par Neal Ford et le livre "Building Evolutionary Architectures", sont des tests automatisés qui valident les propriétés architecturales :
// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
packages := analyzeImports("./internal/handler/...")
for _, pkg := range packages {
for _, imp := range pkg.Imports {
assert.NotContains(t, imp, "database/sql",
"Handler %s imports database/sql directly", pkg.Name)
assert.NotContains(t, imp, "gorm.io",
"Handler %s imports GORM directly", pkg.Name)
}
}
}
Les fonctions de fitness sont puissantes pour appliquer des règles spécifiques, mais elles nécessitent un effort initial pour les écrire et les maintenir. Elles vérifient des contraintes, pas le modèle complet.
Outils d'analyse statique
Des outils comme ArchUnit (Java), Deptrac (PHP) et go-arch-lint (Go) analysent la structure du code et appliquent des règles de dépendances :
// go-arch-lint configuration
components:
handler:
in: ./internal/handler/
service:
in: ./internal/service/
repository:
in: ./internal/repository/
rules:
handler:
can_depend_on: [service]
service:
can_depend_on: [repository]
repository:
can_depend_on: []
Ces outils sont excellents pour appliquer une architecture en couches au sein d'une seule codebase. Ils n'adressent pas le drift inter-services ni ne valident que le modèle d'architecture correspond au code.
Évaluation assistée par LLM
Thoughtworks a placé la réduction du drift d'architecture avec les LLM dans l'anneau Assess du Technology Radar Vol. 34 (avril 2026). Leur formulation du problème mérite d'être citée, parce qu'elle ne vient pas d'un éditeur de logiciel :
Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.
En français : l'usage croissant des agents de codage IA peut accélérer le drift par rapport à la codebase et aux designs d'architecture prévus. Sans contrôle, ce drift s'aggrave à mesure que les agents et les humains reproduisent les patterns existants, y compris ceux qui sont dégradés, créant une boucle de rétroaction où du mauvais code engendre du code encore pire.
La technique qu'ils décrivent associe des outils d'analyse déterministes (ils citent Spectral, ArchUnit et Spring Modulith) à une évaluation par LLM, pour capter les violations sémantiques qu'un moteur de règles ne sait pas exprimer, puis utilise le LLM pour aider à corriger ce qu'il a trouvé. Leurs équipes l'ont appliquée aux guidelines de qualité d'API et à la définition de zones architecturales qui guident les changements générés par les agents.
Deux de leurs leçons méritent d'être reprises quel que soit l'outil que vous utilisez. Un premier scan remonte plus de violations que personne ne triera, donc la priorisation est le vrai travail. Et le correctif d'un agent a besoin de sa propre boucle de vérification, parce que "il a changé le code" et "il a amélioré le système" sont deux affirmations différentes.
Assess est l'anneau "à regarder, nous ne le recommandons pas encore" de Thoughtworks. Traitez-le comme tel. Ce qu'il tranche, c'est que le problème est assez réel pour qu'un grand cabinet de conseil le mette par écrit, ce qui est plus que ce que la plupart des argumentaires sur le drift peuvent invoquer.
Scoring automatisé du drift
C'est l'approche d'Archyl. Au lieu de vérifier des règles spécifiques, il valide l'ensemble du modèle d'architecture par rapport à la codebase :
- Chaque système documenté correspond-il à un dépôt ?
- Chaque container documenté correspond-il à un répertoire dans la codebase ?
- Chaque élément de code documenté référence-t-il un fichier qui existe toujours ?
- Les deux extrémités de chaque relation documentée sont-elles toujours valides ?
Le résultat est un score de 0 à 100 et un détail par élément de ce qui correspond, de ce qui est documenté mais a disparu, et de ce qui existe dans le code mais n'a jamais été écrit nulle part. Là où les fonctions de fitness vérifient les contraintes que vous avez pensé à écrire, ceci vérifie l'ensemble du modèle que vous avez déjà.
Les décisions clés de conception dans la détection de drift d'Archyl :
Léger. Aucun appel IA et aucun contenu de fichier récupéré. Une seule requête d'arbre récursive vers votre fournisseur Git, puis une correspondance de chemins et de noms avec le modèle. Le calcul prend quelques secondes.
Déterministe. Même codebase, même modèle, même score. Pas de variabilité liée à la température du LLM ou au prompt engineering.
Économique. Lancez-le à chaque push sans souci de coût. Une centaine de calculs par jour, pas de problème.
Actionnable. Le détail nomme les éléments qui ont dévié, vous savez donc quoi corriger.
Le compromis est dans le premier point. Vérifier des chemins et des noms plutôt que lire le code rend le score rapide, gratuit et reproductible, et cela veut dire que la vérification est structurelle. Elle voit un container dont le répertoire a disparu et un élément de code dont le fichier a été supprimé. Elle ne voit pas l'appel REST devenu message de queue alors que les deux services ont gardé leurs noms. C'est le drift comportemental, le seul type de la taxonomie en haut de ce guide qu'aucune vérification bon marché ne capte. La revue manuelle et l'évaluation par LLM sont ce dont vous disposez pour cela.
Comment le score de drift est calculé, en détail couvre la formule, ce qui est exclu du dénominateur et pourquoi, ainsi que le reste des limites.
Fermer la boucle
La détection seule ne change rien. Un score que quelqu'un calcule une fois et regarde est un audit, pas une boucle de feedback. Trois mécanismes en font une, plus une distinction qu'il vaut mieux poser correctement avant de brancher quoi que ce soit. Les pratiques de workflow qui les accompagnent, l'architecture as code, la documentation dans la definition of done, l'adoption de règles de conformité, font l'objet de la documentation d'architecture vivante.
Automatiser la détection de drift dans la CI
Le mécanisme qui a le plus de mordant est une porte CI qui échoue quand le drift dépasse un seuil, parce que c'est le seul qui arrête un merge :
on:
push:
branches: [main]
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: archyl-com/actions/drift-score@v1
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
organization-id: ${{ secrets.ARCHYL_ORG_ID }}
project-id: 'your-project-uuid'
threshold: '70'
Quand le build échoue parce que le score de drift a chuté, quelqu'un doit le corriger avant de merger. La précision de la documentation devient aussi non-négociable que les tests qui passent.
Fixez le seuil en dessous de votre score actuel, pas au chiffre que vous aimeriez avoir. Une porte qui échoue dès la première exécution est désactivée dès la première exécution. Relevez-la à mesure que l'équipe construit l'habitude.
Mettre en place des alertes de drift
Archyl supporte les alertes webhook pour les événements de drift :
drift.score_computed: Se déclenche à chaque calcul de drift. Postez dans un canal Slack pour la visibilité.drift.score_degraded: Se déclenche quand le score chute de 10+ points. C'est votre système d'alerte précoce.
Configurez ces alertes vers un canal que votre équipe surveille. La prise de conscience est la première étape vers l'action.
Conduire des revues d'architecture
Les revues d'architecture mensuelles ou trimestrielles servent plusieurs objectifs :
- Valider que l'architecture documentée correspond toujours à la réalité
- Identifier le drift que les outils automatisés ont manqué (le drift comportemental, par exemple)
- Discuter de si les components qui ont dévié doivent être mis à jour dans le code ou dans la documentation
- Revoir et mettre à jour les ADR pour les décisions qui pourraient nécessiter d'être reconsidérées
Ne confondez pas drift et conformité
On les lance ensemble assez souvent pour que ça vaille la peine de les séparer, parce qu'ils sont calculés différemment et qu'ils échouent pour des raisons différentes.
La détection de drift demande si votre modèle correspond à la réalité. Elle compare l'architecture documentée au dépôt et produit un score.
Les règles de conformité demandent si la réalité suit vos règles : le container frontend ne doit pas dépendre du container de base de données, toute API publique passe par la gateway, chaque service possède sa propre base de données. Une vérification de conformité peut passer sur un modèle qui a fortement dérivé, et un modèle parfaitement exact peut violer toutes les règles que vous avez.
Vous voulez les deux, et vous ne devriez pas lire l'un des deux chiffres comme s'il était l'autre.
Drift d'architecture vs. érosion d'architecture
Ces termes sont liés mais distincts :
Le drift d'architecture est la divergence entre documentation et implémentation. Le code peut être parfaitement correct -- la documentation est juste fausse.
L'érosion d'architecture est la dégradation de l'architecture elle-même. Le code viole les principes architecturaux, accumule la dette technique, et devient plus difficile à maintenir. L'érosion est un problème de qualité de code. Le drift est un problème de précision de documentation.
Perry et Wolf traçaient la ligne à un autre endroit en 1992 : pour eux, les deux étaient des propriétés du système plutôt que de la documentation, l'érosion étant causée par la violation de l'architecture et le drift par l'insensibilité à celle-ci. L'usage moderne est plus lâche et plus utile à une équipe qui travaille, mais si vous lisez la littérature académique sur l'érosion d'architecture, attendez-vous à ce que les termes s'y positionnent différemment d'ici.
Ils coexistent souvent. Quand la documentation dérive, les équipes perdent la conscience de l'architecture prévue. Sans cette conscience, elles font des changements qui érodent l'architecture. Le drift permet l'érosion.
C'est pourquoi la détection de drift compte au-delà de la simple précision de documentation. Une documentation précise sert de référence qui prévient l'érosion. Quand tout le monde peut voir l'architecture prévue, ils sont plus enclins à la maintenir.
Mesurer et suivre le drift dans le temps
Un score de drift unique est utile. Une tendance est puissante.
Établir une ligne de base
Lancez le premier calcul avant de changer quoi que ce soit à la façon dont l'équipe travaille. Ce qu'il renvoie est votre ligne de base, et un premier chiffre bas est une information plutôt qu'un verdict. Une documentation que personne n'a jamais été chargé de maintenir n'a pas échoué ; elle n'a simplement jamais été mesurée.
Résistez à l'envie de corriger des choses avant la première exécution. Vous voulez le chiffre qui décrit la situation dans laquelle vous êtes réellement, pas celui que vous obtenez après un week-end de nettoyage.
Suivre la tendance
Un score isolé est un fait sur aujourd'hui. La tendance, c'est ce qui vous dit si ce que vous avez changé a fonctionné :
- Le drift s'améliore-t-il ou s'aggrave-t-il dans le temps ?
- Un sprint ou une release spécifique a-t-il causé une chute ?
- Le seuil CI tient-il la ligne, ou est-ce que tout le monde l'abaisse ?
Archyl stocke chaque calcul avec son détail complet, de sorte qu'un rapport historique peut être rouvert et comparé élément par élément. Quel que soit l'outil que vous utilisez, gardez l'historique. Un score de drift que vous recalculez de zéro chaque trimestre puis jetez est de nouveau un audit.
Fixer un objectif que vous pouvez réellement tenir
Choisissez le chiffre suivant plutôt que le chiffre idéal. Si aujourd'hui c'est 58, l'objectif utile est 65 et la conversation utile porte sur les cinq éléments qui vous y amènent. Une équipe qui s'engage à atteindre 90 % d'ici la fin du trimestre ne s'engage généralement à rien.
Le rôle de la détection de drift dans le développement assisté par IA
C'est la partie qui a le plus changé récemment, et c'est pourquoi Thoughtworks a écrit l'entrée citée plus haut : les agents reproduisent les patterns qu'ils trouvent, y compris les dégradés, donc le drift qui s'accumulait autrefois à la vitesse des commits humains s'accumule maintenant à la vitesse des commits générés.
Les agents IA s'appuient de plus en plus sur la documentation d'architecture pour le contexte. Via des protocoles comme MCP, les agents peuvent lire votre modèle C4, vos ADR et vos règles de conformité avant de générer du code. Cela les rend plus efficaces -- ils génèrent du code qui correspond à votre architecture au lieu de deviner.
Mais ça ne fonctionne que si la documentation est précise. Un agent qui lit un modèle C4 obsolète et génère du code basé dessus produira du code qui correspond à la mauvaise architecture. L'agent amplifie le drift au lieu de le prévenir.
La détection de drift crée la boucle de feedback qui garde les agents IA honnêtes :
- L'agent lit l'architecture via MCP
- L'agent génère du code qui correspond à l'architecture documentée
- Le code est mergé, changeant potentiellement l'architecture réelle
- La détection de drift s'exécute et capte toute divergence
- La porte CI échoue si le drift dépasse le seuil
- L'équipe met à jour la documentation pour refléter la réalité
- L'agent lit l'architecture mise à jour -- la boucle se ferme
Sans l'étape 4, la boucle est ouverte. La documentation devient de plus en plus fictive. Les agents génèrent de plus en plus du code qui correspond à une architecture imaginaire. L'écart se creuse à chaque commit.
La détection de drift est le mécanisme qui ferme cette boucle.
Commencer avec la détection de drift
Si vous avez déjà un modèle quelque part
Mesurez-le avant de changer quoi que ce soit d'autre. C'est le premier geste le moins coûteux qui existe et il ne vous engage à rien.
Si votre architecture vit déjà dans du Structurizr DSL, LikeC4, IcePanel ou un catalogue Backstage, importez ce modèle et calculez un score dessus, tel quel. Vous mesurez la documentation que vous avez déjà écrite, dans l'état où vous l'avez laissée. Pas de changement de workflow, pas de nouvelle habitude pour l'équipe, pas encore de décision sur l'outillage. Le chiffre est l'entrée de cette décision, pas son résultat.
Deux réserves honnêtes. Les importeurs ne sont pas sans perte : les vues, les styles et le layout ne survivent pas, et le parser Structurizr ignore les environnements et les nœuds de déploiement, mais il les nomme avec leur numéro de ligne dans sa liste d'avertissements, donc relisez cette liste et le modèle importé avant de faire confiance au dénominateur. Et le score décrit le modèle qui est arrivé, pas le fichier que vous avez exporté.
Ce qui revient est une liste par élément. Un score de 84 est un problème de maintenance que vous pouvez planifier. Un score de 41 signifie que des décisions ont été prises sur la base d'un document qui décrit un autre système, et il vaut mieux l'apprendre maintenant que pendant le prochain incident.
Si vous n'avez pas de documentation d'architecture
Commencez avec la découverte IA. Connectez un dépôt, laissez la découverte proposer le modèle C4, et approuvez ou rejetez ce qu'elle suggère plutôt que de le dessiner. Une fois qu'il y a un modèle, la détection de drift est ce qui le maintient honnête.
Si vous suivez déjà le drift
Mettez-la dans la CI. Fixez un seuil en dessous de votre score actuel. Configurez l'alerte de dégradation. Faites du drift une métrique que l'équipe voit chaque semaine, pas un chiffre qu'une personne calcule avant une revue.
Peu importe d'où vous partez
Le drift s'accumule comme la dette technique : plus vous le laissez, plus il y en a à réconcilier, et moins quelqu'un fait confiance au document entre-temps. La différence, c'est que vous pouvez savoir où vous en êtes aujourd'hui sans rien corriger d'abord.
Votre documentation d'architecture reflète soit la réalité, soit elle ne la reflète pas. L'intérêt d'un score de drift, c'est que vous n'avez plus à deviner laquelle des deux.
Pour aller plus loin : comment le score de drift est calculé pour le mécanisme, la documentation d'architecture vivante pour les pratiques qui gardent un modèle juste, et qu'est-ce que le modèle C4 si vous partez de zéro. Définitions : l'architecture drift, la documentation vivante, et la détection de drift dans le produit. Le plan Developer est gratuit et ne demande pas de carte, si vous voulez mettre un chiffre sur la documentation que vous avez déjà : archyl.com.