Architecture de la documentation : ADR et journaux de décisions pour les systèmes générés par l'IA

Quand vous construisez un système piloté par l’IA, chaque décision technique compte. Pas seulement pour le code qui s’exécute aujourd’hui, mais pour les développeurs qui vont le lire dans six mois, pour les auditeurs qui vérifient la conformité, pour les nouveaux arrivants qui doivent comprendre pourquoi vous avez choisi ce modèle et pas un autre. Et pourtant, trop souvent, ces décisions disparaissent dans les mémoires des développeurs, ou pire, dans les discussions Slack oubliées.

Qu’est-ce qu’un ADR ?

Un Architecture Decision Record (ADR), ou en français Enregistrement de Décision d’Architecture, c’est un document court, simple, et précis qui explique pourquoi vous avez pris une décision technique importante. Ce n’est pas une spécification, pas un manuel d’utilisation. C’est une trace écrite d’un choix fait, avec son contexte, ses alternatives rejetées, et ses conséquences.

Imaginons que vous devez choisir entre deux modèles d’IA pour traiter les requêtes clients : un modèle léger mais moins précis, ou un modèle lourd mais plus fiable. Vous avez discuté, testé, et vous avez opté pour le modèle lourd. Sans ADR, cette décision devient un mythe : "On a toujours fait comme ça." Avec un ADR, vous écrivez :

• Contexte : Les erreurs de classification des demandes clients entraînent des pertes financières et une baisse de la confiance.
• Décision : Nous adoptons le modèle GPT-4-turbo pour sa précision supérieure (94,2 % selon les tests).
• Conséquences : Coût de traitement multiplié par 3, latence moyenne de 850 ms, nécessite un scaling automatique. Les alternatives (Claude 3 Haiku, Llama 3 8B) ont été rejetées pour leur taux d’erreur > 12 %.

Ce document, stocké dans votre dépôt Git à côté du code, devient une référence sacrée. Quand quelqu’un demande "Pourquoi on utilise ça ?", vous lui donnez un lien. Pas une explication orale. Pas un souvenir flou. Un fait.

Pourquoi les ADR sont indispensables avec l’IA

L’IA génère du code, des architectures, des choix. Mais elle ne comprend pas le pourquoi humain.

Un modèle d’IA peut vous proposer de remplacer votre base de données PostgreSQL par MongoDB parce que "c’est plus rapide pour les documents". Mais il ne sait pas que votre équipe a passé deux ans à migrer des données financières sensibles vers PostgreSQL pour respecter la norme PCI-DSS. Il ne sait pas que le service de support a un script personnalisé qui dépend de la syntaxe SQL exacte de PostgreSQL. Il ne sait pas que le responsable sécurité a refusé MongoDB après une faille en 2022.

Les ADR combattent cette myopie. Ils obligent l’équipe à poser des questions : Quelle est la contrainte réelle ? Qui est impacté ? Quel est le vrai risque ? Sans ça, l’IA vous donne des solutions techniques, mais pas des décisions architecturales.

Selon une étude de Salesforce publiée en avril 2024, les systèmes d’IA génèrent correctement les aspects techniques d’une décision dans 92 % des cas. Mais ils ne comprennent le contexte métier que dans 63 % des cas. Sans l’intervention humaine, vous finissez avec des ADRs parfaitement formulés… mais complètement erronés.

Comment structurer un bon ADR

Il n’y a pas de règle universelle, mais les meilleures pratiques convergent. Voici ce qu’un ADR efficace doit contenir :

1. Titre clair : "Choix du modèle d’IA pour le traitement des requêtes clients"
2. Date de création : Le jour où la décision a été prise.
3. Statut : Décision adoptée, en cours de discussion, ou rejetée.
4. Contexte : Pourquoi cette décision est nécessaire. Quel problème résout-elle ? Quelle est la pression ?
5. Décision : Ce que vous avez choisi. Sans ambiguïté.
6. Conséquences : Ce que ça change. Positif et négatif. Coût, performance, maintenance, sécurité, impact sur les équipes.
7. Alternatives rejetées : Pourquoi pas l’autre option ? C’est souvent la partie la plus utile pour les futurs lecteurs.

Un ADR ne doit pas dépasser une page. S’il est trop long, vous avez probablement essayé de tout écrire. Concentrez-vous sur le pourquoi, pas sur le comment. Le code, les schémas, les tests - ils sont ailleurs. L’ADR, lui, explique le choix.

L’IA comme assistant, pas comme décideur

Les outils comme Claude Code, GitHub Copilot, ou des scripts personnalisés peuvent maintenant générer des ADRs à partir du code existant. C’est révolutionnaire.

