Architecture décisionnelle : pourquoi les ADRs changent tout
Architecture décisionnelle : pourquoi les ADRs changent tout
J'ai rejoint une équipe bancaire en mission où le même débat revenait toutes les deux semaines : "Pourquoi on a choisi PostgreSQL plutôt que MongoDB ?" La décision avait deux ans. Personne ne s'en souvenait. Et chaque fois, on reconstruisait le contexte de zéro, parfois en prenant une direction différente de la précédente.
Ce n'était pas un manque d'intelligence. C'était un manque de mémoire organisationnelle.
Les Architecture Decision Records (ADRs) sont la réponse à ce problème. Un document court (une à deux pages) qui répond à une seule question : "Pourquoi avons-nous fait ce choix technique ?" Le concept existe depuis les années 2000. La plupart des équipes ne l'utilisent toujours pas.
Et ça leur coûte cher.
Le coût réel des décisions non documentées
Dans une équipe de 10 développeurs, si chaque développeur perd 2 heures par mois à reconstruire le contexte de décisions passées, ça représente 240 heures par an, soit plus de 6 semaines-développeur perdues sur des débats déjà tranchés.
Quand j'ai mené cet exercice chez un client dans le secteur assurance (60 développeurs, 8 équipes), les résultats étaient éloquents : 73% des développeurs n'avaient pas conscience des 3 dernières décisions architecturales majeures prises par leur propre équipe. Le coût en onboardings ratés, en refactorings inutiles, en duplications de solutions était supérieur à 400 heures par trimestre.
J'ai demandé à chaque équipe de répondre par écrit à trois questions :
- "Pourquoi utilisez-vous cette technologie plutôt que l'alternative ?"
- "Qui a pris la décision d'adopter ce pattern et quand ?"
- "Avez-vous des décisions en cours avec lesquelles vous n'êtes pas d'accord mais que vous n'avez jamais remises en question ?"
La diversité des réponses (et surtout les "je ne sais pas") a suffi à convaincre les équipes de changer leurs pratiques.
Michael Nygard, dans son billet fondateur de 2011 sur les ADRs, posait la même exigence : capturer les décisions architecturalement significatives et leur contexte, pas seulement leur résultat. Ce qui importe, c'est de comprendre pourquoi une décision a été prise, pas seulement laquelle.
Le template ADR en 5 sections
Un ADR bien rédigé répond à 5 questions dans l'ordre :
Contexte : quelle situation nécessite cette décision ? Quelles contraintes s'appliquent ? Qui est impliqué ?
Décision : quelle est la décision prise, formulée comme une assertion active ("Nous utilisons PostgreSQL comme base de données principale") plutôt que comme une question ouverte.
Statut : proposed | accepted | deprecated | superseded. Le statut évolue dans le temps : une décision peut être remplacée par une nouvelle ADR.
Conséquences : implications positives et négatives. Qu'est-ce qui devient plus simple ? Qu'est-ce qui devient plus difficile ?
Alternatives considérées : quelles autres options ont été évaluées et pourquoi ont-elles été écartées ?
# ADR-0001 : Utilisation de PostgreSQL comme base de données principale
## Contexte
Notre service de gestion des commandes nécessite une base de données relationnelle
avec support des transactions ACID. L'équipe a de l'expérience avec PostgreSQL et MySQL.
Contrainte : déploiement sur AWS, budget infrastructure limité.
## Décision
Nous utilisons PostgreSQL 15 comme base de données principale pour tous les services
qui nécessitent une persistance relationnelle.
## Statut
Accepté (2026-01-14)
## Conséquences
- Positives : ACID garanti, support JSON natif, extensions riches (PostGIS si besoin)
- Négatives : scaling vertical nécessaire avant sharding ; expertise spécifique requise
- Impact sur l'équipe : formation nécessaire pour 3 développeurs juniors
## Alternatives considérées
- MySQL 8.0 : écarté car support JSON moins mature et licensing Oracle
- MongoDB : écarté car nos données sont relationnelles
- DynamoDB : écarté car coût à l'usage imprévisible et expertise absente
Votre équipe refait les mêmes débats techniques sans jamais capitaliser sur les décisions passées ?
Je vois ce pattern dans toutes les équipes que j'accompagne : des heures perdues à reconstituer le contexte de décisions qui auraient dû être documentées. Un appel de 30 minutes suffit à définir la stratégie d'adoption des ADRs adaptée à votre équipe et à identifier les 10 décisions passées à documenter en priorité.
Les 3 premières ADRs à rédiger
Ne commencez pas par les décisions les plus anciennes ni les plus complexes. Commencez par les 3 décisions qui génèrent le plus de questions récurrentes.
Pour identifier lesquelles, je pose toujours ces questions :
- Quelle décision technique revient en débat à chaque onboarding d'un nouveau développeur ?
- Quelle décision architecturale génère des "oui mais pourquoi ?" récurrents en code review ?
- Quelle décision récente mérite d'être documentée pendant que le contexte est encore frais ?
Pour les décisions prises sans documentation, je recommande d'écrire l'ADR avec ce qu'on sait, même imparfaitement. Un ADR incomplet vaut mieux que pas d'ADR. Le statut reconstructed signale que le document a été rédigé après-coup.
Organisation et rituels de maintenance
Je recommande cette structure dans le dépôt Git :
docs/
architecture/
decisions/
0001-postgresql-base-de-donnees.md
0002-event-driven-architecture.md
0003-monorepo-structure.md
README.md ← index des ADRs avec titre et statut
Trois règles de maintenance que j'impose à toutes les équipes que j'accompagne :
Numérotation séquentielle. ADR-0001, ADR-0002... La chronologie fait partie de l'information.
Ne jamais modifier ni supprimer une ADR. Seulement la superseder avec une nouvelle. La trace historique a de la valeur : comprendre pourquoi une décision a changé est aussi utile que la décision actuelle.
Rituel de PR. À chaque pull request contenant un changement architectural significatif, vérifier si une ADR doit être créée ou mise à jour. Ce check peut être intégré dans le template de PR.
L'outil adr-tools (CLI open source) génère et gère les ADRs depuis le terminal. Pour les équipes sur Confluence, l'intégration est possible, mais je garde toujours le dépôt Git comme source de vérité.
Le piège de la rétro-documentation exhaustive
Ne pas essayer de documenter toutes les décisions passées d'un coup. La rétro-documentation exhaustive est un projet qui ne se termine pas et qui décourage l'équipe avant qu'elle prenne le pli.
Ma recommandation : documenter toutes les nouvelles décisions systématiquement à partir d'aujourd'hui, et rattraper les décisions passées au fil des besoins : lors des onboardings, des débats récurrents, ou des refactorings qui remettent en question des choix passés.
En 3 mois à ce rythme, les équipes que j'accompagne ont entre 15 et 25 ADRs actives. C'est suffisant pour changer la culture.
Ce que ça change concrètement
| Action | Résultat |
|---|---|
| Calculer le coût des décisions non documentées | Conviction de l'équipe |
| Adopter le template en 5 sections | Format standardisé |
| Rédiger les 3 premières ADRs prioritaires | Premières ADRs dans le dépôt |
| Setup le registre et les rituels de PR | Processus pérenne |
FAQ sur les ADRs
1. Où stocker les ADRs : dans le dépôt Git ou dans Confluence/Notion ?
Dans le dépôt Git, si possible. Les ADRs sont du code de documentation : elles doivent versionner avec le code qu'elles documentent. Une ADR dans Git est visible dans les PR, peut être liée aux commits concernés, et survit aux migrations d'outils. Si votre organisation exige Confluence pour la documentation, utilisez-le en complément, mais gardez le dépôt Git comme source de vérité. J'ai vu trop d'ADRs perdues lors de migrations Confluence.
2. Faut-il un ADR pour chaque décision technique ou seulement les grandes décisions d'architecture ?
Seulement les décisions significatives : choix de technologie, choix d'architecture (microservices vs monolithe, synchrone vs asynchrone), patterns de design appliqués à l'ensemble du système, décisions de sécurité ou de conformité. Pas besoin d'ADR pour les décisions de code quotidiennes : quel nom de variable, quelle structure de fichier dans un composant. La règle empirique que j'utilise : si la décision fera débat dans 6 mois, elle mérite une ADR. Par exemple, le choix d'adopter un pattern Database per Service dans une architecture microservices est typiquement le genre de décision qui doit être documentée dans une ADR.
3. Que faire quand une ADR ancienne devient obsolète ?
Créer une nouvelle ADR qui supersede l'ancienne. L'ancienne garde son statut superseded avec une référence vers la nouvelle. Jamais modifier l'ADR originale : la trace historique des décisions a de la valeur, même quand elles sont remplacées. Comprendre pourquoi une décision a changé est souvent aussi utile que comprendre la décision actuelle.
4. Comment introduire les ADRs dans une équipe qui n'a jamais documenté ses décisions ?
Je commence toujours par l'exemple. Je rédige les 3 premières ADRs moi-même, les présente en réunion d'équipe, et explique la valeur qu'elles auraient eue lors de situations passées concrètes, des situations que l'équipe reconnaît. Ensuite, j'invite les développeurs à rédiger les ADRs pour leurs prochaines décisions avec du support. Après 3 cycles, la pratique s'installe naturellement.
5. Est-ce que les ADRs ralentissent le processus de décision ?
Non, et c'est le contrepoint que j'entends toujours. Rédiger une ADR prend 30 minutes. Refaire le même débat dans 6 mois prend 3 heures, mobilise 5 personnes, et produit parfois une décision différente de la précédente sans raison valable. Le retour sur investissement est immédiat après la première ADR utilisée pour clore un débat récurrent. C'est d'autant plus vrai pour un CTO en début de mandat : parmi les 90 premiers jours d'un CTO, poser les bases de la gouvernance architecturale (dont les ADRs) est l'une des décisions structurantes les plus durables.
Ressource gratuite : Engineering Maturity Self-Assessment
L'Engineering Maturity Self-Assessment couvre le domaine Gouvernance & Documentation : évaluez votre maturité sur les pratiques de décision architecturale, la documentation, et la cohérence du système. Score et plan d'action en 10 minutes.
