Registres de décision pour le développement logiciel piloté par l'IA

Les registres de décision constituent la couche de mémoire manquante dans le développement logiciel assisté par l’IA. Ils capturent non seulement ce qui a été construit, mais aussi pourquoi — et cette distinction devient critique lorsque les outils d’IA écrivent votre code.

Les registres de décision sont la couche de mémoire manquante

La programmation pilotée par l’IA change l’économie du développement logiciel en rendant le code moins cher à générer, plus facile à refactoriser et plus rapide à jeter. C’est utile. C’est aussi dangereux, car lorsque la production du code devient plus facile, la ressource rare n’est plus la frappe — la ressource rare est le jugement.

Pourquoi l’équipe a-t-elle choisi PostgreSQL plutôt que DynamoDB ? Pourquoi le produit exige-t-il une révision humaine avant d’envoyer des e-mails générés par l’IA ? Pourquoi l’interface affiche-t-elle des suggestions dans un panneau latéral au lieu de les appliquer directement ? Pourquoi une approche plus simple a-t-elle été rejetée il y a six mois ? Le code peut montrer ce qui existe, mais il explique rarement pourquoi il existe.

Les registres de décision résolvent ce problème en fournissant un document court, versionné, qui capture un choix important, le contexte qui l’entoure, les alternatives considérées et les conséquences que l’équipe a acceptées. Dans une base de code assistée par l’IA, ces registres deviennent plus qu’une simple documentation — ils deviennent une mémoire de projet durable que les humains et les agents de codage IA peuvent lire avant de faire des changements futurs. La règle opérationnelle pratique est simple : conserver les registres de décision comme des fichiers Markdown dans le dépôt, les réviser comme du code, et permettre aux futurs outils d’IA de les lire avant de proposer ou d’implémenter des modifications.

Qu’est-ce qu’un registre de décision ?

Un registre de décision est un enregistrement écrit d’une décision significative, structuré pour répondre à quatre questions fondamentales : que avons-nous décidé, pourquoi l’avons-nous décidé, quelles alternatives avons-nous considérées, et quelles conséquences avons-nous acceptées ? La forme la plus courante est le Registre de Décision Architecturale, abrégé en ADR (Architecture Decision Record). Les ADR sont largement utilisés pour documenter les décisions techniques, et le même modèle peut être étendu au-delà de l’architecture, vers le produit et le design.

Pour la programmation pilotée par l’IA, trois types sont particulièrement utiles :

Ensemble, les ADR, PDR et DDR décrivent non seulement la structure du système, mais aussi l’intention du produit et le raisonnement derrière l’expérience utilisateur. Cette combinaison est importante car les agents IA peuvent lire le code, mais le code seul ne contient pas assez de contexte pour prendre de bonnes décisions. Les registres de décision offrent aux systèmes IA une source d’intention de projet révisée, durable et approuvée par des humains.

Registres de Décision Architecturale (ADR)

Les Registres de Décision Architecturale capturent les décisions techniques et structurelles. Utilisez un ADR lorsqu’une décision affecte la forme du système — ses frontières, ses dépendances, son modèle opérationnel ou sa maintenabilité à long terme.

Des exemples de décisions qu’il vaut la peine d’enregistrer sous forme d’ADR incluent :

• Choisir PostgreSQL comme base de données principale
• Utiliser une architecture orientée événements pour le traitement en arrière-plan
• Conserver l’application comme un monolithe modulaire
• Introduire une file d’attente de messages
• Choisir REST plutôt que GraphQL
• Utiliser le rendu côté serveur pour l’application web
• Exiger que tous les travaux en arrière-plan soient idempotents
• Adopter un modèle d’authentification et d’autorisation spécifique

Un ADR n’est pas un document d’architecture complet — il est intentionnellement petit, enregistrant une décision importante à un moment spécifique. Un bon ADR prévient l’amnésie architecturale : sans lui, les contributeurs futurs pourraient redécouvrir les mêmes compromis, rouvrir de vieux débats ou annuler accidentellement des contraintes importantes.

Dans la programmation pilotée par l’IA, les ADR pèsent encore plus lourd. Les outils IA sont souvent habiles en optimisation locale, et ils peuvent proposer un changement techniquement plausible qui viole une contrainte architecturale plus large. Un ADR donne à l’IA une limite claire : « C’est ainsi que ce système est censé être structuré. »

Registres de Décision Produit (PDR)

