Introduction à l'ADR (Architecture Decision Record) — la méthode minimale pour conserver « pourquoi on a choisi cette conception » sur un petit projet

« Pourquoi c’est un échange de fichiers ici ? On ne pourrait pas simplement consulter la base directement ? » — un développeur qui ouvre le code d’un système dont il vient d’hériter tombe presque toujours sur ce genre de question. Et dans la plupart des cas, la personne qui connaissait la réponse a déjà quitté le projet.

Il y avait sûrement une raison. Peut-être que l’autorisation de se connecter directement à la base de données du système partenaire n’avait jamais été accordée, ou peut-être que c’était la seule méthode suffisamment sûre pour tenir les délais de l’époque. Mais si cette raison n’a pas été conservée, le successeur se retrouve figé devant du code dont il ne sait pas s’il peut y toucher — ou, à l’inverse, fonce et détruit la raison même que ce code protégeait.

Sur ce blog, nous avons déjà couvert la manière de mener un projet de développement sur mesure dans « Externalisation et développement sur mesure d’une application Windows : ce qu’il faut clarifier avant de se lancer », et le cadre contractuel dans « Choisir entre quasi-mandat et contrat d’entreprise — ce que nous enseigne le « Modèle de transaction et de contrat » de l’IPA ». Cet article se situe une étape plus loin : que faire pour qu’un système, une fois construit, continue de tenir plusieurs années. Nous présentons l’ADR (Architecture Decision Record), un mécanisme permettant de conserver la raison d’une décision de conception avec un effort minimal, en nous plaçant dans le contexte d’un développement sur mesure ou interne de petite taille.

1. La conclusion d’abord

• Avant même un document de conception exhaustif, c’est un journal des décisions qu’il faut conserver. Ce qui pose vraiment problème lors de la maintenance, ce n’est pas de ne pas savoir ce que fait le code, mais de ne pas savoir pourquoi il a été fait ainsi.
• Un ADR est un format léger qui consigne une décision unique dans un seul fichier, selon la structure fixe titre / statut / contexte / décision / conséquences. Michael Nygard l’a proposé en 2011, et la règle de base est d’une à deux pages par décision, au maximum.¹
• Il vit dans le même dépôt que le code (par exemple docs/adr/0001-title.md) — sous contrôle de version au côté du code, revu en même temps que la revue de code, plutôt que dans un wiki ou un dossier partagé.¹²
• Une décision ne s’écrase jamais. Quand vous changez de cap, ajoutez un nouvel ADR et faites passer le statut de l’ancien à Superseded, avec une référence croisée entre les deux. Un journal d’ADR est en ajout seul.²
• Plutôt que de tout consigner, ne rédigez un ADR que pour les décisions difficiles à changer plus tard, qui avaient plusieurs alternatives également raisonnables, ou qu’une contrainte a tranchées. Les règles de nommage et les réglages du formateur sont hors périmètre.²
• Dans mon expérience, tenir chaque fiche en 15 à 30 minutes de rédaction est ce qui fait que l’habitude survit dans la durée. Un modèle trop lourd s’éteint dès les trois premières entrées.
• En développement sur mesure, un ADR devient un livrable que vous pouvez partager avec le client. Il fonctionne tel quel comme document d’explication lors de la recette, et comme document de transmission lors d’un changement de personnel ou de prestataire.

2. Le problème du « pourquoi c’est comme ça, déjà ? »

2.1 Le code dit le Quoi, jamais le Pourquoi

En lisant le code, et en y passant le temps nécessaire, on finit par comprendre ce qu’il fait. Ce qu’on ne peut pas déduire, ce sont des « pourquoi » comme ceux-ci.

• Pourquoi la base de données est-elle SQLite plutôt que SQL Server ?
• Pourquoi l’intégration avec l’autre système passe-t-elle par des fichiers CSV plutôt que par une API web ?
• Pourquoi seul ce rapport lance-t-il Excel pour imprimer ?
• Pourquoi le projet est-il encore sur .NET Framework au lieu d’avoir été porté vers le .NET actuel ?

