Un Architecture Decision Record tient sur une page. Bien écrit, il survit aux personnes qui l'ont rédigé — et c'est précisément ce qu'on attend de lui.
Une équipe d'ingénierie prend des décisions d'architecture en permanence. Le choix d'une base de données, d'un découpage en services, d'un protocole d'échange, d'un format de sérialisation : la plupart se tranchent en quelques jours, parfois en une seule réunion, et se gravent ensuite dans le code pour des années. Six mois plus tard, le raisonnement s'est effacé. Un an plus tard, la personne qui portait la décision a changé d'équipe. Le nouvel arrivant pose la question évidente — « pourquoi est-ce qu'on utilise ça ? » — et reçoit un haussement d'épaules, ou pire, une reconstruction confiante et fausse.
Le code montre le quoi. Il ne montre presque jamais le pourquoi. Un schéma de base de données décrit comment les données sont structurées ; il ne dit rien des options écartées, ni des contraintes qui ont rendu celle-ci raisonnable à un moment donné. C'est cet écart que l'Architecture Decision Record — l'ADR — vient combler.
Ce qu'un ADR capture, et ce qu'il n'est pas
L'idée a été formalisée par Michael Nygard en 2011, dans un billet bref et depuis abondamment cité. Un ADR est un document court — une page suffit — qui consigne une décision d'architecture : la situation qui l'a rendue nécessaire, les options considérées, le choix retenu et ses conséquences. Il vit dans le dépôt, versionné au même titre que le code. Et il est immuable : on ne corrige pas un ADR accepté, on en écrit un nouveau qui le remplace. La pile des ADR remplacés n'est pas un déchet — c'est la trace de l'évolution du système.
Un ADR n'est pas de la documentation pour la documentation. Ce n'est pas non plus un document de conception, qui décrit comment un composant fonctionne. C'est plus modeste, et plus durable : un message adressé à une personne précise — celle qui héritera du système sans avoir assisté à la discussion. Tout le reste en découle.
Les modèles d'ADR varient. Celui de Nygard est minimal ; d'autres, comme MADR, sont plus riches. Le gabarit importe moins que les questions auxquelles un ADR utile répond. Il y en a cinq : quel était le contexte, quelles contraintes pesaient, quels besoins fallait-il satisfaire, quelles alternatives ont été pesées, et quelle décision a été prise. Un ADR qui répond honnêtement à ces cinq questions est utile, quel que soit le modèle dans lequel il est coulé.
Le contexte
Le contexte décrit la situation telle qu'elle était — pas telle qu'on aimerait l'avoir vue avec le recul. C'est la section la plus difficile à écrire correctement, parce que la tentation est constante d'y glisser déjà la conclusion.
Un bon contexte expose les forces en présence : l'état du système au moment de la décision, la pression qui a forcé un choix, ce qui était vrai alors. Il doit permettre à un lecteur qui n'était pas là de comprendre le problème avant de découvrir la réponse. Le test est simple : si l'on masque la section « décision », le contexte tient-il encore debout comme un exposé de problème, ou n'est-il déjà qu'un plaidoyer pour une issue connue ?
Le contexte est aussi la seule section d'un ADR qui se périme volontairement. Il fige un instant. C'est une qualité, pas un défaut : des années plus tard, le lecteur sait que la décision était juste à ce moment-là, même si la situation a changé depuis. Un ADR ne prétend pas être vrai pour toujours. Il prétend être honnête sur son époque.
Les contraintes
Les contraintes sont les limites qui n'étaient pas négociables : un budget, une échéance, une pile technique déjà en place, les compétences présentes dans l'équipe, une exigence réglementaire, un héritage qu'on n'avait pas le droit de toucher.
Cette section a une fonction précise : elle explique pourquoi l'option « manifestement meilleure » n'a pas été retenue. Sans elle, toute décision passée paraît stupide à un lecteur futur qui ne voit pas la cage dans laquelle on travaillait. L'ingénieur qui reprend le système dans deux ans n'aura pas vécu l'échéance, ni la réunion où l'on a appris que telle dépendance était imposée. Les contraintes sont ce qui le protège — et ce qui vous protège de son mépris.
Une contrainte mal écrite est une contrainte vague. « Le temps était limité » n'apprend rien. « La décision devait être livrée avant la fin du trimestre, sans renfort » est une contrainte : datée, mesurable, opposable.
Les besoins
Les besoins se confondent souvent avec les contraintes ; ils en sont pourtant l'exact complément. Une contrainte est ce qui vous limite. Un besoin est ce que la décision doit atteindre.
Un seuil de latence, un débit cible, un volume à encaisser, une propriété qui devait être garantie — la cohérence forte plutôt que la disponibilité, ou l'inverse. Les besoins sont les critères de notation des alternatives. Tant qu'ils ne sont pas posés, on ne peut pas justifier un choix : on ne peut que l'affirmer. C'est la différence entre « nous avons retenu cette base parce qu'elle tenait nos 5 000 écritures par seconde sous 20 ms de latence p99 » et « nous avons retenu cette base parce qu'elle nous a paru solide ».
Si vous n'arrivez pas à formuler les besoins, ce n'est pas la section qui manque — c'est la décision qui n'est pas mûre.
Les alternatives
C'est la section qui distingue un ADR utile d'un ADR décoratif. Elle consigne les options réellement considérées, chacune évaluée face aux besoins et aux contraintes posés plus haut.
La discipline tient en un mot : honnêteté. Une alternative présentée en homme de paille — une demi-phrase dédaigneuse à côté de l'option choisie — ne trompe personne et ne sert à rien. Les options écartées doivent l'être équitablement, avec leurs vrais mérites énoncés. La valeur de cette section se révèle plus tard : le jour où quelqu'un propose « et pourquoi pas X, tout simplement ? », l'ADR montre que X a été pesé, et pourquoi il a perdu. Ou bien il montre, honnêtement, que X n'avait pas été envisagé — une information tout aussi précieuse.
C'est aussi ici qu'on note l'option qu'on aurait choisie si une contrainte avait sauté. Cette phrase-là vaut de l'or pour le lecteur futur : elle lui dit quoi reconsidérer le jour où le budget, l'échéance ou la dépendance imposée n'existent plus.
La décision
La décision énonce le choix, clairement, et ses conséquences. La première moitié est facile. La seconde est celle qu'on escamote.
Toute décision d'architecture achète un avantage à un prix. Une section « décision » qui n'aligne que des bénéfices n'est pas une décision d'ingénierie — c'est un argumentaire. L'ADR honnête nomme le compromis qu'il consent : ce que le choix rend simple, et ce qu'il rend difficile ; ce qu'il ouvre, et ce qu'il ferme. « Ce découpage nous donne des déploiements indépendants ; il nous coûte une transaction distribuée que nous devrons gérer à la main » est une décision complète. La moitié qui fait mal est aussi la plus utile : c'est elle qui prévient le lecteur futur du mur qu'il va rencontrer, et lui confirme qu'on l'avait vu venir.
Ce qui tient l'ensemble
Cinq sections ne font pas un ADR utile à elles seules. Quelques principes les tiennent.
Une décision par document. Dès qu'un ADR prétend couvrir « notre architecture », il ne capture plus rien. Un ADR, un choix, un titre qui nomme ce choix.
L'immuabilité. Un ADR accepté ne se réécrit pas. S'il devient faux, on en rédige un autre qui le remplace et le référence. La continuité de la trace vaut mieux qu'un document toujours « à jour » mais sans mémoire.
La brièveté. Une page. Si un ADR s'allonge, c'est que la décision n'est pas claire, ou qu'on en a empilé plusieurs. La longueur n'est pas un signe de sérieux.
L'écriture au moment de la décision. Un ADR rédigé après coup, une fois le code livré, sent la justification. Écrit pendant qu'on hésite encore, il garde la trace de l'incertitude réelle — et c'est cette incertitude assumée qui le rendra crédible plus tard.
Le test
Il existe une façon simple de savoir si un ADR a mérité sa place. Confiez-le à quelqu'un qui rejoindra l'équipe dans deux ans, sur un système qu'il découvre. S'il peut reconstruire non seulement ce que vous avez fait, mais pourquoi c'était raisonnable de le faire — alors l'ADR a fait son travail. S'il referme le document avec la même question qu'au début, le gabarit était là, mais pas l'ADR.
schema est le carnet d'architecture de newline. Sa page de gauche porte un gabarit ADR — contexte, contraintes, besoins, alternatives, décision — face à une grille de schémas en page de droite : une décision par double page. [NL-01] schema; – newline \n