Bonnes pratiques pour les Architecture Decision Records (ADRs) - Archyl Blog

On a passé deux semaines à débattre d'un choix de base de données qu'on avait déjà fait et rejeté un an plus tôt. C'est là que j'ai découvert les ADRs, et ils nous ont fait gagner des heures incalculables depuis.

Bonnes pratiques pour les Architecture Decision Records (ADRs)

La réunion durait depuis deux heures. On débattait pour savoir s'il fallait utiliser PostgreSQL ou MongoDB pour un nouveau service. Les arguments volaient dans tous les sens — intégrité relationnelle, schémas flexibles, familiarité de l'équipe, complexité opérationnelle.

Puis quelqu'un a mentionné : "On n'a pas eu exactement cette discussion l'année dernière pour le service utilisateur ?"

Silence. On l'avait eue. Un an plus tôt, on avait passé un temps similaire à débattre de la même question, choisissant finalement PostgreSQL. Mais personne ne se souvenait du raisonnement. L'ingénieur qui avait mené cette discussion avait quitté l'entreprise. Alors nous y voilà, ayant exactement le même débat en repartant de zéro.

C'est à ce moment que j'ai découvert les Architecture Decision Records (ADRs), et ils nous ont fait gagner des heures incalculables à ne plus relitiger des débats déjà résolus.

Qu'est-ce qu'un ADR ?

Un ADR est un court document qui capture une seule décision architecturale. Pas un document de design couvrant tout sur un système, juste une décision :

  • Ce qu'on a décidé
  • Pourquoi on l'a décidé
  • Quelles alternatives on a considérées
  • Quelles sont les conséquences

Le format est délibérément léger. Un ADR devrait tenir sur une page. S'il est plus long, vous documentez probablement plus d'une décision.

L'anatomie d'un bon ADR

Après avoir écrit des dizaines d'ADRs et en avoir lu des centaines d'autres, j'ai trouvé que les meilleurs suivent une structure cohérente :

Titre et numéro

Chaque ADR reçoit un numéro séquentiel et un titre concis :

ADR-0042: Utiliser PostgreSQL pour le Service de Commandes

Le numéro compte. Il crée une timeline des décisions et rend les ADRs faciles à référencer dans les discussions : "Comme on l'a décidé dans l'ADR-42..."

Statut

Les ADRs ont des états de cycle de vie :

  • Proposé : Encore en discussion
  • Accepté : Décision prise, on suit ça
  • Déprécié : Plus pertinent (un nouvel ADR le remplace)
  • Rejeté : On a considéré ça mais décidé contre

Le statut rejeté est particulièrement précieux. Parfois vous voulez capturer pourquoi vous n'avez pas fait quelque chose, pour que les futures équipes ne proposent pas la même chose.

Contexte

C'est là que vous décrivez la situation qui a provoqué la décision. Quel problème résolvons-nous ? Quelles contraintes avons-nous ? Qui est affecté ?

## Contexte

Le service de commandes a besoin de stockage persistant pour les données
de commandes. On s'attend à traiter 50 000 commandes par jour initialement,
croissant à 500 000 dans deux ans. Les commandes ont une structure bien
définie mais peuvent avoir besoin de champs de métadonnées supplémentaires
avec le temps. L'équipe a de l'expérience avec les bases de données
relationnelles et documentaires.

Soyez spécifique sur les contraintes. "On a besoin de conformité ACID" est bien plus utile que "on a besoin de fiabilité." Les futurs lecteurs doivent comprendre les forces qui ont façonné la décision.

Décision

Énoncez la décision clairement. Pas "on pourrait considérer" ou "on devrait explorer" — ce qu'on a réellement décidé.

## Décision

On utilisera PostgreSQL 15 comme base de données principale pour
le service de commandes.

On a choisi PostgreSQL parce que :

- La conformité ACID est requise pour les données de commandes financières
- Les colonnes JSON fournissent de la flexibilité de schéma pour les métadonnées
- Notre équipe infra a de l'expérience opérationnelle avec PostgreSQL
- Les patterns de requêtes sont bien adaptés à la modélisation relationnelle

Notez que ça n'énonce pas juste la décision mais explique brièvement le raisonnement. La section suivante entre plus dans les détails, mais même la section décision devrait être auto-explicative.

Alternatives considérées