Derrière des décisions comme celles-ci, il y a toujours une raison qui vit en dehors du code lui-même — le budget et le délai de l’époque, des contraintes côté client, un arbitrage avec les actifs existants. C’est trop volumineux pour tenir dans un commentaire, et « l’historique de la façon dont on est arrivé à cette décision » ne trouve pas facilement sa place dans un document de conception non plus. Le résultat, c’est que la raison ne survit nulle part.

2.2 Tous les endroits où l’on conserve habituellement une décision disparaissent en quelques années

Alors, où vit réellement aujourd’hui la raison derrière une décision de conception ? Comparons les emplacements les plus courants.

Les recommandations d’architecture de Microsoft font exactement le même constat : une décision non documentée finit par être oubliée, ce qui provoque la reprise du même débat et des changements qui vont à l’encontre de l’intention d’origine.²

2.3 En développement sur mesure, une rupture de contrat est une rupture de mémoire

Pour un développement interne, « il suffit de demander à telle personne » fonctionne un moment, mais en développement sur mesure s’ajoute, en plus des mutations et départs de personnel, un changement de prestataire. Au moment où le prestataire qui a développé le système et celui qui en assure la maintenance deviennent deux entreprises distinctes, tout le « pourquoi » qui vivait dans les conversations orales et les messages de chat disparaît complètement.

Du point de vue contractuel aussi, il est tout à fait normal que développement et maintenance relèvent de contrats et de phases distincts (nous avons couvert cette structure dans notre article expliquant le « Modèle de transaction et de contrat » de l’IPA). Et sous un contrat de quasi-mandat, précisément parce que le prestataire mène le travail de façon autonome, un enregistrement qu’il peut montrer au client — de ce qui a été décidé et comment — devient la preuve qui étaye cette confiance. L’ADR aide sur ces deux fronts à la fois.

3. Qu’est-ce qu’un ADR

3.1 La proposition de Nygard — cinq éléments et un plafond de deux pages

L’ADR est le format que Michael Nygard a proposé dans son article de blog de 2011, « Documenting Architecture Decisions ».¹ Les points principaux sont les suivants.

• Un fichier par décision. Les numéroter séquentiellement, et ne jamais réutiliser un numéro
• Garder le fichier dans un format léger comme Markdown, à l’intérieur du dépôt du projet
• Structurer autour de cinq éléments : titre / statut / contexte / décision / conséquences
• Le statut progresse de proposé (proposed) à approuvé (accepted), et lorsqu’il est infirmé, passe à obsolète (deprecated) ou remplacé (superseded). Ne jamais supprimer l’ancien enregistrement
• Tenir l’ensemble en une à deux pages, rédigées en prose complète, qu’un futur développeur peut lire comme une conversation

Malgré le mot « architecture » dans le nom, ce n’est pas une technique réservée aux grands systèmes. Bien au contraire, ce format minimal et fixe est particulièrement efficace sur les petites équipes, sans architecte dédié ni personne assignée à la documentation. Les modèles et outils d’ADR sont aussi organisés de façon systématique sur le site communautaire (adr.github.io), qui constitue un bon point d’entrée pour l’idée de « consigner une décision architecturalement significative avec sa justification et ses compromis ».³

3.2 Un modèle Markdown

Voici le modèle minimal que j’utilise sur les petits projets, en restant fidèle au format original de Nygard.

# ADR-NNNN : (résumez la décision en une courte phrase)

## Statut

Proposé | Approuvé | Obsolète | Remplacé (→ ADR-MMMM)

## Contexte

Pourquoi cette décision est-elle devenue nécessaire ? Décrivez les
hypothèses techniques et métier, les contraintes (budget, délai,
actifs existants, environnement du client) et les alternatives
envisagées, d'une manière qu'un lecteur qui ne connaît pas le
contexte de l'époque puisse quand même suivre.

## Décision

