Documenter les décisions (ADR)¶

Capturer le contexte de chaque choix pour que les décisions survivent au turnover.

Pourquoi documenter les décisions¶

Les décisions architecturales sont prises une fois, mais leurs conséquences durent des années. Un ADR (Architecture Décision Record) capture le contexte qui a rendu une décision rationnelle — ce qui permet de la revisiter quand ce contexte change.

Sans ADR, les équipes rejouent les mêmes debats à chaque rotation de personnel. Avec des ADR, la décision est accessible avec son contexte original : les alternatives considérées, les contraintes du moment, les conséquences anticipees.

Un ADR ne justifie pas un choix après coup. Il documente le raisonnement au moment où le choix est fait — avec les informations disponibles a cet instant. C'est cette honnetete temporelle qui donne sa valeur à l'ADR six mois ou deux ans plus tard.

Structure d'un ADR¶

Un ADR contient quatre sections :

• Titre : identifiant court et descriptif (ADR-001 : Utiliser PostgreSQL comme base principale)
• Contexte : le problème a résoudre et les faits pertinents au moment de la décision — équipe, contraintes, alternatives envisagees
• Décision : ce qui a été choisi, sans ambiguite
• Conséquences : les implications positives et negatives — ce que la décision rend possible et ce qu'elle sacrifie

Templates d'ADR¶

Deux templates dominent dans la pratique. Le choix dépend de la culture de l'équipe.

Template Nygard (original)¶

Le format propose par Michael Nygard en 2011. Minimaliste et efficace.

# ADR-NNN : Titre court et descriptif

**Statut :** proposed | accepted | deprecated | superseded

## Contexte
Le probleme, les faits, les forces en jeu.

## Decision
Ce qu'on a decide de faire.

## Consequences
Ce qui decoule de cette decision — positif et negatif.

Template MADR (Markdown Any Décision Records)¶

Le format MADR ajoute la section "Options considérées" comme élément structurant. Il force l'explicitation des alternatives.

# ADR-NNN : Titre court et descriptif

**Statut :** proposed | accepted | deprecated | superseded
**Date :** YYYY-MM-DD
**Decideurs :** noms des personnes impliquees

## Contexte et probleme
Quelle est la question a laquelle on repond ?

## Facteurs de decision
- Critere 1
- Critere 2
- Critere 3

## Options considerees

### Option 1 : Nom
Description, avantages, inconvenients.

### Option 2 : Nom
Description, avantages, inconvenients.

### Option 3 : Nom
Description, avantages, inconvenients.

## Decision
Option choisie et justification.

## Consequences

### Positif
- ...

### Negatif
- ...

### Neutre
- ...

Workflow des ADR¶

graph LR
    P[proposed] --"validation collective"--> A[accepted]
    A --"contexte invalide"--> D[deprecated]
    A --"remplace par un nouvel ADR"--> S[superseded]
    D --"nouveau besoin"--> P2[nouveau proposed]
    S --"reference le successeur"--> P2

Un ADR passe par proposed lors de sa rédaction initiale, accepted après validation collective, deprecated si la décision n'est plus pertinente sans successeur identifié, et superseded quand un nouvel ADR prend le relai avec un lien explicite.

Processus de validation¶

La validation d'un ADR dépend de la gouvernance en place :

Quand créer un ADR¶

Tout choix qui répond "oui" à l'une de ces questions merite un ADR :

• Le choix est difficile à inverser ?
• Le choix impacte plusieurs équipes ou composants ?
• Des alternatives crédibles ont été considérées et éliminée ?
• Des personnes raisonnables pourraient ne pas être d'accord ?

Un ADR par semaine dans un projet actif est normal. Trop peu signifie que des décisions implicites sont prises sans documentation.

Décisions qui meritent un ADR¶

• Choix de base de données, langage, framework
• Style d'architecture (monolithe, microservices, serverless)
• Stratégie d'authentification et d'autorisation
• Choix de fournisseur cloud ou de service manage
• Stratégie de déploiement (blue-green, canary, rolling)
• Patterns d'intégration (API REST, événements, GRPC)
• Stratégie de tests (pyramide, ratios, outils)

Décisions qui ne meritent pas un ADR¶

• Conventions de nommage (→ linter config)
• Choix d'une librairie utilitaire mineure (→ PR review)
• Configuration d'un outil CI (→ documentation ops)
• Correction de bug (→ commit message)

Exemple complet¶

# ADR-001 : Utiliser PostgreSQL comme base principale

