ADR · Architecture Decision Record

---
name: adr-decision-architecture
description: "Rédige un ADR (Architecture Decision Record) structuré à partir d'une décision technique en cours. Sortie au format standard Michael Nygard : Context, Decision, Consequences, Alternatives considered, avec date, statut et identifiant numéroté. À utiliser quand un dev (tech lead, staff engineer, backend, frontend, DevOps, architecte SI) veut tracer une décision technique structurante (choix de DB, framework, pattern, déploiement) avant qu'elle ne soit oubliée 6 mois plus tard."
metadata:
  iaskills_title: "ADR · Architecture Decision Record"
  metier_slug: dev
  metiers:
    - Devs et tech leads
  secteur: "Tech & DSI"
  tier: free
  compatible:
    - claude-code
    - cowork
    - cursor
    - codex
  version: "1.0.0"
  author: "iaskills"
  editorial:
    pitch: "ADR au format Michael Nygard, structuré et daté. Context, Decision, Consequences, Alternatives considered. Tracé une fois, lisible 3 ans après."
    long_description: "Les décisions d'archi qui ne sont pas écrites finissent par être réinventées (mal) tous les 18 mois. ADR (Architecture Decision Record) répond à ça : un fichier Markdown court par décision, daté, numéroté, qui explique le contexte, ce qui a été décidé, les conséquences acceptées, et les alternatives écartées. Ce skill génère un ADR conforme au format Michael Nygard à partir d'une discussion technique en cours, d'un thread Slack, d'un compte-rendu de réunion d'archi, ou d'une simple description en langue naturelle. Il pose les questions manquantes (date d'effet, statut Proposed/Accepted/Deprecated/Superseded, owners, deadlines) et produit un fichier prêt à committer dans `docs/adr/`. Calibré pour les stacks FR (Vercel, Scaleway, OVH, Clever Cloud, Supabase) et les contextes startup ou DSI scale-up."
    bullets:
      - "Format Michael Nygard standard"
      - "Statut Proposed, Accepted, Deprecated, Superseded"
      - "Alternatives écartées tracées"
      - "Numérotation auto, prêt à committer"
      - "Compatible adr-tools et Markdown ADR"
    exemple_avant: "Le team lead pousse un commit qui passe Postgres à Supabase. Six mois plus tard, un nouveau dev veut savoir pourquoi Supabase plutôt qu'AWS RDS, fouille Slack 30 minutes, demande au CTO en DM, et ressort sans réponse claire. La décision se rejoue à chaque audit."
    exemple_apres: "Le skill produit `docs/adr/0023-passage-supabase.md` : contexte (besoin de RLS multi-tenant, pas d'équipe DBA), décision (Supabase Postgres EU eu-west-3), conséquences (lock-in modéré, latence acceptable), alternatives (Neon, RDS, Convex écartés avec raisons). Lisible en 90 secondes par le prochain dev."
    recommended_metiers:
      - dirigeant-pme
    secteurs:
      - tech-dsi
      - startup-vc
      - conseil-audit
      - finance-comptabilite
      - industrie-manufacture
      - assurance-banque
    metiers_individuels:
      - dev-backend
      - dev-frontend
      - devops
      - architecte-si
      - cto
      - chef-de-projet-it
      - mlops
      - product-manager
      - rssi-cybersecurite
    connecteurs:
      - notion
      - slack
      - drive
---

# ADR · Architecture Decision Record

## Quand utiliser ce skill

Déclencher quand un dev (tech lead, staff engineer, architecte SI, CTO, DevOps, backend, frontend) doit tracer une décision technique structurante qui aura un impact à 6 ou 18 mois. Cas typiques :

- Choix d'une base de données ou d'un BaaS (Supabase vs Neon vs RDS)
- Choix d'un framework ou d'un changement majeur (App Router Next, Remix, Svelte Kit)
- Changement de plateforme cloud (Vercel vs Railway vs OVH vs Scaleway)
- Adoption d'un pattern (event-sourcing, CQRS, repository, hexagonal)
- Choix d'un fournisseur LLM ou d'une stack agent (Anthropic vs OpenAI, Agent SDK vs LangGraph)
- Migration de version structurante (Next 14 → 15, Python 3.10 → 3.12, monorepo Nx → Turborepo)
- Décision d'archi sécu (SSO Auth0 vs Keycloak self-hosted, secret manager AWS vs Doppler)

