ADR (Architecture Decision Records)
Formaliser en 30-60 minutes un ADR rigoureux pour chaque choix structurant, qui prendrait 2-3 heures à rédiger from scratch.
Les ADR (Architecture Decision Records) documentent les choix structurants : pourquoi PostgreSQL plutôt que MongoDB, pourquoi Kafka plutôt que RabbitMQ, pourquoi tel pattern d'authentification. Bien rédigés, ils sauvent des années de "pourquoi on a choisi ça déjà ?" et facilitent l'onboarding. L'IA permet de les produire rapidement avec rigueur. Ce guide présente le workflow.
Workflow étape par étape
Décrire le contexte de la décision
Quel problème on résout, quelles contraintes (perf, équipe, budget, time-to-market), quelles options ont été considérées, qui décide et qui est impacté.
Lister les options envisagées
Au moins 3 options sérieuses avec leurs caractéristiques. L'IA aide à structurer (pas oublier les évidences ni inventer les irréalistes).
Comparer sur des critères pertinents
Critères selon le contexte : performance, scalabilité, courbe d'apprentissage, écosystème, coût, maturité, lock-in. Score chaque option.
Décider et documenter le pourquoi
Décision retenue + raisons claires. Surtout : conséquences positives ET négatives, conditions de succès, signaux qui justifieraient de revisiter.
Versionner dans le repo
Format markdown dans /docs/adr/. Numéroté et daté. Reste consultable longtemps après que les protagonistes ont quitté l'équipe.
Prompts copiables
3 prompts testés et optimisés. Adaptez les variables entre crochets [VARIABLE] à votre contexte.
ADR complet sur un choix technique
Tu es architecte logiciel senior. Formalise un ADR pour cette décision : **Contexte** : [PROBLÈME À RÉSOUDRE] **Contraintes** : [PERF, ÉQUIPE, BUDGET, TIMING] **Options envisagées** : [LISTE 3-5 OPTIONS] **Décision retenue** : [OPTION CHOISIE] **Stack actuelle** : [CONTEXTE TECH] Produis un ADR au format Michael Nygard : ## Status [Proposed / Accepted / Deprecated / Superseded by X] ## Context [3-5 paragraphes : problème, contraintes, ce qui a déclenché la réflexion] ## Options Considered ### Option 1 : [NOM] - Pros - Cons - Coûts (apprentissage, dette, infrastructure) ### Option 2 : [NOM] [idem] ## Decision [Option retenue + raisons claires] ## Consequences ### Positive [3-5 conséquences positives attendues] ### Negative [2-4 conséquences négatives ou compromis assumés] ## Conditions to Revisit [Signaux qui justifieraient de re-questionner cette décision dans 12-24 mois] Marque [À VÉRIFIER] tout chiffre incertain (perf, coûts).
Comparatif technologies multi-critères
Pour ce choix : [TYPE DE TECH — ex : message broker, base de données, framework frontend] **Contexte** : [DÉTAILS] **Contraintes** : [LISTE] Compare ces options sur des critères structurants : [OPTION 1] vs [OPTION 2] vs [OPTION 3] Critères : 1. **Performance** (latence, throughput, ressources) 2. **Scalabilité** (horizontale, verticale, limites) 3. **Maturité et écosystème** (versions stables, communauté, documentation) 4. **Courbe d'apprentissage** (équipe actuelle, recrutement) 5. **Lock-in et portabilité** 6. **Coût total** (licence, infrastructure, opérations) 7. **Sécurité et conformité** Format : tableau comparatif avec scoring /10 par critère, puis recommandation argumentée.
Audit d'un ADR existant
Audite cet ADR : [ADR] Produis : 1. **Forces** : ce qui est bien fait (rigueur, clarté, exhaustivité) 2. **Faiblesses** : ce qui manque (options manquantes, conséquences négatives sous-estimées, pas de plan B) 3. **Mises à jour nécessaires** : étant donné l'évolution depuis la rédaction, qu'est-ce qui a changé dans le paysage tech 4. **Recommandation** : ADR encore valide / à actualiser / à reconsidérer Reste constructif et factuel.
Top outils pour ce cas d'usage
Sélection commentée des 3 meilleurs outils IA pour adr (architecture decision records).
Pourquoi pour ce cas d'usage : Le meilleur reasoning sur les choix techniques complexes nécessitant la pesée multi-critères et l'anticipation des conséquences.
Pourquoi pour ce cas d'usage : Excellence sur la rédaction structurée et rigoureuse des ADR. Format Michael Nygard ou variante au choix.
Pourquoi pour ce cas d'usage : Pour benchmarker en temps réel avec sources fraîches (versions actuelles, retours d'expérience, comparaisons à jour).
ROI estimé
Temps gagné
70% sur la rédaction (30-60 min vs 2-3h)
Gain qualité
ADR systématiquement rigoureux, conséquences négatives explicitées
Coût stack
20-30€/mois
Estimations basées sur des benchmarks 2026 et retours d'utilisateurs. Le ROI réel dépend de votre contexte.
Questions fréquentes
Faut-il un ADR pour chaque décision ?
Non. Règle : ADR pour les décisions structurantes (qui engageront sur 2+ ans, qui coûteraient cher à inverser, qui impactent plusieurs équipes). Pour les détails de mise en œuvre : commentaires de code, README de service. Trop d'ADR = aucun ADR lu.
L'IA peut-elle décider à la place de l'architecte ?
Non. L'IA produit un comparatif rigoureux, mais la décision implique : connaissance fine de l'équipe, contraintes politiques internes, intuitions métier, vision long terme. Le "so what" reste humain.
ADR vs RFC : différence ?
RFC (Request for Comments) : avant la décision, pour discuter et challenger. ADR : après la décision, pour la documenter et la justifier dans le temps. Beaucoup d'équipes utilisent les deux : RFC en cours de discussion, ADR une fois tranché.
Comment maintenir les ADR au fil du temps ?
Status tracking strict : Proposed / Accepted / Deprecated / Superseded by ADR-XXX. Quand une décision est superseded, le nouvel ADR doit référencer l'ancien. C'est ce qui rend l'historique traçable.