ADR, RFC, notes de design : comment documenter vos arbitrages pour vous protéger
Un Architecture Decision Record n'est pas qu'un artefact de bonne pratique : c'est la pièce maîtresse de votre dossier en cas de mise en cause. Voici comment structurer vos ADR, RFC et notes de design pour qu'ils tiennent en justice et déclenchent la garantie RC Pro sans friction.
- Un ADR (Architecture Decision Record) documenté contemporain de la décision a une valeur probante très forte devant un tribunal.
- Le format ADR canonique tient en cinq sections : contexte, options envisagées, décision retenue, conséquences acceptées, validation du client.
- Les RFC internes et les notes de design produites par l'architecte sont opposables au client, à condition d'être datées, archivées et partagées formellement.
- Sans cette documentation, l'architecte se prive de la moitié de son argumentaire devant l'assureur comme devant le juge.
Pourquoi un ADR vaut plus qu'un audit a posteriori
Quand une réclamation arrive, l'architecte logiciel se trouve dans la position la plus inconfortable du métier : devoir reconstituer, parfois deux ou trois ans après les faits, le raisonnement qui a conduit à un choix structurant. À cette distance, la mémoire ne suffit plus. Les emails sont enfouis, les présentations PowerPoint ont disparu avec le compte Slack du client, les comptes rendus de réunion n'ont jamais été formalisés.
L'ADR — Architecture Decision Record — résout ce problème en figeant la décision au moment où elle est prise. Il transforme un raisonnement implicite en preuve datée, contradictoire, validée. Devant un assureur qui instruit un dossier de sinistre, ou devant un juge qui apprécie le respect des règles de l'art, un ADR daté de l'époque vaut infiniment plus qu'une note de défense rédigée trois ans plus tard.
Pour un architecte logiciel, l'ADR est l'équivalent du dossier patient pour un médecin : pas seulement un outil de qualité, mais l'instrument primaire de la défense professionnelle.
Le format ADR canonique en cinq sections
Plusieurs formats coexistent (Michael Nygard 2011, MADR, Y-Statements). Pour la solidité juridique, le format Nygard étendu est le plus efficace. Voici les cinq sections indispensables.
1. Contexte et problème
Décrivez en deux à cinq paragraphes le besoin métier, les contraintes connues à la date de la décision, les éléments d'environnement (budget, équipe, délais). Cette section ancre la décision dans le réel et permet, plus tard, de démontrer que vous avez raisonné sur la base d'informations complètes et disponibles.
2. Options envisagées
Listez au minimum trois options sérieusement étudiées. Pour chacune, mentionnez les avantages, les inconvénients, les coûts estimés et les risques résiduels. Cette section est cruciale : elle prouve que vous n'avez pas choisi par défaut ou par confort, mais après une instruction comparative. Un juge qui voit trois options pesées y voit un acte de diligence ; une seule option présentée fait l'effet inverse.
3. Décision retenue
Énoncez clairement le choix, ses justifications principales, et son périmètre. Précisez ce que la décision ne couvre pas : les composants exclus, les évolutions futures non garanties, les conditions dans lesquelles la décision devrait être réévaluée.
4. Conséquences acceptées
C'est la section la plus stratégique sur le plan défensif. Listez les conséquences positives et négatives de la décision : dette technique acceptée, limitations connues, scénarios de défaillance prévisibles. Cette section signée par le client transfère la charge des risques explicitement acceptés.
5. Validation et traçabilité
Nom du décideur côté client (avec sa fonction), date, mode de validation (réunion, email, signature), version du document, lien vers les pièces jointes (chiffrages, benchmarks, retours d'expérience cités). Sans cette section, un ADR n'a pas de force probante : il ressemble à un brouillon technique.
Quels arbitrages méritent un ADR : la règle des trois critères
Produire un ADR pour chaque ligne de code serait absurde. Produire un ADR pour les seules décisions « importantes » est trop vague. Le critère opérationnel est triple : un arbitrage mérite un ADR s'il remplit au moins deux des trois conditions suivantes.
- Réversibilité difficile. Revenir en arrière coûterait plus de quinze jours-homme ou nécessiterait une migration de données.
- Impact transverse. La décision affecte au moins deux composants, deux équipes, ou crée un couplage durable entre couches.
- Risque résiduel non nul. La décision laisse un risque connu (sécurité, performance, conformité) que le client doit accepter en connaissance de cause.
Les arbitrages typiques à formaliser
- Choix du modèle d'authentification et d'autorisation (RBAC, ABAC, ReBAC, JWT vs sessions, fédération).
- Stratégie de persistance des données (base relationnelle vs NoSQL, modèle de cohérence, gestion des transactions distribuées).
- Frontières entre microservices, choix des protocoles inter-services, gestion des contrats d'API.
- Stratégie de gestion des secrets et de rotation.
- Décisions de conformité (résidence des données, chiffrement, journalisation, droit à l'oubli).
- Choix d'un fournisseur cloud structurant, d'un IdP, d'un SGBD géré.
Règle empirique : un projet structurant de douze mois génère typiquement entre quinze et vingt-cinq ADR. En deçà de dix, vous documentez probablement trop peu pour vous protéger.
RFC internes et notes de design : la deuxième couche de preuve
Les ADR documentent la décision finale. Les RFC (Request For Comments) et les notes de design documentent le processus de réflexion qui y a conduit. Les deux sont complémentaires devant un juge.
Quand produire une RFC plutôt qu'un ADR
La RFC est adaptée aux arbitrages structurants pour lesquels vous voulez recueillir des avis avant de trancher. Elle est typiquement plus longue (cinq à quinze pages), plus exploratoire, et sa version finale aboutit souvent à un ADR. La RFC démontre que la décision a été ouverte à la contradiction, ce qui renforce sa solidité défensive.
Les notes de design technique
Pour les arbitrages secondaires (choix d'une bibliothèque, d'un pattern, d'une convention), une note d'une à deux pages suffit. L'essentiel est qu'elle soit datée, archivée dans le repository du projet ou dans un wiki versionné, et accessible au client.
Le piège des décisions orales
Une décision prise « en stand-up » ou « validée par téléphone » n'a aucune valeur probante si elle n'a pas été suivie d'un mail récapitulatif. La règle d'or : aucune décision structurante ne quitte la réunion sans un écrit envoyé dans les 24 heures, mentionnant les présents, le sujet, le choix retenu, les risques évoqués.
Comment archiver pour que vos preuves tiennent dans cinq ans
Un ADR rédigé en 2024 et perdu en 2027 ne sert à rien. L'archivage est aussi important que la rédaction. Trois règles pratiques.
- Archivez en plusieurs endroits indépendants. Le repository Git du client (qui peut disparaître), votre propre coffre-fort numérique professionnel, et un export PDF horodaté dans un service de notarisation ou de simple cloud personnel. La redondance est ce qui rend la preuve robuste à la disparition d'un compte.
- Horodatage à valeur probante. Pour les arbitrages les plus sensibles, utilisez un service d'horodatage qualifié (eIDAS) ou, à défaut, un envoi recommandé électronique du document à votre propre adresse. Le cachet horodaté est une preuve techniquement difficile à contester.
- Durée de conservation : dix ans minimum. Le délai de prescription contractuelle est de cinq ans, mais la responsabilité décennale en informatique fait débat dans certaines situations (logiciels embarqués, systèmes critiques). Conservez large.
Le réflexe à intégrer à votre RC Pro
L'offre RC Pro Insurio pour architectes logiciels, à partir de 12,90 € par mois, intègre un accompagnement à la déclaration de sinistre qui s'appuie précisément sur ce type de documentation. Un assureur qui voit arriver un dossier accompagné des ADR contemporains, des comptes rendus validés et des registres de risques signés instruit le dossier en faveur de l'architecte. À l'inverse, un dossier sans pièces oblige l'assureur à reconstituer la chronologie à charge.
Documenter, c'est se faire payer plus vite, plus largement, et avec moins de discussions.
Questions fréquentes
Envoyez l'ADR par mail avec accusé de réception, en précisant qu'il vaut acceptation tacite à défaut de réponse contradictoire dans un délai raisonnable (huit à quinze jours). Un mail non contesté pendant des semaines acquiert une force probante substantielle. Conservez le fil de discussion intact.
Un ADR bien fait représente trois à six heures de travail pour un arbitrage important : recherche des options, chiffrage, rédaction, allers-retours. Cela paraît coûteux jusqu'au premier sinistre évité. Ramené au taux journalier moyen d'un architecte freelance, c'est une assurance à 0,3 % du chiffre d'affaires annuel.
Les ADR sont des livrables de la mission et appartiennent au client. Conservez une copie pour votre défense personnelle, dans un espace dont l'accès est protégé. La clause de confidentialité du contrat n'interdit pas la conservation à des fins de défense légale, ce que confirme la jurisprudence.
Très limitée. La force probante d'un ADR vient de sa contemporanéité avec la décision. Un document rédigé a posteriori peut être contesté comme reconstitution intéressée. Si vous n'avez pas pu produire l'ADR au moment, formalisez au moins un compte rendu daté reconstitué avec les pièces d'époque (mails, commits Git, présentations) à l'appui.
Pas un refus de principe, mais une instruction plus difficile et une indemnisation parfois réduite si l'assureur estime que l'architecte n'a pas mis en œuvre les diligences raisonnables. Documenter ses choix fait partie des règles de l'art reconnues : ne pas le faire affaiblit votre position.
Souscrivez votre assurance pro en 2 minutes
Toutes nos protections pour votre activité de Architecte logiciel — attestation immédiate, sans engagement.
* Tarifs indicatifs « à partir de », selon votre profil, votre activité et les garanties choisies. · Voir la fiche Architecte logiciel →
Article rédigé et vérifié par l'équipe Insurio — Tutassûr, courtier en assurance immatriculé à l'ORIAS sous le n° 22001730. Information à caractère général ne se substituant pas aux conditions de votre contrat.