Architecture Decision Record

Enregistrement de décision d’architecture (ADR)

Modèles, exemples et conseils pour consigner les décisions d'architecture.

Un enregistrement de décision d’architecture (ADR) est un document qui consigne une décision d’architecture importante, avec son contexte et ses conséquences.

Traductions: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, اردو, Tiếng Việt, 中文

Effectuez vos propres vérifications préalables sur ces ressources avant de les utiliser dans des systèmes critiques.

Sommaire :

Modèles :

Exemples :

Qu’est-ce qu’un enregistrement de décision d’architecture ?

Un enregistrement de décision d’architecture (architecture decision record, ADR) est un document qui consigne une décision d’architecture importante, ainsi que son contexte et ses conséquences.

Une décision d’architecture (architecture decision, AD) est un choix de conception logicielle qui répond à une exigence significative.

Un journal des décisions d’architecture (architecture decision log, ADL) est l’ensemble de tous les ADR créés et maintenus pour un projet (ou une organisation) donné.

Une exigence architecturalement significative (architecturally-significant requirement, ASR) est une exigence qui a un effet mesurable sur l’architecture d’un système logiciel.

Tout cela relève de la gestion des connaissances en architecture (architecture knowledge management, AKM).

L’objectif de ce document est de donner un aperçu rapide des ADR, de la façon de les créer et des endroits où trouver davantage d’informations.

Abréviations :

  • AD : décision d’architecture

  • ADL : journal des décisions d’architecture

  • ADR : enregistrement de décision d’architecture

  • AKM : gestion des connaissances en architecture

  • ASR : exigence architecturalement significative

Comment commencer à utiliser les ADR

Pour commencer à utiliser les ADR, discutez avec vos coéquipiers des domaines suivants.

Identification des décisions :

  • Quel est le degré d’urgence et d’importance de l’AD ?

  • Doit-elle être prise maintenant, ou peut-elle attendre d’en savoir davantage ?

  • L’expérience personnelle et collective, ainsi que les méthodes et pratiques de conception reconnues, peuvent aider à identifier les décisions.

  • Idéalement, tenez une liste de décisions à prendre qui complète la liste des tâches du produit.

Prise de décision :

  • Il existe de nombreuses techniques de prise de décision, tant générales que propres à l’architecture logicielle, par exemple la cartographie de dialogue.

  • La prise de décision en groupe est un sujet de recherche actif.

Mise en œuvre et application des décisions :

  • Les AD sont utilisées dans la conception logicielle ; elles doivent donc être communiquées aux parties prenantes du système qui le financent, le développent et l’exploitent, et être acceptées par elles.

  • Les styles de codage architecturalement explicites et les revues de code centrées sur les préoccupations et décisions d’architecture sont deux pratiques connexes.

  • Les AD doivent aussi être (ré)examinées lors de la modernisation d’un système logiciel au fil de son évolution.

Partage des décisions (facultatif) :

  • De nombreuses AD se répètent d’un projet à l’autre.

  • Par conséquent, l’expérience acquise avec des décisions passées, bonnes comme mauvaises, peut constituer un atout précieux et réutilisable lorsqu’on applique une stratégie explicite de gestion des connaissances.

Documentation des décisions :

  • De nombreux modèles et outils existent pour consigner les décisions.

  • Voir les communautés agiles, par exemple les ADR de M. Nygard.

  • Voir les processus traditionnels d’ingénierie logicielle et de conception d’architecture, par exemple les mises en page de tableaux suggérées par IBM UMF et par Tyree et Akerman de CapitalOne.

Pour en savoir plus :

Comment commencer à utiliser les ADR avec des outils

  • MySpec — Plateforme automatisée de spécification et de décision d’architecture qui structure la constitution du projet, l’architecture technique et les ADR en Markdown propre, servi via MCP.

Vous pouvez commencer à utiliser les ADR avec des outils de la manière qui vous convient.

Par exemple :

  • Si vous aimez utiliser Google Drive et l’édition en ligne, vous pouvez créer un Google Doc ou un Google Sheet.

  • Si vous aimez utiliser le contrôle de version du code source, comme git, vous pouvez créer un fichier pour chaque ADR.

  • Si vous aimez utiliser des outils de planification de projet, comme Atlassian Jira, vous pouvez utiliser le suivi de planification de l’outil.

  • Si vous aimez les wikis, comme MediaWiki, vous pouvez créer un wiki d’ADR.

