Journal des décisions pour le développement logiciel propulsé par l’IA

Gardez l'intention proche du code.

Sommaire

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

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

Les registres de décisions : 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 coûteux à générer, plus facile à refactoriser et plus rapide à abandonner. C’est utile. C’est aussi dangereux, car lorsque le code devient plus facile à produire, la ressource rare n’est plus la saisie — la ressource rare est le jugement.

Pourquoi l’équipe a-t-elle choisi PostgreSQL au lieu de DynamoDB ? Pourquoi le produit exige-t-il un examen humain avant l’envoi d’e-mails générés par 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écisions résolvent ce problème en fournissant un document court, sous contrôle de version, qui capture un choix important, le contexte qui l’entoure, les alternatives envisagées et les conséquences acceptées par l’équipe. Dans une base de code assistée par IA, ces registres deviennent plus que de la documentation — ils deviennent une mémoire de projet durable que les humains et les agents d’IA peuvent lire avant d’apporter des modifications futures. La règle opérationnelle pratique est simple : maintenir les registres de décisions sous forme de fichiers Markdown dans le dépôt, les examiner 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écisions ?

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 envisagées et quelles conséquences avons-nous acceptées ? La forme la plus courante est le Registre de Décision d’Architecture, abrégé en ADR. Les ADR sont largement utilisés pour documenter les décisions techniques, et le même schéma peut être étendu au-delà de l’architecture vers le travail produit et de conception.

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

Type de registre Capture Exemple
ADR Décisions d’architecture et techniques Utilisation de PostgreSQL comme base de données principale
PDR Décisions sur le comportement et le périmètre produit Les e-mails générés par IA doivent rester des brouillons
DDR Décisions de conception et d’interaction Afficher les suggestions d’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 d’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écisions donnent aux systèmes d’IA une source d’intention projetée, validée, durable et approuvée par les humains.

Registres de Décision d’Architecture (ADR)

Les Registres de Décision d’Architecture capturent les décisions techniques et structurelles. Utilisez un ADR lorsqu’une décision affecte la forme du système — ses frontières, 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 :

  • Choix de PostgreSQL comme base de données principale
  • Utilisation d’une architecture orientée événements pour le traitement en arrière-plan
  • Maintien de l’application sous forme de monolithe modulaire
  • Introduction d’une file de messages
  • Choix de REST au lieu de GraphQL
  • Utilisation du rendu côté serveur pour l’application web
  • Exigence que tous les jobs en arrière-plan soient idempotents
  • Adoption d’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 précis dans le temps. Un bon ADR prévient l’amnésie architecturale : sans lui, les contributeurs futurs peuvent 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 un poids encore plus important. Les outils d’IA sont souvent habiles à l’optimisation locale, et ils peuvent proposer une modification 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 formé. »

Registres de Décision Produit (PDR)

Les Registres de Décision Produit capturent le comportement produit, le périmètre et l’intention destinée aux utilisateurs. C’est moins courant que les ADR, mais c’est souvent aussi précieux — les décisions produit sont fréquemment dispersées dans les tickets, les outils de feuille de route, les fils de discussion, les notes de réunion et la mémoire des gens, ce qui les rend faciles à oublier pour les humains et presque impossibles à inférer de manière fiable pour les outils d’IA.

Utilisez un PDR lorsqu’une décision affecte ce que fait le produit, à qui il sert, ce qui est intentionnellement hors périmètre, ou comment une fonctionnalité destinée aux utilisateurs doit se comporter. Les exemples incluent :

  • Les messages générés par IA doivent rester des brouillons jusqu’à ce qu’ils soient examinés par un humain
  • Les utilisateurs de l’offre gratuite 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 d’IA à 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 peut contenir une limite de trois projets pour les utilisateurs gratuits, et sans PDR, un outil d’IA peut 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 simple édition.

Registres de Décision de Conception (DDR)

