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

Gardez l'intention proche du code.

Sommaire

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.

Registres de décision — ADR, PDR, DDR — reliant l’intention au code

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

La programmation pilotée par l’IA modifie l’économie du développement logiciel en rendant le code moins cher à générer, plus facile à refactorer et plus rapide à jeter. C’est utile. C’est aussi dangereux, car lorsque le code devient plus facile à produire, 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 envisagé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 sous forme de 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 que les registres de décision ?

Un registre de décision est un enregistrement écrit d’une décision significative, structuré pour répondre à quatre questions de base : que avons-nous décidé, pourquoi l’avons-nous décidé, quelles alternatives avons-nous envisagé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 :

Type de registre Capture Exemple
ADR Décisions architecturales et techniques Utiliser PostgreSQL comme base de données principale
PDR Décisions de comportement et de périmètre du produit Les e-mails générés par l’IA doivent rester des brouillons
DDR Décisions de design et d’interaction Afficher les suggestions IA dans un panneau latéral

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 suffisamment de contexte pour prendre de bonnes décisions. Les registres de décision donnent 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 limites, dépendances, modèle opérationnel ou maintenabilité à long terme.

Les exemples de décisions méritant d’être enregistrées en tant qu’ADR incluent :

  • Choisir PostgreSQL comme base de données principale
  • Utiliser une architecture pilotée par é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 toutes les tâches en arrière-plan soient idempotentes
  • Adopter un modèle spécifique d’authentification et d’autorisation

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

Dans la programmation pilotée par l’IA, les ADR ont encore plus de poids. Les outils d’IA sont souvent habiles à l’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 tournée vers 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 threads de chat, les comptes rendus 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 d’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é visible par 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 par é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 cachés

Un PDR est particulièrement utile lorsqu’un choix produit semble arbitraire depuis le code. Le code pourrait contenir une limite de trois projets pour les utilisateurs gratuits, et sans un PDR, un outil d’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 la modifier nécessite une décision produit délibérée, pas 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, visuelles et de design de contenu. Utilisez un DDR lorsqu’une décision affecte la façon dont les utilisateurs interagissent avec le produit, comment l’information est présentée, ou comment un principe de design devrait être appliqué dans les travaux futurs.

Les exemples de décisions de design méritant d’être enregistrées incluent :

  • Utiliser la validation en ligne plutôt que la validation uniquement lors de la soumission
  • Placer les suggestions IA dans un panneau latéral plutôt que directement dans l’éditeur
  • Utiliser la divulgation progressive pour les paramètres avancés
  • Exiger une confirmation avant les actions destructrices
  • Utiliser “Brouillon” et “Publié” au lieu de “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, pas à 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, pas juste 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 conscients de l’historique du projet. Ils peuvent inspecter des fichiers, déduire des modèles 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 parce que cela semble propre isolément. Sans un ADR, l’IA n’a pas de moyen durable de savoir que l’équipe a déjà envisagé et rejeté cette voie, et le résultat est un effort gaspillé ou une régression subtile dans 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 limites du système. Un changement d’interface utilisateur 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 cassant 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 modèles existants dans la base de code, mais les modèles ne sont pas les mêmes que les principes. Parfois, le code existant est un compromis. Parfois, il est transitoire. Parfois, il existe à cause 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 de cette manière.”

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 confiantes 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 soit fusionné.

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

Les registres de décision ne sont pas juste de la documentation — ils font partie d’une manière de travailler plus large qui se situe à l’intersection de la gouvernance architecturale légère, de la documentation en tant que 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 manière utile de décrire le processus plus large est le Développement Orienté Décision.

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

flowchart LR A[Prompt] --> B[Générer le code] B --> C[Test] C --> D[Commettre]

Ce cycle est trop mince pour un travail de système sérieux. Un flux de travail plus robuste traite le dépôt comme un magasin à la fois 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 aussi :

