enregistrements-de-decisions-architecturales

Architecture Decision Records (Enregistrements de Décisions Architecturales)

Capturez les décisions architecturales au fur et à mesure qu'elles se produisent pendant les sessions de codage. Au lieu que les décisions ne vivent que dans des fils Slack, des commentaires de PR ou la mémoire de quelqu'un, ce skill 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 « on fait un ADR de ça »
• 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 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** : proposed | accepted | deprecated | superseded by ADR-NNNN
**Décideurs** : [qui était impliqué]

## Contexte

Quel est le problème que nous observons 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 mettons en œuvre ?

[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 mesure d'atténuation]

Workflow

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 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 — extraire le choix architectural central en cours
3. Recueillir le contexte — quel problème a déclenché cela ? Quelles sont les contraintes ?
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 — scanner les ADR existants dans docs/adr/ et incrémenter
7. Confirmer et écrire — présenter le brouillon d'ADR à l'utilisateur pour révision. N'écrire dans docs/adr/NNNN-titre-de-la-decision.md qu'après approbation explicite. Si l'utilisateur refuse, jeter le brouillon sans écrire aucun fichier.
8. Mettre à jour l'index — ajouter à docs/adr/README.md

Lire les ADR Existants

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

1. Vérifier si docs/adr/ existe — si non, répondre : « Aucun ADR trouvé dans ce projet. Souhaitez-vous commencer à enregistrer les décisions architecturales ? »
2. S'il existe, scanner l'index docs/adr/README.md pour les entrées pertinentes
3. Lire les fichiers ADR correspondants et présenter les sections Contexte et Décision
4. 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 ADR
    ├── 0001-utiliser-nextjs.md
    ├── 0002-postgres-plutot-que-mongo.md
    ├── 0003-rest-plutot-que-graphql.md
    └── template.md            ← modèle vierge pour utilisation manuelle

Format d'Index ADR

# Architecture Decision Records

| ADR | Titre | Statut | Date |
|-----|-------|--------|------|
| [0001](0001-utiliser-nextjs.md) | Utiliser Next.js comme framework frontend | accepted | 2026-01-15 |
| [0002](0002-postgres-plutot-que-mongo.md) | PostgreSQL plutôt que MongoDB pour le stockage principal | accepted | 2026-01-20 |
| [0003](0003-rest-plutot-que-graphql.md) | API REST plutôt que GraphQL | accepted | 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

• « On part sur X »
• « On devrait utiliser X plutôt que Y »
• « Le compromis en vaut la peine parce que... »
• « Enregistre ça comme un ADR »

Signaux implicites (suggérer d'enregistrer un ADR — ne pas créer automatiquement sans confirmation utilisateur)

• Comparer deux frameworks ou bibliothèques et arriver à 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 être lisible 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 essais — si la section contexte dépasse 10 lignes, c'est trop long
• Omettre les alternatives — « on a juste choisi ça » n'est pas une justification valable
• Remplir rétroactivement sans le marquer — si vous enregistrez une décision passée, notez la date d'origine
• Laisser les ADR devenir obsolètes — les décisions remplacées doivent référencer leur remplacement

Cycle de Vie d'un ADR

proposed → accepted → [deprecated | superseded by ADR-NNNN]

• proposed : la décision est en cours de discussion, pas encore engagée
• accepted : la décision est en vigueur et est suivie
• deprecated : la décision n'est plus pertinente (ex. fonctionnalité supprimée)
• superseded : un nouvel ADR remplace celui-ci (toujours lier le remplacement)

Catégories de Décisions à Enregistrer

Catégorie	Exemples
Choix technologiques	Framework, langage, base de données, fournisseur cloud
Patrons d'architecture	Monolithe vs microservices, événementiel, CQRS
Conception d'API	REST vs GraphQL, stratégie de versionnement, mécanisme d'auth
Modélisation de 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 monitoring
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 relecture, cadence de livraison

Intégration avec d'Autres Skills

• Agent planificateur : lorsque le planificateur propose des changements d'architecture, suggérez la création d'un ADR
• Agent relecteur de code : signalez les PR qui introduisent des changements architecturaux sans ADR correspondant