# Architecture Decision Record

> L'ADR permet de rationaliser les décisions d'architecture d'une équipe et d'éviter qu'elles ne soient sans cesse remises en question.

- Author: Mathieu Eveillard
- Published: 2024-07-10
- Updated: 2025-09-15
- Tags: Artisanat logiciel
- Canonical: https://www.mathieueveillard.com/fr/articles/architecture-decision-record/
- Translation (en): https://www.mathieueveillard.com/articles/architecture-decision-record.md

![Architecture Decision Record](https://www.mathieueveillard.com/articles/2024-07-10-architecture-decision-record/architecture-decision-record.webp)

Documenter ou ne pas documenter ? Que documenter ? Pour qui ? Ces questions sont à l'origine de débats enflammés au sein des équipes agiles. Courage, fuyons et n'abordons ici qu'un aspect très précis de la question : un aspect qui, à ma connaissance, fait plutôt consensus.

## Un outil pour rationaliser vos décisions d'équipe

L'Architecture Decision Record (ADR) a pour vocation de documenter les décisions relatives à l'architecture d'un produit, en détaillant les tenants et aboutissants de ces décisions : éléments de contexte, incertitudes et hypothèses faites en conséquence, puis bien sûr les différentes options à l'étude avec leurs avantages et inconvénients. Et bien sûr la décision finale.

**L'objectif est de ne prendre aucune décision structurante à la légère, sur base d'intuitions non étayées ou de préférences personnelles**. On ne connaît que trop l'attrait des développeurs pour la dernière architecture ou techno à la mode, forcément [hyper puissante](https://www.mathieueveillard.com/fr/articles/comment-vs-pourquoi) et que l'on traînera ensuite pendant des années comme un boulet : bonjour ES/CQRS, bonjour les [microservices](https://www.mathieueveillard.com/fr/articles/modular-monolith).

Quelques exemples de sujets que l'on gagnera à documenter au sein d'un ADR :

- Choix d'un pattern de communication entre contextes : orchestration vs. chorégraphie (Event-Driven Architecture) ;
- Choix d'un mode de déploiement : monolithe modulaire vs. microservices ;
- Choix d'une architecture CRUD vs. architecture hexagonale vs. functional core/imperative shell ;
- Choix d'une stratégie de tests.

## L'ADR, pour plus de stabilité et d'homogénéité

L'intérêt de procéder de la sorte est de ne pas rouvrir ces sujets tous les quatre matins, à la faveur d'un nouvel arrivant dans l'équipe ou parce que l'on est confronté aux inconvénients propres à l'option retenue. Une décision n'est jamais sans inconvénient, simplement ces inconvénients sont connus et acceptés parce qu'ils vont de pair avec de plus grands bénéfices. Tout cela a été mis dans la balance et pesé une fois pour toutes, de sorte que si les tenants ne changent pas, la décision n'a aucune raison d'être remise en question ; en revanche, si une hypothèse est invalidée par l'expérience, ou si le contexte change, la décision peut être remise à l'étude.

Faire la démarche de consigner ces décisions dans un ADR incite également à statuer sur un plus grand nombre de sujets, évitant que chaque développeur travaille à sa sauce dans son coin. Idéalement, on souhaiterait ne pas pouvoir dire si un bout de code a été écrit par Paul ou par Paulette. La codebase y gagne en homogénéité, ce qui facilite les refactorings ultérieurs. Pour cette raison, **mieux vaut souvent une décision dont on sait qu'elle n'est pas idéale plutôt que pas de décision**.

## Quand commencer et comment s'y prendre ?

Mais au fait, à quel moment doit-on initialiser un ADR ? La création d'un [Walking Skeleton](https://www.mathieueveillard.com/fr/articles/walking-skeleton) est tout indiquée pour cela, puisqu'à cette occasion l'équipe définit les éléments les plus saillants de l'architecture ; ce jalon permet à l'équipe de traverser la phase de développement intense qui mène au MVP en limitant la [dette technique](https://www.mathieueveillard.com/fr/articles/dette-technique). Bien sûr, les choses ne sont pas figées dans le marbre : l'architecture est appelée à vivre au rythme du produit.

L'ADR permet justement cela, mais il faut en préciser la manière : **un ADR est immuable**. Pour amender une ancienne décision, l'équipe ne modifie pas la décision correspondante : elle en ajoute une nouvelle, qui fait référence à l'ancienne. Autrement dit, un fonctionnement append only, et si vous avez pensé « Event Sourcing », bravo 👏 Idéalement, les décisions seront numérotées de manière continue, comme cela se fait pour les factures. Et tout cela sera tracé par un outil de Version Control (communément Git).

À bien y regarder, le fait de tenir un ADR est une pratique très fédératrice pour une équipe, en ce sens que l'acceptation de son mode de fonctionnement vaut constitution, quand les décisions qui y sont consignées sont autant de lois. Il ne serait d'ailleurs pas aberrant d'en élargir la portée en y faisant figurer des décisions de toutes natures relatives à la vie de l'équipe. Et cela s'est déjà vu : je connais au moins un cas d'application dans les ressources humaines, sans aucun lien avec la tech.