flowchart TB subgraph top[" "] direction LR A[Cadrer le problème] --> B[Identifier les décisions existantes] --> C[Explorer les options et compromis] --> D[Enregistrer la décision sélectionnée] end subgraph bottom[" "] direction LR E[Générer ou modifier le code] --> F[Revoir le code vs les décisions] --> G[Fusionner l'implémentation et la mémoire] --> H[Utiliser le registre pour guider le travail futur] end D --> E

Ce processus transforme le dépôt en 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 avec chaque décision prise.

Les registres de décision et la documentation en tant que code

Les registres de décision fonctionnent mieux lorsqu’ils suivent les principes de la documentation en tant que code, ce qui signifie qu’ils doivent être stockés dans le même dépôt que le code, écrits en Markdown simple, révisés dans les pull requests, versionnés avec Git, liés aux problèmes et pull requests associés, et recherchables par les humains et les outils d’IA. C’est beaucoup plus fiable que de stocker des décisions importantes dans des chats, des pages wiki, des présentations ou des comptes rendus de réunion — ces outils peuvent encore être utiles pour la discussion, mais la décision acceptée devrait toujours vivre près du code. Maintenir les spécifications, tests et code synchronisés dans le développement IA étend cette même habitude de “lier au registre” en un modèle de traçabilité complet qui lie les IDs de décision de conception et de requirement aux tests et pull requests.

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

docs/
  decisions/
    architecture/
      0001-utiliser-postgresql-pour-le-stockage-principal.md
      0002-garder-la-facturation-dans-l-application-principale.md
    product/
      0001-l-email-genere-par-l-ia-requiert-une-revision-humaine.md
      0002-limite-du-projet-niveau-gratuit.md
    design/
      0001-utiliser-la-validation-en-ligne.md
      0002-placer-les-suggestions-ia-dans-le-panneau-lateral.md

Pour les plus 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 d’IA à charger en 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 mise en page cmd/, internal/, et api/ décrite dans Structure de projet Go : Pratiques & Patterns, qui recommande docs/ comme domicile pour les décisions architecturales et les références API.

Un modèle de registre de décision pratique

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

# Décision : Titre court

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

## Contexte

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

## Décision

Énoncer la décision clairement.

## Alternatives envisagé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 ...
- Préférer ...
- Demander une révision quand ...

## Liens

- Problèmes associés :
- Pull requests associés :
- Fichiers associés :
- Rend obsolète :
- Rendu obsolète par :

La section “Guidance IA” est optionnelle, 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 agents futurs travaillant dans la même zone de la base de code.

Que doit-on mettre dans 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 vrai débat
  • Introduisent un compromis à long terme
  • Dépendent de contraintes commerciales, de conformité ou opérationnelles
  • Seraient coûteuses à redécouvrir plus tard
  • Les outils d’IA futurs pourraient plausiblement mal faire
  • Les contributeurs futurs pourraient être tentés d’inverser casually

Les mauvais candidats incluent les petits choix de refactor, 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 devraient 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 quand l’équipe veut discuter d’une décision dans un pull request avant de s’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, quand les anciens modèles existent dans la base de code à côté des approches plus récentes.

Le principe important est que les registres de décision devraient être amicaux à l’ajout. Quand 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 à rédiger des documents structurés à partir du contexte. Après une discussion, une revue d’architecture 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 devrait cependant pas être automatiquement fait confiance. 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 la propriétaire de la décision.

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

L’autre moitié de la pratique est d’instruire 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 tout Registre de Décision Architectural, Produit ou Design qui s'applique.
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 les tâches plus grandes, renforcez le rôle des registres comme mémoire de projet :

Utilisez les registres de décision comme mémoire de projet.
N'inversez pas les décisions acceptées sans proposer une nouvelle décision les rendant 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 fiabilité pour les projets complexes ou à longue durée de vie.

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 liste de vérification PR rend l’habitude visible :

## Liste de vérification des registres de décision

- [ ] Cette PR n'introduit pas de décision architecturale, produit ou design significative.
- [ ] Cette PR introduit une décision significative et inclut un nouveau registre de décision.
- [ ] Cette PR change une décision précédente et inclut un registre la rendant obsolète.
- [ ] Les registres de décision existants pertinents ont été pris en compte.
- [ ] 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 liste de vérification est simple, mais elle change le comportement en rappelant à l’équipe que le code n’est pas le seul artefact qui compte dans un pull request. Elle rend aussi naturel de capturer quand un changement généré par l’IA viole silencieusement une décision précédente.

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 — les conseils d’approbation centraux, les documents initiaux volumineux, et les processus de garde qui bloquent plutôt que guident. 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îne de décisions qui peut être révisée, référencée et construite sur le 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é faites, ce qui est une forme de gouvernance plus saine et plus honnête :

  • De petits registres au lieu de documents géants
  • 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 aussi 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 ce qu’il faut 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 vide et sont particulièrement utiles pour les décisions de tarification et d’emballage, les modèles de permissions, les limites et quotas, les flux de sécurité et révision IA, les choix d’intégration, les définitions de rôles utilisateurs, les règles de collaboration, les politiques de rétention de 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 de cette manière ?” Un PDR donne la réponse sous une forme que les humains et les outils d’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 tokens et les règles d’utilisation, mais ils documentent rarement pourquoi le système fonctionne de cette manière. Les Registres de Décision Design combler ce vide. 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 designers, développeurs et outils d’IA futurs à appliquer le principe correctement dans de nouvelles situations. Sans le DDR, un agent IA pourrait générer une interaction plus rapide qui saute la confirmation parce qu’elle semble plus efficace. Avec le DDR, l’agent peut reconnaître que préserver la propriété de sécurité est intentionnel 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 exigeraient 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 préserver le contrôle utilisateur a été pondéré plus lourdement que la vitesse du flux de travail. Une spécification d’architecture peut définir une limite de service, et son ADR explique pourquoi l’équipe a choisi cette limite 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 à longue durée de vie. Quand vous adoptez une chaîne d’outils pilotée par spécification, comparez comment chaque option expose ce contexte ; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows décompose la portabilité, les portes de révision, et l’ancrage du dépôt à travers les configurations principales. Pour le processus neutre en cinq phases que ces outils implémentent, voir Flux de travail de Développement Piloté par Spécification : Des Requirements au Code.

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 à cause de ces contraintes et compromis.” Ce “plutôt que Y” est la partie précieuse. Les outils d’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 sont pas un remplacement pour 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 faire respecter 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 sont pas un remplacement pour 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 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 n’affecte que 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 quand la décision est prise, pas des mois plus tard quand tout le monde a oublié les compromis. C’est acceptable d’en rédiger un pendant un pull request. C’est encore mieux de le rédiger avant l’implémentation, pendant 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é plutôt que l’exhaustivité — un registre concis qui est lu est beaucoup plus précieux qu’un complet qui est sauté.

Enregistrer des décisions sans conséquences

La section des 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é à cause du choix.

Modifier 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é. Les bases de connaissances compilées font face au problème identique sous un nom différent — Maintenance Wiki LLM : Dérive, Contradictions et Révision l’appelle la dérive de décision, et applique la même règle de rendre obsolète plutôt que d’écraser aux pages wiki.

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

L’IA peut produire un registre poli 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 des 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 associé.
  6. Instructez les outils de codage IA à lire les registres pertinents avant de faire des changements futurs dans la zone.
  7. Rendez les registres obsolètes quand les décisions changent, en préservant l’ancien registre pour l’histoire.

Cela ne nécessite pas de nouvelle bureaucratie ou de rôle de documentation dédié. Cela nécessite une petite habitude : préserver un 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
Propriétaires : É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 envisagées

### DynamoDB

Avantages :
- Scalabilité opérationnelle
- Bonne adéquation pour les modèles 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 à 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, un indexation mature et
un support de reporting flexible.

## Guidance IA

Quand vous modifiez le code de persistance, préférez la modélisation relationnelle dans PostgreSQL.
N'introduisez pas une seconde base de données principale sans un ADR la rendant 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
Propriétaires : É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 envisagé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 seulement 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 existant des clients de messagerie 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 la rendant 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 sauf si un nouveau PDR accepté 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
Propriétaires : Équipe Design

## Contexte

Les utilisateurs ont besoin d'aide pour améliorer le contenu écrit, mais ils ont aussi besoin de 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 envisagées

### Appliquer les suggestions en ligne

Avantages :
- Rapide
- Semble intégré

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

### Afficher les suggestions dans une modale

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 explicite de l'utilisateur.

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 tout registre de décision accepté qui s'applique
à cette tâche. Résumez les contraintes avant de proposer des changements de code.

Rédiger un nouvel 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 tout conflit, registre de décision manquant, 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 obsolète l'existant.
Préservez le raisonnement historique, expliquez ce qui a changé, et liez les deux registres.

Lecture connexe

S'abonner

Recevez de nouveaux articles sur les systèmes, l'infrastructure et l'ingénierie IA.