Les Registres de Décision Produit capturent le comportement du produit, le périmètre et l’intention面向 l’utilisateur. C’est moins courant que les ADR, mais c’est souvent tout aussi précieux — les décisions produit sont fréquemment dispersées dans les tickets, les outils de roadmap, les fils de discussion, les notes de réunion et les mémoires des gens, ce qui les rend faciles à oublier pour les humains et presque impossibles à déduire de manière fiable pour les outils IA.

Utilisez un PDR lorsqu’une décision affecte ce que le produit fait, à qui il sert, ce qui est intentionnellement hors périmètre, ou comment une fonctionnalité面向 l’utilisateur devrait se comporter. Les exemples incluent :

• Les messages générés par l’IA doivent rester des brouillons jusqu’à ce qu’ils soient révisés par un humain
• Les utilisateurs du niveau gratuit peuvent créer jusqu’à trois projets
• Les espaces de travail supprimés sont récupérables pendant 30 jours
• La facturation d’équipe est hors périmètre pour la version 1
• Les utilisateurs peuvent exporter leurs données sans contacter le support
• Les résumés IA de faible confiance affichent un avertissement au lieu d’être masqués

Un PDR est particulièrement utile lorsqu’un choix produit semble arbitraire dans le code. Le code pourrait contenir une limite de trois projets pour les utilisateurs gratuits, et sans un PDR, un outil IA pourrait traiter ce nombre comme une constante magique et suggérer de le modifier. Avec un PDR, l’IA peut voir que la limite est liée à la stratégie de tarification, au coût d’intégration ou à la charge de support — et que sa modification nécessite une décision produit délibérée, et non une modification rapide.

Registres de Décision Design (DDR)

Les Registres de Décision Design capturent les décisions d’expérience utilisateur, d’interaction, de design visuel et de design de contenu. Utilisez un DDR lorsqu’une décision affecte la manière dont les utilisateurs interagissent avec le produit, la présentation de l’information, ou l’application d’un principe de design dans les travaux futurs.

Des exemples de décisions de design qu’il vaut la peine d’enregistrer incluent :

• Utiliser une validation en ligne plutôt que uniquement à la soumission
• Placer les suggestions IA dans un panneau latéral plutôt que directement dans l’éditeur
• Utiliser la révélation progressive pour les paramètres avancés
• Exiger une confirmation avant les actions destructrices
• Utiliser « Brouillon » et « Publié » plutôt que « Inactif » et « Actif »
• Garder les actions principales visibles sur les écrans mobiles

L’intention de design est facile à perdre pendant l’implémentation. Un développeur peut simplifier un flux, ou un agent IA peut générer un composant qui fonctionne techniquement mais brise le modèle d’interaction prévu. Par exemple, un DDR pourrait enregistrer : « Nous affichons les suggestions d’écriture IA à côté du document, et non à l’intérieur, car les utilisateurs doivent comparer le texte généré avec leur propre brouillon avant d’accepter les modifications. » Ce registre donne aux contributeurs futurs un principe à préserver, et non simplement une mise en page à copier.

Pourquoi les registres de décision comptent davantage avec l’IA

Les outils de codage IA sont puissants, mais ils sont souvent sans état ou seulement partiellement au fait de l’historique du projet. Ils peuvent inspecter des fichiers, inférer des motifs et générer des changements — mais ils ne savent pas automatiquement quelles décisions sont intentionnelles, lesquelles sont accidentelles, et lesquelles ont déjà été débattues et résolues. Cela crée plusieurs risques distincts.

L’IA peut rouvrir des débats clos

Si l’équipe a déjà décidé d’utiliser un monolithe modulaire, un agent IA peut toujours proposer d’extraire un service car cela semble propre isolément. Sans un ADR, l’IA n’a pas de moyen durable de savoir que l’équipe a déjà considéré et rejeté cette voie, et le résultat est un effort gaspillé ou une régression subtile de la cohérence du système.

L’IA peut optimiser localement et endommager globalement

Un refactor généré peut rendre un fichier plus propre tout en violant les frontières du système. Un changement d’interface peut réduire la complexité des composants tout en affaiblissant l’expérience utilisateur prévue. Un changement de produit peut simplifier l’implémentation tout en brisant les hypothèses de tarification ou de conformité. Les registres de décision donnent à l’IA un cadre de référence plus large avant qu’elle n’agisse sur des signaux à portée étroite.

L’IA peut préserver le code mais perdre l’intention

