Architecture Decision Records (ADR) : le guide complet

Chaque système logiciel est façonné par des centaines de décisions. PostgreSQL plutôt que MongoDB. REST plutôt que GraphQL. Monolithe plutôt que microservices. Event-driven plutôt que request-response. Chaque choix contraint les choix futurs, et ensemble ils définissent l'architecture.

Le problème, c'est que les décisions sont invisibles. Le code montre ce qui a été construit, pas pourquoi ça a été construit de cette façon. Six mois après avoir choisi PostgreSQL, personne ne se souvient si l'équipe a envisagé DynamoDB, quelles étaient les exigences de performance, ou pourquoi la cohérence éventuelle était inacceptable. La décision est inscrite dans le code, mais le raisonnement est perdu.

Les Architecture Decision Records (ADR) résolvent ce problème en capturant chaque décision significative dans un document court et structuré. C'est l'une des pratiques de documentation les plus rentables en ingénierie logicielle -- simple à adopter, peu coûteuse à maintenir, et inestimable quand on en a besoin.

Ce guide couvre tout, des bases aux pratiques avancées : ce que sont les ADR, comment les rédiger, des templates à adopter immédiatement, les pièges courants, et comment intégrer les ADR dans votre workflow avec un outillage moderne.

Qu'est-ce qu'un Architecture Decision Record ?

Un Architecture Decision Record est un document court qui capture une seule décision architecturale. L'accent est mis sur une seule et court :

• Une seule : Un ADR, une décision. "Utiliser PostgreSQL pour le service de commandes" est un ADR. "Définir toute la stratégie de base de données" est un document de conception, pas un ADR.
• Court : Un ADR devrait tenir sur une page. S'il est plus long, vous documentez probablement plusieurs décisions ou incluez trop de détails d'implémentation.

Le concept a été popularisé par Michael Nygard dans un billet de blog de 2011. Depuis, les ADR ont été adoptés par des organisations allant des startups aux gouvernements. Le Government Digital Service du Royaume-Uni, Spotify, et d'innombrables équipes d'ingénierie utilisent les ADR comme pratique standard.

Ce que les ADR capturent

Chaque ADR répond à quatre questions fondamentales :

1. Quel était le contexte ? Quelle situation ou quel problème a motivé cette décision ?
2. Qu'avons-nous décidé ? Quel est le choix architectural spécifique que nous avons fait ?
3. Quelles alternatives avons-nous considérées ? Quelles autres options étaient sur la table ?
4. Quelles sont les conséquences ? Quels compromis, risques et implications accompagnent cette décision ?

C'est tout. Quatre questions. Un ADR bien rédigé peut répondre aux quatre en moins d'une page.

Ce que les ADR ne sont pas

• Pas des documents de conception. Les ADR ne décrivent pas comment quelque chose est implémenté. Ils décrivent pourquoi une approche particulière a été choisie.
• Pas des RFC. Les RFC (Request for Comments) sont des propositions de discussion. Les ADR documentent des décisions conclues (même si un ADR peut commencer comme proposition et passer à accepté).
• Pas des comptes-rendus de réunion. Les ADR capturent le résultat, pas la discussion qui y a mené.
• Pas une documentation exhaustive. Les ADR complètent les diagrammes d'architecture, les specs API et les runbooks. Ils ne les remplacent pas.

Le template ADR standard

Plusieurs templates d'ADR existent, mais la plupart sont des variations de la même structure de base. Voici un template pratique qui équilibre exhaustivité et concision :

# ADR-NNNN: [Titre court décrivant la décision]

## Statut

[Proposé | Accepté | Déprécié | Remplacé par ADR-XXXX]

## Date

[AAAA-MM-JJ]

## Contexte

[Décrivez la situation. Quel problème résolvons-nous ? Quelles contraintes
existent ? Quelles forces sont en jeu ? Soyez spécifique -- incluez des chiffres,
des délais, les compétences de l'équipe et les exigences techniques quand c'est
pertinent.]

