Le Registre de Décisions d'Architecture : Pourquoi Votre Équipe en a Besoin
Toutes les équipes d'ingénierie ont eu cette conversation. Un développeur ouvre un module, regarde une implémentation qui semble inutilement complexe et demande : "Pourquoi a-t-on construit ça comme ça ?" Le silence s'installe. La personne qui a pris la décision est partie il y a huit mois. Personne ne peut expliquer le raisonnement réel.
L'équipe fait l'une de deux choses. Soit elle laisse en l'état par peur ("il y avait probablement une raison"). Soit elle refactorise, réintroduisant sans le savoir exactement le problème que l'implémentation originale était conçue pour éviter.
Les Architecture Decision Records règlent ce problème. Ce sont l'une des pratiques les plus simples et au meilleur ROI qu'une équipe d'ingénierie puisse adopter, et la plupart des équipes ne les utilisent pas.
Ce qu'est Vraiment un ADR
Un ADR est un document court — généralement moins d'une page — qui capture une seule décision architecturale. Pas un document de conception. Pas un RFC. Juste un enregistrement de ce qui a été décidé, pourquoi, et quelles sont les conséquences attendues.
Le format est délibérément minimal. La structure la plus utilisée, basée sur la proposition originale de Michael Nygard, comporte cinq sections :
- Titre. Une courte phrase nominale.
- Statut. Proposé, Accepté, Déprécié ou Remplacé.
- Contexte. Quelle est la situation ? Quelles forces sont en jeu ?
- Décision. Qu'avons-nous décidé ? Exprimez-le clairement.
- Conséquences. Qu'est-ce qui découle de cette décision ? Positives et négatives.
Pourquoi la Section Contexte est Tout
La décision elle-même est généralement évidente en regardant le code. Ce que vous ne pouvez pas voir, c'est le pourquoi. Et c'est là que réside toute la valeur.
Un bon contexte capture le paysage décisionnel du moment : les alternatives qui existaient, les contraintes dans lesquelles l'équipe opérait, les compromis évalués.
Exemples de Bons Sujets pour les ADRs
Le seuil que j'utilise : si la décision est difficile à inverser, affecte plusieurs parties du système, ou sera questionnée par de futurs membres de l'équipe, écrivez un ADR.
Exemples :
- Choix de base de données. "ADR-003 : Utiliser PostgreSQL pour les données transactionnelles et Redis pour le stockage de sessions."
- Approche d'authentification. "ADR-007 : Implémenter une authentification stateless basée sur JWT avec tokens de rafraîchissement."
- Sélection de service tiers. "ADR-015 : Utiliser Stripe pour le traitement des paiements."
Où Vivent les ADRs
C'est non négociable : les ADRs vivent dans le dépôt de code. Pas dans Confluence. Pas dans Google Docs. Dans le dépôt, dans un répertoire comme /docs/adr/, versionné avec le code qu'ils décrivent.
Le Coût de l'Absence d'ADRs
Connaissance tribale. Les décisions architecturales vivent dans les têtes de ceux qui les ont prises. Quand ces personnes partent, la connaissance part avec elles.
Débats refaits. Sans enregistrement du pourquoi, les équipes revisitent les mêmes discussions tous les quelques mois.
Friction lors de l'onboarding. Un nouveau membre de l'équipe doit faire de l'ingénierie inverse de toute la logique architecturale.
Démarrer Sans Bureaucratie
La prochaine fois que votre équipe prend une décision architecturale significative, faites en sorte que la personne qui l'a portée passe 20 minutes à l'écrire en format cinq sections. Mettez-la dans une PR. Revoyez-la. Fusionnez-la. C'est votre premier ADR.
Chez Conectia, nous avons vu les ADRs faire une différence particulièrement grande dans les équipes distribuées. Quand nos ingénieurs senior rejoignent l'équipe d'un client, les ADRs existants leur permettent de comprendre la logique architecturale en jours plutôt qu'en semaines.
Vous construisez une équipe qui prend de solides décisions architecturales et les documente ? Parlez à un CTO — nos ingénieurs senior LATAM apportent la discipline de la prise de décision structurée à votre codebase dès le premier jour.
