Architecture Decision Records (ADR) : tracer vos choix

Janvier 2019, une grande banque européenne. Un développeur senior découvre dans le code une architecture microservices complexe avec 47 services communiquant via RabbitMQ. Personne dans l’équipe actuelle ne sait pourquoi ce choix a été fait il y a 3 ans. L’architecte original est parti. Les spécifications techniques sont muettes sur ce point.

L’équipe passe 6 mois à investiguer avant de comprendre que RabbitMQ avait été choisi pour sa capacité de dead-letter queues, essentielle pour la conformité réglementaire. Sans cette connaissance, ils étaient sur le point de migrer vers Kafka — une décision qui aurait violé les exigences de la régulation bancaire.

Un simple ADR de 2 pages aurait évité ces 6 mois perdus.

Qu’est-ce qu’un ADR ?

Un Architecture Decision Record (ADR) est un document court qui capture une décision architecturale significative, son contexte et ses conséquences. Le concept a été formalisé par Michael Nygard en 2011 dans son article fondateur « Documenting Architecture Decisions ↗ ».

Origine du terme

Michael Nygard, auteur de « Release It! », a créé le concept d’ADR en constatant que « personne ne lit les gros documents d’architecture, mais ne pas connaître les raisons derrière les décisions architecturales importantes peut mener à des conséquences désastreuses ».

L’analogie du journal de bord

Imaginez un capitaine de navire qui traverse l’Atlantique. Chaque jour, il consigne dans son journal :

• La situation : météo, position, état de l’équipage
• Les décisions prises : changement de cap, réduction de voilure
• Les raisons : tempête annoncée, vent favorable
• Les conséquences anticipées : retard de 2 jours, économie de carburant

Si un autre capitaine reprend le navire, ce journal lui permet de comprendre le voyage sans avoir à tout réinventer.

Un ADR joue le même rôle pour votre architecture logicielle : il capture le raisonnement derrière chaque décision importante.

ADR vs documentation classique

Aspect	Documentation classique	ADR
Longueur	Des dizaines de pages	1-2 pages maximum
Portée	Système complet	Une seule décision
Mise à jour	Rare (souvent obsolète)	Immutable (on crée un nouvel ADR)
Question	« Comment ça marche ? »	« Pourquoi ce choix ? »
Audience	Nouveaux arrivants	Futurs décideurs
Durée de vie	Courte (devient obsolète)	Permanente (historique)

La documentation classique explique l’état actuel. Les ADR expliquent le chemin parcouru.

Pourquoi les ADR sont indispensables

Le coût de la connaissance perdue

Les décisions architecturales ont une caractéristique particulière : elles sont faciles à oublier mais coûteuses à redécouvrir.

Sans ADR

Scénario typique :

1. Un architecte fait un choix technique important
2. Il en parle en réunion, envoie un email
3. 18 mois plus tard, il quitte l’entreprise
4. Un nouveau développeur se demande « pourquoi PostgreSQL et pas MongoDB ? »
5. Personne ne se souvient, l’email est introuvable
6. L’équipe passe des semaines à analyser, benchmarker
7. Ils prennent une décision… peut-être la même, peut-être différente
8. Le cycle recommence

Avec ADR

Scénario avec ADR :

1. Un architecte fait un choix technique important
2. Il rédige un ADR en 30 minutes
3. 18 mois plus tard, il quitte l’entreprise
4. Un nouveau développeur se demande « pourquoi PostgreSQL et pas MongoDB ? »
5. Il ouvre docs/adr/0015-use-postgresql-for-main-database.md
6. En 5 minutes, il comprend le contexte, les alternatives évaluées, la décision
7. Il peut soit valider que le contexte est toujours pertinent, soit créer un nouvel ADR s’il a changé

Les quatre bénéfices mesurables

Bénéfice	Impact
Onboarding accéléré	-40% de temps pour comprendre l’architecture existante
Décisions plus rapides	Évite de ré-analyser les mêmes options
Moins de « pourquoi ? »	Réduit les interruptions des seniors
Audit facilité	Traçabilité des choix pour conformité

Statistique Spotify

Chez Spotify, l’adoption des ADR a réduit de 60% le temps passé en « décision archeology » — la recherche des raisons historiques derrière les choix techniques.

Anatomie d’un ADR

Un ADR efficace suit une structure standardisée. Le template le plus populaire est MADR (Markdown Architectural Decision Records), mais le template original de Michael Nygard reste une référence.

Template Nygard (original)

Le template original est minimaliste — c’est sa force :

docs/adr/0001-record-architecture-decisions.md

# 1. Record architecture decisions

Date: 2024-01-15

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as described by Michael Nygard.

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset,
see Nat Pryce's adr-tools.

Les cinq sections obligatoires :