Un modèle peut suivre les motifs existants dans la base de code, mais les motifs ne sont pas les mêmes que les principes. Parfois, le code existant est un compromis. Parfois, il est transitoire. Parfois, il existe en raison d’une contrainte externe qui n’est pas visible dans le fichier. Les registres de décision expliquent la différence entre « c’est ainsi que ça fonctionne » et « c’est pourquoi ça a été construit ainsi. »

L’IA peut générer un raisonnement plausible mais erroné

L’IA peut rédiger des registres de décision, mais elle peut aussi inventer des explications sonnant le confiance qui ne correspondent pas à la décision réelle. C’est pourquoi la révision humaine est non négociable : l’IA peut générer le premier brouillon d’un registre, mais un humain doit vérifier qu’il décrit avec précision la décision réelle, les alternatives et les conséquences avant que le registre ne soit fusionné.

Les registres de décision dans une méthodologie plus large

Les registres de décision ne sont pas seulement de la documentation — ils font partie d’une manière plus large de travailler qui se situe à l’intersection de la gouvernance architecturale légère, de la documentation comme code, des flux de travail de gestion des connaissances augmentés par l’IA, de la découverte produit, du raisonnement de design, de la gouvernance IA et de la révision de code. Une façon utile de décrire le processus plus large est le Développement Orienté Décision.

La plupart des flux de travail de programmation pilotée par l’IA se concentrent étroitement sur la boucle générer-réviser-commettre :

Ce cycle est trop mince pour un travail système sérieux. Un flux de travail plus robuste traite le dépôt comme un magasin de code et d’intention — les diagrammes ici utilisent Mermaid, un format léger qui fonctionne bien à l’intérieur des registres de décision Markdown également :

Ce processus transforme le dépôt en quelque chose de plus qu’un magasin de code. Il devient la source de vérité pour l’implémentation, l’intention et le raisonnement — un artefact durable qui accumule de la valeur à chaque décision prise.

Registres de décision et documentation comme code

Les registres de décision fonctionnent mieux lorsqu’ils suivent les principes de la documentation comme code, ce qui signifie qu’ils doivent être stockés dans le même dépôt que le code, écrits en Markdown brut, révisés dans les pull requests, versionnés avec Git, liés aux problèmes et pull requests connexes, et recherchables par les humains et les outils IA. C’est bien plus fiable que de stocker des décisions importantes dans des chats, des pages wiki, des présentations ou des notes de réunion — ces outils peuvent encore être utiles pour la discussion, mais la décision acceptée doit toujours vivre près du code.

Une structure de dépôt bien organisée pour les registres de décision pourrait ressembler à ceci :

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Pour les petits projets, une structure plus plate fonctionne tout aussi bien. L’organisation exacte des dossiers importe moins que la cohérence — les registres doivent être faciles à trouver, faciles à réviser, et faciles pour les outils IA à charger comme contexte avant d’agir sur la base de code. Pour les équipes Go, cette structure docs/decisions/ s’intègre naturellement à côté de la disposition cmd/, internal/ et api/ décrite dans Structure de projet Go : Pratiques & Modèles, qui recommande docs/ comme domicile pour les décisions architecturales et les références API.

Un modèle pratique de registre de décision

Un modèle de registre de décision utile doit être assez court pour que les gens l’utilisent réellement. Voici un modèle Markdown pratique qui inclut une section de guidance IA facultative mais précieuse :

# Décision : Titre court

Statut : Proposé | Accepté | Obsolète | Déprécié
Date : AAAA-MM-JJ
Type : Architecture | Produit | Design
Responsables : Équipe ou noms

## Contexte

Décrire le problème, les contraintes, les objectifs, les besoins des utilisateurs, les faits techniques,
et les facteurs commerciaux qui ont conduit à cette décision.

## Décision

Énoncer la décision clairement.

## Alternatives considérées

### Option 1

Avantages :
- ...

Inconvénients :
- ...

## Conséquences

Décrire ce qui devient plus facile, ce qui devient plus difficile, et quels risques
ou travaux de suivi cela crée.

## Guidance IA

Quand un assistant IA travaille dans ce domaine, il devrait :
- Préserver ...
- Éviter ...
- Privilégier ...
- Demander une révision quand ...

## Liens

- Problèmes connexes :
- Pull requests connexes :
- Fichiers connexes :
- Rend obsolète :
- Rendue obsolète par :

La section « Guidance IA » est facultative, mais pour la programmation pilotée par l’IA, elle est extrêmement précieuse — elle transforme le registre de décision en une instruction durable pour les futurs agents travaillant dans le même domaine de la base de code.

