Un Architecture Decision Record (ADR) est un ensemble de documents 📄 contenant les décisions architecturales et technologiques prises au cours de la vie d’une application.
Un ADR inclut du contexte, des alternatives considérées, et des justifications des décisions.
Je pense que cela arrive à tout le monde (et si ce n'est pas encore le cas, ça le sera un jour) de rejoindre un projet ou une application et de se demander : "💩 Mais pourquoi ont-ils conçu cela de cette façon ?" ou "Pourquoi ont-ils utilisé cette technologie ?"
Si les personnes qui ont pris ces décisions ne sont plus là ou si cela remonte à longtemps, il peut être difficile de comprendre ces choix.
C'est là qu'un ADR est utile, car il garde une trace des décisions prises.
Ses objectifs
Tracer les décisions
Enregistre l'historique des choix architecturaux ce qui permet de préserver la connaissance
Fournit un contexte pour chaque décision, ce qui facilite la compréhension dans le futur
Améliorer la communication
Facilite la compréhension entre les membres de l'équipe
Aide à l'intégration de nouveaux membres
Aide lors d’audit ou revue
Aider aux futurs prises de décision
Offre des précédents pour guider les choix ultérieurs
Permet d'éviter la répétition d'erreurs passées
L’importance est de tracer à un moment T et de bien rappeler les conditions dans lesquels le choix a été réalisé.
Un choix réalisé en 2010 peut avoir été le meilleure choix à faire à l’époque mais en 2025, un outil permet de le faire plus efficacement. Ce qui ne veut pas dire que le développeur/architecte en 2010 était moins bon mais qu’il a du faire avec les possibilités de l’époque.
Structure d'un ADR
Ci-dessous une proposition de structure.
Titre : Bref résumé de la décision
Statut : Proposé, Accepté, Rejeté, Déprécié, Remplacé
Contexte : Situation qui a conduit à la décision
Date : La date de la proposition
Décision : Description de la décision prise
Conséquences : Impact de la décision, positif et négatif
Alternatives Considérées : Autres options envisagées
Participants : Personnes impliquées dans la décision
Outils
Ce qui est bien avec les ADRs c’est qu’il faut juste un endroit où stocker ces documents.
On peut donc retrouver :
Git
Gitlab et Github avec leur gestion de page peut être intéressant
Gestion des versions
Relectures via PR/MR
Confluence
- Nombreux projets possèdent déjà un Confluence
Il existe aussi des outils plus poussés comme Structurizr qui permet de gérer la modélisation des architectures avec l’intégration d’ADRs ou Mkdocs permettant de gérer des documents avec un rendu web.
Pour ma part, je reste généralement sur un repository Gitab 🦊.
Ressource(s)
- Templates d’ADRs : https://adr.github.io/adr-templates/