Formulez-la de façon directe, à la voix active : « Nous allons faire X. »
Une à trois phrases.

## Conséquences

Décrivez à la fois ce qui s'améliore et ce qui se dégrade (les
compromis) du fait de cette décision. S'il existe une condition
qui justifierait de la reconsidérer plus tard, notez-la aussi.

Le point clé est d’écrire aussi les points négatifs dans Conséquences. Une décision sans compromis vaut à peine la peine d’être consignée. Les recommandations de Microsoft insistent également sur le fait de ne pas cacher les conséquences d’une décision, que ce soit intentionnellement ou par accident, et qu’un enregistrement sans justification perd de sa valeur avec le temps.²

4. Ce qu’il faut écrire dans un ADR, et ce qu’il ne faut pas écrire

La première cause d’abandon des ADR, c’est de vouloir en rédiger un pour tout. Les recommandations de Microsoft indiquent de limiter ce qu’on consigne aux éléments qui affectent la structure du système ou un attribut de qualité important, et qui sont difficiles à revenir en arrière.² Traduit en règle pratique du quotidien, cela donne le tableau suivant.

En cas de doute, il n’y a qu’un seul test : la personne qui regardera ce code dans un an — vous y compris — aurait-elle envie de demander pourquoi ? Si oui, rédigez-le ; si c’est évident à la lecture du code ou des réglages, ne le faites pas.

Un autre piège consiste à raisonner sur le bon niveau de granularité en termes de « type de document ». Décider à l’avance de cette répartition des rôles, comme ci-dessous, lève les hésitations.

5. Faire vivre les ADR sur de petits projets en sous-traitance

5.1 Répertoire et nommage des fichiers

Créez docs/adr/ juste sous la racine du dépôt, et nommez les fichiers avec un numéro de séquence suivi d’un court slug.

docs/
  adr/
    0001-record-architecture-decisions.md
    0002-use-sqlite-for-local-storage.md
    0003-excel-report-via-com-automation.md
    0007-excel-report-via-openxml-library.md

Le geste classique consiste à faire de la toute première entrée un ADR portant sur la décision d’utiliser des ADR elle-même. Ainsi, un successeur peut comprendre toute la convention de fonctionnement rien qu’en ouvrant docs/adr/.

5.2 Quand rédiger, et qui relit

• Rédigez-le au moment même où la décision est prise. En clôture d’une discussion de conception, transformez la conclusion de la réunion en ADR le jour même. Comme on le verra plus loin, attendre pour tout rédiger d’un coup est voué à l’échec.
• Intégrez les ADR à la revue de code. Tout ce qu’on vérifie, c’est si une pull request touchant à une approche architecturale contient bien un ajout ou une mise à jour d’ADR. Aucune réunion d’approbation dédiée aux ADR n’est nécessaire — l’intégrer à la revue existante est la réponse réaliste pour une petite équipe. Garder les ADR sous contrôle de version fait aussi partie des recommandations de Microsoft.²
• Pour revenir sur une décision, rédigez un nouvel ADR et faites passer le statut de l’ancien à Superseded, avec une référence croisée entre les deux. Ne réécrivez jamais le corps. Ne pas modifier un enregistrement approuvé, et préserver l’historique via une chaîne de remplacements — c’est exactement ce que signifie traiter un ADR comme un journal en ajout seul.²

5.3 L’ADR comme livrable partagé avec le client

En développement sur mesure, je recommande de partager les ADR avec le client comme partie des livrables. Il y a trois bénéfices.

