Pourquoi cette décision a été prise ? Qui l’a validée ? La documentation ne le dit pas… ou elle est obsolète. Les ADR et RFC résolvent ce problème de façon élégante.

Le problème : Documentation morte

Symptômes classiques

# README.md (last updated: 2 years ago)
## Architecture

We use microservices...

// Mais personne ne sait :
// - Pourquoi microservices ?
// - Quelles alternatives ont été considérées ?
// - Qui a décidé ?

Résultat :

  • Décisions refaites plusieurs fois
  • Contexte perdu
  • Nouveaux arrivants perdus

ADR : Architecture Decision Records

Qu’est-ce qu’un ADR ?

Document léger qui capture UNE décision d’architecture.

Structure :

# ADR-001 : Choix de la base de données

## Status
Accepted

## Context
Nous avons besoin de stocker des données utilisateur avec 
des relations complexes. Le volume attendu est de 100k users.

## Decision
Nous utiliserons PostgreSQL comme base de données principale.

## Consequences

### Positive
- ACID garanti
- Relations SQL naturelles
- Écosystème mature

### Negative
- Scaling vertical principalement
- Pas optimal pour time-series data

Template ADR

# ADR-XXX : [Titre court de la décision]

Date: YYYY-MM-DD
Status: [Proposed | Accepted | Deprecated | Superseded]
Deciders: [@alice, @bob]

## Context
[Quel problème essayons-nous de résoudre ?]
[Quelles sont les contraintes ?]

## Decision
[Quelle solution avons-nous choisi ?]

## Alternatives Considered
### Option A
- Pros: ...
- Cons: ...

### Option B  
- Pros: ...
- Cons: ...

## Consequences
### Positive
- ...

### Negative
- ...

### Risks
- ...

Exemples ADR réels

ADR-003 : Migration vers Microservices

# ADR-003 : Migration vers architecture microservices

Date: 2025-03-15
Status: Accepted
Deciders: [@john-cto, @alice-arch, @bob-lead]

## Context

Notre monolithe actuel (250k LOC) pose problèmes :
- Déploiements lents (45min)
- Scaling impossible par composant
- 3 équipes bloquées mutuellement

## Decision

Migration progressive vers microservices sur 18 mois.

Phase 1 : Extraire service "Payments" (forte isolation)
Phase 2 : Extraire service "Notifications"
Phase 3 : Évaluer résultats avant suite

## Alternatives Considered

### Modular Monolith
Pros: Moins complexe, pas de réseau
Cons: Pas de scaling indépendant, deploy groupé

### Serverless Functions
Pros: Auto-scaling, pas d'infra
Cons: Cold starts, coûts imprévisibles

## Consequences

### Positive
- Deploy indépendant par service
- Scaling granulaire
- Équipes autonomes

### Negative
- Complexité réseau
- Distributed tracing requis
- Coût infra +30%

### Risks
- Over-engineering si mal fait
- Latency network overhead
- Debugging complexe

## Mitigation
- Commencer petit (1 service)
- Mesurer avant/après
- Pas de Big Bang rewrite

ADR-012 : Choix framework frontend

# ADR-012 : React pour le nouveau dashboard

Date: 2025-08-01
Status: Accepted
Deciders: [@frontend-team]

## Context

Refonte dashboard analytics. Critères :
- Performance (60 FPS sur graphiques)
- Écosystème de composants
- Compétences équipe existantes

## Decision

React 18 avec TypeScript.

## Alternatives Considered

### Vue 3
Pros: Plus simple, Composition API
Cons: Moins de libs graphiques

### Svelte
Pros: Performance incroyable, bundle petit
Cons: Écosystème limité, équipe à former

## Consequences

### Positive
- Recharts pour graphiques
- shadcn/ui pour composants
- Équipe déjà compétente

### Negative
- Bundle size plus gros que Svelte
- Virtual DOM overhead

## Implementation
- Setup: 1 semaine
- Migration progressive
- Coexistence avec Angular legacy

RFC : Request for Comments

Différence ADR vs RFC

ADR :

  • Décision déjà prise
  • Document court
  • Archive historique

RFC :

  • Proposition en discussion
  • Document détaillé
  • Processus de validation

Template RFC

# RFC-XXX : [Titre de la proposition]

Author: @alice
Date: YYYY-MM-DD
Status: Draft | Review | Accepted | Rejected

## Summary
[1 paragraphe : Qu'est-ce qu'on propose ?]

## Motivation
[Pourquoi faire ce changement ?]
[Quel problème ça résout ?]

## Detailed Design
[Comment exactement on va faire ?]
[Diagrammes, code examples]

## Drawbacks
[Quels sont les inconvénients ?]

## Alternatives
[Quelles autres solutions possibles ?]

## Open Questions
[Points à clarifier]

## Timeline
- Week 1: ...
- Week 2: ...

Exemple RFC réel

# RFC-005 : Rate Limiting API

Author: @bob-backend
Date: 2025-09-15
Status: Review

## Summary

Implémenter rate limiting sur l'API publique pour éviter
l'abuse et garantir QoS.

## Motivation

### Problèmes actuels
- 1 client abuse l'API (1M req/day vs 10k normal)
- Coût infra +$2k/mois à cause de cet abus
- Autres clients impactés (latency)

### Objectifs
- Limiter abus
- Fair usage entre clients
- Protéger infra

## Detailed Design

### Approach: Token Bucket