Que doit contenir un registre de décision ?

Tous les choix ne méritent pas un registre, et si chaque petit détail d’implémentation devient un registre de décision, le processus s’effondre dans le bruit. Créez un registre de décision lorsqu’un choix est significatif et susceptible d’importer plus tard.

Les bons candidats sont les décisions qui :

• Affectent plusieurs parties du système
• Encodent une promesse produit
• Résolvent un débat réel
• Introduisent un compromis à long terme
• Dépendent de contraintes commerciales, de conformité ou opérationnelles
• Seraient coûteuses à redécouvrir plus tard
• Les outils IA futurs pourraient plausiblement faire mal
• Les contributeurs futurs pourraient être tentés d’inverser casually

Les mauvais candidats incluent les petits choix de refactorisation, les corrections de bugs évidentes, les expériences temporaires, les décisions de nommage locales, et les détails d’implémentation sans conséquence durable. Une bonne règle de base est simple : si l’inversion de la décision nécessiterait une discussion, enregistrez la décision.

Valeurs de statut et cycle de vie

Les registres de décision doivent avoir un cycle de vie pour signaler leur statut actuel. Les valeurs de statut les plus simples sont suffisantes.

Proposé — La décision est en cours de considération mais pas encore acceptée. Utilisez ceci lorsque l’équipe souhaite discuter d’une décision dans un pull request avant de s’y engager.

Accepté — La décision est active et devrait guider le travail futur. La plupart des registres de décision utiles passeront la plus grande partie de leur vie dans cet état.

Obsolète — La décision a été remplacée par un registre plus récent. Ne supprimez pas les anciens registres ; conservez-les pour l’historique et liez-les à la décision plus récente afin que l’évolution de la pensée reste visible.

Déprécié — La décision n’est plus recommandée mais peut encore décrire des parties existantes du système. C’est particulièrement utile pendant les migrations, lorsque les anciens motifs existent dans la base de code aux côtés des approches plus récentes.

Le principe important est que les registres de décision doivent être favorables à l’ajout. Lorsque l’équipe change de direction, créez un nouveau registre et liez l’ancien plutôt que de réécrire l’histoire pour rendre le passé plus propre.

Comment l’IA devrait générer des registres de décision

L’IA peut aider à créer des registres de décision, et c’est l’un des meilleurs usages de l’IA dans le développement logiciel — elle est rapide pour rédiger des documents structurés à partir du contexte. Après une discussion, une révision architecturale ou un pull request, vous pouvez demander à un assistant IA de rédiger un registre :

Rédigez un Registre de Décision Architecturale pour la décision dans ce pull request.
Incluez le contexte, les alternatives, les conséquences et la guidance IA.
Sauvegardez-le en Markdown sous docs/decisions/architecture.

Pour le travail produit :

Rédigez un Registre de Décision Produit expliquant pourquoi les messages générés par l'IA
doivent rester des brouillons jusqu'à ce qu'ils soient révisés par l'utilisateur.
Incluez l'impact utilisateur, le comportement hors périmètre, les compromis et la guidance IA.

Le registre généré par l’IA ne doit cependant pas être fait confiance automatiquement. La révision humaine devrait vérifier que le contexte est précis, que l’IA n’a pas inventé de raisonnement, que les alternatives listées sont réelles, que les conséquences sont honnêtes, et que la guidance IA correspond à l’intention réelle de l’équipe. L’IA est un assistant de rédaction — elle n’est pas le propriétaire de la décision.

Comment l’IA devrait lire les registres de décision

L’autre moitié de la pratique consiste à instructer l’IA à lire les registres avant d’agir. Avant de demander à un assistant IA d’implémenter un changement, incluez une instruction comme celle-ci :

Avant de modifier cette fonctionnalité, lisez docs/decisions.
Identifiez tous les Registres de Décision Architecturale, Produit ou Design qui s'appliquent.
Suivez les décisions acceptées. Si votre changement proposé entre en conflit avec un registre
de décision, expliquez le conflit avant de modifier le code.

Pour des tâches plus importantes, renforcez le rôle des registres comme mémoire de projet :

Utilisez les registres de décision comme mémoire de projet.
Ne renversez pas les décisions acceptées sans proposer une nouvelle décision qui les rend obsolètes.
Quand vous générez du code, expliquez quels registres de décision ont influencé l'implémentation.

