ADR - Architecture Decision Record

À quoi sert ce document

L'ADR consigne une décision technique au moment où elle se prend, avec les contraintes qui la rendaient raisonnable. Sa force est son coût : une page, écrite pendant la discussion, versionnée à côté du code. Les ADR forment un journal des choix qui évite deux pathologies classiques, redébattre indéfiniment un arbitrage déjà rendu, et casser sans le savoir un équilibre construit pour une raison précise. Une décision remplacée n'est jamais supprimée : elle passe au statut « remplacée par » et reste lisible.

Quand le produire

• Pour tout choix coûteux à défaire : découpage, protocole, base de données, framework, format d'échange.
• Quand deux options défendables ont été comparées et qu'il faut mémoriser pourquoi l'une a gagné.
• Quand une contrainte externe impose un choix qui paraîtra incompréhensible plus tard.
• Quand on décide sciemment de ne pas faire quelque chose. Les non-décisions se perdent encore plus vite.

Le plan, rubrique par rubrique

1. Titre

   Un numéro et une phrase qui énonce la décision, pas le sujet.

   • Numérotation continue et immuable (ADR-014)
   • « Utiliser un format Parquet pour les fichiers d'échange » plutôt que « Choix du format de fichier »

2. Statut

   L'état de la décision dans son cycle de vie.

   • Proposée, acceptée, rejetée, dépréciée, remplacée par ADR-nnn
   • Date de changement de statut

3. Contexte

   Les forces en présence au moment de la décision. Le passage le plus utile trois ans après.

   • Problème à résoudre et contraintes applicables
   • Contraintes non techniques : délai, compétences, budget, politique interne
   • Ce qui est tenu pour acquis au moment de décider

4. Options envisagées

   Les alternatives réellement étudiées, avec ce qui plaidait pour et contre chacune.

   • Option, avantages, inconvénients
   • Raison de l'écarter

5. Décision

   Ce qui est retenu, formulé à l'affirmative et sans conditionnel.

6. Conséquences

   Ce qui devient plus facile, ce qui devient plus difficile, ce qu'il faudra surveiller.

   • Conséquences positives
   • Conséquences négatives acceptées
   • Impacts sur les autres composants, sur l'exploitation, sur les compétences à acquérir
   • Conditions qui justifieraient de revenir sur la décision

Les erreurs qui coûtent cher

• Écrire l'ADR trois mois après la décision. La fiche fait partie de la décision, pas de son archivage : passé un délai, les contraintes réelles ont déjà été oubliées.
• Supprimer ou réécrire un ADR devenu faux. Il passe au statut « remplacé » : l'historique des choix est précisément ce qui a de la valeur.
• Ne consigner que les conséquences positives. Un ADR sans coût accepté n'a pas décrit un arbitrage, il a décrit une justification.
• En faire un document de dix pages. La brièveté est ce qui rend la pratique tenable dans la durée.