Enregistrements de Décisions Architecturales (ADR)
Capturez les décisions architecturales au fur et à mesure qu'elles se produisent lors des sessions de codage. Au lieu que les décisions ne vivent uniquement dans des threads Slack, des commentaires de PR ou la mémoire de quelqu'un, cette compétence produit des documents ADR structurés qui vivent aux côtés du code.
Quand Activer
- L'utilisateur dit explicitement "enregistrons cette décision" ou "ADR ceci"
- L'utilisateur choisit entre des alternatives significatives (framework, bibliothèque, pattern, base de données, conception d'API)
- L'utilisateur dit "nous avons décidé de..." ou "la raison pour laquelle nous faisons X au lieu de Y est..."
- L'utilisateur demande "pourquoi avons-nous choisi X ?" (lire les ADRs existants)
- Pendant les phases de planification où les compromis architecturaux sont discutés
Format ADR
Utilisez le format ADR léger proposé par Michael Nygard, adapté pour le développement assisté par IA :
# ADR-NNNN : [Titre de la décision]
**Date** : AAAA-MM-JJ
**Statut** : proposé | accepté | déprécié | remplacé par ADR-NNNN
**Décideurs** : [qui était impliqué]
## Contexte
Quel est le problème que nous voyons et qui motive cette décision ou ce changement ?
[2 à 5 phrases décrivant la situation, les contraintes et les forces en jeu]
## Décision
Quel est le changement que nous proposons et/ou que nous faisons ?
[1 à 3 phrases énonçant clairement la décision]
## Alternatives Envisagées
### Alternative 1 : [Nom]
- **Avantages** : [bénéfices]
- **Inconvénients** : [inconvénients]
- **Pourquoi pas** : [raison spécifique du rejet]
### Alternative 2 : [Nom]
- **Avantages** : [bénéfices]
- **Inconvénients** : [inconvénients]
- **Pourquoi pas** : [raison spécifique du rejet]
## Conséquences
Qu'est-ce qui devient plus facile ou plus difficile à faire à cause de ce changement ?
### Positives
- [bénéfice 1]
- [bénéfice 2]
### Négatives
- [compromis 1]
- [compromis 2]
### Risques
- [risque et atténuation]
Flux de Travail
Capturer un Nouvel ADR
Lorsqu'un moment de décision est détecté :
- Initialiser (première fois uniquement) — si
docs/adr/n'existe pas, demandez à l'utilisateur confirmation avant de créer le répertoire, unREADME.mdamorcé avec l'en-tête du tableau d'index (voir Format de l'Index ADR ci-dessous), et untemplate.mdvierge pour usage manuel. Ne créez pas de fichiers sans consentement explicite. - Identifier la décision — extraire le choix architectural principal en cours
- Rassembler le contexte — quel problème a déclenché cela ? Quelles contraintes existent ?
- Documenter les alternatives — quelles autres options ont été envisagées ? Pourquoi ont-elles été rejetées ?
- Énoncer les conséquences — quels sont les compromis ? Qu'est-ce qui devient plus facile/plus difficile ?
- Attribuer un numéro — analyser les ADRs existants dans
docs/adr/et incrémenter - Confirmer et écrire — présenter le brouillon d'ADR à l'utilisateur pour révision. Écrire dans
docs/adr/NNNN-titre-decision.mduniquement après approbation explicite. Si l'utilisateur refuse, jeter le brouillon sans écrire de fichiers. - Mettre à jour l'index — ajouter à
docs/adr/README.md
Lire les ADRs Existants
Lorsqu'un utilisateur demande "pourquoi avons-nous choisi X ?" :
- Vérifier si
docs/adr/existe — si non, répondre : "Aucun ADR trouvé dans ce projet. Souhaitez-vous commencer à enregistrer des décisions architecturales ?" - S'il existe, analyser l'index
docs/adr/README.mdpour les entrées pertinentes - Lire les fichiers ADR correspondants et présenter les sections Contexte et Décision
- Si aucune correspondance n'est trouvée, répondre : "Aucun ADR trouvé pour cette décision. Souhaitez-vous en enregistrer un maintenant ?"
Structure du Répertoire ADR
docs/
└── adr/
├── README.md ← index de tous les ADRs
├── 0001-utilisation-nextjs.md
├── 0002-postgres-plutot-que-mongo.md
├── 0003-rest-plutot-que-graphql.md
└── template.md ← modèle vierge pour usage manuel
Format de l'Index ADR
# Enregistrements de Décisions Architecturales
| ADR | Titre | Statut | Date |
|-----|-------|--------|------|
| [0001](0001-utilisation-nextjs.md) | Utiliser Next.js comme framework frontend | accepté | 2026-01-15 |
| [0002](0002-postgres-plutot-que-mongo.md) | PostgreSQL plutôt que MongoDB pour le stockage principal | accepté | 2026-01-20 |
| [0003](0003-rest-plutot-que-graphql.md) | API REST plutôt que GraphQL | accepté | 2026-02-01 |
Signaux de Détection de Décision
Surveillez ces schémas dans la conversation qui indiquent une décision architecturale :
Signaux explicites
- "Allons avec X"
- "Nous devrions utiliser X au lieu de Y"
- "Le compromis en vaut la peine parce que..."
- "Enregistre ceci en tant qu'ADR"
Signaux implicites (suggérer d'enregistrer un ADR — ne pas créer automatiquement sans confirmation de l'utilisateur)
- Comparer deux frameworks ou bibliothèques et aboutir à une conclusion
- Faire un choix de conception de schéma de base de données avec une justification énoncée
- Choisir entre des patrons architecturaux (monolithe vs microservices, REST vs GraphQL)
- Décider d'une stratégie d'authentification/autorisation
- Sélectionner une infrastructure de déploiement après avoir évalué des alternatives
Ce qui Fait un Bon ADR
À Faire
- Soyez spécifique — "Utiliser Prisma ORM" pas "utiliser un ORM"
- Enregistrez le pourquoi — la justification compte plus que le quoi
- Incluez les alternatives rejetées — les développeurs futurs ont besoin de savoir ce qui a été envisagé
- Énoncez les conséquences honnêtement — chaque décision a des compromis
- Restez court — un ADR doit pouvoir être lu en 2 minutes
- Utilisez le présent — "Nous utilisons X" pas "Nous utiliserons X"
À Ne Pas Faire
- Enregistrer des décisions triviales — les choix de nommage de variables ou de formatage ne nécessitent pas d'ADR
- Écrire des dissertations — si la section contexte dépasse 10 lignes, c'est trop long
- Omettre les alternatives — "nous venons de choisir" n'est pas une justification valide
- Compléter rétroactivement sans le marquer — si vous enregistrez une décision passée, notez la date d'origine
- Laisser les ADRs devenir obsolètes — les décisions remplacées doivent référencer leur remplacement
Cycle de Vie d'un ADR
proposé → accepté → [déprécié | remplacé par ADR-NNNN]
- proposé : la décision est en discussion, pas encore engagée
- accepté : la décision est en vigueur et suivie
- déprécié : la décision n'est plus pertinente (ex. fonctionnalité supprimée)
- remplacé : un ADR plus récent remplace celui-ci (toujours lier le remplacement)
Catégories de Décisions Valant la Peine d'Être Enregistrées
| Catégorie | Exemples |
|---|---|
| Choix technologiques | Framework, langage, base de données, fournisseur cloud |
| Patrons architecturaux | Monolithe vs microservices, événementiel, CQRS |
| Conception d'API | REST vs GraphQL, stratégie de versionnement, mécanisme d'authentification |
| Modélisation des données | Conception de schéma, décisions de normalisation, stratégie de cache |
| Infrastructure | Modèle de déploiement, pipeline CI/CD, stack de surveillance |
| Sécurité | Stratégie d'authentification, approche de chiffrement, gestion des secrets |
| Tests | Framework de test, objectifs de couverture, équilibre E2E vs intégration |
| Processus | Stratégie de branchement, processus de révision, cadence de livraison |
Intégration avec d'Autres Compétences
- Agent planificateur : lorsque le planificateur propose des changements d'architecture, suggérez de créer un ADR
- Agent de révision de code : signalez les PR qui introduisent des changements architecturaux sans ADR correspondant