Enregistrements de décision d’architecture (ADR)

Ce qu’est un ADR et le problème qu’il résout

Un enregistrement de décision d’architecture (ADR) est un court document texte qui consigne une décision architecturalement significative : la situation qui l’a imposée, les options mises en balance, ce qui a été choisi et ce qui découle de ce choix. Un ensemble de ces enregistrements, conservés dans l’ordre, forme le journal des décisions d’un système. L’idée de consigner les décisions est ancienne (la recherche sur la justification des choix de conception remonte à plusieurs décennies, et Jeff Tyree et Art Akerman ont publié un modèle détaillé de décision dans IEEE Software en 2005), mais la forme légère qu’utilisent aujourd’hui la plupart des équipes vient du billet de blog de Michael Nygard, Documenting Architecture Decisions, publié le 15 novembre 2011.

Le point de départ de Nygard était un problème que connaît toute équipe qui dure. Un nouveau développeur découvre dans le code une décision qui paraît étrange : une file supplémentaire, une table dupliquée, une bibliothèque que personne ne choisirait aujourd’hui. Sans savoir pourquoi elle a été prise, le nouveau venu n’a que deux mauvaises options. Il peut l’accepter aveuglément, en préservant quelque chose dont les raisons ne s’appliquent peut-être plus, ou la modifier aveuglément, en cassant quelque chose dont les raisons valent toujours. Le remède de Nygard était de consigner les raisons au moment où la décision est prise, dans un petit fichier conservé avec le code, pour que la motivation voyage avec le système. Les gros documents d’architecture y parviennent rarement, car personne ne les met à jour ; un court enregistrement d’une seule décision, écrit une fois et jamais réécrit, reste vrai, parce qu’il prétend seulement décrire ce qui était connu et décidé à une date donnée.

Cela s’appuie directement sur l’anatomie d’une décision présentée au chapitre 1 : décisions et compromis : contexte, options, critères, décision et ses raisons, conséquences et statut. Un ADR n’est rien d’autre que cette anatomie mise par écrit dans un format prévisible. Il répond aussi à la question que la section Architecture ou conception laisse ouverte en pratique : si l’architecture est l’ensemble des décisions significatives, le journal des ADR est ce qu’une équipe possède de plus proche d’une liste de son architecture.

Le format de Nygard

Nygard a proposé cinq parties. La plupart des équipes les utilisent encore, en plaçant souvent le statut en tête pour que les lecteurs voient d’emblée si l’enregistrement est en vigueur. Ses conseils sur la manière de rédiger chaque partie comptent autant que les intitulés.

Nygard suggérait aussi qu’un enregistrement tienne sur une ou deux pages, que les enregistrements soient numérotés séquentiellement sans que les numéros soient jamais réutilisés, et qu’ils vivent dans le dépôt du projet en texte brut. Chacune de ces petites règles a sa raison d’être : les enregistrements courts sont lus, des numéros stables peuvent être cités dans les commentaires du code et les messages de commit, et le texte brut dans le dépôt peut être revu et versionné comme du code.

Autres modèles : MADR, Y-statements et formes plus riches

Le format de Nygard ne dit rien d’explicite sur les options rejetées, et beaucoup d’équipes ont constaté que les alternatives sont précisément ce qu’un lecteur ultérieur veut le plus connaître. Plusieurs modèles les ajoutent.

MADR (Markdown Architectural Decision Records, maintenu sur adr.github.io) est le modèle structuré le plus utilisé. Sa version actuelle au moment de la rédaction est la 4.0.0, publiée en septembre 2024. Le modèle complet comporte un titre, puis Contexte et énoncé du problème, des Facteurs de décision facultatifs, les Options envisagées, le Résultat de la décision avec des sous-sections facultatives Conséquences et Confirmation, des Avantages et inconvénients des options facultatifs et des Informations complémentaires facultatives. Les métadonnées comme le statut, la date, les décideurs, et les personnes consultées et informées peuvent figurer dans un en-tête YAML. Deux idées de MADR méritent d’être reprises même si vous utilisez un autre format. Les facteurs de décision explicitent les critères avant que les options soient jugées, ce qui est la discipline de la matrice pondérée du chapitre 1 sous une forme compacte. La Confirmation indique comment l’équipe vérifiera que la décision est réellement mise en œuvre et qu’elle tient toujours, par exemple au moyen d’une revue, d’un test ou d’une vérification automatisée de l’architecture.