## Décision

[Énoncez la décision clairement et de manière concise. Utilisez la voix active :
"Nous utiliserons X" et non "X devrait être envisagé."]

## Alternatives considérées

### [Alternative 1]
- Avantages : ...
- Inconvénients : ...
- Raison du rejet : ...

### [Alternative 2]
- Avantages : ...
- Inconvénients : ...
- Raison du rejet : ...

## Conséquences

### Positives
- [Ce qui devient plus facile ou meilleur]

### Négatives
- [Ce qui devient plus difficile ou pire]

### Risques
- [Ce qui pourrait mal tourner]

## Décisions liées

- [Liens vers les ADR liés]

Détail de chaque section

Statut suit le cycle de vie d'une décision. Le flux typique est : Proposé -> Accepté. Si les circonstances changent, un ADR devient Déprécié ou Remplacé par un ADR plus récent. Point important : vous ne devriez jamais supprimer d'ADR -- même les décisions rejetées sont précieuses car elles empêchent les futures équipes de reconsidérer des options déjà évaluées.

Date établit quand la décision a été prise. Cela fournit un contexte temporel : "Nous avons choisi cette technologie en 2024 quand notre échelle était X. Maintenant que notre échelle est 10X, nous devrions reconsidérer."

Contexte est la section la plus importante. Un contexte bien rédigé donne aux futurs lecteurs suffisamment d'informations pour comprendre pourquoi cette décision avait du sens à l'époque, même si les circonstances ont changé depuis. Incluez des chiffres spécifiques ("nous traitons 50 000 commandes par jour"), des contraintes ("doit être conforme PCI-DSS"), et des facteurs d'équipe ("trois ingénieurs ont de l'expérience PostgreSQL, aucun n'a d'expérience MongoDB").

Décision doit être sans ambiguïté. "Nous utiliserons PostgreSQL 16 comme store de données principal pour le service de commandes" est bien. "Nous devrions probablement envisager une base de données relationnelle" n'est pas un ADR -- c'est une suggestion.

Alternatives considérées est la section qui fait gagner le plus de temps à long terme. Quand un nouvel ingénieur demande "pourquoi n'avons-nous pas utilisé MongoDB ?", la réponse est là. Quand l'équipe revisite la décision un an plus tard, elle peut voir ce qui a été évalué et pourquoi ça a été rejeté. Sans cette section, les équipes refont les mêmes débats indéfiniment.

Conséquences est une question d'honnêteté intellectuelle. Chaque décision a des compromis. Reconnaître les inconvénients construit la confiance et aide les futures équipes à comprendre quand les circonstances pourraient justifier de revisiter la décision.

Un exemple complet d'ADR

Voici un ADR réaliste qui illustre le template en pratique :

# ADR-0023: Utiliser Apache Kafka pour la communication inter-services

## Statut

Accepté

## Date

2025-11-15

## Contexte

Notre plateforme est passée de 3 microservices à 12 au cours de l'année
écoulée. Les services communiquent actuellement de manière synchrone via
des appels HTTP REST. Cela crée plusieurs problèmes :

- Défaillances en cascade : quand le service d'inventaire est en panne,
  le service de commandes ne peut pas traiter les commandes, même si les
  vérifications d'inventaire pourraient être éventuelles.
- Couplage fort : les services doivent connaître les contrats API et les
  endpoints les uns des autres.
- Goulots d'étranglement de performance : certaines opérations déclenchent
  des chaînes de 4-5 appels synchrones, ajoutant de la latence.

Nous traitons environ 100 000 événements par jour. Nous prévoyons une
croissance à 500 000 dans les 12 mois. L'équipe compte 8 ingénieurs
backend, dont 2 ont une expérience préalable de Kafka.

## Décision

