ADR (Architecture Decision Record)

Architecture 🟢 Junior

Définition

Document court, versionné avec le code, qui consigne une décision d'architecture importante : contexte, décision, conséquences, statut (proposé, accepté, déprécié, remplacé). Popularisé par Michael Nygard dans son billet « Documenting Architecture Décisions » de 2011, le format a évolué vers des modèles comme MADR. Une ADR n'est jamais modifiée après acceptation : on en écrit une nouvelle qui la remplace.

Analogie

Le journal de bord d'un capitaine : on ne réécrit pas les pages d'hier, on ajoute celle d'aujourd'hui en expliquant pourquoi on change de cap.

Exemple de code

# docs/adr/0007-remplacer-ingress-nginx-par-gateway-api.md
# 7. Remplacer Ingress NGINX par la Gateway API
Date : 2026-03-02
Statut : Accepté (remplace ADR-0003)
## Contexte
Ingress NGINX est retiré par le projet Kubernetes en mars 2026 :
plus de correctifs de sécurité.
## Décision
Migrer vers Envoy Gateway + HTTPRoute via ingress2gateway.
## Conséquences
+ routage canary natif, rôles séparés plateforme/équipes
- formation, réécriture des annotations spécifiques

Cas d'usage

Toute décision structurante (base de données, découpage en services, framework, hébergement) qu'un nouvel arrivant devra comprendre dans deux ans.

Anti-pattern

Écrire l'ADR après coup pour justifier, ou la modifier en silence : elle perd sa valeur d'historique honnête.

Termes liés

#architecture#documentation#interview

En entretien

Explique-moi ce qu'est une ADR.
C'est un document court, versionné avec le code, qui consigne une décision d'architecture importante : contexte, décision, conséquences, statut. Popularisé par Michael Nygard en 2011, il sert pour toute décision structurante qu'un nouvel arrivant devra comprendre dans deux ans.
Comment gère-t-on une ADR qui devient obsolète ?
On ne la modifie jamais après acceptation, on en écrit une nouvelle qui la remplace en changeant son statut. C'est comme le journal de bord d'un capitaine : on n'efface pas les pages d'hier, on ajoute celle d'aujourd'hui.
Quel anti-pattern décrédibilise une ADR ?
L'écrire après coup pour justifier une décision déjà prise, ou la modifier en silence, ce qui lui fait perdre sa valeur d'historique honnête. Une ADR doit refléter le raisonnement au moment de la décision.

Sources

Fiche mise à jour le 2026-09-27