Le Y-statement (déclaration en Y), proposé par Olaf Zimmermann et ses collègues et présenté pour la première fois à la conférence SATURN en 2012, condense une décision en une seule phrase structurée : Dans le contexte de (un cas d’utilisation ou un composant), face à (une préoccupation ou une exigence de qualité), nous avons opté pour (l’option) et écarté (les alternatives), afin d’obtenir (les bénéfices), en acceptant que (les inconvénients). Le nom est un jeu de mots sur why (« pourquoi » en anglais). Un Y-statement est idéal pour le résumé d’un journal des décisions, une diapositive, un commentaire de code ou la description d’une pull request ; pour une porte à sens unique contestée, il est généralement trop condensé, et les équipes le développent en un enregistrement complet.

Des modèles plus lourds existent pour les contextes réglementés ou de très grande taille. Le modèle de Tyree et Akerman de 2005 ajoute des champs comme les hypothèses, les contraintes, les décisions liées, les exigences liées et les implications. Ils sont utiles quand les décisions doivent être rattachées aux exigences pour un auditeur ; pour la plupart des équipes produit, ils ajoutent un effort que personne ne lit.

Statut, cycle de vie, et pourquoi on ne modifie pas les enregistrements acceptés

Un ADR passe par un petit nombre d’états. Il commence comme proposé, généralement sous la forme d’une pull request qui ajoute le fichier, pour que la discussion ait lieu dans les commentaires de revue. Quand les personnes responsables sont d’accord, il est fusionné comme accepté. Une proposition refusée peut être conservée comme rejetée, ce qui est précieux : la prochaine personne qui suggère la même idée trouve le raisonnement antérieur. Plus tard, un enregistrement accepté peut devenir obsolète (la décision ne s’applique plus, peut-être parce que le composant a été retiré) ou être remplacé par un enregistrement plus récent, avec des liens dans les deux sens. MADR liste le même ensemble : proposé, rejeté, accepté, obsolète et remplacé.

La règle centrale est que le contenu d’un enregistrement accepté n’est pas réécrit. Si l’équipe change d’avis, elle rédige un nouvel ADR qui remplace l’ancien, et ne modifie que la ligne de statut de l’ancien enregistrement pour renvoyer vers le nouveau. Les raisons sont pratiques. D’abord, l’enregistrement témoigne de ce qui était connu et décidé à un moment donné ; le modifier après coup transforme l’histoire en fiction et détruit la confiance qui rend le journal utile. Ensuite, l’ancien enregistrement explique pourquoi le système avait cette forme pendant une période, ce qui compte quand on débogue d’anciennes données ou qu’on lit du code ancien. Enfin, un nouvel enregistrement oblige l’équipe à dire ce qui a changé dans le contexte, ce qui est souvent l’enseignement le plus important. Les petites corrections (une coquille, un lien cassé) sont sans danger ; changer la décision, les raisons ou les conséquences ne l’est pas. La description de cette pratique par Martin Fowler dit la même chose : une fois accepté, un enregistrement n’est pas rouvert ; on rédige plutôt un enregistrement qui le remplace.

Où conserver les ADR

Conservez les ADR dans le dépôt du code qu’ils régissent, sous forme de fichiers en texte brut (généralement en Markdown), une décision par fichier, avec un numéro d’ordre et un court identifiant (slug) dans le nom du fichier. Deux conventions de répertoires sont courantes : doc/adr, la valeur par défaut de l’outil en ligne de commande adr-tools de Nat Pryce, et docs/decisions, recommandée par MADR avec des noms comme 0012-publish-order-events-through-broker.md. Thoughtworks a placé les ADR légers dans l’anneau Adopt de son Technology Radar (pour la dernière fois en 2018) et a expressément recommandé la gestion de versions plutôt qu’un wiki, pour que les enregistrements restent en phase avec le code qu’ils décrivent.

Conserver les enregistrements à côté du code présente des avantages concrets. Ils sont revus dans les mêmes pull requests que le code qui les met en œuvre, ils sont versionnés et branchés avec lui, un développeur peut les trouver avec les mêmes outils de recherche, et le code peut y renvoyer : un commentaire comme voir ADR-0012 au-dessus d’un relais d’outbox indique au lecteur suivant où se trouvent les raisons. Les décisions qui couvrent de nombreux dépôts, comme le choix d’un fournisseur d’identité à l’échelle de l’organisation, ont besoin d’un emplacement à elles ; un dépôt d’architecture dédié avec les mêmes conventions fonctionne bien, avec des liens depuis chaque base de code concernée.