1. Cela devient un support pour la recette et l’explication. Plutôt que d’expliquer oralement pourquoi le système est structuré ainsi, il suffit de montrer l’ADR. Comme le client est lui-même partie prenante des contraintes — budget, délai, environnement — qui ont motivé une décision, l’avoir noté par écrit évite un décalage de compréhension par la suite.
2. C’est une assurance contre un changement de prestataire. Du côté du client, le fait de disposer ou non d’un « historique des décisions » à transmettre au prochain prestataire change radicalement le coût et le risque de la transmission. Nous avons décrit comment s’organiser avant de passer commande dans « Externalisation et développement sur mesure d’une application Windows : ce qu’il faut clarifier avant de se lancer », mais au moment de décider, dans le contrat, quelle documentation doit survivre après la livraison, les ADR figurent parmi les options offrant le meilleur rapport valeur/effort.
3. Cela s’accorde bien avec le reporting du quasi-mandat. Un contrat de quasi-mandat impose de rendre compte de la façon dont le travail a été mené, et les ADR peuvent servir tels quels de rapport pour une phase de conception.

5.4 Un ordre de grandeur réaliste du temps que ça prend

Dans mon expérience, rédiger une entrée en suivant le modèle prend 15 à 30 minutes. Sur un petit projet, les décisions surviennent peut-être quelques fois par mois, si bien qu’un investissement d’une à deux heures par mois préserve tous les « pourquoi » sans exception. Comparé au temps perdu en investigation, en re-débat et en transmission quelques années plus tard, il y a peu de projets où cela ne se rentabilise pas.

6. Erreurs fréquentes

« Le rédiger d’un coup, plus tard » en particulier est un piège dans lequel on a tendance à tomber lorsqu’on introduit les ADR en cours de vie d’un système existant. Plutôt que de chercher à reconstituer chaque décision passée, l’approche réaliste consiste à remonter et rédiger seulement une poignée des décisions majeures dont on se souvient encore, puis à construire vers l’avant à partir des décisions d’aujourd’hui. Même sur un système existant (brownfield), cela vaut la peine de remonter et de consigner les décisions passées qu’on peut encore reconstituer.²

7. Exemples concrets d’ADR

Voici deux ADR complets sur des sujets qui reviennent souvent dans les petites applications métier Windows (le contenu est un exemple généralisé).

Le premier est une décision classique de choix technologique : la base de données.

# ADR-0002 : Stocker les données métier dans SQLite

## Statut

Approuvé (2026-07-17)

## Contexte

Ce système est une application de bureau de gestion des stocks pour
un site unique. Il y a deux ou trois utilisateurs, mais en pratique
elle est installée sur un seul PC partagé dans le bureau et utilisée
à tour de rôle (une seule personne à la fois). Le client n'a aucun
personnel capable d'exploiter un serveur de base de données sur
site, et il n'y a pas non plus de budget pour du matériel serveur.
Le volume de données devrait rester de l'ordre de quelques centaines
de Mo, même après dix ans d'exploitation. Nous avons envisagé SQL
Server Express, SQLite et un fichier Access (.accdb). SQL Server
Express a été écarté car le client n'a pas la capacité continue de
construire et vérifier un serveur après le passage de Windows
Update. Access a été écarté en raison du risque de corruption en
cas d'écritures concurrentes et de sa faible perspective de
migration future.

## Décision

Nous utiliserons SQLite pour le stockage des données. Le fichier de
base de données ne sera pas placé dans un dossier partagé ; il
vivra localement sur le PC principal. Les sauvegardes sont prises
quotidiennement sous forme d'instantané via VACUUM INTO, enregistré
sur le NAS (copier le fichier en direct pendant que l'application
tourne n'est pas une option, car cela risque une sauvegarde
corrompue par un fichier WAL manqué ou une concurrence d'écriture).

## Conséquences

- Bon point : aucun serveur de base de données à construire ou maintenir. Les sauvegardes tiennent en une seule instruction SQL
- Bon point : le runtime peut être livré avec l'application, ce qui simplifie l'installation
- Mauvais point : les écritures sont verrouillées au niveau de la base de données, ce qui empêche toute extension à plusieurs sites ou à de nombreux utilisateurs simultanés
- Mauvais point : migrer vers une base de données serveur plus tard nécessitera une migration des données et une refonte de la couche de connexion
- Revoir cette décision dès qu'une utilisation simultanée depuis plusieurs PC devient nécessaire (dans ce cas, passer à une base de données serveur ou à une architecture par API)

Le second est un exemple de révision d’une décision déjà prise. Portez attention à la façon dont Superseded est utilisé ici aussi.

# ADR-0007 : Générer les rapports Excel avec une bibliothèque plutôt que par automation COM

## Statut

Approuvé (2026-07-17) ── remplace l'ADR-0003 (adoption de l'automation COM)

