Aller au contenu
Cabinet d'expertise en transformation technologique · ARDIANE Group Innover, sécuriser, réussir

Lexique

Architecture decision record (ADR) : définition, rubriques et documents voisins

Domaine

Ingénierie

L'essentiel

Un architecture decision record (ADR) est un court document qui consigne une décision d'architecture, le contexte qui l'a motivée et ses conséquences. Michael Nygard en a décrit le format dans un billet du 15 novembre 2011 ; les ADR d'un projet, numérotés et conservés même lorsqu'ils sont remplacés, forment son journal des décisions.

Sommaire de la page

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.

Insights

À lire sur le sujet

Tous les insights
Bâtir puis réviser un tech radar d'entreprise qui éclaire les choix d'architecture

Un tech radar, ou radar technologique, place les technologies qu'une organisation emploie ou examine dans des quadrants et des anneaux qui disent la confiance qu'elle leur accorde. Management Square propose une méthode pour en construire un et le tenir à jour : périmètre et quadrants, sens des anneaux, propositions et décisions, publication, révision, et ce qu'il change dans les décisions d'architecture.

Lire l'analyse
REST, GraphQL, gRPC ou événements : comparer les styles pour bâtir une architecture API

L'architecture API désigne ici les choix par lesquels un système d'information expose ses fonctions et ses données à d'autres logiciels : style de chaque interface, forme du contrat, règles d'évolution et de sécurité. Management Square compare REST, GraphQL, gRPC et les API pilotées par événements, puis décrit ce qu'une stratégie d'API fixe à l'échelle du système d'information.

Lire l'analyse
Mettre en œuvre le spec driven development avec un assistant de code, et savoir quoi relire

Le spec driven development, ou développement piloté par les spécifications, consiste à faire rédiger puis relire une spécification, un plan technique et une liste de tâches avant qu'un assistant de code n'écrive le code. Management Square décrit ici les étapes de cette méthode dans l'ordre, avec le livrable de chacune et la relecture qu'il appelle, d'après des sources publiques lues le 12 novembre 2026.

Lire l'analyse

FAQ

Questions fréquentes

Une autre question ? Posez-la-nous

Que signifie ADR ?

ADR est le sigle d'architecture decision record. Un architecture decision record est un court document qui consigne une décision d'architecture, le contexte qui l'a motivée et ses conséquences. Michael Nygard en a décrit le format dans le billet « Documenting Architecture Decisions », daté du 15 novembre 2011. Le site adr.github.io appelle journal des décisions (decision log) l'ensemble des ADR créés et tenus à jour dans un projet.

Que contient un ADR ?

Dans le format décrit par Michael Nygard, un ADR comprend cinq rubriques : un titre, le contexte, la décision, le statut et les conséquences. Le contexte expose en termes neutres les forces en présence, la décision s'énonce en phrases complètes, et les conséquences incluent les effets négatifs. Le site adr.github.io recense d'autres gabarits d'ADR, dont MADR et le Y-statement.

Que devient un ADR lorsque la décision change ?

Dans le format décrit par Michael Nygard, un ADR dont la décision est renversée n'est pas supprimé. Il est conservé et marqué comme remplacé (superseded), avec un renvoi vers l'ADR qui lui succède. Les ADR y sont numérotés dans l'ordre de leur création et un numéro n'est jamais réemployé, si bien que le journal garde la suite des décisions.

Un projet à faire aboutir ?

Un premier échange suffit pour situer votre enjeu, identifier les bons interlocuteurs et vous dire franchement ce que nous pouvons apporter.