docs/
  decisions/
    README.md                                  <- the decision log (index)
    0001-record-architecture-decisions.md
    0004-use-hosted-card-fields.md
    0007-use-managed-postgresql-for-orders.md
    0012-publish-order-events-through-broker.md
    template.md
src/
  ordering/
    outbox_relay.py      # comment: see docs/decisions/0012-...

Quelles décisions méritent un ADR

Rédiger un ADR pour chaque choix enfouit les plus importants ; n’en rédiger aucun fait perdre les raisons. Le critère est l’importance, telle que définie au chapitre 1 : une décision mérite un enregistrement quand elle est coûteuse à inverser, touche un attribut de qualité clé, a une large portée, contraint d’autres équipes ou a été contestée. En pratique, cela concerne des choix comme le stockage de données principal, le style de communication entre services, un fournisseur d’identité, une politique de versionnage d’API, une plateforme d’hébergement, une décision de développer ou d’acheter, et les conventions dont la violation coûte cher (la représentation des montants, le stockage des fuseaux horaires). Cela inclut aussi les décisions de ne pas faire quelque chose que l’on ne cesse de suggérer, comme ne pas introduire de cache pour l’instant.

Les choix locaux, peu coûteux à inverser et invisibles hors d’un seul module ne nécessitent généralement pas d’enregistrement : le choix d’une bibliothèque d’assertions de test, le nom d’une classe, l’organisation interne d’un composant. Un signal utile est la question que poserait un nouveau venu : si quelqu’un risque de demander mais pourquoi diable ont-ils fait ça ? dans l’année, rédigez l’enregistrement maintenant, pendant que les raisons sont fraîches.

Un ADR complet commenté

La plateforme de livraison de repas utilisée tout au long de ce chapitre comprend des applications pour les clients, les restaurants et les livreurs, un service des commandes, des paiements via un prestataire de paiement externe, l’affectation des livreurs et des notifications. L’enregistrement ci-dessous suit la structure de MADR, légèrement raccourcie. Remarquez comment le contexte donne des chiffres et des dates plutôt que des adjectifs, comment les facteurs sont énoncés avant les options, comment les options rejetées sont examinées équitablement, et comment les conséquences incluent des coûts réels. La décision elle-même (une messagerie asynchrone pour les événements de commande) est étudiée en détail au chapitre 6 : architecture pilotée par les événements ; ici, l’important est la manière dont elle est consignée.

# ADR-0012: Publish order events through a managed message broker

- Status: Accepted
- Date: 2026-09-14
- Deciders: ordering team lead, platform lead, principal architect
- Consulted: restaurant, courier and notifications teams; SRE
- Related: ADR-0007 (managed PostgreSQL for the order service)

## Context and problem statement

When a customer's payment succeeds, the ordering service calls the restaurant,
courier-dispatch and notification services synchronously over HTTP before it
confirms the order. On Friday evenings (peak about 40 orders/s) p99 order
confirmation time reaches 4.2 s against our target of 1.5 s (scenario QS-3).
On Friday 21 August a notification-service outage blocked all new orders for
23 minutes. Two new consumers (loyalty points, analytics) want order data.

## Decision drivers

- Order confirmation must not depend on notification or dispatch availability.
- p99 confirmation under 1.5 s at three times today's peak.
- No order event may be lost, even if a service crashes mid-request.
- New consumers should not require changes to the ordering service.
- The platform team has three people; operational load must stay small.

## Considered options

1. Keep synchronous calls; add timeouts, retries and circuit breakers.
2. Publish events to a managed message broker using a transactional outbox.
3. Let consumers poll a shared "order_events" table in the order database.

## Decision outcome

Chosen option: 2. We will publish OrderPlaced, OrderAccepted, OrderPickedUp,
OrderDelivered and OrderCancelled events to our cloud provider's managed
broker. The ordering service writes each event to an outbox table in the
same database transaction as the order; a relay publishes it. Payment
authorisation stays synchronous, because the customer must see the result.

### Consequences

- Good: confirmation no longer waits for downstream services.
- Good: loyalty and analytics can subscribe without ordering-team work.
- Bad: services become eventually consistent; the restaurant tablet may
  show a new order a second or two after the customer's confirmation.
- Bad: a broker to pay for and monitor; consumers must be idempotent
  because delivery is at-least-once.
