Toute équipe a connu ce moment. Un nouvel arrivant ouvre le code, tombe sur un choix étrange, une file de messages là où un simple appel HTTP aurait suffi, une base NoSQL pour des données parfaitement relationnelles, et pose la question fatale :
« Pourquoi on a fait ça ? » Silence gêné. La personne qui savait est partie il y a deux ans. Le ticket Jira dit « mise en place du bus ». Le wiki n'a pas été mis à jour depuis 2023.
Le code dit
comment les choses fonctionnent. Il ne dit jamais
pourquoi elles sont comme ça. Et c'est précisément ce pourquoi qui manque le plus quand vient le moment de changer quelque chose.
Le vrai coût d'une décision oubliée
Une décision dont on a perdu la raison devient l'une de deux choses, et les deux coûtent cher.
Un tabou. Personne n'ose y toucher, parce qu'on ne sait pas ce qui casserait. On construit autour, on contourne, on empile. Le choix d'il y a trois ans devient une contrainte permanente, même si le contexte qui le justifiait a disparu depuis longtemps.
Une cible. À l'inverse, quelqu'un de motivé décide que c'était une erreur et la défait. Sauf que la raison existait bien : une contrainte réglementaire, un pic de charge en fin de mois, un client qui exigeait un hébergement particulier. On redécouvre le problème en production, et on refait la même décision, en plus cher.
Dans les deux cas, l'équipe paie pour une information qui a existé, un jour, dans la tête de quelqu'un.
Un ADR, c'est quoi exactement ?
Un
ADR (
Architecture Decision Record) est une note courte qui consigne une décision technique importante au moment où on la prend. Pas un dossier d'architecture de quarante pages. Une page, souvent moins. Le format le plus répandu tient en cinq rubriques :
- Titre : la décision, formulée simplement. « Utiliser PostgreSQL pour le service de facturation. »
- Statut : proposé, accepté, remplacé par l'ADR n° X.
- Contexte : la situation et les contraintes du moment. Volumétrie, délais, compétences de l'équipe, exigences du client.
- Décision : ce qu'on a choisi.
- Conséquences : ça implique, y compris le négatif. Ce qu'on gagne, ce qu'on sacrifie, ce qu'il faudra surveiller.
La rubrique la plus précieuse n'est pas celle qu'on croit. Ce n'est pas la décision, c'est le
contexte. C'est lui qui permettra, dans deux ans, de savoir si la décision tient toujours, ou si le monde a changé autour d'elle.
Les ADR vivent avec le code
Le secret d'un ADR qui sert, c'est son emplacement. Pas dans un outil de documentation à part que personne n'ouvre, mais
dans le dépôt de code, typiquement un dossier docs/adr/, avec un fichier Markdown numéroté par décision.
Trois avantages immédiats. L'ADR est versionné avec le code qu'il explique. Il passe en revue comme n'importe quelle modification, ce qui transforme la décision en discussion d'équipe plutôt qu'en verdict solitaire. Et il est là où le développeur cherche : à côté du code.
Les règles qui font que ça marche
On n'efface jamais un ADR. Une décision dépassée n'est pas supprimée, elle passe au statut « remplacé », avec un lien vers celle qui la remplace. L'historique des décisions raconte l'histoire du système, y compris ses virages. C'est souvent la partie la plus instructive.
On n'écrit pas d'ADR pour tout. Le nom d'une variable ou le choix d'une bibliothèque de dates ne méritent pas une note. Le bon critère : une décision difficile ou coûteuse à défaire. Changer de base de données, de mode d'authentification, de découpage en services, de stratégie de déploiement.
On l'écrit au moment de la décision, pas après. Un ADR rédigé six mois plus tard reconstruit un contexte qu'on a en partie oublié. Il devient une justification, pas un témoignage.
On documente aussi les options écartées. « On a envisagé Kafka, trop lourd à opérer pour une équipe de quatre. » Cette ligne évitera, dans un an, une réunion entière pour reposer la même question.
En pratique
Pas besoin d'un grand chantier pour démarrer. Créez le dossier, écrivez un premier ADR pour la prochaine décision importante, et un second, rétroactif, pour la décision dont tout le monde se demande le pourquoi. Ajoutez une ligne dans la checklist de revue :
« Cette modification mérite-t-elle un ADR ? » Au bout de quelques mois, vous aurez sans effort ce qu'aucune documentation n'arrive à maintenir : la mémoire des choix.
Chez
Olympp, nos consultants arrivent régulièrement sur des systèmes dont ils doivent comprendre l'histoire en quelques jours. Un dossier d'ADR bien tenu, c'est des semaines d'archéologie économisées. Et quand il n'existe pas, c'est souvent la première chose qu'on propose de créer.
Olympp, ingénierie augmentée. Le code dit comment ; nous, on aime garder la trace du pourquoi.