Ne pas utiliser pour :

- Une simple PR de code (un commit message conventionnel suffit)
- Une décision réversible en moins d'une journée (changer un nom de variable env)
- Un choix de dépendance mineure (lodash vs ramda)
- Une discussion encore ouverte sans candidat clair (faire un RFC ou une note de cadrage avant)

## Ce que tu dois faire

### Étape 1, collecter le contexte de la décision

Demander à l'utilisateur, ou extraire d'un thread Slack ou d'un compte-rendu :

1. **Le problème ou le besoin produit** : pourquoi cette décision arrive maintenant. Forces en présence (deadline, contrainte sécu, performance, coûts, conformité RGPD).
2. **Le candidat retenu** : nom précis (techno, fournisseur, version), périmètre d'application.
3. **Les alternatives évaluées** : 2 à 4 options écartées avec un argument court par option.
4. **Les contraintes dures** : budget, hébergement EU obligatoire, certification (SOC 2, HDS, ISO 27001), licence open source compatible, équipe in-house ou externe.
5. **Le statut** : Proposed (en discussion), Accepted (validé), Deprecated (à abandonner), Superseded by ADR-XXXX (remplacé par un autre).
6. **Le numéro ADR** : lire `docs/adr/` ou demander à l'utilisateur. Convention : 4 chiffres + slug, ex `0023-passage-supabase.md`. Si pas connu, proposer le prochain dispo.
7. **La date d'effet** : date de la décision (ISO 8601, JJ-MM-AAAA dans le corps si plus lisible).
8. **Les owners** : qui porte la décision (un nom, pas une équipe abstraite). Optionnel mais recommandé.

### Étape 2, structurer l'ADR au format Michael Nygard

Sections obligatoires, dans cet ordre :

1. **Title** (H1) : `ADR-NNNN: <Titre court à l'impératif ou au substantif>`. Ex : `ADR-0023: Passer la persistance applicative sur Supabase Postgres`.
2. **Status** : Proposed, Accepted, Deprecated, ou `Superseded by ADR-NNNN`. Ligne courte.
3. **Date** : ISO 8601 (`2026-05-04`).
4. **Context** : 5 à 10 lignes. Pourquoi cette décision arrive, quelles forces en présence, quelles contraintes. Le lecteur doit comprendre la situation sans contexte externe.
5. **Decision** : 3 à 8 lignes. Ce qui est décidé concrètement, en une phrase principale, suivie des modalités d'application (périmètre, équipes concernées, calendrier).
6. **Consequences** : 4 à 10 lignes, en bullet list. Conséquences positives (ce qu'on gagne), négatives (ce qu'on accepte), et neutres (changements de processus, formations à prévoir).
7. **Alternatives considered** : 2 à 4 alternatives, une sous-section H3 par alternative. Pour chacune : 2 lignes de description, puis la raison du rejet en 1 phrase.

### Étape 3, ajouter les métadonnées et la traçabilité

À la fin du fichier, sous une ligne séparatrice `---` :

- **Owners** : noms des porteurs de la décision (optionnel).
- **References** : liens vers la PR initiale, le ticket Linear, le thread Slack, la doc fournisseur.
- **Supersedes** ou **Superseded by** : lien vers l'ADR remplacé ou qui remplace.

Si l'ADR remplace une décision antérieure, ouvrir l'ADR précédent pour passer son statut à `Superseded by ADR-NNNN` (signaler à l'utilisateur la double édition à faire).

### Étape 4, restituer le fichier

Bloc Markdown unique, prêt à coller dans `docs/adr/<NNNN>-<slug>.md`. Si l'utilisateur travaille avec [adr-tools](https://github.com/npryce/adr-tools), le format est compatible directement.

Stocker l'ADR dans Notion, Drive ou Slite si l'équipe ne versionne pas la doc dans le repo ; le format Markdown reste le même.