L’idée centrale de la méthode ADR est de documenter les décisions d’architecture, pas l’architecture elle-même. Ce qui se perd avec le temps n’est pas le « quoi » (qui est en réalité lisible dans le code) mais le « pourquoi » : le contexte, les contraintes et les alternatives écartées. Un ADR capture ce raisonnement au moment où il est encore frais. Mettre en place une architecture de données et mettre en place une gouvernance de données reposent sur des processus très semblables : analyser, décider, formaliser.
Qu’est-ce que la méthode ADR : historique et usages
Publiée en novembre 2011 par Michael Nygard (architecte logiciel américain, auteur de Release It ! et à l’époque associé chez Relevance — devenu Cognitect) dans un billet de blog considéré comme fondateur, « Documenting Architecture Decisions », la méthode ADR (Architecture Decision Record) part d’un constat simple : dans les projets agiles, la documentation d’architecture traditionnelle est soit ignorée, soit obsolète. Michael Nygard propose donc de consigner non pas l’architecture, mais chaque décision structurante, dans un fichier court, numéroté et versionné avec le code source, articulé en cinq rubriques : titre, statut, contexte, décision, conséquences. Un ADR accepté n’est jamais modifié : s’il devient caduc, un nouveau le complète et l’ancien est marqué « superseded », de sorte que la collection forme un journal historique du raisonnement de l’équipe. La pratique s’est diffusée rapidement : outillée dès 2016 par adr-tools (Nat Pryce), classée « Adopt » par le Technology Radar de Thoughtworks en novembre 2016, elle s’est ensuite dotée d’un site de référence communautaire (adr.github.io) et de variantes normalisées, notamment MADR (Markdown ADR) et les Y-statements d’Olaf Zimmermann, qui la rattache à la notion de « décision architecturalement significative » de la norme ISO 42010. Aujourd’hui, elle est documentée comme pratique recommandée par AWS (guide dédié dans AWS Prescriptive Guidance) ; Microsoft (Azure Well-Architected Framework) ; Red Hat, décrite dans son usage interne par Spotify (« When Should I Write an Architecture Decision Record », 2020) ; et elle a fait l’objet en novembre 2025 d’un cadre officiel du gouvernement britannique, publié par le Department for Science, Innovation and Technology avec le Government Digital Service, qui la rend obligatoire pour les décisions transverses à l’administration.
Les principes basiques de la méthode ADR
• Unicité. Une décision égale un document. Chaque ADR est court (entre une et deux pages), autonome, numéroté séquentiellement (0001, 0002…) et n’est jamais fusionné avec un autre.
• Immuabilité. Un ADR accepté ne se modifie plus. S’il devient caduc, on en écrit un nouveau qui le complète, et on marque l’ancien « Superseded by ADR-00XX » (ou tout autre équivalent dans votre langue de travail). La collection forme ainsi un journal historique, pas un document vivant. Cela se rapproche du concept de main-courante largement utilisé dans le domaine militaire.
• Proximité du code. Les ADR vivent dans le dépôt de code (typiquement doc/adr/ en Markdown), versionnés avec le code, comme n’importe quel changement.
• Seuil de pertinence. On ne documente que les décisions « architecturalement significatives » : celles qui sont couteuses à inverser, qui affectent des propriétés structurantes (performance, sécurité, cout, couplage) ou qui touchent plusieurs équipes. C’est le point le plus délicat, documenter suffisamment, mais pas trop.
• Écriture pour le futur lecteur. Le destinataire est le développeur qui arrivera dans deux ans et se demandera « pourquoi diable ont-ils fait ça ? ». Aujourd’hui le « lecteur » sera peut-être un agent qui aura besoin de comprendre l’architecture. L’ensemble des ADR pourra également entrainer un LLM qui répondra aux questions que se posent les utilisateurs sur les choix d’architecture.
La forme d’un ADR : cinq sections regroupées dans un même document
1. Titre : une phrase descriptive, numérotée.
2. Statut : Proposed / Accepted / Deprecated / Superseded (by ADR-00XX).
3. Contexte : les forces en présence, factuelles et neutres : contraintes techniques, organisationnelles, politiques, réglementaires.
4. Décision : formulée à la voix active : « Nous allons… », qui souligne la responsabilisation des acteurs qui ont pris cette décision.
5. Conséquences : ce qui devient plus facile et plus difficile après coup, positif comme négatif. C’est la section la plus souvent bâclée et pourtant la plus utile, en particulier pour une analyse a posteriori.
Il existe également des variantes ou développements complémentaires autour de la méthode ADR : MADR (Markdown ADR), plus riche, ajoute explicitement les options considérées et les critères de décision ; le format Y-statement condense la décision en une phrase structurée. Des outils comme adr-tools automatisent la numérotation et le chaînage des remplacements.
Attention à ne pas tomber dans le piège de l’écriture justificative, a posteriori. Un ADR rédigé après coup pour justifier une décision déjà prise perd sa valeur ; l’intérêt est justement de forcer l’explicitation des alternatives, et de les documenter, avant de trancher. L’ADR est donc rédigé pendant le processus de décision, afin d’en capter les principales étapes.
Adapter l’ADR à la gouvernance des données… le GDR (Governance Decision Record)
La mise en place d’une gouvernance des données, et son suivi quotidien, nécessitent de prendre des décisions, certaines mineures, d’autres structurantes, dont les effets se feront sentir dans le temps, parfois plusieurs années après. Ceux qui ont pris la décision ne sont souvent plus là, ou plus aux mêmes fonctions ; et lorsque la décision est ancienne, les raisons du choix, les arguments exposés, les débats tenus, les arguments échangés… se sont effacés des mémoires humaines, et personne à l’époque ne les avait consignés. Sur ce plan, gouvernance des données et architecture sont très proches.
L’idée est donc d’appliquer la méthode ADR aux décisions liées à la mise en place de la gouvernance des données. On passe de la méthode Architecture Decision Record (ADR) à la méthode Governance Decision Record (GDR). Et finalement très peu de choses vont changer. Les principes de la méthode évoqués ci-dessus (unicité, immuabilité…) restent identiques. La forme d’un GDR reste identique à celle d’un ADR.
Pour combiner deux formats intéressants, je vous propose de regrouper vos décisions de gouvernance (GDR) dans un Bundle OKF (lire les articles que j’ai déjà publiés sur le sujet pour comprendre les atouts de ce format ouvert publié en juin 2026 par Google). Ce bundle au format OKF regroupera donc :
- Un fichier index.md qui recense l’ensemble des décisions chronologiques
- Un fichier GDR-XXXX.md pour chaque décision suivant le format proposé ci-dessous
- Un fichier log.md qui enregistre les évolutions de format de l’ensemble du bundle
Le cœur du dispositif est bien entendu l’ensemble des fichiers GDR-XXXX.md qui chacun détaille une décision et la manière dont elle a été prise.
Dans chaque fichier .md, les sections suivantes peuvent être renseignées. Comme vous le verrez dans le modèle, certaines sections sont obligatoires, d’autres facultatives :
- Description du problème à résoudre et de son contexte
- Facteurs de décision
- Choix envisagés
- Avantages et inconvénients des différentes options
- Décision prise
- Et toute autre rubrique que vous trouverez intéressant d’ajouter dans votre contexte
Qui a en charge la rédaction des GDR ?
Évidemment, c’est celui qui coordonne les tâches de gouvernance (responsable de la gouvernance des données, coordinateur du comité de gouvernance, voir data steward) qui est responsable de cette documentation. La confier à un stagiaire sera contre-productif et montrera le peu d’intérêt que vous portez à la démarche.
Au-delà du « qui », la question du « quand » est importante. Il est totalement déconseillé de rédiger une GDR a posteriori de la décision. Il est donc difficile de reconstruire l’historique des décisions de gouvernance qui n’auraient pas été documentées au moment de leur mise en œuvre. Vous démarrez avec les décisions d’aujourd’hui.
En effet, la documentation de la décision doit être faite pendant le processus décisionnel. Cela permet de documenter les solutions envisagées, les arguments évoqués par chacun, le contexte de chaque décision prise ; tout cela pendant les débats. C’est en cela que l’ensemble des GDR se rapproche de la notion de main courante.
Quelles décisions méritent la rédaction d’un GDR ?
C’est la principale question ! Si vous multipliez les GDR à chaque fois que vous changez une virgule, vous allez vous noyer sous la documentation. À l’inverse, oubliez de documenter une décision, et vous le regretterez dans le futur (ou vos successeurs le regretteront).
Il est habituel de classer les décisions en deux catégories :
- Décisions facilement réversibles (et peu couteuses à renverser) : un GDR n’est alors pas indispensable ;
- Décisions complexes et couteuses à renverser : un GDR doit alors obligatoirement être rédigé.
Utiliser les GDR pour comprendre comment une décision a été prise
Bien sûr, la consultation de l’historique des GDR permettra de retrouver le contexte d’une décision prise dans le passé, les personnes impliquées, le contexte, etc. Un simple moteur de recherche permettra de retrouver, par mots clés, les décisions anciennes.
Mais l’IA nous permet aujourd’hui d’imaginer d’autres formes d’utilisation. Si vous avez suivi mon conseil, et choisi de structurer vos GDR sous forme d’un bundle OKF, ce dernier peut être connecté à votre LLM interne. Posez une question dans votre LLM sur la gouvernance des données, et ce dernier saura lire l’histoire des décisions (les GDR) et rédiger une réponse. Une utilisation qui confirme le rôle central que prend le LLM dans l’interface entre un utilisateur et les différents composants du système d’information.
Dans un futur plus lointain, il est également possible d’imaginer que des agents d’IA sauront lire les décisions de gouvernance prises dans le passé, et vérifier la conformité de leurs actions par rapport à ces décisions.
Combien cela coute, combien cela rapporte ?
Question classique liée à tout investissement en temps. Soyez honnête, créer un fichier .md pour chaque décision importante ne prendra pas très longtemps… allez.. disons une heure par décision, et je suis large. Le cout est donc minimum. En revanche, si vous cherchez à estimer le temps perdu à essayer de comprendre pourquoi et comment une décision passée a été prise ; ce sont sans doute de nombreuses heures qu’il vous faudra additionner. Le retour sur investissement est donc évident. Encore faut-il que vous soyez animé par la volonté de bien faire, et surtout par la volonté de léguer un système durable.
Alors, en conclusion, si vous avez tenu jusqu’à la fin de cet article, j’aimerais vous solliciter au travers des commentaires. Avez-vous déjà mis en œuvre une démarche de documentation des décisions de gouvernance ? Sous quelle forme ? La structuration GDR vous donne-t-elle envie d’essayer ? Quels bénéfices et/ou difficultés y voyez-vous ?
Bibliographie et liens
- Modèle GDR proposé en support de cet article : https://kdrive.infomaniak.com/app/share/2447909/9541c78e-8a21-45fa-88e1-7887e9c017a8
- Le dépôt de référence de l’ADR avec des liens vers les modèles et les méthodes : https://adr.github.io/
- Norme ISO 42010 sur la documentation des architectures : https://en.wikipedia.org/wiki/ISO/IEC_42010
- L’article de référence de Michael Nygard en 2011 : https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- L’implémentation de ADR dans les standards du gouvernement de Grande-Bretagne : https://www.gov.uk/government/publications/architectural-decision-record-framework/architectural-decision-record-framework
- Facilitating Software Architecture : le livre de Andrew Harmel-Law qui décrit comment prendre ses décisions d’architecture et les documenter : https://facilitatingsoftwarearchitecture.com/
- Implémentation de ADR à l’aide de fichiers Markdown : https://adr.github.io/madr/#full-template
Qu’est-ce que la méthode ADR : historique et usages
Publiée en novembre 2011 par Michael Nygard (architecte logiciel américain, auteur de Release It ! et à l’époque associé chez Relevance — devenu Cognitect) dans un billet de blog considéré comme fondateur, « Documenting Architecture Decisions », la méthode ADR (Architecture Decision Record) part d’un constat simple : dans les projets agiles, la documentation d’architecture traditionnelle est soit ignorée, soit obsolète. Michael Nygard propose donc de consigner non pas l’architecture, mais chaque décision structurante, dans un fichier court, numéroté et versionné avec le code source, articulé en cinq rubriques : titre, statut, contexte, décision, conséquences. Un ADR accepté n’est jamais modifié : s’il devient caduc, un nouveau le complète et l’ancien est marqué « superseded », de sorte que la collection forme un journal historique du raisonnement de l’équipe. La pratique s’est diffusée rapidement : outillée dès 2016 par adr-tools (Nat Pryce), classée « Adopt » par le Technology Radar de Thoughtworks en novembre 2016, elle s’est ensuite dotée d’un site de référence communautaire (adr.github.io) et de variantes normalisées, notamment MADR (Markdown ADR) et les Y-statements d’Olaf Zimmermann, qui la rattache à la notion de « décision architecturalement significative » de la norme ISO 42010. Aujourd’hui, elle est documentée comme pratique recommandée par AWS (guide dédié dans AWS Prescriptive Guidance) ; Microsoft (Azure Well-Architected Framework) ; Red Hat, décrite dans son usage interne par Spotify (« When Should I Write an Architecture Decision Record », 2020) ; et elle a fait l’objet en novembre 2025 d’un cadre officiel du gouvernement britannique, publié par le Department for Science, Innovation and Technology avec le Government Digital Service, qui la rend obligatoire pour les décisions transverses à l’administration.
Les principes basiques de la méthode ADR
• Unicité. Une décision égale un document. Chaque ADR est court (entre une et deux pages), autonome, numéroté séquentiellement (0001, 0002…) et n’est jamais fusionné avec un autre.
• Immuabilité. Un ADR accepté ne se modifie plus. S’il devient caduc, on en écrit un nouveau qui le complète, et on marque l’ancien « Superseded by ADR-00XX » (ou tout autre équivalent dans votre langue de travail). La collection forme ainsi un journal historique, pas un document vivant. Cela se rapproche du concept de main-courante largement utilisé dans le domaine militaire.
• Proximité du code. Les ADR vivent dans le dépôt de code (typiquement doc/adr/ en Markdown), versionnés avec le code, comme n’importe quel changement.
• Seuil de pertinence. On ne documente que les décisions « architecturalement significatives » : celles qui sont couteuses à inverser, qui affectent des propriétés structurantes (performance, sécurité, cout, couplage) ou qui touchent plusieurs équipes. C’est le point le plus délicat, documenter suffisamment, mais pas trop.
• Écriture pour le futur lecteur. Le destinataire est le développeur qui arrivera dans deux ans et se demandera « pourquoi diable ont-ils fait ça ? ». Aujourd’hui le « lecteur » sera peut-être un agent qui aura besoin de comprendre l’architecture. L’ensemble des ADR pourra également entrainer un LLM qui répondra aux questions que se posent les utilisateurs sur les choix d’architecture.
La forme d’un ADR : cinq sections regroupées dans un même document
1. Titre : une phrase descriptive, numérotée.
2. Statut : Proposed / Accepted / Deprecated / Superseded (by ADR-00XX).
3. Contexte : les forces en présence, factuelles et neutres : contraintes techniques, organisationnelles, politiques, réglementaires.
4. Décision : formulée à la voix active : « Nous allons… », qui souligne la responsabilisation des acteurs qui ont pris cette décision.
5. Conséquences : ce qui devient plus facile et plus difficile après coup, positif comme négatif. C’est la section la plus souvent bâclée et pourtant la plus utile, en particulier pour une analyse a posteriori.
Il existe également des variantes ou développements complémentaires autour de la méthode ADR : MADR (Markdown ADR), plus riche, ajoute explicitement les options considérées et les critères de décision ; le format Y-statement condense la décision en une phrase structurée. Des outils comme adr-tools automatisent la numérotation et le chaînage des remplacements.
Attention à ne pas tomber dans le piège de l’écriture justificative, a posteriori. Un ADR rédigé après coup pour justifier une décision déjà prise perd sa valeur ; l’intérêt est justement de forcer l’explicitation des alternatives, et de les documenter, avant de trancher. L’ADR est donc rédigé pendant le processus de décision, afin d’en capter les principales étapes.
Adapter l’ADR à la gouvernance des données… le GDR (Governance Decision Record)
La mise en place d’une gouvernance des données, et son suivi quotidien, nécessitent de prendre des décisions, certaines mineures, d’autres structurantes, dont les effets se feront sentir dans le temps, parfois plusieurs années après. Ceux qui ont pris la décision ne sont souvent plus là, ou plus aux mêmes fonctions ; et lorsque la décision est ancienne, les raisons du choix, les arguments exposés, les débats tenus, les arguments échangés… se sont effacés des mémoires humaines, et personne à l’époque ne les avait consignés. Sur ce plan, gouvernance des données et architecture sont très proches.
L’idée est donc d’appliquer la méthode ADR aux décisions liées à la mise en place de la gouvernance des données. On passe de la méthode Architecture Decision Record (ADR) à la méthode Governance Decision Record (GDR). Et finalement très peu de choses vont changer. Les principes de la méthode évoqués ci-dessus (unicité, immuabilité…) restent identiques. La forme d’un GDR reste identique à celle d’un ADR.
Pour combiner deux formats intéressants, je vous propose de regrouper vos décisions de gouvernance (GDR) dans un Bundle OKF (lire les articles que j’ai déjà publiés sur le sujet pour comprendre les atouts de ce format ouvert publié en juin 2026 par Google). Ce bundle au format OKF regroupera donc :
- Un fichier index.md qui recense l’ensemble des décisions chronologiques
- Un fichier GDR-XXXX.md pour chaque décision suivant le format proposé ci-dessous
- Un fichier log.md qui enregistre les évolutions de format de l’ensemble du bundle
Le cœur du dispositif est bien entendu l’ensemble des fichiers GDR-XXXX.md qui chacun détaille une décision et la manière dont elle a été prise.
Dans chaque fichier .md, les sections suivantes peuvent être renseignées. Comme vous le verrez dans le modèle, certaines sections sont obligatoires, d’autres facultatives :
- Description du problème à résoudre et de son contexte
- Facteurs de décision
- Choix envisagés
- Avantages et inconvénients des différentes options
- Décision prise
- Et toute autre rubrique que vous trouverez intéressant d’ajouter dans votre contexte
Qui a en charge la rédaction des GDR ?
Évidemment, c’est celui qui coordonne les tâches de gouvernance (responsable de la gouvernance des données, coordinateur du comité de gouvernance, voir data steward) qui est responsable de cette documentation. La confier à un stagiaire sera contre-productif et montrera le peu d’intérêt que vous portez à la démarche.
Au-delà du « qui », la question du « quand » est importante. Il est totalement déconseillé de rédiger une GDR a posteriori de la décision. Il est donc difficile de reconstruire l’historique des décisions de gouvernance qui n’auraient pas été documentées au moment de leur mise en œuvre. Vous démarrez avec les décisions d’aujourd’hui.
En effet, la documentation de la décision doit être faite pendant le processus décisionnel. Cela permet de documenter les solutions envisagées, les arguments évoqués par chacun, le contexte de chaque décision prise ; tout cela pendant les débats. C’est en cela que l’ensemble des GDR se rapproche de la notion de main courante.
Quelles décisions méritent la rédaction d’un GDR ?
C’est la principale question ! Si vous multipliez les GDR à chaque fois que vous changez une virgule, vous allez vous noyer sous la documentation. À l’inverse, oubliez de documenter une décision, et vous le regretterez dans le futur (ou vos successeurs le regretteront).
Il est habituel de classer les décisions en deux catégories :
- Décisions facilement réversibles (et peu couteuses à renverser) : un GDR n’est alors pas indispensable ;
- Décisions complexes et couteuses à renverser : un GDR doit alors obligatoirement être rédigé.
Utiliser les GDR pour comprendre comment une décision a été prise
Bien sûr, la consultation de l’historique des GDR permettra de retrouver le contexte d’une décision prise dans le passé, les personnes impliquées, le contexte, etc. Un simple moteur de recherche permettra de retrouver, par mots clés, les décisions anciennes.
Mais l’IA nous permet aujourd’hui d’imaginer d’autres formes d’utilisation. Si vous avez suivi mon conseil, et choisi de structurer vos GDR sous forme d’un bundle OKF, ce dernier peut être connecté à votre LLM interne. Posez une question dans votre LLM sur la gouvernance des données, et ce dernier saura lire l’histoire des décisions (les GDR) et rédiger une réponse. Une utilisation qui confirme le rôle central que prend le LLM dans l’interface entre un utilisateur et les différents composants du système d’information.
Dans un futur plus lointain, il est également possible d’imaginer que des agents d’IA sauront lire les décisions de gouvernance prises dans le passé, et vérifier la conformité de leurs actions par rapport à ces décisions.
Combien cela coute, combien cela rapporte ?
Question classique liée à tout investissement en temps. Soyez honnête, créer un fichier .md pour chaque décision importante ne prendra pas très longtemps… allez.. disons une heure par décision, et je suis large. Le cout est donc minimum. En revanche, si vous cherchez à estimer le temps perdu à essayer de comprendre pourquoi et comment une décision passée a été prise ; ce sont sans doute de nombreuses heures qu’il vous faudra additionner. Le retour sur investissement est donc évident. Encore faut-il que vous soyez animé par la volonté de bien faire, et surtout par la volonté de léguer un système durable.
Alors, en conclusion, si vous avez tenu jusqu’à la fin de cet article, j’aimerais vous solliciter au travers des commentaires. Avez-vous déjà mis en œuvre une démarche de documentation des décisions de gouvernance ? Sous quelle forme ? La structuration GDR vous donne-t-elle envie d’essayer ? Quels bénéfices et/ou difficultés y voyez-vous ?
Bibliographie et liens
- Modèle GDR proposé en support de cet article : https://kdrive.infomaniak.com/app/share/2447909/9541c78e-8a21-45fa-88e1-7887e9c017a8
- Le dépôt de référence de l’ADR avec des liens vers les modèles et les méthodes : https://adr.github.io/
- Norme ISO 42010 sur la documentation des architectures : https://en.wikipedia.org/wiki/ISO/IEC_42010
- L’article de référence de Michael Nygard en 2011 : https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- L’implémentation de ADR dans les standards du gouvernement de Grande-Bretagne : https://www.gov.uk/government/publications/architectural-decision-record-framework/architectural-decision-record-framework
- Facilitating Software Architecture : le livre de Andrew Harmel-Law qui décrit comment prendre ses décisions d’architecture et les documenter : https://facilitatingsoftwarearchitecture.com/
- Implémentation de ADR à l’aide de fichiers Markdown : https://adr.github.io/madr/#full-template