**Statut :** accepted
**Date :** 2026-03-10
**Decideurs :** equipe backend (Alice, Bob, Carol)

## Contexte

L'equipe connait PostgreSQL et dispose d'expertise operationnelle sur ce moteur.
Le domaine metier requiert des transactions ACID pour les operations de commande.
Le volume de donnees projete est inferieur a 10 TB sur 3 ans.
Aucun besoin identifie de requetes geospatiales complexes ou de donnees time-series natives.

Alternatives considerees :
- MySQL : moins bon support JSON et CTEs recursives, pas d'avantage identifie
- MongoDB : pas de transactions ACID natives avant v4, expertise equipe inexistante
- CockroachDB : distribue mais overkill pour le volume projete, cout superieur

## Decision

Adopter PostgreSQL 16 en mode managed (Cloud SQL sur GCP).
Le choix managed reduit la charge operationnelle : backups automatiques,
patches de securite, failover automatique en cas de panne de zone.

## Consequences

Positif :
- Transactions ACID sans configuration supplementaire
- Expertise equipe exploitable immediatement
- Ecosystem riche : extensions, ORMs, tooling de migration (Flyway, Liquibase)

Negatif / Attention :
- Pas de support natif pour les donnees time-series : utiliser TimescaleDB si ce besoin emerge
- Cout managed superieur a un self-hosted pour des volumes importants (> 5 TB)
- Vendor lock partiel sur Cloud SQL : migration vers un autre provider possible mais non triviale

Outillage¶

adr-tools (CLI)¶

L'outil adr-tools de Nat Pryce automatise la gestion des ADR en ligne de commande :

# Initialiser le repertoire ADR
adr init docs/adr

# Creer un nouvel ADR
adr new "Utiliser PostgreSQL comme base principale"

# Marquer un ADR comme superseded
adr new -s 1 "Migrer vers CockroachDB pour la scalabilite"

# Generer une table des matieres
adr generate toc

# Generer un graphe de liens entre ADR
adr generate graph

L'outil généré des fichiers Markdown numerotes dans le répertoire cible. La numerotation séquentielle est gérée automatiquement.

log4brains¶

log4brains est un outil plus récent qui généré un site web statique à partir des ADR. Il ajoute :

• Navigation par tags et par statut
• Timeline chronologique
• Recherche plein texte
• Preview en local avant publication
• Intégration CI pour publier automatiquement

# Installation
npm install -g log4brains

# Initialisation
log4brains init

# Preview local
log4brains preview

# Build du site statique
log4brains build

Comparaison des outils¶

ADR en pratique¶

Lier les ADR au code¶

Un ADR est plus utile quand il est lie au code qu'il impacte :

• Dans les PR : mentionner l'ADR dans la description de la PR qui implémenté la décision
• Dans le code : ajouter un commentaire // See ADR-001 a proximite du code impacte
• Dans la CI : un ADR peut déclencher la création d'architecture fitness functions qui valident la décision en continu

Revue périodique¶

Les ADR ne sont pas eternels. Mettre en place une revue périodique (trimestrielle ou semestrielle) pour identifier :

• Les ADR dont le contexte a change (nouvelles contraintes, équipe différente)
• Les ADR deprecated qui n'ont pas encore de successeur
• Les décisions implicites qui manquent d'ADR

Métriques de sante¶

Quelques indicateurs pour évaluer si la pratique ADR fonctionne :

Stockage et organisation¶

Convention de nommage¶

docs/adr/
  0001-utiliser-postgresql.md
  0002-architecture-monolithe-modulaire.md
  0003-authentification-via-keycloak.md
  0004-strategie-deploiement-blue-green.md
  0005-migration-vers-cockroachdb.md    # supersedes 0001

La numerotation séquentielle a quatre chiffres est la convention la plus repandue. Elle permet le tri naturel dans le système de fichiers et dans les outils.

Organisation multi-équipe¶

Dans une organisation avec plusieurs équipes, deux stratégies :

• ADR centralises : un seul dépôt d'ADR pour toute l'organisation. Avantage : vue globale. Inconvénient : goulot d'étranglement.
• ADR distribués : chaque équipe a ses ADR dans son dépôt. Les ADR transversaux vivent dans un dépôt d'architecture partage. Avantage : autonomie. Inconvénient : fragmentation.

La stratégie distribuée fonctionne mieux à l'échelle, à condition qu'un index central référence tous les ADR transversaux.

Anti-patterns ADR¶

Chapitre suivant : Modeliser le contexte (C4) — quatre niveaux de zoom pour communiquer l'architecture au bon public.