Comment commencer à utiliser les ADR avec git

Si vous aimez utiliser le contrôle de version git, voici comment nous aimons commencer à utiliser les ADR avec git pour un projet logiciel typique doté de code source.

Créez un répertoire pour les fichiers ADR :

$ mkdir adr

Pour chaque ADR, créez un fichier texte, par exemple choose-database.md :

$ vi choose-database.md

Écrivez dans l’ADR ce que vous voulez. Consultez les modèles de ce dépôt pour vous inspirer.

Validez (commit) l’ADR dans votre dépôt git.

Compétences Claude Code pour les ADR

Ce dépôt fournit deux compétences (skills) Claude Code dans skills/, afin qu’un agent de codage IA puisse rédiger et maintenir des ADR comme le recommande ce projet :

  • architecture-decision-record-skill — à usage général, pour quiconque rédige un ADR dans n’importe quel projet. Aide à décider si une décision nécessite un ADR, crée un répertoire adr/ ou decisions/, nomme le fichier, choisit un modèle parmi les onze squelettes fournis et rédige de solides sections Contexte/Décision/Conséquences.

  • architecture-decision-record-maintainer-skill — spécifiquement pour les mainteneurs de ce dépôt. Documente l’organisation du dépôt, la convention de miroir entre README et locales, et les étapes exactes pour ajouter un nouveau modèle, exemple ou lien d’outil.

Pour utiliser une compétence, copiez son dossier dans .claude/skills/ à la racine du dépôt sur lequel vous travaillez (ou dans ~/.claude/skills/ pour la rendre disponible dans tous les projets), puis demandez à Claude Code de rédiger ou de relire un ADR.

Conventions de nommage des fichiers

Si vous choisissez de créer vos ADR avec des fichiers texte ordinaires, vous voudrez peut-être définir votre propre convention de nommage des fichiers ADR.

Nous préférons une convention de nommage des fichiers qui suit un format précis.

Exemples :

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Notre convention de nommage des fichiers :

  • Le nom comporte une locution verbale à l’impératif présent. Cela facilite la lecture et correspond à notre format de messages de commit.

  • Le nom utilise des minuscules et des tirets (comme ce dépôt). C’est un compromis entre lisibilité et facilité d’utilisation côté système.

  • L’extension est markdown. Cela peut être utile pour une mise en forme facile.

Conseils pour rédiger de bons ADR

Caractéristiques d’un bon ADR :

  • Justification (Rationale) : expliquez les raisons de prendre cette AD en particulier. Cela peut inclure le contexte (voir ci-dessous), les avantages et inconvénients des différents choix possibles, des comparaisons de fonctionnalités, des analyses coûts-avantages, et plus encore.

  • Spécifique (Specific) : chaque ADR doit porter sur une seule AD, pas sur plusieurs.

  • Horodatage (Timestamps) : indiquez quand chaque élément de l’ADR a été rédigé. C’est particulièrement important pour les aspects susceptibles d’évoluer dans le temps, comme les coûts, les calendriers, le passage à l’échelle, etc.

  • Immuable (Immutable) : ne modifiez pas les informations existantes d’un ADR. Amendez plutôt l’ADR en ajoutant de nouvelles informations, ou remplacez-le en créant un nouvel ADR.

Caractéristiques d’une bonne section « Contexte » dans un ADR :

  • Expliquez la situation de votre organisation et ses priorités métier.

  • Incluez la justification et les considérations fondées sur la composition sociale et les compétences de vos équipes.

  • Incluez les avantages et inconvénients pertinents, et décrivez-les dans des termes qui correspondent à vos besoins et à vos objectifs.

Caractéristiques d’une bonne section « Conséquences » dans un ADR :

  • Expliquez ce qui découle de la prise de décision. Cela peut inclure les effets, les résultats, les livrables, les suites à donner, et plus encore.

  • Incluez des informations sur les ADR ultérieurs. Il est relativement courant qu’un ADR entraîne la nécessité d’autres ADR, par exemple lorsqu’un ADR fait un grand choix d’ensemble qui crée à son tour le besoin de décisions plus petites.

  • Incluez les processus de revue après action. Il est habituel que les équipes revoient chaque ADR un mois plus tard, afin de comparer les informations de l’ADR avec ce qui s’est passé en pratique, pour apprendre et progresser.

