Le choix dont plus personne ne connaît la raison
Une personne rejoint un projet et y trouve un choix technique qui la déroute. Michael Nygard part de cette situation dans « Documenting Architecture Decisions » (15 novembre 2011), le billet de blog qui, d’après le site adr.github.io, a popularisé l’architecture decision record. Faute de connaître les raisons et les conséquences de la décision, écrit-il, elle n’a que deux issues : l’accepter aveuglément, alors que le contexte a peut-être changé, ou la changer aveuglément, au risque de défaire ce qu’elle protégeait.
Définition de l’architecture decision record
L’expression, abrégée en ADR, peut se rendre par « enregistrement de décision d’architecture » (traduction de cette fiche). Michael Nygard décrit l’ADR comme un court fichier texte, qui expose un ensemble de forces et une seule décision prise en réponse. Il réserve le format aux décisions qu’il dit « architecturally significant » : celles qui touchent la structure, les caractéristiques non fonctionnelles, les dépendances, les interfaces ou les techniques de construction.
Le site adr.github.io écrit « architectural decision record » : un ADR y consigne une seule décision d’architecture et sa justification, et les ADR d’un projet forment son journal des décisions (decision log). Ces sources ont été lues le 12 novembre 2026.
Cinq rubriques, des fichiers numérotés et jamais effacés
Le billet fixe cinq rubriques, citées sous leur nom d’origine.
- Title (titre) : un groupe nominal court.
- Context (contexte) : les forces en présence, techniques, politiques ou sociales, décrites en termes neutres.
- Decision (décision) : la réponse retenue, en phrases complètes.
- Status (statut) : proposed (proposé) ou accepted (accepté), puis deprecated (obsolète) ou superseded (remplacé) si un ADR ultérieur revient sur la décision.
- Consequences (conséquences) : le contexte qui résulte de la décision, effets négatifs et neutres compris.
Les ADR se rangent dans le dépôt du projet, en texte léger (Markdown ou Textile, par exemple), et se numérotent à la suite. Une décision renversée garde son ADR, marqué comme remplacé. Chaque ADR tient en une ou deux pages, écrites comme une conversation avec un futur développeur.
Lecture de cette fiche, non du billet : un raccourci assumé, soit une dette technique délibérée, a sa place parmi les conséquences.
MADR, Y-statement : d’autres gabarits, et une objection
Le site adr.github.io recense d’autres gabarits. MADR (Markdown Architectural Decision Records) ajoute les options envisagées, avec leurs avantages et leurs inconvénients. Le Y-statement ramène la décision à une phrase : dans tel contexte, face à telle préoccupation, telle option est retenue pour telle qualité, au prix de tel inconvénient. Le site cite aussi des outils en ligne de commande, dont adr-tools et Log4brains.
Michael Nygard rapporte une objection : rangés avec le code, les ADR sont moins accessibles aux chefs de projet et aux parties prenantes qui ne fréquentent pas le dépôt. Il y répond par l’échange de liens vers le dépôt.
ADR, dossier d’architecture, schémas C4 : ne pas confondre
Un dossier d’architecture expose, pour un projet entier, les exigences, les options étudiées et la solution retenue. Un ADR porte une seule décision.
Un schéma montre une structure sans dire pourquoi elle a été retenue : les diagrammes du C4 model décrivent les conteneurs et les composants d’un système, l’ADR garde la raison d’un découpage.
Un ADR vaut pour un projet donné ; les principes communs à tous les projets relèvent de l’architecture d’entreprise.
Exemple : la saisie hors connexion d’une coopérative agricole
Supposons une coopérative agricole qui développe l’application mobile de ses chauffeurs de collecte. L’ADR 4, « Saisie hors connexion des pesées », expose le contexte : des silos sans couverture réseau. La décision : l’application enregistre les pesées sur le téléphone et les transmet au retour du réseau. Les conséquences : le stock connu du siège est en retard sur le terrain, et des doublons devront être rapprochés. Plus tard, les silos sont couverts : un ADR 19 retient la saisie en ligne, et l’ADR 4 passe au statut « remplacé ».
Notre page architecture SI compte un tel registre parmi ses livrables, à côté du dossier d’architecture.