ADR (Architecture Decision Record)

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

Termes liés

Sources

• adr.github.io/
• github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md