Les Registres de Décision de Conception capturent les décisions d’expérience utilisateur, d’interaction, visuelles et de conception de contenu. Utilisez un DDR lorsqu’une décision affecte la manière dont les utilisateurs interagissent avec le produit, la façon dont l’information est présentée, ou comment un principe de conception doit être appliqué aux travaux futurs.

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

  • Utilisation de la validation en ligne au lieu de la validation uniquement à l’envoi
  • Placement des suggestions d’IA dans un panneau latéral au lieu de directement dans l’éditeur
  • Utilisation de la révélation progressive pour les paramètres avancés
  • Exigence de confirmation avant les actions destructives
  • Utilisation de « Brouillon » et « Publié » au lieu de « Inactif » et « Actif »
  • Maintien des actions principales visibles sur les écrans mobiles

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

Pourquoi les registres de décisions sont plus importants avec l’IA

Les outils d’IA pour le codage sont puissants, mais ils sont souvent sans état ou seulement partiellement conscients de l’historique du projet. Ils peuvent inspecter les fichiers, inférer des schémas et générer des modifications — mais ils ne savent pas automatiquement quelles décisions sont intentionnelles, quelles 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 d’IA peut toujours proposer d’extraire un service parce que cela semble propre en isolation. Sans 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 de la cohérence du système.

L’IA peut optimiser localement et nuire 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 utilisateur peut réduire la complexité des composants tout en affaiblissant l’expérience utilisateur prévue. Un changement produit peut simplifier l’implémentation tout en brisant les suppositions de tarification ou de conformité. Les registres de décisions donnent à l’IA un cadre de référence plus large avant qu’elle n’agisse sur des signaux étroitement définis.

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

Un modèle peut suivre les schémas existants dans la base de code, mais les schémas ne sont pas la même chose 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écisions 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écisions, mais elle peut aussi inventer des explications qui font autorité et qui ne correspondent pas à la décision réelle. C’est pourquoi l’examen humain 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 précisément la décision réelle, les alternatives et les conséquences avant que le registre ne soit fusionné.

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

Les registres de décisions ne sont pas seulement de la documentation — ils font partie d’une manière de travailler plus large située à l’intersection de la gouvernance architecturale légère, des documents comme du code, des flux de gestion des connaissances augmentés par l’IA, de la découverte produit, du raisonnement de conception, de la gouvernance de l’IA et de l’examen du code. Une façon utile de décrire le processus plus large est le Développement Orienté vers les Décisions.

La plupart des flux de travail de programmation pilotée par l’IA se concentrent étroitement sur la boucle génération-examen-engagement :

flowchart LR A[Invite] --> B[Générer le code] B --> C[Tester] C --> D[Engager]

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