Cela change le rôle de l’IA de « prédire du code plausible » à « opérer à l’intérieur d’un système documenté de contraintes » — une amélioration significative de la fiabilité pour les projets complexes ou de longue durée.

Les registres de décision dans les pull requests

Les registres de décision devraient faire partie de la révision normale des pull requests plutôt que d’un processus séparé. Une simple entrée de checklist PR rend l’habitude visible :

## Checklist de registre de décision

- [ ] Ce PR n'introduit pas de décision architecturale, produit ou design significative.
- [ ] Ce PR introduit une décision significative et inclut un nouveau registre de décision.
- [ ] Ce PR modifie une décision précédente et inclut un registre qui la rend obsolète.
- [ ] Les registres de décision existants pertinents ont été considérés.
- [ ] Le code généré par l'IA suit les registres de décision acceptés.
- [ ] Les registres de décision générés par l'IA ont été révisés par un humain.

Cette checklist est simple, mais elle change le comportement en rappelant à l’équipe que le code n’est pas le seul artefact important dans un pull request. Elle rend également naturel de repérer lorsqu’un changement généré par l’IA viole silencieusement une décision antérieure.

Les registres de décision et la gouvernance architecturale

La gouvernance architecturale traditionnelle échoue souvent parce qu’elle est trop lourde, trop lente, ou trop déconnectée de l’implémentation — des conseils d’approbation centraux, de grands documents en amont, et des processus de garde-fou qui bloquent plutôt que de guider. Les registres de décision offrent une alternative plus légère qui s’intègre directement dans le flux de travail de développement.

Ils ne nécessitent pas un conseil d’architecture central pour chaque changement, ni ne bloquent les équipes d’apprendre et de s’adapter. Au lieu de cela, ils créent une traînée de décisions qui peut être révisée, référencée et construite au fil du temps. Cela soutient l’architecture évolutive : l’architecture peut changer, mais elle change avec mémoire plutôt qu’en dépit d’elle. L’équipe peut revisiter les anciennes décisions sans avoir à redécouvrir pourquoi elles ont été prises, ce qui est une forme de gouvernance plus saine et plus honnête :

• Des petits registres au lieu de documents gigantesques
• Révision près du code au lieu d’un théâtre d’approbation séparé
• Contexte historique au lieu de connaissances tribales
• Compromis explicites au lieu d’hypothèses cachées

Les registres de décision et la gestion de produit

Le travail produit a également besoin de mémoire de décision, et c’est un domaine où la valeur des registres de décision est souvent sous-estimée. Une roadmap dit ce qui pourrait arriver. Un ticket dit quoi construire ensuite. Les analyses disent ce que les utilisateurs ont fait. Aucun de ceux-ci n’explique pleinement pourquoi un comportement produit existe.

Les Registres de Décision Produit combler ce manque et sont particulièrement utiles pour les décisions de tarification et de packaging, les modèles de permissions, les limites et quotas, les flux de sécurité et de révision IA, les choix d’intégration, les définitions de rôles utilisateur, les règles de collaboration, les politiques de rétention des données, et les limites de périmètre des fonctionnalités. Une fois implémentées, les décisions produit deviennent invisibles dans le code — plus tard, quelqu’un ne voit que le code et demande : « Pourquoi ça fonctionne comme ça ? » Un PDR donne la réponse sous une forme que les humains et les outils IA peuvent trouver et utiliser.

Les registres de décision et les systèmes de design

Les systèmes de design documentent souvent les composants, les jetons et les règles d’utilisation, mais ils documentent rarement pourquoi le système fonctionne ainsi. Les Registres de Décision Design combler ce manque. Une bibliothèque de composants pourrait dire « utilisez le dialogue de confirmation pour les actions destructrices », tandis qu’un DDR explique le raisonnement : « Nous exigeons une confirmation pour les actions destructrices car les utilisateurs travaillent souvent avec des données d’équipe partagées, et la suppression accidentelle a un coût de récupération élevé. »

Ce raisonnement importe au-delà du composant spécifique. Il aide les futurs designers, développeurs et outils IA à appliquer le principe correctement dans de nouvelles situations. Sans le DDR, un agent IA peut générer une interaction plus rapide qui saute la confirmation car elle semble plus efficace. Avec le DDR, l’agent peut reconnaître que la préservation de la propriété de sécurité est intentionnelle et non négociable.

Comment les registres de décision soutiennent le développement piloté par spécification

