- Générateur ADR — Architecture Decision

Qu'est-ce qu'un ADR ?

Un Architecture Decision Record (ADR) est un document court et structuré qui capture une décision architecturale importante prise au cours d'un projet logiciel. Introduit par Michael Nygard en 2011, ce format permet de conserver la mémoire des choix techniques : pourquoi cette technologie, pourquoi ce pattern, pourquoi ce compromis.

Sans ADR, les décisions architecturales se perdent dans des conversations Slack, des réunions oubliées ou des têtes qui quittent l'équipe. Avec un ADR, n'importe quel développeur rejoignant le projet comprend immédiatement le contexte des choix passés.

Pourquoi documenter les décisions architecturales ?

• Mémoire collective — Les décisions survivent aux rotations d'équipe
• Onboarding accéléré — Un nouveau développeur comprend le "pourquoi" en lisant le ADR
• Éviter les discussions en boucle — "On a déjà évalué Redis, voici pourquoi on a choisi Kafka : ADR-007"
• Audit et conformité — Traçabilité des choix pour les équipes soumises à des audits techniques
• Réversibilité informée — Le statut "Déprécié" permet de signaler qu'une décision est obsolète

ADR vs autres formes de documentation

Structure d'un ADR

La structure proposée par ce générateur s'inspire du format MADR (Markdown Any Decision Records), une évolution du format original de Michael Nygard. Elle couvre les 6 sections essentielles d'une bonne décision documentée.

① Métadonnées (numéro, date, statut, participants)

Le numéro identifie l'ADR de façon unique (ADR-001, ADR-042…). Utilisez une séquence croissante par projet. Le statut évolue dans le temps :

• Proposé — En cours d'évaluation, pas encore validé
• Accepté — Décision retenue et appliquée
• Déprécié — Toujours en place mais plus recommandé
• Remplacé — Supplanté par un ADR plus récent (ex : "Remplacé par ADR-015")
• Rejeté — Option évaluée mais non retenue

② Contexte et problème

C'est la section la plus importante. Décrivez la situation qui a nécessité une décision : contraintes techniques, volume de données, contraintes d'équipe, exigences métier. Plus le contexte est précis, plus l'ADR sera utile dans 2 ans.

③ Décision prise

Soyez direct : "Nous avons choisi X" ou "Nous allons utiliser Y". Expliquez brièvement pourquoi cette option a été retenue parmi les alternatives. Inutile d'entrer dans les détails d'implémentation — c'est le rôle de la spec technique.

④ Conséquences (positives et négatives)

Une décision honnête documente les deux côtés. Les conséquences positives justifient le choix ; les conséquences négatives permettent de préparer les mitigations. Un ADR sans conséquences négatives est souvent incomplet.

⑤ Alternatives considérées

Listez les options évaluées et pourquoi elles ont été écartées. Cela évite de "ré-inventer la roue" lors de futures discussions : si quelqu'un propose MongoDB 3 ans plus tard, l'ADR montre déjà pourquoi cette option a été rejetée.

Exemple d'ADR complet (Markdown généré)

# ADR-003: Adoption de PostgreSQL comme base principale

## Métadonnées
| Champ | Valeur |
|-------|--------|
| **Date** | 2026-03-15 |
| **Statut** | Accepté |
| **Participants** | Alice (Lead Dev), Bob (Archi) |

## Contexte et problème
L'API reçoit 50 000 requêtes/jour. L'ORM génère des
requêtes N+1 qui dégradent les temps de réponse (p95 > 800ms).

## Décision
Utiliser PostgreSQL avec des requêtes SQL natives pour
les endpoints critiques, en complément de l'ORM.

## Conséquences
### ✅ Positives
- Performances améliorées de 40% (p95 → 180ms)
- Requêtes optimisées avec EXPLAIN ANALYZE

### ❌ Négatives / Risques
- Maintenance SQL plus complexe
- Couplage fort à PostgreSQL

## Alternatives considérées
- MongoDB — rejeté : schéma trop flexible pour nos relations
- MySQL — limitations sur les types JSON avancés

Cas d'usage concrets

Les ADR s'appliquent à tout projet logiciel, quelle que soit la stack ou la taille de l'équipe. Voici des exemples représentatifs par domaine.

Choix de base de données

Décision classique : PostgreSQL vs MySQL vs MongoDB. Un ADR précise les contraintes (volume, transactions, schéma) qui ont orienté le choix, et documente les limites acceptées (ex : couplage vendor).

Choix de framework frontend

React vs Angular vs Vue. L'ADR capture les critères évalués : taille de l'équipe, courbe d'apprentissage, écosystème, contraintes de performance sur mobile. En 2 ans, quand Angular 20 sortira, l'ADR justifiera (ou infirmera) le choix initial.

Stratégie de déploiement

• Monolith vs microservices (ADR classique pour les architectures distribuées)
• Docker + Kubernetes vs VMs classiques
• Hébergement cloud : AWS vs Azure vs GCP
• Stratégie CI/CD : GitHub Actions vs GitLab CI vs Jenkins

Gestion de l'authentification

JWT vs sessions côté serveur vs OAuth2 vs Keycloak. Un ADR sur l'auth documente les implications sécurité, la durée de vie des tokens, et les compromis stateless/stateful.

Décisions de sécurité

• Algorithme de hachage des mots de passe (bcrypt vs Argon2)
• Politique CORS et headers de sécurité
• Stratégie de rotation des secrets (Vault, AWS Secrets Manager)
• Niveau de chiffrement des données au repos

Gestion des erreurs et monitoring

Sentry vs Datadog vs solution maison. L'ADR justifie le budget, les fonctionnalités critiques (alerting, traces distribuées, dashboards) et l'intégration avec la stack existante.

Patterns architecturaux