Nous adopterons Apache Kafka comme mécanisme principal pour la
communication asynchrone inter-services. Le HTTP synchrone restera
pour les patterns request/response où l'appelant a besoin d'un résultat
immédiat (ex. : vérifications d'authentification).

Nous utiliserons Confluent Cloud comme fournisseur Kafka managé pour
minimiser la charge opérationnelle.

## Alternatives considérées

### RabbitMQ
- Avantages : Plus simple à opérer, courbe d'apprentissage plus faible,
  supporte plusieurs patterns de messaging (pub/sub, point-to-point, routing).
- Inconvénients : Moins adapté aux patterns d'event sourcing que nous
  prévoyons d'adopter. Capacités de replay/rembobinage plus faibles.
  L'élan de la communauté s'est déplacé vers Kafka pour les architectures
  event-driven.
- Raison du rejet : Nous anticipons le besoin de rejouer les événements
  pour l'audit et le débogage. L'architecture basée sur les logs de
  Kafka est mieux adaptée.

### AWS SQS + SNS
- Avantages : Entièrement managé, pas d'infrastructure à maintenir,
  intégration étroite avec AWS.
- Inconvénients : Vendor lock-in avec AWS. Garanties d'ordonnancement
  des messages limitées. Pas de traitement de flux intégré (nécessiterait
  Kinesis ou Lambda). Coût par message plus élevé à notre volume projeté.
- Raison du rejet : Nous voulons éviter d'approfondir le lock-in AWS,
  et nous avons besoin de la livraison ordonnée des messages pour les
  événements financiers.

### Garder le HTTP synchrone (avec circuit breakers)
- Avantages : Pas de nouvelle infrastructure. L'équipe est déjà familière.
  Les circuit breakers adressent les défaillances en cascade.
- Inconvénients : Ne résout pas le couplage fort. La latence s'accumule
  toujours à travers les chaînes d'appels. Les circuit breakers sont un
  pansement, pas une solution au problème fondamental de couplage.
- Raison du rejet : Traite les symptômes, pas la cause racine.

## Conséquences

### Positives
- Les services deviennent découplés : les producteurs n'ont pas besoin
  de connaître les consommateurs.
- Les défaillances en cascade sont éliminées pour les workflows asynchrones.
- Le replay d'événements permet des capacités puissantes de débogage et d'audit.
- Fondation pour les patterns d'event sourcing dans les futurs services.

### Négatives
- La complexité opérationnelle augmente (cluster Kafka, schema registry,
  gestion des consumer groups). Atténué par l'utilisation de Confluent Cloud.
- L'équipe a besoin de formation sur les concepts et patterns Kafka.
- La cohérence éventuelle remplace la cohérence forte pour les flux
  asynchrones. Certains workflows nécessitent une refonte.
- Le débogage de flux asynchrones distribués est plus difficile que le
  traçage d'appels HTTP synchrones. Nous aurons besoin de tracing
  distribué (voir ADR-0024).

### Risques
- Si le volume de messages dépasse les paliers de tarification de
  Confluent Cloud, les coûts pourraient augmenter significativement.
  Surveiller et mettre en place des alertes.
- L'évolution des schémas entre services nécessite de la discipline.
  Planifier l'adoption d'Avro avec le schema registry.

## Décisions liées

- ADR-0024: Adopter OpenTelemetry pour le tracing distribué
- ADR-0018: Contrats de communication entre services (remplacé par cet ADR)

Cet ADR fait environ 400 mots. Il a pris peut-être 20 minutes à écrire. Il fera économiser des heures de réunions au cours des prochaines années.

Quand écrire un ADR

Tous les choix techniques ne nécessitent pas un ADR. Choisir entre deux bibliothèques JSON n'en justifie pas un. Mais certaines décisions le méritent absolument.

Écrivez un ADR quand :

• La décision affecte la structure du système. Tout ce qui change la façon dont les services communiquent, où les données vivent, ou comment les components sont organisés.
• La décision est coûteuse à inverser. Choisir une base de données, un système de messaging ou une plateforme de déploiement. Si défaire cette décision prend plus d'un sprint, documentez pourquoi vous l'avez prise.
• Plusieurs options viables existent. Si le choix est évident, pas besoin d'ADR. Si vous avez débattu entre trois options, capturez le raisonnement.
• La décision traverse les frontières d'équipe. Tout choix architectural qui affecte d'autres équipes devrait être documenté pour qu'elles comprennent le rationnel.
• Le futur vous pourrait remettre en question le choix. S'il y a une chance que quelqu'un (y compris le futur vous) demande "pourquoi avons-nous fait ça ?", écrivez-le maintenant.

Passez l'ADR quand :

• Le choix suit un standard d'équipe établi (ex. : "nous utilisons toujours Go pour le backend" n'a pas besoin d'un nouvel ADR pour chaque service)
• La décision est trivialement réversible (renommer une variable, choisir un formateur de code)
• La décision est purement cosmétique (style de code, conventions de nommage -- celles-ci appartiennent à un guide de style)

Cycle de vie et gouvernance des ADR

Le cycle de vie

Les ADR ont un cycle de vie naturel :

1. Brouillon/Proposé : Quelqu'un identifie une décision à prendre et rédige un brouillon d'ADR. L'équipe discute.
2. Accepté : L'équipe est d'accord sur la décision. Le statut de l'ADR passe à Accepté.
3. Actif : La décision est en vigueur. L'ADR sert de documentation de référence.
4. Remplacé : Une nouvelle décision remplace celle-ci. L'ancien ADR reçoit un statut "Remplacé par ADR-XXXX". Le nouvel ADR référence l'ancien.
5. Déprécié : La décision n'est plus pertinente (peut-être que le système auquel elle s'appliquait a été décommissionné).

