ADR (Architecture Decision Record) : documenter des décisions utiles

Un ADR n’est pas un document d’architecture de plus : c’est une note courte qui capture le contexte, la décision et ses conséquences. Bien utilisé, il évite les débats répétitifs, accélère l’alignement et rend les choix durables.

Les équipes techniques passent beaucoup de temps à discuter, arbitrer, choisir… puis à oublier pourquoi elles ont choisi certaines décisions.
Le résultat est connu :

• les mêmes débats reviennent tous les 3 mois,
• on re-questionne des décisions sans le contexte de l’époque,
• l’onboarding dépend de “ceux qui savent”,
• et des migrations inutiles naissent d’une simple perte de mémoire.

Un ADR (Architecture Decision Record) sert à éviter cela. Ce n’est pas une “grosse doc d’architecture”, ni un cahier des charges : c’est une note courte qui capture une décision importante, avec le minimum de contexte pour qu’elle reste compréhensible et réutilisable.

I.D’où vient le terme ADR, et pourquoi “à la Nygard” ?  

1)Point historique  

Les ADR (Architecture Decision Records) sont devenus populaires grâce au billet de Michael Nygard, Documenting Architecture Decisions (15 novembre 2011), où il propose une approche volontairement légère : consigner une décision “architecturalement significative” avec juste assez de contexte pour qu’elle reste compréhensible dans le temps.

Le template souvent appelé “Nygard ADR” (Title / Status / Context / Decision / Consequences) vient directement de cette proposition et a été repris par la communauté comme format de référence.

En pratique, on peut dire que Nygard a surtout popularisé et standardisé une méthode simple pour garder la mémoire des décisions, ce qui explique pourquoi on le cite encore aujourd’hui quand on parle d’ADR.

2) C’est quoi un ADR, exactement ?  

Un ADR est un document (souvent 1 page max) qui répond à trois questions :

1. Dans quel contexte décide-t-on ?
2. Qu’est-ce qu’on décide ?
3. Quelles conséquences on accepte ?

Le but n’est pas de produire un document “beau”. Le but est de rendre une décision :

• rejouable (on comprend le raisonnement),
• stable (on évite de refaire le débat),
• contestable sainement (si on change, on sait ce qu’on change et pourquoi).

II. Quand écrire un ADR (et quand ne pas en écrire)  

Écrire un ADR si…  

• la décision impacte plusieurs composants / équipes,
• le coût de changement est élevé (migration, données, sécurité),
• la décision sera re-lue dans 6–12 mois,
• une option écartée reviendra forcément dans une discussion future,
• la décision touche des “principes” : standardisation, observabilité, patterns, etc.

Exemples typiques :

• choix d’une base de données (PostgreSQL vs DynamoDB),
• organisation d’un monorepo (Nx vs Bazel vs Turbo),
• stratégie d’authentification (OIDC, SSO, tokens),
• format d’events / schéma (Avro/Protobuf/JSON),
• conventions de déploiement ou d’environnements.

Ne pas écrire un ADR si…  

• c’est une décision triviale (ex : “renommer une variable”),
• c’est réversible en 10 minutes,
• c’est purement locale à un fichier ou un module,
• la décision ne survivra pas à la semaine.

L’ADR n’est pas un système de contrôle. C’est un outil de mémoire pour les décisions qui comptent.

III. Le format “à la Nygard” : simple et durable  

L’approche popularisée par Michael Nygard vise un format court.

a) Contexte — dans quelle situation prend-on cette décision ?  

Le contexte explique pourquoi ce sujet existe maintenant.
Il doit contenir juste assez d’informations pour qu’un lecteur futur comprenne les contraintes de l’époque.

• périmètre (système, équipe, projet),
• état actuel (“aujourd’hui on fait X”),
• contraintes (temps, budget, sécurité, legacy, compétences),
• objectifs (ce qu’on cherche à optimiser).

Exemple :
“On déploie un service Go sur Kubernetes. Les builds CI prennent ~18 minutes. On veut réduire le temps de feedback sans perdre la reproductibilité ni augmenter fortement la complexité locale.”

b) Décision — qu’est-ce qu’on choisit ?  

La décision doit se lire en diagonale : courte, claire, sans ambiguïté.

• option retenue,
• scope exact (inclus / exclu si besoin),
• owner (qui porte la mise en œuvre).

Exemple :
“Nous adoptons un remote cache + une exécution ‘affected’ des tâches CI (option B) pour réduire le temps moyen de pipeline.”

c) Statut — où en est la décision ?  

Une décision a une vie. Le statut évite les ADR “fantômes”.

• Proposed | Accepted | Rejected | Deprecated | Superseded (par ADR-XXXX)

Exemple :
“Statut : Proposed (validation après PoC sur un service).”

d) Conséquences — qu’est-ce que cette décision implique ?  

C’est la partie “honnête”. On écrit ce qu’on gagne et ce qu’on accepte de perdre.

• bénéfices attendus,
• trade-offs,
• risques,
• impacts (docs, onboarding, maintenance, outillage).

Exemple :