1. Titre : numéroté, action claire (« Use X for Y »)
2. Date : quand la décision a été prise
3. Status : Proposed, Accepted, Deprecated, Superseded
4. Context : pourquoi cette décision est nécessaire
5. Decision : ce qui a été décidé
6. Consequences : impacts positifs et négatifs

Template MADR (enrichi)

Le template MADR ajoute des sections utiles pour les décisions complexes :

docs/adr/0042-use-postgresql-for-main-database.md

# ADR-0042 : Utiliser PostgreSQL comme base de données principale

## Statut

Accepted

## Contexte et problème

Notre application a besoin d'une base de données relationnelle capable de :
- Gérer des transactions ACID complexes
- Stocker des données JSON semi-structurées
- Supporter 10 000 requêtes/seconde en lecture

L'équipe a des compétences MySQL et MongoDB, mais pas PostgreSQL.

## Decision Drivers

* Performance en lecture intensive
* Support JSON natif sans sacrifier les jointures SQL
* Coût de licence (open-source préféré)
* Maturité de l'écosystème (tooling, monitoring)
* Courbe d'apprentissage pour l'équipe

## Options considérées

### Option 1 : MySQL 8.x

**Avantages** :
- Équipe déjà formée
- Large communauté

**Inconvénients** :
- Support JSON moins mature que PostgreSQL
- Performances JSON inférieures dans nos benchmarks

### Option 2 : PostgreSQL 16

**Avantages** :
- Excellent support JSON (JSONB indexable)
- Performances supérieures dans nos tests (+30%)
- Extensions riches (PostGIS, TimescaleDB)

**Inconvénients** :
- Formation équipe nécessaire (2-3 semaines)
- Certains outils internes à adapter

### Option 3 : MongoDB 7.x

**Avantages** :
- Flexibilité schéma
- Équipe partiellement formée

**Inconvénients** :
- Pas de transactions multi-documents fiables
- Coût plus élevé à grande échelle

## Décision

**Nous choisissons PostgreSQL 16** pour toutes les nouvelles applications.

Raisons principales :
1. Les benchmarks montrent +30% de performance sur nos cas d'usage
2. Le support JSONB permet de mixer relationnel et document
3. L'écosystème d'extensions répond à nos besoins futurs (géospatial, time-series)

## Conséquences

### Positives

* Performance garantie pour nos cas d'usage
* Base technologique pérenne (PostgreSQL en croissance)
* Possibilité d'utiliser des extensions avancées

### Négatives

* Investissement formation : 3 semaines pour l'équipe
* Migration des outils internes : 2 sprints estimés
* Besoin de recruter un DBA avec expertise PostgreSQL

### Neutres

* Les applications MySQL existantes restent sur MySQL
* Revue dans 12 mois pour valider les hypothèses de performance

## Liens

* Supersedes: ADR-0023 (Use MySQL for all databases)
* Benchmarks: /docs/benchmarks/database-comparison-2024.md
* RFC associée: /docs/rfc/0015-database-strategy.md

Cycle de vie d’un ADR

Un ADR n’est pas un document figé — il évolue selon un cycle de vie défini :

Les quatre statuts

Proposed

Proposed : la décision est en cours de discussion.

L’ADR est rédigé mais pas encore validé. C’est le moment des revues, des commentaires, des ajustements.

## Status
Proposed

Reviewers: @alice, @bob
Discussion: https://github.com/org/repo/pull/123

Accepted

Accepted : la décision est validée et active.

L’équipe s’engage à respecter cette décision. Tout nouveau code doit s’y conformer.

## Status
Accepted

Accepted by: Architecture Board
Date: 2024-01-15

Deprecated

Deprecated : la décision n’est plus pertinente.

Le contexte a changé, mais il n’y a pas de remplacement direct. Par exemple, un composant entier a été supprimé.

## Status
Deprecated

Deprecated: 2024-06-01
Reason: Service X has been decommissioned

Superseded

Superseded : la décision est remplacée par une nouvelle.

Un nouvel ADR a été créé avec une décision différente. L’ancien ADR reste lisible pour l’historique.

## Status
Superseded by ADR-0067

Superseded: 2024-06-15
See: docs/adr/0067-migrate-to-cockroachdb.md

Règle d'or

Un ADR n’est jamais modifié après acceptation. Si le contexte change, créez un nouvel ADR qui référence l’ancien. Cela préserve l’historique des décisions.

Quand rédiger un ADR ?

Toutes les décisions ne méritent pas un ADR. Voici comment identifier celles qui le nécessitent.

Le test des « 5 pourquoi inversés »

Si vous pouvez répondre « oui » à au moins 3 de ces questions, un ADR est justifié :