## Contexte

Il existe une exigence de sortir les factures et les récapitulatifs
mensuels sous forme de fichiers Excel. Cela a d'abord été implémenté
avec l'automation COM d'Excel selon l'ADR-0003, mais un traitement
par lot nocturne sans surveillance a répété laissé des processus
Excel bloqués et arrêté le traitement, et le fait de nécessiter une
licence Office sur la machine d'exécution est devenu un problème
récurrent à chaque renouvellement de poste. Nous avons envisagé de
continuer avec l'automation COM (en ajoutant une surveillance des
processus), de passer à une bibliothèque générant directement le
format Open XML, et de convertir les rapports en PDF (un changement
de cahier des charges). Le PDF a été écarté car le client s'appuie
sur la possibilité d'ajouter des annotations directement dans Excel.

## Décision

Nous basculerons les rapports vers une génération directe de .xlsx
via une bibliothèque, sans dépendance à Excel lui-même. La mise en
forme est conservée sous forme de fichier .xlsx modèle dans le
dépôt, et la génération fonctionne en remplissant les cellules.

## Conséquences

- Bon point : Excel n'est plus requis dans l'environnement d'exécution, et les exécutions sans surveillance deviennent stables
- Bon point : le problème de processus résiduels est éliminé de façon structurelle
- Mauvais point : toutes les fonctionnalités d'Excel ne sont pas disponibles, ce qui oblige à simplifier une partie de la mise en forme des rapports existants
- Mauvais point : transformer les rapports existants en modèles demande un effort de refonte
- L'ADR-0003 est marqué Superseded, avec une référence vers cet ADR

Il suffit de lire ces deux entrées pour répondre aux questions qui reviennent immanquablement lors d’une transmission : « pourquoi ce système n’a-t-il pas de base de données serveur ? » et « pourquoi le code des rapports garde-t-il des traces de lancement d’Excel ? ». Ensemble, elles font environ 1 500 caractères et prennent moins d’une heure à rédiger.

8. En résumé

• Ce qui pose problème quand c’est perdu lors de la maintenance et de la transmission, ce n’est pas le What mais le Why. Une décision non documentée finit par être oubliée, ce qui provoque la reprise de débats déjà tranchés et des changements allant à l’encontre de l’intention d’origine.²
• Un ADR est un format d’enregistrement léger : une décision par fichier, cinq éléments, une à deux pages maximum. La forme originale de Nygard fonctionne telle quelle pour un développement de petite taille.¹
• Ne rédigez que les décisions difficiles à changer, qui avaient de véritables alternatives, ou qu’une contrainte a tranchées. Laissez les conventions et la mise en forme à l’automatisation — elles sont hors périmètre d’un ADR.²
• Gardez-les dans docs/adr/, et relisez-les en même temps que la pull request. Ne jamais écraser une décision — la remplacer via Superseded — et garder l’historique immuable.¹²
• En développement sur mesure, un ADR devient un livrable qui a aussi de la valeur pour le client, en servant de document de recette et de document de transmission lors d’un changement de prestataire.
• Quinze à trente minutes par entrée. Commencez par en rédiger un pour votre toute prochaine décision de conception — et si vous travaillez sur un système existant, commencez par remonter et rédiger seulement une poignée des décisions majeures dont vous vous souvenez encore.

Articles connexes

