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

Dans de nombreux projets, certaines décisions techniques deviennent rapidement obscures. Des questions telles que « Pourquoi ce framework a-t-il été choisi ? » ou « Pourquoi utilise-t-on Redis ici, mais pas ailleurs ? » se posent souvent. Au fil du temps, avec le changement de développeurs et la disparition des discussions sur des plateformes comme Slack, les décisions prises il y a plusieurs mois deviennent difficiles à comprendre.

C’est ici qu’intervient l’Architecture Decision Record (ADR). Un ADR est un document simple qui sert à conserver une trace des décisions techniques significatives dans un projet. Contrairement à une documentation exhaustive, un ADR est généralement court, simple et centré sur une seule décision. L’objectif principal est de répondre à la question essentielle : « Pourquoi cette décision a-t-elle été prise ? »

Un ADR typique contient plusieurs éléments clés :

• Le contexte : qui explique le problème rencontré.
• La décision : qui décrit le choix effectué.
• Les conséquences : qui détaillent les avantages, limites ou compromis associés.

Voici un exemple simplifié d’ADR :

ADR-001 : Utilisation de PostgreSQL

Contexte

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

Décision

Utiliser PostgreSQL comme base principale.

Conséquences

• SQL puissant
• Bonnes performances relationnelles
• Infrastructure plus lourde qu’une base NoSQL

Bien que ce type de document puisse sembler anodin, il devient extrêmement précieux avec le temps.

Pourquoi mettre en place des ADR ?

Sans ADR, de nombreux projets se retrouvent avec des décisions « historiques » que plus personne ne comprend réellement. Cela peut engendrer divers problèmes :

• Duplication de solutions
• Remise en question constante des choix techniques
• Crainte de modifier certaines parties du projet
• Difficulté dans l’intégration de nouveaux membres dans l’équipe

De plus, cela accentue le risque lié au « bus factor », un concept qui désigne le risque que des connaissances critiques soient perdues si une personne clé quitte le projet.

La mise en place d’ADR est particulièrement bénéfique dans :

• Les projets de longue durée
• Les équipes en expansion
• Les architectures complexes
• Les projets open source

Une bonne nouvelle est qu’il est possible de commencer immédiatement sans outils spécifiques. Beaucoup d’équipes choisissent de stocker leurs ADR dans un dossier, par exemple :

/docs/adr

ou directement :

/adr

L’important n’est pas le format, mais de commencer à documenter le plus tôt possible. En architecture logicielle, comprendre pourquoi certaines décisions ont été prises des années plus tard est tout aussi crucial que de prendre de bonnes décisions.

Source : Article original sur l’Architecture Decision Record.