Le développement piloté par spécification explique ce que le système devrait faire. Les registres de décision expliquent pourquoi l’équipe a choisi cette direction, et la distinction importe significativement pour le travail assisté par l’IA.

Une spécification de fonctionnalité peut dire que les e-mails générés par l’IA doivent être sauvegardés comme brouillons. Un Registre de Décision Produit explique pourquoi l’envoi automatique a été rejeté, quels risques ont été considérés, et quels changements futurs nécessiteraient une nouvelle décision. Une spécification de design peut décrire une interaction de panneau latéral, tandis que le DDR correspondant explique pourquoi les éditions IA en ligne ont été explicitement rejetées et pourquoi la préservation du contrôle utilisateur a été pondérée plus lourdement que la vitesse du flux de travail. Une spécification d’architecture peut définir une frontière de service, et son ADR explique pourquoi l’équipe a choisi cette frontière plutôt qu’une alternative plus simple ou plus distribuée.

La spécification guide l’implémentation. Le registre de décision préserve le jugement. Ensemble, ils donnent aux agents de codage IA à la fois des instructions et du contexte — le « quoi » et le « pourquoi » — ce qui rend la combinaison si efficace pour les systèmes complexes et de longue durée.

Les registres de décision ne sont pas des spécifications

Les registres de décision sont liés aux spécifications, mais ils servent un but différent. Une spécification dit « le système doit faire X », tandis qu’un registre de décision dit « nous avons choisi X plutôt que Y en raison de ces contraintes et compromis. » Ce « plutôt que Y » est la partie précieuse. Les outils IA génèrent souvent des solutions en trouvant un chemin plausible vers le résultat demandé, mais les registres de décision leur disent quels chemins plausibles ont déjà été explorés, évalués et rejetés — réduisant le churn et améliorant la qualité du travail assisté par l’IA.

Les registres de décision ne remplacent pas les tests

Les tests vérifient le comportement ; les registres de décision expliquent l’intention. Les deux sont nécessaires et ils fonctionnent ensemble. Un test peut imposer que les e-mails générés par l’IA doivent être sauvegardés comme brouillons, tandis qu’un Registre de Décision Produit explique que c’est requis car les utilisateurs doivent réviser la communication générée par l’IA avant qu’elle ne quitte le système. Le test protège le comportement. Le registre de décision protège le sens. Ensemble, ils rendent les changements futurs plus sûrs et plus prévisibles.

Les registres de décision ne remplacent pas les commentaires de code

Les commentaires de code expliquent les détails d’implémentation locaux, tandis que les registres de décision expliquent des décisions plus larges. Utilisez les commentaires pour les lignes surprenantes, les cas limites, les contournements, et les fonctions qui ne peuvent pas être simplifiées. Utilisez les registres de décision pour expliquer pourquoi une architecture existe, pourquoi un comportement produit existe, pourquoi un modèle d’interaction existe, et pourquoi l’équipe a choisi une direction plutôt qu’une autre. Si l’explication affecte seulement quelques lignes, un commentaire est l’outil approprié. Si elle affecte la direction du système, un registre de décision est l’outil approprié.

Erreurs courantes

Écrire des registres trop tard

Un registre de décision devrait être écrit lorsque la décision est prise, et non des mois plus tard quand tout le monde a oublié les compromis. Il est acceptable de rédiger un pendant un pull request. C’est encore mieux de le rédiger avant l’implémentation, tandis que la décision est encore activement discutée et que les alternatives sont fraîches.

Rendre les registres trop longs

Un registre de décision n’est pas un essai. Il devrait être assez détaillé pour préserver le jugement mais assez court pour que les gens le lisent réellement. Privilégiez la clarté sur l’exhaustivité — un registre concis qui est lu est bien plus précieux qu’un complet qui est sauté.

Enregistrer des décisions sans conséquences

La section conséquences est le cœur du registre. Une décision sans conséquences énoncées est souvent juste une préférence plutôt qu’une vraie décision. Les bons registres admettent les compromis honnêtement, y compris ce qui devient plus difficile ou risqué en raison du choix.

Éditer les anciens registres comme si l’histoire avait changé

Quand une décision change, créez un nouveau registre et marquez l’ancien comme obsolète. Réécrire silencieusement une ancienne décision pour qu’elle corresponde à l’état actuel détruit le contexte historique qui rend les registres de décision précieux. L’histoire est utile précisément parce qu’elle montre comment la pensée a évolué.

Laisser les registres générés par l’IA fusionner sans révision

