# 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

=> /fr/portfolio/set-the-platforms-founding-technical-decisions/ les choix techniques fondateurs d'une plateforme
=> https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html Guide AWS sur le processus de décision d’architecture
=> https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record Microsoft Azure Well-Architected sur les fiches de décision
=> https://www.gov.uk/government/publications/architectural-decision-record-framework Cadre britannique pour les décisions d’architecture

=> https://engineer.company/fr/glossary/architecture-decision-record/ Cette page sur le Web