Important : ne supprimez jamais d'ADR. Même les ADR dépréciés ou remplacés sont précieux. Ils forment une chronologie de l'évolution architecturale.

Numérotation

Utilisez des numéros séquentiels : ADR-0001, ADR-0002, etc. Le numéro fournit un ordre chronologique et rend les ADR faciles à référencer en conversation : "comme décidé dans l'ADR-42."

Certaines équipes utilisent une numérotation basée sur la date (ADR-2026-03-27-kafka) mais les numéros séquentiels sont plus simples et plus largement utilisés.

Cadence de revue

Définissez un rappel trimestriel pour revoir vos ADR :

• Y a-t-il des décisions acceptées qui ne sont plus valides ?
• Les contraintes ont-elles changé de manière à invalider les hypothèses ?
• Y a-t-il des décisions que l'équipe a prises informellement qui devraient être capturées ?

Cette revue prévient la dégradation des ADR et maintient la collection à jour.

Où stocker les ADR

Les approches les plus courantes, par ordre de recommandation :

Dans le dépôt de code

Stockez les ADR dans docs/adr/ ou docs/decisions/ au sein de votre dépôt. C'est l'approche la plus populaire et pour de bonnes raisons :

• Les ADR sont versionnés aux côtés du code qu'ils décrivent
• Ils apparaissent dans les pull requests et les revues de code
• Ils ne peuvent pas être orphelins dans un wiki que personne ne visite
• Ils sont découvrables via grep ou la recherche

Convention : un fichier markdown par ADR, nommé avec le numéro et un slug :

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

Dans un outil d'architecture dédié

Des outils comme Archyl fournissent une gestion intégrée des ADR avec des capacités supplémentaires :

• Relier les ADR directement aux éléments du modèle C4 (containers, components, relations)
• Rechercher et filtrer les ADR à travers tous les projets
• Suivre le statut et le cycle de vie des ADR
• Connecter les ADR aux règles de conformité qui appliquent la décision

L'avantage clé d'un outil d'architecture est le contexte. Quand un développeur regarde le container PostgreSQL dans un diagramme C4, il peut naviguer vers l'ADR qui explique pourquoi PostgreSQL a été choisi. La décision et l'architecture sont connectées, pas cloisonnées.