flowchart TB subgraph top[" "] direction LR A[Cadrer le problème] --> B[Identifier les décisions existantes] --> C[Explorer les options et les compromis] --> D[Enregistrer la décision retenue] end subgraph bottom[" "] direction LR E[Générer ou modifier le code] --> F[Examiner le code par rapport aux 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 quelque chose de plus que simple stockage 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.

Registres de décisions et documents comme du code

Les registres de décisions fonctionnent le mieux lorsqu’ils suivent les principes des documents comme du code, ce qui signifie qu’ils doivent être stockés dans le même dépôt que le code, écrits en Markdown simple, examinés dans les requêtes d’extraction, versionnés avec Git, liés aux requêtes et demandes d’extraction associées, et consultables par les humains et les outils d’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 toujours être utiles pour la discussion, mais la décision acceptée doit toujours vivre à proximité du code. Maintenir les spécifications, les tests et le code en synchronisation dans le développement IA étend cette même habitude de « relier au registre » à un modèle de traçabilité complet qui lie les identifiants de décisions de conception et de exigences aux tests et aux requêtes d’extraction.

Une structure de dépôt bien organisée pour les registres de décisions 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 projets plus petits, 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 à examiner 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 disposition cmd/, internal/ et api/ décrite dans Structure de projet Go : pratiques et schémas, qui recommande docs/ comme lieu pour les décisions d’architecture et les références API.

Un modèle de registre de décision pratique

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 guidage IA optionnelle mais précieuse :

# Décision : Titre court

Statut : Proposé | Accepté | Remplacé | Déprécié
Date : AAAA-MM-JJ
Type : Architecture | Produit | Conception
Responsables : Équipe ou noms

## Contexte

Décrivez 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

Énoncez clairement la décision.

## Alternatives envisagées

### Option 1

Avantages :
- ...

Inconvénients :
- ...

## Conséquences

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

## Guidage IA

Lorsqu'un assistant IA travaille dans cette zone, il devrait :
- Préserver ...
- Éviter ...
- Préférer ...
- Demander un examen lorsque ...

## Liens

- Requêtes associées :
- Demandes d'extraction associées :
- Fichiers associés :
- Remplace :
- Remplacé par :

La section « Guidage 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 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 en bruit. Créez un registre de décision lorsqu’un choix est significatif et susceptible d’être important plus tard.

Les bons candidats sont des 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
  • Serait coûteux de redécouvrir plus tard
  • Les futurs outils d’IA pourraient raisonnablement se tromper
  • Les futurs contributeurs pourraient être tentés de renverser facilement

Les mauvais candidats incluent les petits choix de refactorisation, les corrections de bugs évidentes, les expérimentations 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 le renversement de la décision nécessiterait une discussion, enregistrez la décision.

Valeurs de statut et cycle de vie

Les registres de décisions devraient avoir un cycle de vie pour indiquer leur statut actuel. Les valeurs de statut les plus simples sont suffisantes.

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

Accepté — La décision est active et doit guider le travail futur. Les registres de décision les plus utiles passeront la majeure partie de leur vie dans cet état.

Remplacé — La décision a été remplacée par un registre plus récent. N’effacez pas les anciens registres ; conservez-les pour l’historique et liez-les à la décision plus récente afin que l’évolution de la réflexion reste visible.

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

Le principe important est que les registres de décision doivent être compatibles avec l’ajout. Lorsque l’équipe change de cap, créez un nouveau registre et liez l’ancien plutôt que de réécrire l’historique 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 une requête d’extraction, vous pouvez demander à un assistant IA de rédiger un registre :

Rédigez un Registre de Décision d'Architecture pour la décision dans cette requête d'extraction.
Incluez le contexte, les alternatives, les conséquences et le guidage IA.
Enregistrez-le sous forme de Markdown dans docs/decisions/architecture.

Pour le travail produit :

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

Cependant, le registre généré par IA ne devrait pas être automatiquement crédité. L’examen humain 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 le guidage IA correspond à l’intention réelle de l’équipe. L’IA est une assistante 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 consiste à instruire l’IA à lire les registres avant d’agir. Avant de demander à un assistant IA d’implémenter une modification, incluez une instruction comme celle-ci :

Avant de modifier cette fonctionnalité, lisez docs/decisions.
Identifiez tout Registre de Décision d'Architecture, Produit ou Conception applicable.
Suivez les décisions acceptées. Si votre modification proposée 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écisions comme mémoire de projet.
Ne renversez pas les décisions acceptées sans proposer une nouvelle décision de remplacement.
Lorsque 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 dans un système documenté de contraintes » — une amélioration significative de la fiabilité pour les projets complexes ou à long terme.

Registres de décisions dans les requêtes d’extraction

Les registres de décisions devraient faire partie de l’examen normal des requêtes d’extraction plutôt qu’être un processus séparé. Une simple entrée de liste de contrôle pour la requête d’extraction rend l’habitude visible :

## Liste de contrôle des registres de décision

- [ ] Cette requête d'extraction n'introduit pas de décision significative d'architecture, de produit ou de conception.
- [ ] Cette requête d'extraction introduit une décision significative et inclut un nouveau registre de décision.
- [ ] Cette requête d'extraction modifie une décision précédente et inclut un registre de remplacement.
- [ ] Les registres de décision existants pertinents ont été pris en considération.
- [ ] Le code généré par IA respecte les registres de décision acceptés.
- [ ] Les registres de décision générés par IA ont été examinés par un humain.

Cette liste de contrôle est simple, mais elle change le comportement en rappelant à l’équipe que le code n’est pas le seul artefact qui compte dans une requête d’extraction. Elle rend également naturel de détecter lorsqu’une modification générée par IA viole silencieusement une décision précédente.

Registres de décisions et gouvernance architecturale

La gouvernance architecturale traditionnelle échoue souvent parce qu’elle est trop lourde, trop lente ou trop détachée de l’implémentation — les comités d’approbation centraux, les grands documents préliminaires et les processus de contrôle qui bloquent plutôt que de guider. Les registres de décisions 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 comité d’architecture central pour chaque changement, ni n’empêchent-ils les équipes d’apprendre et de s’adapter. Au contraire, ils créent une traîne de décisions qui peut être examinée, référencée et développée au fil du temps. Cela soutient l’architecture évolutive : l’architecture peut changer, mais elle change avec mémoire plutôt que malgré elle. L’équipe peut réexaminer 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 :

  • Petits registres au lieu de documents géants
  • Examen près du code plutôt que théâtre d’approbation séparé
  • Contexte historique plutôt que savoir tribal
  • Compromis explicites plutôt que suppositions cachées

Registres de décisions et 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écisions est souvent sous-estimée. Une feuille de route dit ce qui pourrait se produire. Un ticket dit quoi construire ensuite. Les analytiques disent ce que les utilisateurs ont fait. Aucune de ces choses n’explique entièrement pourquoi un comportement produit existe.

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

Registres de décisions et systèmes de conception

Les systèmes de conception 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 de Conception comblent cette lacune. Une bibliothèque de composants pourrait dire « utilisez la boîte de dialogue de confirmation pour les actions destructives », tandis qu’un DDR explique le raisonnement : « Nous exigeons une confirmation pour les actions destructives car les utilisateurs travaillent souvent avec des données d’équipe partagées, et la suppression accidentnelle a un coût de récupération élevé. »

Ce raisonnement est important au-delà du composant spécifique. Il aide les concepteurs, développeurs et outils d’IA futurs à appliquer le principe correctement dans de nouvelles situations. Sans le DDR, un agent d’IA peut 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 dirigé par spécification

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

Une spécification fonctionnelle peut dire que les e-mails générés par IA doivent être enregistré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 quelles modifications futures exigeraient une nouvelle décision. Une spécification de conception peut décrire une interaction de panneau latéral, tandis que le DDR correspondant explique pourquoi les modifications d’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 à long terme. Lorsque vous adoptez une chaîne d’outils dirigée par spécification, comparez comment chaque option met en avant ce contexte ; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows détaille la portabilité, les points de contrôle d’examen et l’ancrage dans le dépôt à travers les configurations principales. Pour le processus neutre en outils en cinq phases implémenté par ces outils, voir Flux de travail de développement dirigé par spécification : des exigences au code. La plupart des outils SDD ne gèrent que proprement la moitié « livrée » de cette boucle ; Propositions rejetées OpenSpec : une convention de mémoire de décision couvre l’autre moitié — enregistrer une décision rejetée de manière suffisamment durable pour qu’un agent la vérifie avant de reproposer la même idé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 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 les retouches et améliorant la qualité du travail assisté par 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 IA doivent être enregistrés comme brouillons, tandis qu’un Registre de Décision Produit explique que c’est requis parce que les utilisateurs doivent examiner la communication générée par 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 modifications futures plus sûres 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 savoir pourquoi une architecture existe, pourquoi un comportement produit existe, pourquoi un schéma 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 les registres trop tard

Un registre de décision devrait être écrit lorsque la décision est prise, et non des mois plus tard lorsque tout le monde a oublié les compromis. Il est normal d’en faire un brouillon dans une requête d’extraction. Il est encore mieux d’en faire un brouillon avant l’implémentation, alors 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 détaillé suffisamment pour préserver le jugement, mais court suffisant pour que les gens le lisent réellement. Préférez la clarté à l’exhaustivité — un registre concis qui est lu est beaucoup plus précieux qu’un registre exhaustif 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 plus risqué en raison du choix.

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

Lorsqu’une décision change, créez un nouveau registre et marquez l’ancien comme remplacé. 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’historique est utile précisément parce qu’il montre comment la réflexion a évolué. Les bases de connaissances compilées font face au même problème sous un nom différent — Maintenance de Wiki LLM : dérive, contradictions et examen l’appelle dérive de décision et applique la même règle de remplacer plutôt que d’écraser aux pages wiki.

Laisser les registres générés par IA fusionner sans examen

L’IA peut produire un registre soigné et bien structuré qui est subtilement faux. Traitez les registres de décision générés par IA exactement comme le code généré par IA — examinez-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 hors 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 aux côtés des modifications 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 IA.

Un modèle opérationnel léger

Un processus d’équipe pratique qui ajoute un surcroît minimal ressemble à ceci :

  1. Pendant la planification ou l’implémentation, identifier si une décision significative est en cours.
  2. Demander à un assistant IA de rédiger un ADR, PDR ou DDR basé sur la discussion.
  3. Examiner le brouillon en tant qu’équipe, en vérifiant le contexte, les alternatives et les conséquences.
  4. Engager le registre sous forme de Markdown dans le dépôt.
  5. Le lier depuis la requête ou la demande d’extraction associée.
  6. Instruire les outils de codage IA à lire les registres pertinents avant d’apporter des modifications futures dans la zone.
  7. Remplacer les registres lorsque les décisions changent, en préservant l’ancien registre pour l’historique.

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

Exemple d’ADR

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

Statut : Accepté
Date : 25/06/2026
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 rapports fréquentes
et à des exigences de forte cohérence 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 :
- Évolutif sur le plan opérationnel
- Bon choix pour les schémas d'accès clé-valeur prévisibles

Inconvénients :
- Plus complexe pour les requêtes relationnelles
- Plus difficile pour les rapports 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 en matière de prise en charge JSON,
  d'options d'indexation et de compétences existantes

## Conséquences

PostgreSQL devient une dépendance opérationnelle centrale. L'équipe doit gérer
les migrations avec soin et surveiller les performances des requêtes. En retour, l'
application bénéficie d'un modélisation relationnelle forte, d'une indexation mature et
d'une prise en charge flexible des rapports.

## Guidage IA

Lors de la modification du code de persistance, privilégiez la modélisation relationnelle dans PostgreSQL.
N'introduisez pas une seconde base de données principale sans un ADR de remplacement.

Exemple de PDR

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

Statut : Accepté
Date : 25/06/2026
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 à haute confiance parce que les erreurs peuvent atteindre les clients, les partenaires ou
les équipes internes.

## Décision

Les e-mails générés par IA doivent être créés en tant que brouillons. Un utilisateur humain doit
les examiner et les envoyer.

## Alternatives envisagées

### Envoi automatique

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

Inconvénients :
- Risque plus élevé de messages incorrects ou inappropriés
- Confiance utilisateur réduite
- Plus difficile de se rétablir des erreurs

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

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

Inconvénients :
- Encourage toujours un examen superficiel
- Ne s'adapte pas aussi bien au comportement existant des clients e-mail que les brouillons

## Conséquences

Le flux de travail est légèrement plus lent, mais plus sûr et plus fiable.
L'automatisation future peut améliorer la vitesse d'examen, mais ne doit pas contourner
l'approbation humaine sans un PDR de remplacement accepté.

## Guidage IA

Lors de la construction de fonctionnalités de génération d'e-mail, créez des brouillons par défaut.
N'ajoutez pas l'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 : 25/06/2026
Type : Conception
Responsables : Équipe Conception

## Contexte

Les utilisateurs ont besoin d'aide pour améliorer le contenu écrit, mais ils doivent aussi rester
maîtres du texte final. Les modifications d'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
- Se sent intégré

Inconvénients :
- Brouille l'auteur
- Rend l'examen 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, en particulier sur les petits écrans.
Cependant, il préserve le contrôle utilisateur et rend l'examen plus clair.

## Guidage IA

Lors de l'ajout de fonctionnalités d'assistance à l'écriture, préservez la séparation entre
le texte utilisateur et les suggestions IA. N'appliquez pas le 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 IA.

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

Lisez docs/decisions et identifiez tout registre de décision accepté applicable
à cette tâche. Résumez les contraintes avant de proposer des modifications de code.

Rédiger un nouveau ADR :

Rédigez un Registre de Décision d'Architecture pour cette décision technique.
Incluez le contexte, la décision, les alternatives, les conséquences et le guidage 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 le guidage IA.

Rédiger un nouveau DDR :

Rédigez un Registre de Décision de Conception pour ce schéma d'interaction.
Incluez le problème utilisateur, les alternatives, les compromis, les conséquences et le guidage IA.

Examiner une requête d’extraction par rapport aux décisions existantes :

Examinez cette requête d'extraction par rapport aux registres de décision acceptés dans docs/decisions.
Identifiez tout conflit, registre de décision manquant, ou décisions qui devraient
être remplacées.

Remplacer une décision :

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

Lectures complémentaires

S'abonner

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