1. Coût de changement : cette décision sera-t-elle coûteuse à modifier plus tard ?
2. Impact équipe : plusieurs personnes seront-elles affectées ?
3. Durée de vie : cette décision sera-t-elle pertinente dans 2 ans ?
4. Alternatives : avez-vous évalué plusieurs options ?
5. Risque de réinterprétation : quelqu’un pourrait-il mal comprendre ce choix ?

Exemples concrets

Décision	ADR nécessaire ?	Raison
Choix du langage principal	Oui	Impact majeur, durée de vie longue
Choix du framework web	Oui	Coût de changement élevé
Stratégie de branching Git	Oui	Impact équipe, réinterprétation possible
Nom d’une variable	Non	Impact négligeable
Choix entre deux librairies HTTP	Selon contexte	Dépend de la criticité
Architecture microservices vs monolithe	Absolument	Décision fondamentale

Signal chez Spotify

Chez Spotify, un bon indicateur est : « Si cette décision génère une discussion de plus de 30 minutes en réunion, elle mérite un ADR. »

Anti-patterns à éviter

1. L’ADR roman

Symptôme : ADR de plus de 3 pages.

Problème : personne ne le lira. L’ADR perd sa fonction de référence rapide.

Solution : un ADR = une décision. Si vous avez besoin de plus d’espace, c’est que vous documentez plusieurs décisions.

2. L’ADR sans alternatives

Symptôme : « Nous avons choisi X » sans mentionner Y et Z.

Problème : le lecteur ne comprend pas pourquoi X plutôt qu’autre chose.

Solution : toujours documenter au moins 2-3 options évaluées, même si le choix semblait évident.

## Options considérées

### Option 1 : Ne rien faire
Maintenir l'architecture actuelle.
**Rejeté** : ne résout pas le problème de scalabilité.

### Option 2 : Solution choisie
[...]

3. L’ADR post-mortem

Symptôme : ADR rédigé 6 mois après la décision.

Problème : le contexte est oublié, les alternatives ne sont plus claires.

Solution : rédiger l’ADR au moment de la décision, même en version draft.

4. L’ADR orphelin

Symptôme : ADR jamais référencé, non intégré au workflow.

Problème : les développeurs ne savent pas qu’il existe.

Solution : intégrer les ADR au processus de revue de code, les lier dans les README.

5. L’ADR trop technique

Symptôme : ADR incompréhensible pour quelqu’un hors de l’équipe immédiate.

Problème : perd sa valeur de transmission de connaissance.

Solution : un bon ADR doit être compréhensible par un développeur rejoignant l’équipe.

Outils et intégration

Structure de fichiers recommandée

project/
├── docs/
│   └── adr/
│       ├── 0000-use-adr.md
│       ├── 0001-use-typescript.md
│       ├── 0002-choose-react-framework.md
│       ├── 0003-api-rest-vs-graphql.md
│       └── template.md
├── src/
└── README.md

Convention de nommage

Le format NNNN-titre-en-kebab-case.md est le standard. Le numéro à 4 chiffres permet le tri chronologique et l’identification rapide.

adr-tools : CLI pour gérer vos ADR

L’outil adr-tools ↗ automatise la gestion des ADR :

Installation et utilisation

# Installation (macOS)
brew install adr-tools

# Initialiser le dossier ADR
adr init docs/adr

# Créer un nouvel ADR
adr new "Use PostgreSQL for main database"
# Crée docs/adr/0001-use-postgresql-for-main-database.md

# Marquer un ADR comme superseded
adr new -s 1 "Migrate to CockroachDB"
# Crée 0002 et met à jour le statut de 0001

# Générer une table des matières
adr generate toc > docs/adr/README.md

# Générer un graphe des liens
adr generate graph | dot -Tpng > docs/adr/graph.png

Log4brains : interface web pour ADR

Log4brains ↗ génère un site web navigable à partir de vos ADR :

Installation et utilisation

# Installation
npm install -g log4brains

# Initialiser dans un projet existant
log4brains init

# Prévisualiser en local
log4brains preview

# Générer le site statique
log4brains build

L’outil génère une interface web avec recherche, filtres par statut, et graphe des dépendances entre ADR.

Intégration CI/CD

Automatisez la validation des ADR dans votre pipeline :

.github/workflows/adr-check.yml

name: ADR Validation

on:
  pull_request:
    paths:
      - 'docs/adr/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate ADR format
        run: |
          for file in docs/adr/[0-9]*.md; do
            # Vérifier la présence des sections obligatoires
            grep -q "## Status" "$file" || echo "Missing Status in $file"
            grep -q "## Context" "$file" || echo "Missing Context in $file"
            grep -q "## Decision" "$file" || echo "Missing Decision in $file"
          done

      - name: Check sequential numbering
        run: |
          expected=1
          for file in docs/adr/[0-9]*.md; do
            num=$(basename "$file" | cut -d'-' -f1 | sed 's/^0*//')
            if [ "$num" != "$expected" ]; then
              echo "Gap in numbering: expected $expected, got $num"
            fi
            expected=$((expected + 1))
          done