L’IA peut produire un registre soigné et bien structuré qui est subtilement incorrect. Traitez les registres de décision générés par l’IA exactement comme le code généré par l’IA — révisez-les soigneusement, vérifiez que le raisonnement est précis, et assurez-vous que la section conséquences reflète ce que l’équipe a réellement accepté.

Cacher les registres en dehors du dépôt

Si les registres de décision vivent dans un wiki séparé ou un système de documentation, ils sont moins susceptibles d’être mis à jour avec les changements de code et beaucoup moins susceptibles d’être lus par les outils de codage IA chargeant le contexte pour une tâche. Les garder dans le dépôt n’est pas juste une commodité — c’est ce qui rend la pratique fonctionnelle pour le développement assisté par l’IA.

Un modèle opérationnel léger

Un processus d’équipe pratique qui ajoute une surcharge minimale ressemble à ceci :

1. Pendant la planification ou l’implémentation, identifiez si une décision significative est prise.
2. Demandez à un assistant IA de rédiger un ADR, PDR ou DDR basé sur la discussion.
3. Révisez le brouillon en équipe, en vérifiant le contexte, les alternatives et les conséquences.
4. Commitez le registre en Markdown dans le dépôt.
5. Liez-le depuis le problème ou le pull request connexe.
6. Instructez les outils de codage IA à lire les registres pertinents avant de faire des changements futurs dans le domaine.
7. Rendre les registres obsolètes quand les décisions changent, en préservant l’ancien registre pour l’historique.

Cela ne nécessite pas de nouvelle bureaucratie ou de rôle de documentation dédié. Cela nécessite une petite habitude : préserver le jugement important au moment où il est créé, près du code où il sera nécessaire.

Exemple d’ADR

# Décision : Utiliser PostgreSQL pour le stockage principal de l'application

Statut : Accepté
Date : 2026-06-25
Type : Architecture
Responsables : Équipe Plateforme

## Contexte

L'application a besoin d'un stockage relationnel durable pour les comptes, projets,
permissions et événements d'audit. L'équipe s'attend à des requêtes de rapport fréquentes
et à des exigences de cohérence forte pour les vérifications de permissions.

## Décision

Nous utiliserons PostgreSQL comme base de données principale de l'application.

## Alternatives considérées

### DynamoDB

Avantages :
- Évolutivité opérationnelle
- Bon ajustement pour les motifs d'accès clé-valeur prévisibles

Inconvénients :
- Plus complexe pour les requêtes relationnelles
- Plus difficile pour le reporting ad hoc
- Moins familier pour l'équipe actuelle

### MySQL

Avantages :
- Base de données relationnelle mature
- Modèle opérationnel familier

Inconvénients :
- PostgreSQL correspond mieux aux besoins de l'équipe pour le support JSON,
  les options d'indexation et l'expertise existante

## Conséquences

PostgreSQL devient une dépendance opérationnelle centrale. L'équipe doit gérer
les migrations soigneusement et surveiller les performances des requêtes. En retour,
l'application obtient un modélisation relationnelle forte, une indexation mature et
un support de rapport flexible.

## Guidance IA

Quand vous modifiez le code de persistance, privilégiez la modélisation relationnelle dans PostgreSQL.
N'introduisez pas de deuxième base de données principale sans un ADR qui rend ce registre obsolète.

Exemple de PDR

# Décision : Les e-mails générés par l'IA doivent rester des brouillons

Statut : Accepté
Date : 2026-06-25
Type : Produit
Responsables : Équipe Produit

## Contexte

Le produit peut générer des réponses d'e-mail en utilisant l'IA. L'envoi d'e-mail est une
action de haute confiance car les erreurs peuvent atteindre les clients, partenaires ou
équipes internes.

## Décision

Les e-mails générés par l'IA doivent être créés comme brouillons. Un utilisateur humain doit
les réviser et les envoyer.

## Alternatives considérées

### Envoyer automatiquement

Avantages :
- Flux de travail plus rapide
- Moins d'effort utilisateur

Inconvénients :
- Risque plus élevé de messages incorrects ou inappropriés
- Confiance utilisateur plus faible
- Plus difficile à récupérer des erreurs

### Demander confirmation uniquement après génération

Avantages :
- Garde le flux de travail simple
- Fournit un certain contrôle utilisateur

Inconvénients :
- Encourage encore une révision superficielle
- Ne correspond pas aussi bien au comportement des clients e-mail existants que les brouillons

## Conséquences