Dennis Adolfi a montré dans son projet Umbraco qu’en utilisant une IA pour analyser les commits et les changements de code, il réduisait le temps de création d’un ADR de 73 %. L’IA scanne le code, identifie les changements architecturaux, et propose un premier draft basé sur un template.

Mais voici la clé : l’IA ne signe jamais un ADR. Elle le rédige. Vous le validez.

Les meilleures équipes aujourd’hui utilisent un modèle hybride :

• L’IA : recherche les alternatives, formate le texte, identifie les impacts techniques, suggère des dates et des références.
• Le développeur : ajoute le contexte métier, explique les compromis humains, justifie les choix non techniques, ajoute la responsabilité.

À Salesforce, chaque ADR généré par l’IA doit inclure une déclaration explicite : "L’IA a préparé ce document. L’équipe architecturale en est responsable. Les décisions finales sont humaines." C’est ce qui évite la confiance aveugle.

Les pièges à éviter

Les ADRs sont puissants… mais ils peuvent devenir une charge si mal gérés.

Piège 1 : Les ADRs oubliés. 78 % des développeurs les reportent jusqu’à ce que le contexte soit flou. Résultat : des documents vides ou erronés. Solution : intégrez la création d’un ADR dans votre workflow. Exemple : "Tout changement d’architecture doit être accompagné d’un ADR avant le merge."

Piège 2 : Les ADRs immuables. Certains disent qu’un ADR, une fois signé, ne doit jamais être modifié. Mais la réalité est plus fluide. Une décision peut être révisée. La solution ? Ajoutez des mises à jour avec date. "Mise à jour du 15/12/2025 : après 3 mois de production, le modèle a montré une dégradation de 8 % de précision. Nous passons à GPT-4o. ADR original conservé pour historique."

Piège 3 : Les ADRs trop abstraits. "Nous avons choisi une architecture microservices." C’est une phrase vide. Pourquoi ? Quels services ? Quelle communication ? Quelle stratégie de déploiement ? Sans détails, l’ADR ne sert à rien. Soyez concret.

Comment commencer ?

Vous n’avez pas besoin de réinventer la roue. Voici comment démarrer en 3 étapes :

1. Choisissez un template. Utilisez celui de GitHub (joelparkerhenderson/architecture-decision-record). Il est simple, clair, et largement adopté.
2. Créez un dossier. Dans votre dépôt, créez un dossier docs/adr/. Chaque ADR est un fichier 001-decision-titre.md.
3. Commencez par un seul ADR. Prenez la dernière décision architecturale importante que vous avez prise. Écrivez-la maintenant. Pas demain. Pas après les vacances. Maintenant.

Ensuite, demandez à votre équipe : "Quelle décision a été prise il y a 6 mois que personne ne se souvient plus ?" Écrivez l’ADR en arrière-plan. C’est ce qu’on appelle le "brownfield ADR" - documenter ce qui a déjà été fait. Microsoft rapporte que cette pratique réduit le temps d’intégration des nouveaux développeurs de 41 % sur les projets Azure.

Le futur : ADRs en temps réel

Le prochain pas ? Des ADRs générés automatiquement pendant les revues de code.

À Salesforce, ils testent un système qui analyse chaque pull request. Si un changement touche une interface API, un modèle d’IA, ou une dépendance critique, il propose automatiquement : "Un ADR est nécessaire pour ce changement. Voulez-vous le créer maintenant ?"

Le but : éliminer les décisions non documentées. Selon leur roadmap, ils visent une réduction de 40 % des décisions architecturales non enregistrées d’ici fin 2025.

Et ça ne s’arrête pas là. Les outils comme docToolchain et Structurizr commencent à lier les ADRs aux diagrammes d’architecture, aux tests de performance, et même aux métriques de production. L’ADR devient le cœur d’un système de documentation vivant, connecté, et automatisé.

Conclusion : La documentation comme avantage compétitif

Les systèmes générés par l’IA ne sont pas seulement plus rapides. Ils sont plus complexes. Et plus risqués.

Les équipes qui documentent leurs décisions ne sont pas plus lentes. Elles sont plus résilientes. Elles n’ont pas besoin de réexpliquer les mêmes choix. Elles ne perdent pas des années de savoir-faire quand quelqu’un quitte l’équipe. Elles passent moins de temps à débattre du passé - parce que le passé est écrit.

Les ADRs ne sont pas une contrainte. C’est votre carte du trésor. Votre mémoire collective. Votre garantie que les décisions prises aujourd’hui ne deviendront pas des cauchemars demain.

Commencez par un seul ADR. Pas un manuel. Pas une norme. Un seul document. Un seul choix. Et voyez comment ça change la façon dont votre équipe parle de l’architecture.