- Neutral: event schemas become public contracts and need versioning.

### Confirmation

Load test at 120 orders/s in staging before go-live; a build check fails
if the ordering service gains an HTTP client for notification or dispatch.

## Pros and cons of the other options

- Option 1: least new infrastructure, but a slow dependency still delays
  every order, and each new consumer means another call to add.
- Option 3: no new infrastructure, but couples every consumer to our schema
  and adds polling load to the order database (see ADR-0007).

Revoir les ADR

Comme un ADR est un fichier du dépôt, le mécanisme de revue naturel est la pull request. La personne qui propose l’ouvre avec le statut proposé ; les personnes concernées commentent ; l’enregistrement est révisé ; quand les personnes responsables sont d’accord, le statut passe à accepté et la pull request est fusionnée. La discussion reste ainsi attachée à l’enregistrement et visible pour quiconque lira plus tard l’historique.

Qui doit faire la revue dépend de la manière dont les décisions sont gouvernées. Dans un modèle centralisé, un comité d’architecture approuve les enregistrements significatifs. Dans le processus de consultation (advice process) décrit par Andrew Harmel-Law (martinfowler.com, 2021), n’importe qui peut prendre une décision architecturale, à condition de demander d’abord l’avis de toutes les personnes réellement concernées et de celles qui ont l’expertise pertinente, et de consigner ces avis ; la personne qui décide n’est pas tenue de suivre les avis, mais doit les entendre. Les ADR sont la colonne vertébrale de ce processus : les avis figurent dans l’enregistrement, et un forum consultatif ouvert et régulier examine les enregistrements proposés. Les modèles de gouvernance sont traités au chapitre 11 : la gouvernance dans les organisations agiles.

La liste de contrôle ecADR d’Olaf Zimmermann (2020) donne aux personnes qui font la revue une définition compacte de « terminé » pour une décision. Evidence (éléments probants) : il y a des raisons de croire que l’option fonctionnera, d’après un spike, une preuve de concept ou une expérience fiable. Criteria (critères) : au moins deux options ont été comparées au regard des préoccupations des parties prenantes. Agreement (accord) : la décision a été mise à l’épreuve par des pairs et l’équipe l’accepte. Documentation : elle est consignée et partagée avec les personnes concernées. Realisation and review (réalisation et réexamen) : la mise en œuvre est planifiée, et une date ou un déclencheur pour la réexaminer est fixé. Une personne qui vérifie ces cinq points, ainsi que l’honnêteté des conséquences, repère la plupart des enregistrements faibles.

Anti-patrons

Les ADR échouent de manière reconnaissable. Zimmermann en a catalogué plusieurs en 2023 sous des noms faciles à retenir, et les plus nuisibles méritent d’être connus.

Le journal des décisions comme index

Chaque enregistrement est utile ; le journal dans son ensemble l’est davantage. Un court fichier d’index (souvent le README.md du dossier des décisions) liste chaque enregistrement avec son numéro, son titre, son statut et sa date. Un nouveau venu le lit en cinq minutes et obtient un historique condensé de l’architecture : ce qui a été décidé, ce qui a été rejeté, ce qui a été remplacé et quand. Des outils comme adr-tools peuvent générer l’index et créer des enregistrements de remplacement qui mettent automatiquement à jour le statut de l’ancien, et des outils de documentation, dont le DSL de Structurizr, peuvent importer un dossier d’ADR dans la documentation publiée.

Traitez le journal comme une partie de la description d’architecture. Le modèle arc42 comporte une section consacrée aux décisions d’architecture qui peut simplement y renvoyer, et un pipeline docs-as-code peut le publier avec le reste de la documentation.

# Decision log

| ADR  | Title                                                | Status                 | Date       |
|------|------------------------------------------------------|------------------------|------------|
| 0001 | Record architecture decisions                        | Accepted               | 2025-03-02 |
| 0004 | Use the payment provider's hosted card fields        | Accepted               | 2025-04-18 |
| 0007 | Use managed PostgreSQL for the order service         | Accepted               | 2025-06-11 |
| 0009 | Send push notifications through a third-party SDK    | Superseded by 0015     | 2025-09-30 |
| 0012 | Publish order events through a managed broker        | Accepted               | 2026-09-14 |
| 0013 | Store courier locations in a time-series database    | Rejected               | 2026-09-20 |
| 0015 | Run our own notification service on the broker       | Accepted               | 2026-10-08 |