Le flux de travail est légèrement plus lent, mais plus sûr et plus digne de confiance.
L'automatisation future peut améliorer la vitesse de révision, mais ne doit pas contourner
l'approbation humaine sans un PDR qui rend ce registre obsolète.

## Guidance IA

Quand vous construisez des fonctionnalités de génération d'e-mail, créez des brouillons par défaut.
N'ajoutez pas d'envoi automatique à moins qu'un nouveau PDR accepté ne l'autorise explicitement.

Exemple de DDR

# Décision : Afficher les suggestions d'écriture IA dans un panneau latéral

Statut : Accepté
Date : 2026-06-25
Type : Design
Responsables : Équipe Design

## Contexte

Les utilisateurs ont besoin d'aide pour améliorer le contenu écrit, mais ils doivent aussi rester
maîtres du texte final. Les éditions IA en ligne peuvent rendre difficile la distinction
entre le contenu écrit par l'utilisateur et les suggestions générées.

## Décision

Les suggestions d'écriture IA apparaîtront dans un panneau latéral. Les utilisateurs peuvent accepter,
rejeter ou copier les suggestions dans l'éditeur principal.

## Alternatives considérées

### Appliquer les suggestions en ligne

Avantages :
- Rapide
- Ressent intégré

Inconvénients :
- Floute l'auctorialité
- Rend la révision plus difficile
- Peut surprendre les utilisateurs

### Afficher les suggestions dans un modal

Avantages :
- Expérience focalisée
- Facile à implémenter

Inconvénients :
- Interrompt le flux d'écriture
- Plus difficile de comparer la suggestion et le texte original

## Conséquences

Le panneau latéral prend plus d'espace écran, surtout sur les petits écrans.
Cependant, il préserve le contrôle utilisateur et rend la révision plus claire.

## Guidance IA

Quand vous ajoutez des fonctionnalités d'assistance à l'écriture, préservez la séparation entre
le texte utilisateur et les suggestions IA. N'appliquez pas de texte généré directement
dans le document sans action utilisateur explicite.

Bibliothèque de prompts suggérée

Utilisez ces prompts pour faire des registres de décision une partie du développement quotidien assisté par l’IA.

Trouver les registres pertinents avant de travailler sur une fonctionnalité :

Lisez docs/decisions et identifiez tous les registres de décision acceptés qui s'appliquent
à cette tâche. Résumez les contraintes avant de proposer des changements de code.

Rédiger un nouveau ADR :

Rédigez un Registre de Décision Architecturale pour cette décision technique.
Incluez le contexte, la décision, les alternatives, les conséquences et la guidance IA.
Gardez-le concis et spécifique.

Rédiger un nouveau PDR :

Rédigez un Registre de Décision Produit pour ce comportement produit.
Incluez l'impact utilisateur, le périmètre, les alternatives, les conséquences et la guidance IA.

Rédiger un nouveau DDR :

Rédigez un Registre de Décision Design pour ce modèle d'interaction.
Incluez le problème utilisateur, les alternatives, les compromis, les conséquences et la guidance IA.

Réviser un pull request contre les décisions existantes :

Révisez ce pull request contre les registres de décision acceptés dans docs/decisions.
Identifiez tous les conflits, registres de décision manquants, ou décisions qui devraient
être rendues obsolètes.

Rendre une décision obsolète :

Créez un nouveau registre de décision qui rend le registre existant obsolète.
Préservez le raisonnement historique, expliquez ce qui a changé, et liez les deux registres.

Lecture connexe

• Format ADR original de Michael Nygard — le post fondateur qui a lancé le mouvement ADR
• Organisation GitHub ADR — outils, modèles et ressources communautaires pour gérer les registres de décision
• Qu’est-ce que le Développement Piloté par Spécification ? La Spéc comme Source de Vérité — la définition canonique du SDD expliquant comment les spécifications de fonctionnalité complètent les registres de décision : les deux rendent l’intention durable, à différents niveaux du système
• Développement Piloté par Spécification vs Vibe Coding : Waterfall ? — quand utiliser le SDD et quand rester avec des flux de travail plus rapides et plus lâches
• Architecture d’Application en Production : Patterns d’Intégration, Design de Code et Accès aux Données — le cluster home couvrant l’intégration, le test, l’accès aux données et les patterns de documentation logicielle
• IA pour la Gestion des Connaissances : Des Flux de Travail Réels Qui Tiennent la Route — des flux de travail de connaissances augmentés par l’IA pratiques qui complètent la pratique des registres de décision