ADR : décider par écrit

Prérequis : aucun (pratique transverse).

Pourquoi

« Pourquoi on a fait comme ça ? » — 6 mois plus tard, personne ne sait, alors on défait (et on refait la même erreur). L'ADR (Architecture Decision Record) fige le contexte, le choix et ses conséquences en une page.

Concepts

• Format : Titre + date + statut (proposé/accepté/déprécié) + contexte (le problème, les contraintes) + décision + conséquences (ce qu'on gagne, ce qu'on perd, ce qu'on fera si ça rate). Une page, pas un mémoire.
• Où : dans le repo (docs/adr/0007-postgres-plutot-que-mongo.md), numérotés, immuables (une décision changée = nouvelle ADR qui remplace, on n'édite pas le passé).
• Quand : choix structurants (stack, découpage, protocole, fournisseur) — pas chaque if. Seuil : « le regretterait-on dans 6 mois sans trace ? ».

Exemple : squelette

# 0007. Postgres plutôt que Mongo pour les commandes
Date : 2026-03-14 — Statut : accepté
Contexte : besoin de transactions multi-lignes + équipe SQL.
Décision : Postgres, JSONB pour le flexible.
Conséquences : +transactions, +compétences ; -scaling horizontal simple.
Si échec : réévaluer à 100k commandes/jour.

Cas réel

Migration « évidente » vers le nouveau framework à la mode, refaite 2 ans après le choix initial… dont personne ne retrouvait les raisons (licence ? perf ?). L'ADR d'origine disait : « écarté pour X ». Trois semaines perdues à redécouvrir X.

Pièges

• ADR de 10 pages que personne ne lit : une page, vocabulaire simple, conséquences honnêtes (y compris les inconvénients !).
• Décisions orales « on s'est compris » : famous last words — écrit ou oublié.
• Statuts jamais mis à jour : une ADR « acceptée » pour un choix abandonné ment. Déprécier explicitement.

À retenir

Une page par choix structurant, contexte + décision + conséquences, immuable et numérotée.