```typescript
interface RateLimitConfig {
  maxTokens: number;      // 1000 requests
  refillRate: number;     // 100 req/min
  burstSize: number;      // 200 req burst
}

class RateLimiter {
  async checkLimit(clientId: string): Promise<boolean> {
    const tokens = await redis.get(`ratelimit:${clientId}`);
    if (tokens < 1) {
      return false;  // Limite atteinte
    }
    await redis.decr(`ratelimit:${clientId}`);
    return true;
  }
}

Limits par tier

Free:
  requests_per_minute: 100
  burst: 200

Pro:
  requests_per_minute: 1000
  burst: 2000

Enterprise:
  requests_per_minute: 10000
  burst: 20000

Response headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640000000

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000120
Retry-After: 120

Drawbacks

  • Complexité : Redis requis
  • Overhead : 1-2ms par requête
  • Faux positifs possibles (burst légitime)

Alternatives

Alternative 1: API Gateway (Kong)

Pros: Feature built-in, battle-tested Cons: +$500/mois, nouvelle infra

Alternative 2: CloudFlare rate limiting

Pros: Zero code, CDN level Cons: Moins flexible, coût variable

Open Questions

  1. Comment gérer webhooks ? (exemptés de rate limit ?)
  2. Grace period pour clients existants ?
  3. Alerting si client atteint limite ?

Timeline

  • Week 1: Implement Redis-based limiter
  • Week 2: Add monitoring & alerts
  • Week 3: Deploy to staging
  • Week 4: Gradual rollout (10% → 100%)

Success Metrics

  • Abuse incidents : -100%
  • API cost : -30%
  • P95 latency : No regression

## Processus de décision avec RFC

### Phase 1 : Draft (1-3 jours)

Author écrit RFC → Partage en review avec 2-3 pairs → Itère sur feedback initial


### Phase 2 : Review (1 semaine)

RFC posté dans Slack #architecture → Équipes concernées commentent → Author répond aux questions → Open Questions résolues


### Phase 3 : Decision Meeting (1h)

Meeting avec stakeholders → Présentation RFC (15min) → Discussion (30min) → Décision (Accept/Reject/Revise)


### Phase 4 : Accepted → ADR

RFC Accepted → Créer ADR correspondant → Implementer selon timeline → Update ADR si déviation


## Où stocker ADR et RFC ?

### Option 1 : Repo Git (recommandé)

repo/ ├── docs/ │ ├── adr/ │ │ ├── 001-use-postgresql.md │ │ ├── 002-adopt-graphql.md │ │ └── 003-microservices.md │ └── rfc/ │ ├── 001-rate-limiting.md │ ├── 002-caching-strategy.md │ └── 003-multi-region.md


**Avantages :**
- Versionné avec le code
- Pull requests pour review
- Historique Git complet

### Option 2 : Confluence/Notion

**Avantages :**
- Interface riche
- Commentaires inline
- Accessibles non-devs

**Inconvénients :**
- Pas versionné
- Peut devenir obsolète

### Option 3 : Hybrid

Git : ADR (archives) Confluence : RFC (en cours de discussion)

RFC Accepted → ADR dans Git


## Outils

### adr-tools

```bash
# Installer
npm install -g adr-tools

# Init
adr init docs/adr

# Nouveau ADR
adr new "Use PostgreSQL for main database"

# Génère docs/adr/0001-use-postgresql-for-main-database.md

Docusaurus / MkDocs

# Site de documentation avec ADR/RFC
mkdocs new architecture-docs

# Structure
docs/
├── index.md
├── adr/
│   └── 001-postgresql.md
└── rfc/
    └── 001-rate-limiting.md

# Build
mkdocs serve  # http://localhost:8000

Métriques de succès

Adoption mesurée

Avant ADR/RFC :

  • Décisions documentées : 10%
  • “Pourquoi ?” répondu : Rarement
  • Onboarding nouveau : 2 semaines

Après ADR/RFC :

  • Décisions documentées : 95%
  • “Pourquoi ?” dans ADR : Toujours
  • Onboarding nouveau : 3 jours

Qualité décisions

Nombre de fois où on re-fait une décision :
Avant : 4/an
Après : 0/an

Décisions basées sur data (vs opinion) :
Avant : 30%
Après : 85%

Erreurs à éviter

Erreur 1 : ADR trop longs

❌ ADR-001 : Use PostgreSQL (50 pages)

✅ ADR-001 : Use PostgreSQL (2 pages)
   + Link vers RFC-001 pour détails

Erreur 2 : Pas d’ownership

❌ Deciders: [Team]

✅ Deciders: [@alice-tech-lead, @bob-cto]

Erreur 3 : Modifier ancien ADR

❌ Éditer ADR-003 pour changer décision

✅ Créer ADR-015 qui supersede ADR-003

ADR = immutable history.

Erreur 4 : RFC sans deadline

❌ Status: Draft (depuis 6 mois)

✅ Deadline: 2025-10-20
   Si pas de décision → Auto-reject

Conclusion

ADR et RFC transforment la documentation :

Documentation traditionnelle :

  • Obsolète dès écrite
  • Contexte perdu
  • Décisions refaites

Avec ADR/RFC :

  • Toujours à jour (archives immutables)
  • Contexte préservé
  • Décisions traçables

Commencez aujourd’hui :

  1. Créer docs/adr/ dans votre repo
  2. Documenter votre dernière décision
  3. Établir process RFC pour prochaines

Simple, léger, impact énorme.

Et vous, comment documentez-vous vos décisions ?