• feedback plus rapide, PR plus fluides
• mise en place initiale plus complexe
• risque de cache incorrect → besoin de garde-fous
• nécessite une doc de setup + une mesure continue du gain

e) Alternatives considérées — qu’est-ce qu’on a écarté, et pourquoi ?  

Le but n’est pas de prouver qu’on a “raison”.
Le but est de rendre visibles les options, et de documenter pourquoi elles ne passent pas les critères.

• Option A : cache CI classique (gain limité / peu stable)
• Option C : Docker layer caching (impose Docker/local / friction)

Exemple :
“Nous n’avons pas retenu Docker layer caching car il ajoute une dépendance forte à Docker en local et complexifie l’expérience développeur.”

f) Plan d’exécution — optionnel, mais souvent décisif  

Beaucoup d’équipes s’arrêtent à Contexte/Décision/Conséquences.
Ajouter 4–6 lignes transforme l’ADR en décision opérationnelle (sinon elle “dort”).

Les next steps doivent être : courts, assignés, vérifiables.

• checklist d’actions,
• owner,
• échéance indicative,
• critère de validation,
• rollback si risque élevé.

Exemple :

• PoC sur un service (Hélène, vendredi)
• Mesurer le temps CI avant/après (moyenne, variance, taux d’échec)
• Documenter le setup + règles d’invalidation du cache (README)
• Décider généralisation si gain > 30% et stabilité OK (sinon rollback)

IV. Comment faire pour que les ADR restent légers  

Un ADR échoue rarement parce que le format est mauvais. Il échoue parce que :

• personne ne sait quand en écrire,
• personne ne les lit,
• personne ne les met à jour quand ils sont remplacés.

Voici des pratiques qui marchent.

Règle 1 — Un ADR = une décision (et une seule)  

Ne mélange pas “choix de DB” + “conventions de repo” + “format d’events” dans un seul doc.
Si tu dois faire ça, c’est souvent que tu as plusieurs décisions.

Règle 2 — Garder les ADR près du code  

Le plus courant : un dossier docs/adr/ dans le repo.
Exemple de nommage :

• docs/adr/0001-use-postgresql.md
• docs/adr/0002-ci-remote-cache.md

Le numéro rend les références stables.

Règle 3 — L’ADR est validé comme du code  

Une bonne routine :

• l’ADR est une PR,
• elle reçoit des commentaires,
• elle est acceptée / rejetée comme le reste.

Tu peux même demander : “si tu contestes, propose une alternative et une conséquence”.

Règle 4 — Remplacer proprement  

Quand une décision change :

• l’ADR original passe en Superseded by ADR-00XX,
• le nouvel ADR explique le nouveau contexte (souvent différent).

Cette discipline évite les “docs contradictoires”.

V. Un exemple complet (mini ADR réaliste)  

# ADR-0002 — CI: Remote cache + affected tasks

Status: Accepted
Date: 2026-02-23
Owner: Hélène

## Context
Our Go services run on Kubernetes. CI pipelines average 18 minutes.
We want faster feedback without forcing Docker locally and without losing reproducibility.

## Decision
Adopt remote caching plus "affected-only" task execution for CI.
Scope: one service first, then extend to the monorepo if results are stable.

## Consequences
+ Faster feedback; fewer stalled PRs
+ Better scalability as the repo grows
- Initial setup complexity (cache backend, auth)
- Risk of incorrect cache hits → need safeguards and invalidation rules

## Alternatives considered
A) Standard CI cache: limited gains, inconsistent
C) Docker layer caching: adds local Docker dependency and friction

## Execution plan
- [ ] PoC on one service (Hélène, Friday)
- [ ] Measure before/after (avg, variance, failure rate)
- [ ] Write setup + invalidation rules (README)
- [ ] Rollout if gain > 30% and stable; rollback otherwise

VI. Pièges classiques  

“On écrit des ADR pour tout”

• Résultat : personne ne lit, et l’équipe déteste l’outil.
• En bref : on garde l’ADR pour les décisions à coût de changement élevé.

“On écrit l’ADR après coup”

• Résultat : justification a posteriori, pas de débat sain.
• En bref : on écris l’ADR pendant la décision (PR + commentaires).

“L’ADR remplace la discussion”

• En réalité : Non. L’ADR remplace surtout l’oubli.
• En bref : on discute quand nécessaire, puis cristallise dans l’ADR.

“On ne sait pas si c’est encore vrai”

• En bref : on utilise Status + Superseded et garde un index.

Conclusion  

Il faut mettre les ADR au service d’une équipe et non pas l’inverse.

Un bon signe que tes ADR fonctionnent :

• est quand un personne nouvelle dans l’équipe peut répondre “pourquoi on fait ça comme ça ?” en 2 minutes,
• une discussion “déjà vue” se ferme avec un lien vers un ADR,
• l’équipe débat sur des critères (contexte/conséquences) et pas sur des préférences implicites.

Liens utiles  

• Article fondateur ADR (Michael Nygard, 2011)
• Templates ADR (adr.github.io) — Plusieurs modèles prêts à l’emploi, dont le template “Nygard”.
• Travailler en remote : liberté, efficacité… et conditions de réussite — article de blog