Dans un wiki (non recommandé)

Les wikis (Confluence, Notion, etc.) sont l'endroit où les ADR vont pour être oubliés. Ils sont déconnectés du code, difficiles à découvrir, et rarement maintenus. Si vous devez utiliser un wiki, au minimum faites des références croisées avec les ADR depuis le dépôt de code.

Intégrer les ADR dans votre workflow

Faire des ADR une partie des pull requests

Pour les changements architecturaux significatifs, exigez un ADR dans la pull request. Ajoutez une section à votre template de PR :

## Impact architectural

- [ ] Pas de changement architectural
- [ ] ADR créé/mis à jour : [lien]

Cela normalise la création d'ADR et garantit que les décisions sont documentées quand elles sont prises, pas des semaines plus tard quand le contexte s'est estompé.

Utiliser les ADR dans les revues d'architecture

Pendant les revues d'architecture ou les discussions de conception, référencez les ADR existants. "Avant de reconcevoir ceci, vérifions ce que dit l'ADR-15 sur pourquoi nous avons choisi cette approche." Cela donne de la visibilité aux ADR et renforce l'habitude de documenter les décisions.

Connecter les ADR aux diagrammes d'architecture

C'est là que les ADR deviennent vraiment puissants. Quand un ADR est relié à un élément spécifique de votre modèle C4, cela crée un graphe de connaissances navigable :

• Cliquez sur le container Kafka dans votre diagramme de Containers -> voyez l'ADR-0023 expliquant pourquoi Kafka a été choisi
• Cliquez sur la base de données PostgreSQL -> voyez l'ADR-0001 expliquant la sélection de la base de données
• Cliquez sur l'API Gateway -> voyez l'ADR-0012 expliquant pourquoi Kong a été choisi plutôt qu'un routing personnalisé

Dans Archyl, vous pouvez relier les ADR à n'importe quel élément C4 -- systèmes, containers, components ou relations. Cette connexion signifie que les décisions architecturales ne sont pas des documents flottants ; elles sont ancrées aux parties spécifiques de l'architecture qu'elles affectent.

Automatiser ce que vous pouvez

Plusieurs outils peuvent réduire la friction de la gestion des ADR :

• adr-tools (par Nat Pryce) : Un outil en ligne de commande pour créer et gérer les ADR dans un dépôt. Exécutez adr new "Use Kafka for messaging" pour générer un nouvel ADR à partir d'un template.
• Log4brains : Génère un site web cherchable et navigable à partir de vos fichiers markdown d'ADR.
• Archyl : Gère les ADR avec liaison aux éléments C4, suivi de statut et recherche multi-projets.

Pratiques avancées d'ADR

ADR légers (LADR)

Certaines équipes trouvent même le template standard trop lourd. Un ADR léger tient en trois phrases :

Dans le contexte de [situation],
nous avons décidé [décision],
pour atteindre [objectif],
en acceptant [compromis].

Exemple :

Dans le contexte du besoin d'une communication inter-services qui tolère
les pannes de service, nous avons décidé d'utiliser Apache Kafka via
Confluent Cloud, pour atteindre le découplage des services et la capacité
de rejouer les événements, en acceptant une complexité opérationnelle
accrue et la cohérence éventuelle.

Ce format fonctionne bien pour les décisions assez importantes pour être documentées mais qui ne justifient pas un ADR complet.

Journaux de décisions

Un journal de décisions est un document unique qui liste tous les ADR par ordre chronologique avec des résumés d'une ligne. Il sert d'index :

Cela donne un aperçu rapide de toutes les décisions sans ouvrir les fichiers ADR individuels.

ADR pour les décisions non techniques

Les ADR ne se limitent pas aux choix technologiques. Les équipes les utilisent pour :

• Décisions de processus : "Nous ferons du pair programming pour le code critique en matière de sécurité"
• Décisions organisationnelles : "L'équipe plateforme possède tous les containers d'infrastructure"
• Décisions fournisseur : "Nous utiliserons Datadog pour le monitoring au lieu de construire en interne"