C'est la section la plus sous-estimée. Documenter ce que vous n'avez pas choisi est souvent aussi précieux que documenter ce que vous avez choisi.

## Alternatives considérées

### MongoDB

Avantages :

- Stockage JSON natif
- Scaling horizontal plus simple
- Évolution de schéma flexible

Inconvénients :

- Garanties de cohérence plus faibles
- Équipe moins familière avec les opérations
- Nécessiterait des outils supplémentaires pour les transactions

### DynamoDB

Avantages :

- Entièrement managé, opérations minimales
- Excellentes caractéristiques de scalabilité

Inconvénients :

- Lock-in fournisseur avec AWS
- Patterns de requêtes limités à l'accès partition/sort key
- Coût imprévisible à grande échelle

Quand quelqu'un de nouveau rejoint l'équipe et demande "pourquoi on n'a pas utilisé MongoDB ?", vous avez la réponse. Vous n'avez pas besoin de planifier une réunion ou de trouver la personne qui a pris la décision originale.

Conséquences

Chaque décision a des compromis. Soyez honnête à leur sujet.

## Conséquences

### Positives

- Fortes garanties d'intégrité des données
- L'équipe peut s'appuyer sur l'expertise PostgreSQL existante
- Caractéristiques opérationnelles bien comprises

### Négatives

- Les migrations de schéma nécessitent plus de planification que les document stores
- Scaling horizontal plus complexe si on dépasse la capacité single-node
- Besoin d'implémenter du sharding au niveau application si on atteint les limites

### Risques

- Peut nécessiter de revisiter si le volume de commandes dépasse 1M/jour
- Les requêtes sur colonnes JSON moins efficaces que les document stores natifs

Cette section concerne l'honnêteté intellectuelle. Aucune décision n'est parfaite. Reconnaître les inconvénients construit la confiance et aide les futures équipes à comprendre quand elles pourraient avoir besoin de revisiter la décision.

Quand écrire un ADR

Pas chaque choix technique ne nécessite un ADR. Utilisez votre jugement, mais voici quelques lignes directrices :

Écrivez un ADR quand...

  • La décision affecte plusieurs équipes ou services
  • La décision serait coûteuse à inverser
  • Vous choisissez entre plusieurs options viables
  • Les futurs membres de l'équipe pourraient questionner le choix
  • La décision résout un débat technique significatif

N'écrivez pas un ADR quand...

  • Le choix est évident et incontesté
  • La décision n'affecte qu'une personne ou un fichier
  • C'est facilement réversible sans coût significatif
  • C'est un pattern standard que votre équipe suit toujours

Par exemple : "Quelle bibliothèque JSON utiliser ?" n'a probablement pas besoin d'un ADR. "Utiliser GraphQL ou REST pour notre API publique ?" en a définitivement besoin.

De vrais ADRs de nos projets

Voici quelques ADRs réels que nous avons écrits (simplifiés pour cet article) :

ADR-0007: Communication Event-Driven entre Services

Contexte : Nos microservices communiquent actuellement de manière synchrone via HTTP. Ça crée un couplage fort et des échecs en cascade quand les services sont indisponibles.

Décision : On adoptera une architecture event-driven utilisant Apache Kafka pour la communication asynchrone entre services.

Conséquences :

  • Les services deviennent plus résilients aux pannes
  • Cohérence éventuelle au lieu de cohérence forte
  • Complexité opérationnelle accrue (gestion du cluster Kafka)
  • L'équipe a besoin de formation sur les patterns d'event sourcing

ADR-0015: Monorepo pour les Applications Frontend

Contexte : On a 5 applications frontend dans des repositories séparés. Partager du code nécessite de publier des packages. L'expérience développeur souffre des incompatibilités de versions.

Décision : Consolider toutes les applications frontend dans un seul monorepo utilisant Nx.

Alternatives rejetées :

  • Garder des repos séparés avec meilleure gestion de packages : Rejeté car l'overhead de coordination reste
  • Repo unique sans Nx : Rejeté car les temps de build seraient prohibitifs

Conséquences :

  • Partage de code et cohérence simplifiés
  • Une seule PR peut mettre à jour le code partagé et tous les consommateurs
  • Repository plus grand nécessite de meilleurs outils pour le cache de build
  • Potentiel de couplage non intentionnel entre applications

Erreurs courantes que j'ai faites

Erreur 1: Écrire les ADRs après coup

