Architecture Decision Records : comment ne plus perdre le contexte technique

Chaque codebase contient des décisions évidentes pour les personnes qui les ont prises, mais mystérieuses pour tout le monde six mois plus tard.

Pourquoi le module de facturation publie-t-il des événements au lieu d'appeler directement le CRM ? Pourquoi l'API gateway peut-elle importer les contrats partagés, mais pas les packages de feature ? Pourquoi l'équipe a-t-elle gardé le monolithe au lieu d'extraire un service ? Les réponses ont probablement existé quelque part : dans un fil Slack, une réunion, un commentaire de pull request ou la mémoire de quelqu'un.

Puis l'équipe change. Le fil disparaît. La PR est enterrée. La personne qui connaissait le contexte passe sur un autre projet.

C'est comme cela que le contexte technique se perd. Et quand le contexte disparaît, les équipes répètent les mêmes débats, annulent de bonnes décisions et introduisent de la dérive architecturale sans réaliser qu'elles violent une conception intentionnelle.

Les Architecture Decision Records, souvent appelés ADR, sont une manière légère d'éviter cela.

Qu'est-ce qu'un Architecture Decision Record ?

Un Architecture Decision Record est un court document qui capture une décision technique importante, le contexte derrière cette décision, les options considérées et les conséquences acceptées par l'équipe.

Un ADR n'est pas un long document d'architecture. Ce n'est pas un deck stratégique. C'est la trace d'une vraie décision, écrite au moment où la décision est prise.

Un ADR utile répond à cinq questions :

1. Quelle décision avons-nous prise ?
2. Pourquoi devions-nous la prendre ?
3. Quelles options avons-nous envisagées ?
4. Pourquoi avons-nous choisi cette option ?
5. Quels compromis acceptons-nous ?

Le but n'est pas de prouver que l'équipe a pris la décision parfaite. Le but est de rendre la décision lisible pour les mainteneurs futurs.

Pourquoi les ADR sont importants

La plupart des problèmes d'architecture ne viennent pas d'un manque d'intelligence. Ils viennent d'un manque de contexte.

Un nouveau développeur voit une frontière de module et ne sait pas pourquoi elle existe. Une deadline produit arrive, et quelqu'un contourne un service parce que l'import direct est plus rapide. Un reviewer approuve le changement parce que le diff semble raisonnable. Trois mois plus tard, la codebase contient un chemin de dépendance que personne n'avait prévu.

C'est exactement comme cela que les code reviews laissent passer la dette architecturale. Les reviewers inspectent le changement local, mais ils ne connaissent pas toujours la raison historique derrière une frontière.

Les ADR donnent aux reviewers et aux mainteneurs une source de vérité. Quand une PR traverse une frontière, le reviewer peut pointer vers la décision documentée plutôt que s'appuyer sur sa mémoire ou sa préférence personnelle.

Qu'est-ce qui mérite un ADR ?

Tous les choix ne méritent pas un ADR. Vous n'avez pas besoin d'un document de décision pour nommer une fonction helper ou choisir entre deux bibliothèques utilitaires équivalentes.

Écrivez un ADR quand la décision change la forme du système.

Les bons sujets d'ADR incluent :

• Choisir entre monolithe, monolithe modulaire ou microservices
• Définir les frontières de modules dans un monorepo
• Sélectionner une base de données, une queue, un framework ou un fournisseur d'authentification
• Décider comment les services communiquent
• Introduire un package partagé ou une API interne publique
• Changer le modèle de déploiement
• Accepter un compromis architectural temporaire
• Définir quelles dépendances sont interdites

La règle la plus simple : si un développeur futur risque de demander « pourquoi c'est comme ça ? », écrivez un ADR.

Un template d'ADR pratique

Un ADR utile doit être assez court pour que les gens l'écrivent vraiment. Commencez avec cette structure :

# ADR 004 : Garder la facturation dans le monolithe modulaire

## Statut

Accepté

## Contexte

Le domaine facturation touche les abonnements, les factures, les limites d'usage et le cycle de vie client. L'équipe a envisagé de l'extraire dans un service séparé parce que les changements de facturation sont sensibles et importants opérationnellement.

## Décision

Nous garderons la facturation dans le monolithe modulaire pour l'instant, derrière une frontière de module claire et une interface d'événements interne.

## Options considérées

- Extraire la facturation dans un service séparé
- Garder la facturation comme un module applicatif normal
- Garder la facturation dans le monolithe avec des frontières explicites

## Conséquences

Cela simplifie le développement local et les déploiements. Cela signifie aussi que le code de facturation ne doit pas importer directement des modules de feature sans rapport. Si le couplage augmente, nous réévaluerons l'extraction.

C'est suffisant. La valeur vient de la cohérence, pas de la longueur.

