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

Dans beaucoup de projets, certaines décisions techniques finissent par devenir… mystérieuses.

• Pourquoi ce framework a été choisi ?
• Pourquoi ce calcul fonctionne de cette manière ?
• Pourquoi utilise-t-on Redis ici, mais pas ailleurs ?

Le problème, c’est qu’avec le temps, les développeurs changent, les discussions Slack disparaissent, et les décisions prises plusieurs mois auparavant deviennent difficiles à comprendre.

C’est précisément le rôle des ADR, pour Archicture Decision Record.

Architecture Decision Record

Un ADR est un document très simple qui sert à conserver une trace d’une décision technique importante dans un projet.

L’idée n’est pas de rédiger une énorme documentation, au contraire :

Un ADR est généralement court, simple et centré sur une seule décision.

L’objectif est surtout de répondre à une question essentielle : Pourquoi cette décision a-t-elle été prise ?

Un ADR contient souvent :

• le contexte ⇒ explique le problème rencontré.
• la décision ⇒ décrit le choix effectué.
• les conséquences ⇒ détaillent les avantages, limites ou compromis associés.

Voici un exemple très simplifié :

# ADR-001 : Utilisation de PostgreSQL

## Context
Le projet nécessite des relations complexes entre les données.

## Decision
Utiliser PostgreSQL comme base principale.

## Consequences
- SQL puissant
- bonnes performances relationnelles
- infrastructure plus lourde qu’une base NoSQL

Ce type de document peut sembler anodin… mais il devient extrêmement précieux avec le temps.

Pourquoi mettre en place des ADR ?

Sans ADR, beaucoup de projets finissent avec des décisions “historiques” que plus personne ne comprend vraiment.

Et cela crée souvent des problèmes :

• duplication de solutions
• remise en question permanente
• peur de modifier certaines parties du projet
• onboarding plus difficile

Et surtout cela rend encore plus critique le fameux “bus factor”

Mettre en place des ADR est particulièrement utile dans :

• les projets longs
• les équipes qui grandissent
• les architectures complexes
• les projets open source

La bonne nouvelle, c’est qu’on peut commencer, dès aujourd’hui, sans aucun outils

Beaucoup d’équipes stockent simplement leurs ADR dans un dossier :

/docs/adr

Ou directement :

/adr

Le plus important n’est pas le format, mais de commencer à documenter le plus tôt possible.

Parce qu’en architecture logicielle, le problème n’est pas seulement de prendre de bonnes décisions. C’est aussi de comprendre, plusieurs années plus tard, pourquoi elles ont été prises.