Introduction
Les Architecture Decision Records (ADR) sont des documents courts et structurés qui enregistrent les décisions clés prises lors de la conception ou de l'évolution d'un système logiciel. Introduits par Michael Nygard en 2011, ils répondent à un besoin critique : comment justifier et tracer les choix architecturaux au fil du temps ?
Dans un contexte où les équipes distribuées et les projets long terme sont la norme, les ADR surpassent les diagrammes statiques ou les tickets Jira. Ils capturent le contexte, le statut, les décisions et les conséquences, rendant les rationales accessibles à tous – juniors comme seniors. Imaginez un nouveau développeur qui hérite d'un monolithe migré vers des microservices : sans ADR, il devine ; avec, il comprend en 5 minutes pourquoi PostgreSQL a été choisi plutôt que MongoDB.
Pourquoi adopter les ADR en 2026 ? Les régulations comme GDPR ou SOC2 exigent une auditabilité, les audits internes deviennent fréquents, et les outils CI/CD intègrent nativement la doc (GitHub, GitLab). Résultat : réduction de 40% des réunions de recap (selon des études ThoughtWorks), onboarding accéléré, et architecture résiliente face aux turnovers. Ce tutoriel intermédiaire vous guide pas à pas pour les implémenter sans alourdir vos workflows.
Prérequis
- Connaissances intermédiaires en architecture logicielle (patterns comme MVC, microservices).
- Familiarité avec Git et Markdown pour la gestion de versions.
- Expérience en gestion d'équipe agile (Scrum/Kanban).
- Outils : éditeur Markdown (VS Code), repo Git (GitHub/GitLab).
Qu'est-ce qu'un ADR ? Fondations théoriques
Un ADR est un fichier Markdown unique par décision, stocké dans un dossier dédié comme docs/adr/. Contrairement à un wiki verbeux, il est immuable post-publication : les changements génèrent un nouvel ADR.
Analogie : comme un jugement de cour, il fixe le 'pourquoi maintenant' sans réécrire l'histoire. Statuts standards :
| Statut | Signification | Exemple |
|---|---|---|
| -------- | --------------- | --------- |
| Proposed | En discussion | Migration vers Kubernetes. |
| Accepted | Décision validée | Adopté par l'équipe. |
| Deprecated | Remplacé | Par une v2. |
| Superseded | Annulé par un autre ADR. |
Avantage clé : recherche full-text via Git pour 'Kubernetes' révèle l'évolution des choix.
Structure standard d'un ADR
Adoptez le template MADR (Markdown ADR) pour la consistance :
- Titre : Numéroté séquentiellement, ex. "001-use-postgresql-for-user-data.md".
- Status : Proposed/Accepted/etc.
- Context : Problème métier/technique (2-3 phrases).
- Decision : Choix retenu + alternatives rejetées.
- Consequences : Impacts positifs/négatifs (perf, coût, complexité).
- Date : ISO 8601.
``
# 001 - Use PostgreSQL for User Data
## Status
Accepted
## Context
L'app gère 10k users/jour ; MongoDB scale mal en transactions ACID.
## Decision
Migrer vers PostgreSQL 15. Rejeté : Cassandra (trop complexe pour l'équipe).
## Consequences
+ ACID garanti, - Courbe d'apprentissage SQL.
Date: 2026-01-15
``
Étude de cas : Chez Spotify, les ADR ont documenté le passage à l'event sourcing, évitant des regressions lors de refactorings.
Processus de création et intégration workflow
Étape 1 : Déclencheur. Toute décision impactant l'architecture (DB, framework, infra) nécessite un ADR. Règle : si >2 devs impactés, documentez.
Étape 2 : Rédaction. PM/Architecte draft via template GitHub. Pull Request (PR) obligatoire.
Étape 3 : Review. 2 reviewers mini (un tech, un produit). Critères : clarté, exhaustivité alternatives.
Étape 4 : Merge & Numérotation. Auto via GitHub Action (next number).
Intégration CI/CD :
- Hook Git : valider template via
adr-tools(CLI). - Index auto :
adr index generatepour une vue d'ensemble.
Exemple workflow GitHub :
git checkout -b adr/002-use-kafka.- Rédigez,
git commit -m 'adr: propose Kafka for events'. - PR → Merge → Status: Accepted.
Résultat : 100% traçable, searchable.
Gestion avancée : Évolution et maintenance
Les ADR ne meurent pas : Supersede au lieu de supprimer.
Cas complexes :
- Changements mineurs : ADR #003-deprecate-jwt (référence #001).
- Rollback : ADR #004-revert-to-rest (contexte : perf Kafka décevante).
Outils avancés :
- adr-tools : CLI pour init/list/diff.
- GitHub Pages : Générer un site statique des ADR.
Métriques de santé :
| Métrique | Seuil vert | Action |
|---|---|---|
| ---------- | ------------ | -------- |
| Nb ADR/mois | <5 | OK |
| % Accepted | >80% | Review process OK |
| Âge moyen | <2 ans | Audit |
Étude de cas Netflix : 500+ ADR trackent l'évolution de Chaos Engineering, facilitant les audits FedRAMP.
Bonnes pratiques essentielles
- Restez concis : Max 1 page A4. Focus faits, pas opinions.
- Impliquez l'équipe : Review cross-fonctionnel (devops, QA).
- Liez aux tickets :
[#JIRA-123]pour traçabilité. - Automatisez : GitHub Action pour numbering/status update.
- Indexez : README.md avec liens + recherche GitHub Wiki.
Erreurs courantes à éviter
- Trop verbeux : Évitez les essais ; listez 2-3 alternatives max.
- Pas de consequences : Sans impacts mesurables, l'ADR perd valeur (ex. +15% latence).
- Oubli review : Merge solo = biais ; toujours PR.
- Suppression : Ne deletez jamais ; supersede pour historique.
Pour aller plus loin
- Lisez le manifeste original de Michael Nygard.
- Installez adr-tools pour CLI.
- Explorez MADR template.
- Découvrez nos formations Learni sur l'architecture logicielle pour maîtriser les patterns avancés.