Où placer les ADR

Les ADR devraient vivre dans le repository, près du code qu'ils expliquent.

Une structure courante ressemble à ceci :

docs/
  adr/
    0001-use-postgres.md
    0002-modular-monolith-boundaries.md
    0003-github-pr-quality-gates.md

Placer les ADR dans le repository a trois avantages.

D'abord, les ADR sont versionnés avec le code. Si l'architecture change, l'historique de décision change au même endroit.

Ensuite, les ADR peuvent être revus dans les pull requests. Un changement d'architecture significatif devrait inclure à la fois le code et la décision qui l'explique.

Enfin, les ADR deviennent une partie de l'onboarding. Les nouveaux développeurs peuvent lire la trace des décisions au lieu de reconstituer l'histoire depuis d'anciens messages.

Comment les ADR réduisent la dérive architecturale

La dérive architecturale survient quand le code réel diverge progressivement de l'architecture prévue. Les ADR ne l'empêchent pas seuls, mais ils rendent l'architecture prévue explicite.

Par exemple, supposons qu'un ADR dise :

Les packages de feature peuvent dépendre des contrats partagés, mais les contrats partagés ne doivent pas dépendre des packages de feature.

Cette phrase donne quelque chose de concret à appliquer. Vous pouvez la traduire en règles de dépendances, en checklist de review ou en vérifications automatisées sur les PRs.

Sans ADR, la règle reste une connaissance tribale. Avec un ADR, la règle devient une partie du modèle opérationnel de la codebase.

C'est là que les ADR fonctionnent bien avec les vérifications automatisées. L'ADR explique le « pourquoi » ; les outils appliquent le « quoi ». Un quality gate sur GitHub peut bloquer les imports interdits, tandis que l'ADR explique pourquoi cet import est interdit.

Erreurs courantes avec les ADR

L'erreur la plus courante est d'écrire les ADR comme des documents juridiques. Si un ADR prend deux heures à produire, personne ne continuera. Gardez-les simples, pratiques et proches de la décision.

Une autre erreur est de réécrire l'histoire. Les ADR doivent capturer les compromis honnêtement. Si l'équipe a choisi l'option la plus simple à cause de la pression de livraison, dites-le. Les mainteneurs futurs ont besoin de réalité, pas d'une version polie de la réalité.

Une troisième erreur est de traiter les ADR comme une vérité permanente. L'architecture évolue. Quand une décision change, ne modifiez pas l'ancien ADR jusqu'à effacer l'historique. Marquez-le comme remplacé et écrivez-en un nouveau.

## Statut

Remplacé par ADR 009 : Extraire la facturation dans un service séparé

L'ancienne décision reste importante parce qu'elle explique pourquoi le système avait cette forme à ce moment-là.

Connecter les ADR à la code review

Les ADR deviennent vraiment utiles quand ils apparaissent dans le workflow quotidien.

Ajoutez une petite section à votre template de PR :

## Impact architecture

- Cette PR change-t-elle les frontières de modules ?
- Introduit-elle une nouvelle direction de dépendance ?
- Nécessite-t-elle un nouvel ADR ou une mise à jour d'ADR ?

Cela n'a pas besoin d'être bureaucratique. La plupart des PRs répondront « non ». Mais quand la réponse est « oui », l'équipe capture les changements d'architecture avant qu'ils ne deviennent permanents en silence.

Pour les changements plus larges, liez directement l'ADR dans la description de PR. Les reviewers peuvent évaluer l'implémentation et le raisonnement ensemble.

Comment ReposLens aide

ReposLens ne peut pas écrire vos ADR à votre place, mais il peut aider à vérifier les décisions.

Quand vous définissez des frontières dans un ADR, ReposLens vous aide à voir si le code les respecte encore. Si un package partagé commence à dépendre d'un package de feature, le graphe de dépendances rend la violation visible. Si une PR introduit une nouvelle dépendance circulaire, le check d'architecture peut la détecter avant le merge.

Cela ferme la boucle :

• Les ADR documentent l'architecture prévue
• La visualisation des dépendances révèle l'architecture réelle
• Les checks de PR empêchent la divergence accidentelle

Cette combinaison est beaucoup plus forte que la documentation ou l'outillage seuls.

Commencez petit

Vous n'avez pas besoin de documenter toutes les décisions que votre équipe a déjà prises. Commencez par la prochaine décision d'architecture significative.

Créez docs/adr/0001-votre-decision.md. Gardez-le sous une page. Liez-le depuis la PR. Revisitez-le quand l'architecture change.

Le bénéfice arrive plus tard, quand quelqu'un demande pourquoi le système est organisé de cette manière et que la réponse n'est pas cachée dans la mémoire. Elle est là, dans le repository, à côté du code qu'elle protège.