Un nouvel ADR peut remplacer un ADR précédent :

  • Lorsqu’une AD est prise qui remplace ou invalide un ADR précédent, un nouvel ADR doit être créé

Modèles d’exemple d’ADR

Modèles d’exemple d’ADR que nous avons rassemblés sur le web :

Conseils de travail d’équipe pour les ADR

Si vous envisagez d’utiliser des enregistrements de décision avec votre équipe, voici quelques conseils que nous avons appris en travaillant avec de nombreuses équipes.

Vous avez l’occasion de guider vos coéquipiers en discutant ensemble du « pourquoi » plutôt qu’en imposant le « quoi ». Par exemple, les enregistrements de décision sont un moyen pour les équipes de mieux réfléchir et de mieux communiquer ; ils n’ont aucune valeur s’ils ne sont qu’une formalité administrative imposée après coup.

Certaines équipes préfèrent de loin le nom « décisions » à l’abréviation « ADR ». Lorsque certaines équipes utilisent « decisions » comme nom de répertoire, c’est comme si une ampoule s’allumait, et l’équipe se met à y déposer davantage d’informations, comme des décisions relatives aux fournisseurs, à la planification, au calendrier, etc. Tous ces types d’information peuvent utiliser le même modèle. Notre hypothèse est que les gens apprennent plus vite avec des mots (« décisions ») qu’avec des abréviations (« ADR »), qu’ils sont plus motivés pour rédiger des documents de travail en cours lorsque le mot « enregistrement » est retiré, et aussi que certains développeurs et certains managers n’aiment pas le mot « architecture ».

En théorie, l’immuabilité est idéale. En pratique, la mutabilité a mieux fonctionné pour nos équipes. Nous insérons les nouvelles informations dans l’ADR existant, avec un horodatage et une note précisant que l’information est arrivée après la décision. Ce type d’approche mène à un « document vivant » que nous pouvons tous mettre à jour. Les mises à jour typiques surviennent lorsque nous recevons des informations grâce à de nouveaux coéquipiers, à de nouvelles offres, aux résultats concrets de nos usages, ou après des changements ultérieurs chez des tiers, tels que les capacités des fournisseurs, les formules tarifaires, les contrats de licence, etc.

Questions de travail d’équipe pour les ADR

Qui peut créer un ADR ?

Envisagez des aspects comme des personnes précises, des rôles précis, des équipes précises ou des services précis ; envisagez aussi s’il existe des personnes, rôles, équipes ou services pouvant commander un ADR, c’est-à-dire en demander un qu’une autre personne rédigera.

Exemple de réponse : toute personne de notre organisation ayant lu la page README sur l’enregistrement de décision d’architecture peut proposer un ADR, c’est-à-dire qu’elle peut commencer à le rédiger et le partager avec l’équipe.

Qu’est-ce qui justifie de lancer un ADR ?

Envisagez des aspects comme les méthodes de travail des équipes de votre organisation, la structure de votre système logiciel, la coordination entre équipes, la maintenabilité à long terme, les interfaces externes, les personnes que vous voulez faire bénéficier, etc.

Exemple de réponse : nous voulons créer un ADR lorsque nous voulons que les futurs développeurs comprennent le « pourquoi » de ce que nous faisons.

Qu’est-ce qui justifie de ne pas lancer d’ADR ?

Envisagez des aspects comme les décisions qui ne concernent pas l’architecture, ou qui sont minimes, par exemple à risque minimal, autonomes ou limitées à un seul développeur, ou qui sont déjà entièrement couvertes ailleurs, par exemple par des normes, des politiques ou de la documentation, ou qui sont temporaires, comme des solutions de contournement, des preuves de concept ou des expériences.

Exemple de réponse : nous voulons nous passer d’ADR lorsqu’une décision est limitée en portée, en durée, en risque et en coût, ou est déjà couverte ailleurs.

Quel est le cycle de vie d’un ADR ?

Envisagez des aspects comme le processus de création, le processus de recherche, le processus de décision, le processus de mise en œuvre et le processus de retrait. Envisagez comment suivre le cycle de vie de l’ADR dans le temps, par exemple comment faire passer l’ADR d’un état au suivant, et comment le communiquer aux parties prenantes.

