TEMPLATE
Template : Architecture Decision Record
Le modèle et les exemples concrets pour documenter vos décisions d'architecture de manière structurée, traçable et collaborative.
Recevez le template ADR en PDF
Entrez votre email pour recevoir ce template et les 2 exemples au format imprimable.
Qu'est-ce qu'un ADR ?
Un Architecture Decision Record (ADR) est un document court qui capture une décision d'architecture significative, son contexte et ses conséquences. Popularisé par Michael Nygard en 2011, le concept est devenu une pratique essentielle des équipes d'ingénierie modernes.
Pourquoi les ADR sont-ils indispensables ? Parce que les décisions d'architecture sont prises dans un contexte précis qui sera oublié dans six mois. Quand un nouveau développeur rejoint l'équipe et demande "Pourquoi a-t-on choisi MongoDB plutôt que PostgreSQL ?", l'ADR apporte la réponse complète : le contexte, les alternatives évaluées, les critères de décision et les conséquences acceptées. Sans ADR, les équipes reprennent les mêmes débats en boucle, ou pire, remettent en cause des décisions sans comprendre les raisons qui les ont motivées.
Un bon ADR est court (1 à 2 pages), factuel, et rédigé au moment où la décision est prise, pas après coup. Il n'a pas besoin d'être parfait : il doit être utile.
Structure du template
Chaque ADR suit une structure standardisée en six sections. Cette régularité facilite la lecture, la recherche et la maintenance sur le long terme.
Title (Titre)
Un titre court et explicite, préfixé par un numéro séquentiel. Le titre doit décrire la décision, pas le problème. Exemple : "ADR-001: Utilisation de PostgreSQL pour le service de commandes" plutôt que "ADR-001: Choix de base de données".
Status (Statut)
Le cycle de vie de l'ADR : Proposed (en discussion), Accepted (validé et en vigueur), Deprecated (remplacé par un autre ADR), ou Superseded (annulé, avec référence à l'ADR de remplacement). Un ADR accepté n'est jamais supprimé : il est déprécié.
Context (Contexte)
La situation qui motive la décision : contraintes techniques, exigences métier, dettes existantes, pression calendaire. C'est la section la plus importante car elle explique le "pourquoi". Décrivez les forces en jeu de manière factuelle, sans orienter vers la solution retenue.
Decision (Décision)
La décision elle-même, formulée de manière active et affirmative : "Nous utiliserons...", "Nous adoptons...", "Nous ne ferons pas...". Soyez précis sur le périmètre : la décision s'applique-t-elle à toute l'organisation, à un produit, à un service ?
Consequences (Conséquences)
Les implications de la décision, positives et négatives. Quels sont les bénéfices attendus ? Quels sont les compromis acceptés ? Quels risques résiduels devons-nous surveiller ? Cette honnêteté est fondamentale pour la crédibilité de l'ADR.
Alternatives (Alternatives considérées)
Les autres options évaluées et les raisons de leur rejet. Cette section empêche les discussions du type "On aurait dû choisir X" en montrant que X a été considéré et écarté pour des raisons précises.
Exemple 1
ADR-001 : Choix de PostgreSQL vs MongoDB pour le service de commandes
Statut : Accepted — 15 janvier 2025
Contexte
Le service de commandes doit être reconstruit dans le cadre de la migration vers une architecture microservices. Ce service gère environ 50 000 commandes par jour avec des pics à 200 000 lors des périodes promotionnelles. Les données de commande ont un schéma relativement stable (client, produits, adresse, paiement, statut) mais incluent des métadonnées variables selon le canal de vente (web, mobile, marketplace). Le service doit supporter des requêtes transactionnelles (création, mise à jour de statut) et des requêtes analytiques (reporting, tableaux de bord opérationnels). L'équipe de 6 développeurs a une forte expérience SQL et une expérience limitée en bases documentaires.
Décision
Nous utiliserons PostgreSQL 16 pour le service de commandes. Les métadonnées variables seront stockées dans une colonne JSONB, combinant la rigueur du modèle relationnel avec la flexibilité du schemaless pour les cas qui le justifient.
Conséquences
- + Transactions ACID natives pour la cohérence des commandes
- + Requêtes analytiques performantes sans base secondaire
- + Compétences SQL déjà présentes dans l'équipe
- + Écosystème mature (PgBouncer, Patroni, pg_stat_statements)
- - Scaling horizontal plus complexe que MongoDB (lecture seule via replicas)
- - Les requêtes JSONB complexes peuvent être moins performantes qu'un modèle document natif
Alternatives considérées
MongoDB 7 : meilleure flexibilité de schéma et scaling horizontal natif, mais les transactions multi-documents ajoutent de la complexité pour un cas d'usage qui est fondamentalement transactionnel. Le manque d'expérience de l'équipe aurait nécessité 2 à 3 mois de montée en compétences, incompatible avec le calendrier du projet. CockroachDB : combine SQL et scaling horizontal distribué, mais le surcoût en latence d'écriture (consensus Raft) n'est pas justifié pour notre volumétrie actuelle, et le coût de licence est significativement plus élevé.
Exemple 2
ADR-002 : Adoption de Terraform vs Pulumi pour l'IaC
Statut : Accepted — 22 février 2025
Contexte
Notre infrastructure est actuellement provisionnée manuellement via les consoles AWS et GCP. Avec la croissance du nombre de services (de 4 à 15 en 18 mois) et l'adoption du multi-cloud, cette approche n'est plus tenable : les environnements divergent, les déploiements sont lents et les erreurs humaines fréquentes. Nous devons adopter un outil d'Infrastructure as Code pour standardiser et automatiser le provisionnement. L'équipe plateforme est composée de 3 ingénieurs avec une forte culture Python/TypeScript et une expérience limitée en HCL. Nous opérons sur AWS (principal) et GCP (workloads data/ML).
Décision
Nous adopterons Terraform (avec OpenTofu comme plan de contingence) pour l'ensemble de notre Infrastructure as Code. Le state sera stocké sur S3 avec DynamoDB pour le locking. Nous utiliserons une structure de modules internes pour mutualiser les patterns d'infrastructure entre les équipes.
Conséquences
- + Écosystème de providers le plus large du marché (AWS, GCP, Datadog, PagerDuty...)
- + Plan d'exécution (terraform plan) pour valider les changements avant application
- + Communauté massive : documentation, modules publics, support communautaire
- + OpenTofu comme alternative open-source en cas de changement de licence HashiCorp
- - HCL est un langage déclaratif spécifique à apprendre (courbe d'apprentissage de 2-3 semaines)
- - La gestion du state est un point de complexité et un risque opérationnel
- - Les boucles et la logique conditionnelle en HCL sont moins élégantes qu'en Python/TypeScript
Alternatives considérées
Pulumi : permet d'écrire l'IaC en Python ou TypeScript, ce qui correspond mieux aux compétences de l'équipe. Cependant, l'écosystème est plus restreint (certains providers moins matures), la communauté est plus petite (moins de modules réutilisables), et le risque de vendor lock-in est plus élevé (pas d'équivalent OpenTofu). La capacité à écrire de la logique complexe en Python est un avantage rarement nécessaire pour de l'IaC bien structurée. AWS CDK / GCP Deployment Manager : écartés car spécifiques à un seul cloud provider, incompatibles avec notre contexte multi-cloud.
Bonnes pratiques
Quand écrire un ADR ?
- Choix d'une technologie structurante (base de données, framework, cloud provider)
- Adoption d'un pattern d'architecture (microservices, event sourcing, CQRS)
- Décision de ne pas faire quelque chose (aussi important que les décisions positives)
- Tout choix qui serait difficile à inverser après 3 mois de développement
Qui participe ?
- L'auteur : le tech lead ou l'architecte qui porte la proposition
- Les reviewers : les développeurs seniors de l'équipe concernée
- Les stakeholders : Product Owner si impact fonctionnel, SRE si impact opérationnel
- La revue se fait via une Pull Request, comme du code
Où stocker les ADR ?
- Dans le repository Git du projet, dossier
docs/adr/ - Format Markdown pour la lisibilité et le versioning
- Un fichier par ADR, numéroté séquentiellement
- Un fichier INDEX.md qui liste tous les ADR avec leur statut
Besoin d'aide pour structurer vos décisions d'architecture ?