Architecture Decision Records

Architecture Decision Records (ADR) sont des documents courts et structurés qui consignent les décisions d'architecture prises sur un projet. Chaque ADR capture le contexte, la décision, les alternatives envisagées et les conséquences, créant ainsi un historique consultable des choix techniques majeurs.

Les principes :

• Format structuré : chaque ADR suit un template (titre, statut, contexte, décision, conséquences) qui rend les décisions faciles à lire et à comparer.
• Versionnés avec le code : les ADR vivent dans le dépôt Git, à côté du code qu'ils documentent, et évoluent avec le projet.
• Immuables : une décision prise n'est jamais effacée — elle peut être remplacée par une nouvelle ADR, mais l'historique est préservé.
• Légers : un ADR tient généralement en une page, l'objectif est d'être concis et utile, pas exhaustif.
• Outils : des CLI comme adr-tools ou log4brains simplifient la création et la navigation dans les ADR.

Les ADR sont devenus un réflexe systématique sur nos projets chez Dernier Cri. Documenter les grandes décisions d'architecture — choix de framework, stratégie de base de données, patterns d'intégration — est devenu indispensable, surtout quand les agents IA interviennent sur le code. Les ADR fournissent le contexte nécessaire pour que chaque contributeur, humain ou IA, comprenne le pourquoi derrière les choix techniques.