Event sourcing vs state classique, CQRS, Saga pattern pour les transactions distribuées : ces décisions ont des impacts profonds et méritent un ADR documentant les trade-offs de complexité vs bénéfices opérationnels.

Bonnes pratiques

Écrire l'ADR au bon moment

L'idéal est d'écrire l'ADR au moment de la décision, pas 3 mois après. La mémoire sélective gomme les compromis douloureux. Un ADR rétrospectif perd souvent les nuances qui justifiaient le choix à l'époque.

• ✅ Écrire l'ADR pendant la phase d'évaluation (statut "Proposé")
• ✅ Mettre à jour le statut à "Accepté" après validation
• ❌ Ne pas attendre la fin de l'implémentation pour documenter

Garder les ADR courts

Un ADR de 10 lignes lu par toute l'équipe est infiniment plus utile qu'un document de 50 pages que personne ne lit. Visez ½ à 2 pages maximum. Si c'est plus long, c'est probablement une spec technique, pas un ADR.

Utiliser un dépôt dédié ou le repo du projet

Convention commune : placer les ADR dans un dossier docs/adr/ ou architecture/decisions/ à la racine du projet, versionnés avec le code source. Cela garantit que les ADR évoluent avec le projet et sont accessibles à tous les développeurs.

projet/
├── src/
├── docs/
│   └── adr/
│       ├── ADR-001-choix-base-de-donnees.md
│       ├── ADR-002-strategie-authentification.md
│       └── ADR-003-framework-frontend.md
└── README.md

Ne jamais modifier un ADR accepté — le déprécier

Lier les ADR entre eux

Les décisions architecturales ne sont pas isolées. ADR-007 (choix d'event sourcing) peut dépendre de ADR-003 (choix PostgreSQL) et influencer ADR-012 (stratégie de migration). Utilisez la section "Liens et références" pour tisser ces connexions.

Classement et numérotation

Intégrer les ADR en équipe

Un ADR isolé dans un coin est inutile. Sa valeur vient de son adoption collective. Voici comment déployer la pratique ADR dans une équipe de développement.

Outillage recommandé

• adr-tools (CLI bash) — adr new "Adoption de PostgreSQL" génère automatiquement un fichier numéroté avec le template
• Log4brains — Outil Node.js qui génère un site statique à partir de vos ADR Markdown, avec search et liens automatiques
• Architecture Decision Records dans Confluence — Templates natifs disponibles dans l'espace "Architecture"
• GitHub / GitLab — Pull Request = peer review de l'ADR avant acceptation

Processus de validation (workflow recommandé)

1. Rédaction — Un développeur crée l'ADR avec statut "Proposé"
2. Revue — PR/MR ouverte, l'équipe commente sur le contexte, les alternatives, les risques
3. Décision — En réunion ou async, statut mis à "Accepté" ou "Rejeté"
4. Merge — L'ADR accepté rejoint la branche principale
5. Maintenance — Lors de futures évolutions, mettre à jour les statuts

Script CLI pour créer un ADR automatiquement

#!/bin/bash
# Créer un nouvel ADR
# Usage: ./new-adr.sh "Titre de la décision"

ADR_DIR="docs/adr"
LAST_NUM=$(ls $ADR_DIR/ADR-*.md 2>/dev/null | wc -l)
NEXT_NUM=$(printf "%03d" $((LAST_NUM + 1)))
SLUG=$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')
FILENAME="$ADR_DIR/ADR-${NEXT_NUM}-${SLUG}.md"

cat > "$FILENAME" << EOF
# ADR-${NEXT_NUM}: $1

## Métadonnées
| Champ | Valeur |
|-------|--------|
| **Date** | $(date +%Y-%m-%d) |
| **Statut** | Proposé |

## Contexte et problème
[Décrivez le contexte...]

## Décision
[Décrivez la décision...]

## Conséquences
### ✅ Positives
-

### ❌ Négatives / Risques
-
EOF

echo "ADR créé : $FILENAME"

ADR dans les projets Angular / Node.js

Pour les projets Angular ou Node.js, ajoutez les ADR directement dans le repo :

ng new my-app
cd my-app
mkdir -p docs/adr
# Utilisez ce générateur pour créer vos premiers ADR
# Copiez le Markdown dans docs/adr/ADR-001-*.md

Questions fréquentes

Faut-il un ADR pour chaque décision technique ?

Non. Réservez les ADR aux décisions qui engagent l'équipe sur 6 mois ou plus, qui sont difficiles à inverser, ou qui impliquent des compromis significatifs. Le choix d'une variable de nommage ne mérite pas un ADR ; le choix de passer à une architecture event-driven, oui.

Que faire si la décision est mauvaise a posteriori ?

C'est l'une des situations où les ADR brillent. Créez un nouvel ADR qui analyse pourquoi la décision initiale n'a pas fonctionné, documente le nouveau contexte, et propose la direction révisée. Mettez l'ancien ADR en statut "Remplacé par ADR-XXX". La honte n'a pas sa place ici — tout le monde prend de mauvaises décisions avec le contexte disponible.

Peut-on utiliser un format différent de Markdown ?

Oui. Confluence, Notion, Google Docs — l'outil importe moins que la pratique. Cependant, Markdown versionnée avec le code est la convention la plus répandue car elle garantit que les ADR évoluent avec la codebase et sont reviewés via les mêmes outils (GitHub, GitLab).

Quelle différence entre ADR-001 et MADR ?

Le format original de Michael Nygard (2011) est minimaliste : titre, contexte, décision, conséquences. MADR (Markdown Any Decision Records) est une évolution avec plus de sections optionnelles (alternatives, pros/cons structurés). Ce générateur utilise un format hybride, inspiré des deux approches, optimisé pour la lisibilité.