Le meilleur moment pour écrire un ADR est pendant le processus de décision, pas des semaines plus tard. Quand vous écrivez après, vous oubliez les nuances, les alternatives que vous avez considérées, et les contraintes spécifiques.

Maintenant on écrit des brouillons d'ADRs comme partie du processus de décision. La discussion se passe dans le document ADR, pas dans des fils Slack qui disparaissent.

Erreur 2: Les faire trop longs

Si votre ADR fait plus d'une page, vous êtes probablement en train de :

  • Documenter plusieurs décisions (séparez en plusieurs ADRs)
  • Inclure des détails d'implémentation (gardez ça pour les docs de design)
  • Sur-expliquer un contexte évident

La discipline de la brièveté force la clarté.

Erreur 3: Ne pas lier les ADRs liés

Les décisions existent rarement en isolation. Quand on a choisi Kafka pour la communication event-driven (ADR-0007), ça a influencé notre choix de base de données (ADR-0042) parce qu'on pouvait accepter la cohérence éventuelle.

Référencez les ADRs liés :

## Décisions liées

- Voir ADR-0007 pour pourquoi on accepte la cohérence éventuelle
- Remplace ADR-0003 qui recommandait MongoDB

Erreur 4: Abandonner la pratique

Les ADRs apportent de la valeur avec le temps. Un ou deux ADRs n'aident pas beaucoup. Un corpus de 50+ ADRs, accumulés sur des années, devient incroyablement précieux. C'est une histoire recherchable de votre évolution architecturale.

La tentation est d'arrêter de les écrire quand les choses deviennent chargées. Résistez. Les dix minutes passées à écrire un ADR économiseront des heures de réunions plus tard.

Faire des ADRs une partie de votre workflow

La partie la plus difficile n'est pas d'écrire des ADRs — c'est d'en faire une habitude. Voici ce qui fonctionne :

Les stocker avec le code

Mettez les ADRs dans votre repository, typiquement dans docs/adr/ ou docs/decisions/. De cette façon :

  • Ils sont versionnés avec le code qu'ils décrivent
  • Ils apparaissent dans les revues de code
  • Ils ne peuvent pas devenir orphelins dans un wiki quelque part

Utiliser un template

Créez un template markdown que tout le monde utilise. Ça réduit la friction et assure la cohérence :

# ADR-NNNN: Titre

## Statut

Proposé | Accepté | Déprécié | Rejeté

## Contexte

[Quel est le problème qu'on constate qui motive cette décision ?]

## Décision

[Quel est le changement qu'on propose et/ou fait ?]

## Alternatives considérées

[Quelles autres options avons-nous considérées ?]

## Conséquences

[Qu'est-ce qui devient plus facile ou plus difficile suite à ce changement ?]

Revoir les ADRs trimestriellement

Mettez un rappel calendrier pour revoir vos ADRs chaque trimestre :

  • Y a-t-il des décisions qui ne sont plus pertinentes ?
  • Les circonstances ont-elles changé et invalidé nos hypothèses ?
  • Y a-t-il des décisions non documentées qu'on devrait capturer ?

Lier les ADRs aux diagrammes d'architecture

C'est là que des outils comme Archyl brillent. Quand vous liez un ADR à un composant spécifique dans votre diagramme C4, quiconque regarde ce composant peut instantanément voir les décisions qui l'ont façonné.

"Pourquoi ce service parle-t-il à Kafka au lieu de directement à la base de données ?" Cliquez sur l'ADR lié et découvrez.

Conclusion

Les Architecture Decision Records sont une de ces pratiques qui semblent être de l'overhead jusqu'à ce que vous en ayez besoin. Alors ils sont inestimables.

Cette réunion de deux heures sur PostgreSQL vs MongoDB ? On l'a terminée en dix minutes une fois que quelqu'un a trouvé l'ADR original. Tout le contexte était là — les contraintes, les alternatives, le raisonnement. On a rapidement confirmé que la décision originale s'appliquait toujours et on est passé à autre chose.

Commencez petit. La prochaine fois que vous prenez une décision architecturale, prenez quinze minutes pour écrire un ADR. Mettez-le dans votre repository. Dans six mois, quand quelqu'un demandera "pourquoi on l'a fait comme ça ?", vous aurez la réponse.

En savoir plus sur la documentation d'architecture : Introduction au modèle C4 | Pourquoi la documentation compte | Documenter les flux utilisateurs