Vos décisions d'architecture s'évaporent. Les ADR les capturent.

Le jour où personne ne sait pourquoi

Scénario classique. Vous rejoignez un projet Symfony. Dans src/Services/, un service nommé ApiClientService hérite de \GuzzleHttp\Client. Mais le projet utilise aussi symfony/http-client à trois autres endroits, introduit lors d'une mise à jour récente.

Vous posez la question dans Slack. Personne ne sait. La personne qui a fait ce choix a quitté l'équipe en 2022. Il y a peut-être un thread dans Jira — introuvable. Il y a peut-être eu une discussion en réunion — aucun compte rendu.

Résultat : vous maintenez deux clients HTTP dans la même application. Vous ne savez pas si c'est un choix délibéré ou un oubli. Vous n'osez pas toucher à Guzzle. La dette s'accumule.

Ce n'est pas un problème de code. C'est un problème de mémoire collective.

Selon le Stack Overflow Developer Survey 2023, 42 % des développeurs passent plus de 30 minutes par semaine à comprendre du code non documenté. Multipliez par l'équipe. Multipliez par l'année. Le coût de l'oubli est réel, il est récurrent, et il est évitable.

Ce qu'est un ADR — en 3 phrases

Un Architecture Decision Record (ADR) est un document court qui capture une décision architecturale significative, avec son contexte et ses conséquences.

Ce n'est pas un wiki. Ce n'est pas une spec fonctionnelle. C'est une trace écrite du raisonnement : pourquoi ce choix, à ce moment, avec ces contraintes précises — et pas un autre.

Trois termes connexes à connaître une fois :

• AD — la décision elle-même (Architecture Decision)
• ADL — l'ensemble des décisions du projet, accumulées (Architecture Decision Log)
• ASR — l'exigence qui a motivé la décision (Architecturally Significant Requirement)

En pratique : vous rédigerez des AD, vous les accumulerez dans un ADL. Vous n'aurez probablement jamais besoin d'écrire le mot "ASR".

Le format Nygard : 3 sections, c'est tout

Michael Nygard a formalisé ce format en 2011 dans un billet de blog. C'est le plus utilisé parce que c'est le plus simple. Trois sections obligatoires : Contexte, Décision, Conséquences. Rien d'autre.

Voici ADR-0001, rédigé lors d'une migration Symfony 5 vers 7 pour une PME réunionnaise :

# ADR-0001 — Migrer de Guzzle vers symfony/http-client

Date : 2026-03-12
Statut : Accepté

## Contexte

Notre application Symfony 5 utilise GuzzleHTTP 6 pour les appels API externes.
La migration vers Symfony 7 introduit symfony/http-client comme composant natif.
Maintenir deux clients HTTP dans le projet augmente la surface de maintenance.

## Décision

Remplacer GuzzleHTTP par symfony/http-client lors de la migration Symfony 7.
Tous les services qui étendent \GuzzleHttp\Client seront refactorisés.

## Conséquences

- Réduction d'une dépendance tierce (Guzzle supprimé de composer.json)
- Intégration native avec le profiler Symfony (débogage des requêtes HTTP simplifié)
- Refactoring nécessaire : 4 services identifiés (ApiClientService, WebhookService, etc.)
- ADR-0002 traitera le remplacement des mocks Guzzle dans les tests unitaires

20 lignes. Pas de diagramme. Pas d'UML. La décision est datée, contextualisée, avec ses impacts concrets.

Notez la dernière ligne : ADR-0002 est annoncé. Les ADR se chaînent. Chaque décision peut pointer vers une autre, construisant progressivement la mémoire du projet. C'est l'ADL — et il se constitue naturellement, un commit à la fois.

Quand écrire un ADR ?

Cinq déclencheurs. Si l'un se présente dans votre sprint, ouvrez un fichier.

• Choix de librairie tierce — adopter un serializer, remplacer un client HTTP, introduire un outil de test. Toute dépendance externe qui va rester dans votre composer.json pendant des années mérite une trace.
• Changement de structure de base de données — ajout d'une colonne JSON, passage de MySQL à PostgreSQL, création d'une table pivot dont le sens n'est pas évident à froid.
• Décision de sécurité — algorithme de hachage, politique JWT, durée de session, gestion des rôles et permissions.
• Choix d'infrastructure — migrer de Apache à Nginx, adopter Docker, choisir un fournisseur d'emails transactionnels, paramétrer Traefik.
• Refus délibéré d'une option — vous avez évalué une approche et vous ne la retenez pas. Documentez pourquoi. C'est souvent l'ADR le plus précieux : il empêche de réévaluer les mêmes options 18 mois plus tard, avec le même résultat.

Ce qui ne mérite pas un ADR : le nommage des variables, les choix de mise en forme CSS, la configuration locale de votre IDE. La règle pratique : si revenir en arrière sur cette décision coûte plus d'une journée de travail, elle mérite un ADR.

Le développeur solo — et le contexte réunionnais

Je maintiens des projets Symfony legacy à La Réunion depuis 7 ans. Dans ce contexte, le développeur qui reprend le code dans 18 mois, c'est souvent moi-même.

Sans ADR, je retombe dans mes propres pièges. Je me souviens de la solution, pas du raisonnement. Je reconstruis des contextes que j'avais déjà établis, parfois en prenant des décisions contraires à ce que j'avais décidé 2 ans plus tôt pour de bonnes raisons que j'ai oubliées.

Le tissu économique réunionnais amplifie ce phénomène : les projets Symfony legacy locaux sont souvent maintenus par de petites équipes, avec peu de documentation formelle, et un historique de décisions qui disparaît avec les gens qui partent. Les ADR ne résolvent pas tout — mais ils capturent ce qui coûte le plus cher à perdre.

Votre premier ADR : 15 minutes, maintenant

Reprenez un choix technique récent dans votre projet. N'importe lequel — une librairie ajoutée la semaine dernière, une configuration de production modifiée, une refactorisation acceptée ou refusée en revue de code.

Créez le fichier dans votre dépôt :

mkdir -p adr
touch adr/0001-nom-de-la-decision.md

Remplissez les 3 sections Nygard : Contexte, Décision, Conséquences. Visez 15 à 20 lignes, pas plus. Commitez avec un message clair : docs(adr): add ADR-0001 - replace Guzzle with symfony/http-client.

C'est fait. Vous venez de créer la première entrée de votre ADL.

Le template Nygard prêt à l'emploi est disponible sur le repo GitHub CodexLab — un fichier .md à copier directement dans votre projet.

Suite de la série : comment organiser vos ADR dans un workflow Git, comparer 3 formats et intégrer la revue d'ADR à vos pull requests.