ADR : de la documentation bureaucratique à la décision éclairante
Publié le 2026-06-19 par DarkChyper
Cet article est lié à celui sur le DevLille 2026. Le sujet des ADR étant assez intéressant (je pense m'y mettre) et dense, je voulais le mettre en avant dans un article à part.
J'attendais beaucoup de cette conférence du vendredi 12 juin 2026 et je n'ai pas été déçu.
En l'état de l'art, les ADR, cela ne donne pas envie. Souvent considéré comme de la paperasse, une contrainte rédactionnelle supplémentaire avant de se lancer dans le code et qui a le défaut d'être immuable (comme les variables en Rust).
Nicolas Delsaux et Logan Hauspie nous ont fait la démonstration, et l'explication, de leur façon de créer des ADR pour leurs projets. Un talk très inspirant qui redonne de l'intérêt à cette pratique.
Pourquoi créer des ADR ?
- Tracer toutes les décisions pour la postérité
- Justifier les choix auprès des architectes et de la direction
- Améliorer l'onboarding des nouveaux arrivants, moins de risque de "bus factor"
- Valider les choix techniques avant leur mise en œuvre
- Créer une source de vérité unique
Article wikipedia du "Bus Factor"
Les outils d'aide à la décision
Avant de rentrer concrètement dans la création d'un ADR, ils ont exposé 2 outils ou concepts clefs : le "modèle ACED" et Cynefin (/kəˈnɛvɪn/).
Le modèle ACED (Architecture, Context, Engineering, Design) est une matrice de réflexion qui divise un système en quatre quadrants en croisant la question du Pourquoi / Comment avec la dimension Technique / Fonctionnelle. On y retrouve le Contexte (Pourquoi métier), l'Architecture (Pourquoi technique), le Design (Comment métier) et l'Ingénierie (Comment technique). Appliqué à la rédaction des ADR, ce modèle évite l'écueil classique de ne documenter que les détails d'implémentation (le "Comment technique"). Il rappelle à l'équipe que pour qu'une décision soit pertinente et comprise dans le temps, elle doit impérativement capturer les enjeux et les contraintes fonctionnelles qui l'ont motivée.
Site EN expliquant en détail le modèle ACED
Pour aller plus loin, le framework Cynefin vient parfaitement s'ajouter à l'arsenal de l'ADR en jouant le rôle de boussole décisionnelle. Comme l'illustre le schéma, il permet de catégoriser le contexte du problème selon quatre domaines principaux (Clair (ou simple), Compliqué, Complexe, Chaotique) autour d'une zone de Désordre. Utiliser ce quadrant dans un ADR est un moyen redoutable de justifier l'approche choisie par rapport au niveau d'incertitude. Par exemple, si la situation est jugée "Compliquée", l'ADR s'appuiera sur l'analyse d'experts pour justifier une "bonne pratique" (Sense-Analyze-Respond). À l'inverse, face à un contexte "Complexe", l'équipe pourra légitimer un choix technique beaucoup plus expérimental visant à tester le terrain (Probe-Sense-Respond). En intégrant Cynefin, l'ADR ne documente plus seulement une solution technique, mais capture fidèlement l'état d'esprit et l'environnement cognitif de l'équipe au moment où la décision a été prise.
Conception d'un ADR
La conception d'un ADR doit se voir comme une frise chronologique en 7 étapes à dérouler, avec la possibilité de revenir en arrière lorsque certaines étapes viennent à en ajuster d'autres, notamment le contexte. Voici ces 7 étapes :
Poser la question
Cette question est souvent le titre final de l'ADR, on vient clairement poser la question de ce que l'on veut prendre comme décision.
L'exemple donné pendant le talk était : "Comment stocker et exploiter des indicateurs de popularité de librairies ?"
Clarifier le contexte
Cette étape est assez centrale dans la rédaction de l'ADR. Elle va s'étoffer, se clarifier, s'ajuster petit à petit avec les étapes suivantes.
On retrouve les concepts suivants :
- Exigences fonctionnelles : on veut quoi ?
- Exigences non-fonctionnelles : comment on recherche dans les données, est-ce que l'on travaille avec des API ? ...
- Contraintes de l'écosystème : c'est pour quand ? Est-ce qu'il y a une contrainte légale ?
- Principes de l'équipe : DDD ? Enterprise Integration Pattern ? Je suis le seul dev sur le projet alors je ne veux pas avoir à gérer l'ops donc il me faut une base managée dans le cloud...
En plus des concepts précédents, elle reprend également les décisions précédentes (donc des ADR). On n'oublie pas qu'un ADR est immuable, donc si on veut prendre une nouvelle décision sur un point déjà tranché, on doit concevoir un nouvel ADR qui rend le précédent obsolète.
Explorer des alternatives
En se basant sur le contexte, on va utiliser la méthode de l'entonnoir pour retenir ou non les alternatives existantes. Pour chaque alternative, on déroule le contexte et on écarte celles qui ne correspondent pas à un des concepts, et on garde celles qui les valident tous.
Pendant le talk, ils ont parlé du fait qu'une alternative peut être de "ne rien faire", choisir qu'en tout état de cause, le sujet n'est pas à traiter. On crée alors l'ADR pour expliquer ce choix, le documenter afin que le futur de l'équipe sache pourquoi. Cela peut être justifié par l'absence d'alternative correspondant à notre contexte, ou par le fait que ne pas faire quelque chose coûtera moins cher que de le faire.
Étudier ces alternatives
Pour faire simple, discutez de ces alternatives entre corps de métier (devs, architectes...). C'est ici que des exigences nouvelles peuvent apparaître, venant mettre à jour notre contexte. On vient faire une boucle entre le contexte et les alternatives pour affiner les choix possibles.
Par exemple, on hésitait entre 3 alternatives de BDD : PostgreSQL, MongoDB et Google BigQuery. Le développeur à l'origine de la demande indique qu'il est seul sur ce projet, que les délais sont courts, donc il ne veut pas avoir à gérer la base de données. Il faut donc se tourner vers une base managée dans le cloud.
PostgreSQL et Mongo semblent ne plus être des alternatives viables... sauf qu'on peut les avoir chez Aiven.
Oui, mais Michel, l'architecte en chef, indique que dans l'entreprise on n'a pas de compte chez Aiven, mais on en a déjà un chez Google. Il ne reste donc plus que deux alternatives ; on n'oublie pas qu'on peut aussi ne pas avoir de BDD.
Converger vers la décision
Cette étape est un peu incluse dans la précédente si au final une seule alternative est possible. Si plusieurs choix s'offrent à vous, c'est l'étape où l'on tranche.
Écrire une décision claire
"On choisit BigQuery"
Non. L'écriture ne doit pas se limiter au simple choix. Ici, il est nécessaire de reprendre l'ensemble des critères et des discussions qui ont amené à cette décision. On synthétise tout cela dans un gros paragraphe, par exemple.
Se préparer aux conséquences
Choisir c'est renoncer.
Dans cette section, on vient lister les conséquences positives et négatives, avec plus de 3 points dans chaque section pour sortir des "évidences" de notre choix :
- Les opportunités qui s'ouvrent à nous
- Ce qui devient impossible
- Les impacts sur les coûts
- La dette contractée
On y met quoi dans cet ADR ?
- Un titre
- Des statuts : surtout le temps de la rédaction de celui-ci et, petite entorse à son immuabilité, un statut pour l'indiquer obsolète avec un lien vers l'ADR qui le remplace
- La décision : même si le cheminement a été long avant de statuer, et que vous allez mettre toutes les documentations créées tout au long de son écriture, dans la pratique il est plus judicieux d'avoir la réponse de suite plutôt que de se lire 25 pages
- Le contexte rédigé
- Les alternatives étudiées
- Les conséquences
On peut également y adjoindre tous les comptes rendus de réunions, les documentations ajoutées au débat... Je pense aussi aux participants, leur rôle et les dates de leur participation.
Bref, c'est un document très exhaustif qui justifie et acte les choix effectués pour un problème donné. On y gagne alors en transparence et en alignement des connaissances entre les équipes.
Où ranger ces ADR ?
Créer ces ADR, c'est bien, qu'ils soient disponibles, c'est mieux.
Que vous soyez une petite équipe ou une grande organisation, vu que ces ADR sont essentiellement du texte, je les rangerais dans un dépôt GIT. Il s'agit d'un choix judicieux car on ne modifie que rarement ses précédents commits une fois qu'ils sont sur le dépôt distant.
Pour les projets à un seul dépôt, les placer dans un sous-dossier au plus près du code semble une bonne idée. Pour les projets plus conséquents, adopter un dépôt autonome peut s'avérer plus pratique.
Après, un versionneur de code n'est pas nécessairement accessible à des personnes moins à l'aise avec la technique. Mais encore une fois, ces ADR étant principalement du texte (et peut-être des images, des graphiques, des liens...), rien n'empêche d'avoir une petite moulinette CI pour transformer ces ADR en un site statique sur votre intranet.
Mythes, réalité et onboarding
Dans leur présentation, les speakers indiquent qu'un ADR ne facilitera pas l'onboarding, prétextant qu'un projet qui vit depuis quelques années aura nécessairement un nombre d'ADR impossible à ingérer par un nouveau venu. Je ne suis pas vraiment d'accord avec ce point, mais je les rejoins sur le fait que ce n'est pas une documentation suffisante : il manque les guides de bonnes pratiques, les tutoriels, les guidelines...
Actuellement, je travaille sur un projet plutôt atypique, mêlant développement back-end (PHP et Go), front-end (Vue), du React pour faire tourner le front, de la configuration TLS et Nginx à la volée, l'utilisation de protocoles bas niveau gérés par des démons PHP, en "temps réel" (20 ms quand même), le tout sur un OS custom à base de Yocto Linux.
J'adore mon taff
Vu la configuration du projet et sa complexité, il y a forcément eu des choix de faits, dont certains ont été des erreurs, d'autres ont été complétés. Il y a eu des fonctionnalités mises en place puis retirées tout ou en partie du code (ou des échanges API/SSE), car devenues obsolètes par des choix correspondant à de nouveaux objectifs fonctionnels ou provenant de retours terrain non probants.
Aujourd'hui, cette connaissance est essentiellement dans la tête d'une personne. Et bien que celle-ci soit la plus disponible possible pour transmettre ses connaissances (merci :) ), cela ne remplacera pas des écrits concrets et exhaustifs sur ces décisions et revirements.
J'ajouterai que si ces documents sont suffisamment bien structurés et exhaustifs, l'utilisation d'outils IA (comme les notebooks) facilite grandement l'exploration de ces décisions en langage naturel, et cela même avec des modèles tournant localement. Et sans aller dans ce genre de technosolutionnisme, pour tenir une doc texte reprenant le minimum syndical (date, titre, décision, ADR précédent et fichier correspondant), un simple éditeur de texte suffit à faire un tri efficace. Ou, comme indiqué dans le point précédent, la création d'un site web statique accessible en interne.
Clone du repository de la présentation de la conf au DevLille 2026
le compte Mastodon de Nicolas Delsaux
Pour aller plus loin sur le sujet :
Architecture Decision Records (ADR) : Définition Et Comment Nous Le Faisons Chez Zup