Registres de Décisions Architecturales (ADR)

Que fait Registres 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 fils 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 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 ADR existants)
• Pendant les phases de planification où des 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ée | acceptée | dépréciée | remplacée par ADR-NNNN
**Décideurs** : [qui était impliqué]

## Contexte

Quel est le problème que nous observons 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 effectuons ?

[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 pour laquelle elle a été rejetée]

### Alternative 2 : [Nom]
- **Avantages** : [bénéfices]
- **Inconvénients** : [inconvénients]
- **Pourquoi pas** : [raison spécifique pour laquelle elle a été rejetée]

## 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é :

1. Initialiser (première fois uniquement) — si docs/adr/ n'existe pas, demandez la confirmation de l'utilisateur avant de créer le répertoire, un README.md amorcé avec l'en-tête du tableau d'index (voir le format d'index ADR ci-dessous), et un template.md vierge pour une utilisation manuelle. Ne créez pas de fichiers sans consentement explicite.
2. Identifier la décision — extrayez le choix architectural principal en cours
3. Recueillir le contexte — quel problème a motivé cela ? Quelles contraintes existent ?
4. Documenter les alternatives — quelles autres options ont été envisagées ? Pourquoi ont-elles été rejetées ?
5. Énoncer les conséquences — quels sont les compromis ? Qu'est-ce qui devient plus facile/plus difficile ?
6. Attribuer un numéro — analysez les ADR existants dans docs/adr/ et incrémentez
7. Confirmer et écrire — présentez le brouillon d'ADR à l'utilisateur pour révision. Écrivez dans docs/adr/NNNN-decision-title.md uniquement après approbation explicite. Si l'utilisateur refuse, jetez le brouillon sans écrire de fichiers.
8. Mettre à jour l'index — ajoutez à docs/adr/README.md

Lire les ADR Existants

Lorsqu'un utilisateur demande "pourquoi avons-nous choisi X ?" :

1. Vérifiez si docs/adr/ existe — si non, répondez : "Aucun ADR trouvé dans ce projet. Souhaitez-vous commencer à enregistrer des décisions architecturales ?"
2. S'il existe, analysez l'index docs/adr/README.md pour les entrées pertinentes
3. Lisez les fichiers ADR correspondants et présentez les sections Contexte et Décision
4. Si aucune correspondance n'est trouvée, répondez : "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 ADR
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← modèle vierge pour utilisation manuelle

Format de l'Index ADR

# Registres de Décisions Architecturales

| ADR | Titre | Statut | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Utiliser Next.js comme framework frontend | acceptée | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL plutôt que MongoDB pour le stockage principal | acceptée | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | API REST plutôt que GraphQL | acceptée | 2026-02-01 |

Signaux de Détection de Décision

Surveillez ces motifs 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 comme un ADR"

Signaux implicites (suggérez d'enregistrer un ADR — ne créez pas automatiquement sans confirmation de l'utilisateur)

• Comparer deux frameworks ou bibliothèques et parvenir à une conclusion
• Faire un choix de conception de schéma de base de données avec une justification énoncée
• Choisir entre des motifs 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 importe plus que le quoi
• Incluez les alternatives rejetées — les futurs développeurs doivent savoir ce qui a été envisagé
• Énoncez honnêtement les conséquences — 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

• N'enregistrez pas les décisions triviales — le nommage des variables ou les choix de formatage ne nécessitent pas d'ADR
• N'écrivez pas des essais — si la section contexte dépasse 10 lignes, c'est trop long
• N'omettez pas les alternatives — "nous l'avons juste choisi" n'est pas une justification valable
• Ne comblez pas les lacunes sans le marquer — si vous enregistrez une décision passée, notez la date d'origine
• Ne laissez pas les ADR devenir obsolètes — les décisions remplacées doivent référencer leur remplacement

Cycle de Vie d'un ADR

proposée → acceptée → [dépréciée | remplacée par ADR-NNNN]

• proposée : la décision est en cours de discussion, pas encore engagée
• acceptée : la décision est en vigueur et suivie
• dépréciée : la décision n'est plus pertinente (par exemple, fonctionnalité supprimée)
• remplacée : un ADR plus récent remplace celui-ci (toujours lier le remplacement)

Catégories de Décisions Qui Méritent d'Être Enregistrées

Catégorie	Exemples
Choix technologiques	Framework, langage, base de données, fournisseur cloud
Motifs architecturaux	Monolithe vs microservices, événementiel, CQRS
Conception API	REST vs GraphQL, stratégie de versionnement, mécanisme d'auth
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, pile de surveillance
Sécurité	Stratégie d'auth, 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 publication

Intégration avec d'Autres Compétences

• Agent planificateur : lorsque le planificateur propose des modifications architecturales, suggérez de créer un ADR
• Agent relecteur de code : signalez les PR qui introduisent des changements architecturaux sans ADR correspondant