Exemple de réponse : nous voulons qu’un ADR ait cinq étapes de cycle de vie : Initiation → Recherche → Évaluation → Mise en œuvre → Maintenance → Retrait.

Quels sont les critères des étapes du cycle de vie d’un ADR ?

Envisagez des aspects comme les critères d’acceptation d’un ADR, c’est-à-dire : comment savez-vous qu’il est assez bon pour passer d’une étape du cycle de vie à la suivante ? Le problème est-il clairement formulé ? Les alternatives ont-elles été examinées ? Les compromis (trade-offs) sont-ils suffisamment compris et documentés ? Tout le contexte pertinent est-il en place ? Toutes les parties prenantes concernées sont-elles impliquées ? Tous les retours ont-ils été pris en compte ?

Exemple de réponse : nous voulons qu’un ADR soit soumis au vote des parties prenantes lorsque l’équipe active a 1) terminé sa recherche, 2) terminé son évaluation, 3) publié la proposition d’ADR aux parties prenantes avec une demande de commentaires et un délai d’une semaine, 4) intégré et traité tous les commentaires des parties prenantes.

Quels rôles et responsabilités interviennent dans un ADR ?

Envisagez des rôles tels que proposant, chercheur, évaluateur, relecteur, approbateur, mainteneur, etc. Envisagez des responsabilités telles que la communication avec les parties prenantes, la garantie que les attentes sont satisfaites, le partage sur le site web ou l’intranet, et la revue périodique du travail, en particulier lorsque des changements pertinents surviennent.

Exemple de réponse : nous voulons que chaque ADR ait toujours une personne de contact principale, une personne de contact secondaire et une équipe responsable ; ceux-ci sont responsables des communications, des publications, de la maintenance, de la revue périodique au moins une fois par an et, le cas échéant, du retrait final.

Comment la gouvernance intervient-elle dans un ADR ?

Envisagez des aspects comme les méthodes de travail de votre organisation, d’éventuels besoins spéciaux de conformité, par exemple sur le plan juridique ou des ressources humaines, et la manière dont vous voulez gérer consensus, conflit et escalade. Existe-t-il des domaines, des personnes ou des équipes qui peuvent avoir plus d’influence que d’autres sur un ADR, par exemple en pouvant l’approuver, voter dessus ou y opposer leur veto ?

Exemple de réponse : la gouvernance d’un ADR suit cet ordre de priorité : le PDG, le directeur technique (CTO), le directeur juridique (CLO), l’équipe qui met en œuvre un ADR, les experts de l’équipe les plus compétents sur l’ADD. Personne d’autre n’a de pouvoir de gouvernance, sauf mention contraire dans l’ADR.

Quels principes interviennent dans un ADR ?

Envisagez des aspects comme les méthodes de travail de votre organisation, notamment avancer vite ou lentement, consensus ou conflit sur les décisions, préférences en matière de risque ou de sécurité, discussion publique ou privée, etc.

Exemple de réponse : nous appliquons les principes de leadership que sont le biais pour l’action, le désaccord suivi d’engagement (disagree-and-commit), des estimations à 70 % suffisamment bonnes pour les décisions facilement réversibles et facilement isolables, et des méthodes de travail publiques, à l’exception des informations confidentielles telles que décrites dans l’accord de confidentialité de notre organisation.

Concepts de l’étape suivante pour les ADR

Arc42 répond de façon pragmatique à deux questions et peut être adapté à vos besoins. Que faut-il documenter/communiquer sur votre architecture ? Comment faut-il le documenter/communiquer ? Arc42 comprend des enregistrements de décision d’architecture ainsi que des conseils sur les objectifs, les contraintes, les contextes, la qualité, les risques, etc.

Le modèle C4 est une approche facile à apprendre et conviviale pour les développeurs de diagrammes d’architecture logicielle. C4 est un ensemble de diagrammes hiérarchiques pour le contexte, les conteneurs, les composants et le code, avec des diagrammes complémentaires pour le paysage système, la dynamique et le déploiement.

Diagrammes, vues et points de vue d’architecture

Un diagramme d’architecture s’appelle une « vue d’architecture ».

Une « vue d’architecture » est une instance d’un « point de vue d’architecture ».