Si la décision est significative et réversible-mais-coûteuse, un ADR est approprié peu importe si c'est strictement "architectural."

Pièges courants

Écrire les ADR après coup

Le meilleur moment pour écrire un ADR est pendant le processus de décision. En écrire un des semaines plus tard signifie que vous avez oublié les nuances, les alternatives considérées et les contraintes existantes. Faites de la rédaction d'ADR une partie du processus de décision, pas une pensée après coup.

Les rendre trop longs

Si votre ADR dépasse une page, vous documentez probablement plusieurs décisions (divisez-les) ou incluez des détails d'implémentation (gardez-les pour un document de conception). La discipline de la concision force la clarté.

Ne pas documenter les alternatives rejetées

La section "Alternatives considérées" est la partie la plus précieuse d'un ADR à long terme. Sans elle, les futurs ingénieurs proposeront les mêmes alternatives, ignorant qu'elles ont déjà été évaluées et rejetées. Expliquez toujours ce que vous n'avez pas choisi et pourquoi.

Abandonner la pratique

Un ou deux ADR n'apportent pas grand-chose. Cinquante ADR accumulés sur deux ans deviennent une base de connaissances inestimable. La tentation d'arrêter d'écrire des ADR quand les choses s'accélèrent est forte. Résistez. Les 15 minutes passées à écrire un ADR feront économiser des heures de réunions plus tard.

Ne pas revoir ni mettre à jour les statuts

Une collection d'ADR où la moitié des décisions sont obsolètes est trompeuse. Planifiez des revues trimestrielles. Marquez les décisions remplacées. Gardez la collection digne de confiance.

Pourquoi les ADR comptent encore plus à l'ère de l'IA

À mesure que les agents IA deviennent des participants actifs du développement logiciel, les ADR prennent une nouvelle importance. Un agent IA qui écrit du code peut lire vos ADR et comprendre :

• Pourquoi certaines technologies ont été choisies (et doivent continuer à être utilisées)
• Quelles alternatives ont été rejetées (et ne doivent pas être re-proposées)
• Quelles contraintes existent (exigences de conformité, seuils de performance)
• Quels compromis ont été acceptés (cohérence éventuelle, dépendances fournisseur)

Via le serveur MCP d'Archyl, les agents IA comme Claude Code peuvent accéder à vos ADR avant de faire des suggestions architecturales. Au lieu de proposer MongoDB pour un service où vous avez déjà documenté pourquoi PostgreSQL a été choisi, l'agent respecte la décision existante -- ou signale explicitement quand il pense que la décision devrait être reconsidérée.

Cela fait des ADR non seulement de la documentation pour les humains, mais des garde-fous pour l'IA.

Commencer dès aujourd'hui

Si votre équipe n'utilise pas encore les ADR, commencez par ces trois étapes :

1. Choisissez une décision récente. Pensez à un choix architectural que votre équipe a débattu le mois dernier. Rédigez un ADR en utilisant le template ci-dessus. Cela devrait prendre 15-20 minutes.

2. Stockez-le dans votre dépôt. Créez un répertoire docs/adr/ et ajoutez le fichier. Incluez-le dans votre prochaine pull request pour que l'équipe le voie.

3. Faites-en une habitude. Ajoutez une case "Impact architectural" à votre template de PR. Discutez des ADR lors de votre prochaine réunion d'architecture. La pratique prend de l'élan une fois que l'équipe en voit la valeur.

La prochaine fois que quelqu'un demandera "pourquoi avons-nous fait ça comme ça ?" -- et ça arrivera -- vous aurez la réponse.

Explorez davantage la documentation d'architecture : Qu'est-ce que le modèle C4 ? | Bonnes pratiques ADR | Découverte d'architecture par IA. Ou essayez Archyl gratuitement pour gérer vos ADR directement liés à votre modèle C4.