• Comment structurer le contrat de développement et de maintenance ? — Choisir entre quasi-mandat et contrat d’entreprise, ce que nous enseigne le « Modèle de transaction et de contrat » de l’IPA
• La bonne manière de travailler sous un contrat de quasi-mandat pour éviter la sous-traitance déguisée
• Externalisation et développement sur mesure d’une application Windows : ce qu’il faut clarifier avant de se lancer
• Les bases de la rédaction d’un manuel Word — mauvais exemples et pistes d’amélioration

Domaines de conseil associés

Komura Software LLC accompagne l’introduction des ADR dans le cadre d’une revue de conception, l’inventaire et la documentation des décisions de conception d’un système existant, ainsi que la mise en place d’un dispositif de maintenance tourné vers la transmission et les changements de prestataire.

• Conseil technique et revue de conception
• Développement d’applications Windows
• Modification et maintenance de logiciels Windows existants
• Contact

Références

Articles associés

Articles récents partageant les mêmes étiquettes, pour approfondir des sujets proches.

Sujets associés

Ces pages replacent le sujet dans un contexte plus large de services et de décisions.

Services liés à ce sujet

Cet article est directement lié aux services suivants.

Questions fréquentes

Questions souvent posées lors d’une consultation sur le sujet de cet article.

Qu'est-ce qu'un ADR (Architecture Decision Record) ?

C'est un document qui consigne, dans un seul fichier, une décision affectant la structure d'un logiciel, selon un format fixe et court : titre / statut / contexte / décision / conséquences. Michael Nygard a proposé ce format léger en 2011 ; la règle de base est de tenir chaque fiche en une à deux pages maximum et de la committer en Markdown dans le même dépôt que le code. Contrairement à un document de conception exhaustif, il est spécialisé dans la conservation de « pourquoi ce choix a été fait » et des « options écartées ».

Que faut-il écrire dans un ADR, et que peut-on omettre ?

Ce qui mérite d'être écrit : les décisions difficiles à changer par la suite (choix de la base de données ou du mode de communication, format d'une intégration externe, etc.), les décisions prises entre plusieurs options également raisonnables, et les décisions où une contrainte — budget, délai, actifs existants — a été déterminante. À l'inverse, ce qu'un outil ou une convention peut uniformiser mécaniquement, comme les règles de nommage ou les réglages du formateur, ou ce qui est facile à changer et évident à la lecture du code, n'a pas besoin d'un ADR. En cas de doute, appliquez ce test : « moi-même, dans un an, aurais-je envie de demander pourquoi ? »

Si je veux revenir sur une décision passée, ai-je le droit de réécrire l'ancien ADR ?

Non — ne le réécrivez pas ; ajoutez un nouvel ADR qui le remplace. Faites passer le statut de l'ancien ADR à Superseded (remplacé), ajoutez une référence vers le nouvel ADR, et laissez son corps intact. Les recommandations de Microsoft préconisent d'ailleurs de traiter le journal des ADR comme un journal en ajout seul, sans jamais modifier après coup un enregistrement déjà approuvé. Ainsi, l'historique lui-même — de quand et pourquoi la politique a changé — devient à part entière un document de transmission.

Si nous avons déjà un document de conception, l'ADR est-il redondant ?

Ils jouent des rôles différents. Un document de conception montre quelle est la structure actuelle (le What), mais ne conserve généralement pas pourquoi cette structure a été choisie ni ce qui a été écarté (le Why). Un document de conception exhaustif a aussi tendance à cesser d'être mis à jour et à s'écarter du code au bout de quelques années. Un ADR ne demande qu'un ajout de quelques centaines de caractères à chaque décision, ce qui le rend bien moins sujet à devenir obsolète : même quand le document de conception a vieilli, la raison de chaque décision, elle, survit. Pour un développement de petite taille, une organisation réaliste consiste à garder le document de conception détaillé léger et à le compléter par des ADR.

Profil de l’auteur

Page de présentation de l’auteur de l’article.

Go Komura

Représentant de KomuraSoft LLC

Spécialisé dans le développement de logiciels Windows, le conseil technique et l’analyse de pannes, notamment pour les systèmes existants et les incidents difficiles à reproduire.