Exemple complet : ADR réel

Voici un exemple d’ADR issu d’un projet réel (anonymisé) :

docs/adr/0015-use-event-sourcing-for-orders.md

# ADR-0015 : Utiliser l'Event Sourcing pour le domaine Commandes

## Statut

Accepted

Date: 2024-02-20
Auteurs: Marie Dupont, Jean Martin
Reviewers: Équipe Architecture

## Contexte et problème

Le système de gestion des commandes actuel utilise un modèle CRUD classique.
Nous rencontrons plusieurs problèmes :

1. **Audit insuffisant** : impossible de retracer l'historique complet d'une commande
2. **Conflits de mise à jour** : les modifications concurrentes créent des incohérences
3. **Analyse métier limitée** : les données historiques sont perdues après mise à jour
4. **Conformité RGPD** : difficulté à prouver l'historique des consentements

Le volume actuel est de 50 000 commandes/jour, projection à 200 000 dans 18 mois.

## Decision Drivers

* Traçabilité complète de chaque modification
* Performance en lecture (dashboards temps réel)
* Capacité de « replay » pour correction d'erreurs
* Conformité audit SOC 2

## Options considérées

### Option 1 : Ajouter une table d'audit

Conserver le modèle CRUD et ajouter une table `order_audit` avec triggers.

**Avantages** :
- Changement minimal du code existant
- Équipe familière avec l'approche

**Inconvénients** :
- Ne résout pas les conflits de concurrence
- Performance des triggers à grande échelle
- Audit partiel (pas toutes les modifications)

### Option 2 : Event Sourcing (choisi)

Stocker chaque modification comme un événement immuable.
Reconstituer l'état courant par projection des événements.

**Avantages** :
- Traçabilité totale par design
- Résout la concurrence (append-only)
- Permet le replay et les projections multiples
- Adapté aux patterns CQRS

**Inconvénients** :
- Courbe d'apprentissage (pattern peu connu de l'équipe)
- Complexité des migrations de schéma d'événements
- Besoin d'un event store (infrastructure nouvelle)

### Option 3 : Temporal tables (SQL Server)

Utiliser les temporal tables natives de SQL Server.

**Avantages** :
- Intégré au SGBD
- Pas de changement d'architecture

**Inconvénients** :
- Vendor lock-in
- Pas de support pour les projections personnalisées
- Limité aux requêtes SQL

## Décision

**Nous adoptons l'Event Sourcing pour le domaine Commandes.**

L'implémentation utilisera :
- EventStoreDB comme event store (open-source, optimisé pour ce pattern)
- Projections vers PostgreSQL pour les lectures
- Format CloudEvents pour la structure des événements

## Conséquences

### Positives

* Audit natif : chaque changement est un événement horodaté
* Résolution de la concurrence par versioning des agrégats
* Nouvelles possibilités : replay, what-if analysis, debug temporel
* Base solide pour futures fonctionnalités analytiques

### Négatives

* 4 semaines de formation équipe (workshop Event Sourcing)
* 2 sprints pour migration du domaine Commandes existant
* Nouvelle infrastructure : cluster EventStoreDB à provisionner
* Complexité accrue pour les développeurs juniors

### Actions requises

1. [ ] Formation équipe (S1-S2)
2. [ ] Provisioning EventStoreDB (S2)
3. [ ] Migration progressive domaine Commandes (S3-S6)
4. [ ] Documentation des patterns pour autres domaines

## Liens

* RFC: /docs/rfc/0008-event-sourcing-strategy.md
* Benchmark: /docs/benchmarks/eventstore-performance.md
* Formation: https://internal-wiki/event-sourcing-workshop

Checklist avant validation

Avant de marquer un ADR comme « Accepted », vérifiez :

• Titre : actionnable et clair (« Use X for Y »)
• Contexte : le problème est compréhensible sans contexte externe
• Alternatives : au moins 2 options documentées
• Décision : clairement identifiable en 30 secondes
• Conséquences : positives ET négatives listées
• Longueur : moins de 2 pages imprimées
• Public : compréhensible par un nouveau membre de l’équipe
• Liens : références vers documents connexes si nécessaire

Pour aller plus loin

Runbooks : procédures d'urgence Le complément opérationnel des ADR

Postmortems blameless Quand une décision a des conséquences inattendues

Documentation opérationnelle Comment documenter au quotidien

Service Overview Documenter vos services avec contexte

Références externes

• Documenting Architecture Decisions ↗ — Article fondateur de Michael Nygard
• MADR Template ↗ — Template Markdown enrichi
• adr-tools ↗ — CLI pour gérer les ADR
• Log4brains ↗ — Générateur de site ADR
• ADR GitHub Organization ↗ — Ressources et exemples