Un « point de vue d’architecture » cible un public précis ayant des préoccupations précises.

Exemples de points de vue, de vues et de diagrammes d’architecture :

Diagrammes associés :

  • Un diagramme de cas d’utilisation présente les cas d’utilisation à la direction/aux clients ; il précède les exigences, qui précèdent l’architecture logicielle.

  • Un diagramme de déploiement montre le matériel/les ordinateurs physiques sur lesquels les composants logiciels sont déployés.

  • Un diagramme de flux de données montre comment les données circulent dans le système et sont transformées.

  • Un diagramme de séquence sert à montrer comment des protocoles comme HTTP fonctionnent sur un axe temporel.

  • Un diagramme d’activité représente le flux de travail des activités qu’exécute un système logiciel, comme une IA de PNJ.

Fonctions d’aptitude pour des décisions sous forme de code

Les fonctions d’aptitude (fitness functions) sont des vérifications automatisées et objectives, écrites en code de programmation, qui contrôlent que les décisions sont respectées.

  • Les fonctions d’aptitude rendent les décisions testables et vérifiables.

  • Les fonctions d’aptitude pour les décisions peuvent grandement faciliter l’assurance qualité, les processus réglementaires et les objectifs de gouvernance.

Comment les fonctions d’aptitude se rattachent aux décisions

Un enregistrement de décision documente la décision, tandis qu’une fonction d’aptitude la garantit.

  • Exemple de décision : nous utilisons l’event sourcing pour les exigences d’audit.

  • Exemple de fonction d’aptitude : nous utilisons le serveur d’intégration continue pour vérifier que tous les changements d’état doivent produire des événements.

Pourquoi les fonctions d’aptitude aident les décisions

Mesures objectives : les fonctions d’aptitude réussissent ou échouent, de sorte que le travail est visible et clair.

Usage continu : les fonctions d’aptitude sont vos règles vivantes, exécutées à chaque commit et à chaque build.

Confiance pour refactoriser : les fonctions d’aptitude détectent automatiquement les erreurs dans les règles de décision.

Gouvernance évolutive : les fonctions d’aptitude garantissent les normes sans créer de goulots d’étranglement.

Les fonctions d’aptitude peuvent-elles utiliser l’IA ?

Les fonctions d’aptitude peuvent tirer parti des LLM d’IA pour les décisions en posant des questions sur votre travail, comme vos plans, votre code, vos schémas, vos API, etc. :

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Tests unitaires d’architecture

ArchUnit : vérifie les règles d’architecture du code Java à l’aide de n’importe quel framework de tests unitaires Java ordinaire.

ArchUnitTS : vérifie les règles d’architecture du code TypeScript et JavaScript à l’aide de Jest, Vitest, Jasmine, etc.

Garde-fous de décision pour les pull requests

Decision Guardian fait apparaître automatiquement les bons enregistrements de décision au bon moment, c’est-à-dire lorsqu’un développeur modifie activement le code que ces décisions couvrent. Au lieu d’espérer que les développeurs lisent un dossier de documents avant de fusionner, le contexte pertinent apparaît directement dans la pull request.

Cela fonctionne pour tout type d’enregistrement de décision : décisions d’architecture, de données, de conformité, cliniques et médicales, de sécurité, etc.

Fonctionne avec n’importe quel système de CI (GitLab, Jenkins, CircleCI) et comme hook de pre-commit. Open source. Licence MIT.

ADR Guard est une GitHub Action qui fait échouer une pull request lorsque des chemins de code surveillés changent sans qu’un enregistrement de décision d’architecture soit ajouté ou mis à jour. Les dérogations sont explicites : une ligne ADR-Exempt: accompagnée d’une raison franchit la barrière et est inscrite dans le résumé du job. Indépendant des modèles, sans dépendances. Open source. Licence MIT.

Pour plus d’informations

Introduction :

Modèles :

Approfondissement :

Outils :

Conseils propres à des entreprises :

Exemples :

Vidéos :

Podcasts :

Livres :

Voir aussi :

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

  • Decision Reasoning Format (DRF) - Un format YAML/JSON indépendant des fournisseurs et lisible par machine pour représenter les décisions avec raisonnement explicite, hypothèses, état cognitif et compromis. Complète les ADR en ajoutant un raisonnement structuré et validable à la documentation des décisions.