Fiche ADR

Ce que c'est

Une fiche ADR consigne une décision d'architecture qui aura des
conséquences sur la suite du projet. Le sigle vient de l'anglais
architecture decision record. La fiche indique ce que l'équipe a
choisi, dans quelles circonstances, quelles options étaient
sérieuses et quelles conséquences ont été acceptées. Elle peut
porter sur la responsabilité d'un registre, la frontière entre deux
services, leur mode d'échange ou la réaction prévue quand un
composant tombe en panne. Une personne qui arrive plus tard peut
ainsi comprendre les raisons du choix et vérifier si ses hypothèses
tiennent encore.

Le format peut rester simple. Un numéro et une date permettent de
citer la fiche. Le statut indique si elle est proposée, adoptée ou
remplacée. Le contexte expose la difficulté et les contraintes
concrètes. La décision décrit ce qui sera mis en œuvre. Les
conséquences couvrent aussi bien les avantages que les obligations.
Il peut falloir exploiter un nouveau service, prévoir une transition
plus longue ou répéter une migration. Il suffit de décrire les
options avec assez de précision pour que le lecteur saisisse
l'arbitrage.

Publier le texte à un endroit familier fait gagner du temps. Une
équipe peut ranger ses fichiers Markdown à côté du code et les citer
dans les modifications qui exécutent la décision. Un projet réparti
entre plusieurs dépôts peut tenir un index commun. Une adresse
durable et une motivation compréhensible sont utiles au moment du
transfert. La fiche peut renvoyer aux mesures, contraintes et essais
qui permettent de vérifier les faits de départ.

Pourquoi c'est important

Le code renseigne bien sur l'état présent. Les raisons d'un choix
ancien y apparaissent souvent de façon incomplète. Deux bases
peuvent ressembler à un doublon qu'il faudrait supprimer. La
séparation a peut-être servi à contenir un risque pendant qu'un
fournisseur changeait son format d'export. La fiche explique ce que
l'équipe protégeait, pourquoi elle a pris ce chemin et quel
événement conduirait à réexaminer le choix. Elle évite une nouvelle
enquête chaque fois que la question revient.

La fiche aide aussi à formuler un désaccord précis. Une dépendance
peut dispenser l'équipe de développer un ordonnanceur. La personne
d'astreinte devra toutefois savoir rétablir l'état de ce composant
après une interruption. Un collègue peut demander si l'accès et les
compétences seront disponibles. L'équipe d'exploitation peut lire le
même raisonnement avant que le choix soit arrêté. Ensuite, les
personnes qui reprennent le service y trouvent les engagements pris
et la répartition des responsabilités.

Adaptez l'effort au coût d'un retour sur la décision. Modifier un
libellé se comprend d'habitude en consultant l'historique des
changements. Transférer la responsabilité du registre de commandes
ou revoir la gestion des paiements en double touche plusieurs
équipes. Rédigez pendant que les solutions envisagées sont encore
présentes à l'esprit. Conservez une trace des éléments disponibles à
cette date, afin que la personne suivante puisse expliquer la
décision à partir de ce que l'équipe savait alors.

À quoi cela ressemble en pratique

Le portfolio présente les choix techniques fondateurs d'une
plateforme, faits au moment où se dessinait le produit. Ce travail
illustre le genre d'arbitrage dont les raisons méritent d'être
conservées. L'exercice fictif suivant présente une façon de
documenter le choix du système responsable de certaines données.

Un service d'expédition possède une base de commandes et une page
publique où chaque client consulte le statut de ses propres envois.
Des événements arrivent parfois en retard. La page ne doit pas
révéler les commandes d'un autre client. L'équipe choisit un modèle
de lecture séparé qui ne reçoit que les champs autorisés. Une
lecture directe aurait nécessité moins de composants et fourni des
données généralement plus fraîches. Elle aurait rapproché le trafic
public et une nouvelle frontière d'accès du registre de référence.
Réutiliser un export de nuit aurait été simple, mais les
modifications du jour auraient échappé à la page.

Les conséquences se traduisent en tâches. Le support a besoin d'un
indicateur de retard pour savoir quand employer la procédure
interne. Un test du contrat peut détecter un champ introduit par
erreur. Le traitement de mise à jour et l'alerte doivent avoir un
responsable. L'équipe fixe une révision si le retard dépasse le
seuil convenu pendant deux semaines chargées ou si les règles de
séparation changent. La fiche renvoie à la revue de conception et au
test qui matérialise l'engagement.

Quand une nouvelle solution devient nécessaire, ouvrez une nouvelle
fiche et ajoutez des liens dans les deux sens. Le raisonnement
précédent reste utile à l'examen d'une version ancienne. Un index
court avec titres, dates et statuts aide à repérer le choix qui
s'applique.

Avant de fournir un statut, le service public vérifie que la
personne peut consulter cette commande précise. Testez le refus pour
une commande d'un autre client et les champs exacts de la réponse
autorisée.

Où les problèmes surviennent

Une fiche convainc peu quand elle défend le choix retenu et
caricature les autres possibilités. Présentez les meilleurs
arguments qui ont vraiment été avancés. Une autre équipe pourrait,
sous d'autres conditions, avoir raison de choisir autrement.
Rattachez une affirmation importante à la mesure, à la norme ou à
l'engagement concret qui l'a motivée.

Un autre écueil consiste à décrire les avantages en laissant les
coûts sans responsable. Une base supplémentaire ou une file partagée
change le quotidien d'une autre équipe. Indiquez qui exploite le
service, qui tient à jour les autorisations et qui assure la
maintenance. Si une conséquence reste à démontrer, précisez ce qu'il
sera possible d'observer et à quel moment.

Enfin, limitez le volume à ce que l'équipe peut écrire au moment où
elle décide. Une procédure d'exploitation évolue à un autre rythme
et peut rester dans son document, avec un lien. Lors d'un nouveau
choix, conservez la motivation de l'ancien et indiquez clairement
lequel s'applique. Le lecteur n'aura pas besoin de reconstituer le
projet à partir des conversations.

Pour aller plus loin

  * Guide AWS sur le processus de décision d’architecture

  * Microsoft Azure Well-Architected sur les fiches de décision

  * Cadre britannique pour les décisions d’architecture

hCette page sur le Web	URL:https://engineer.company/fr/glossary/architecture-decision-record/	engineer.company	70
