📋 ADR (Architecture Decision Records)

Formalize a rigorous ADR in 30-60 minutes for each architectural choice that would take 2-3 hours to write from scratch.

ADRs (Architecture Decision Records) document architectural choices: why PostgreSQL over MongoDB, why Kafka over RabbitMQ, why this authentication pattern. Well written, they save years of "why did we choose that again?" and facilitate onboarding. AI enables you to produce them quickly with rigor. This guide presents the workflow.

Step-by-step Workflow
1
Describe the decision context

What problem we're solving, what constraints (performance, team, budget, time-to-market), what options were considered, who decides and who is impacted.

2
List the considered options

At least 3 serious options with their characteristics. AI helps structure (don't forget the obvious or invent unrealistic ones).

3
Compare on relevant criteria

Criteria depending on context: performance, scalability, learning curve, ecosystem, cost, maturity, lock-in. Score each option.

4
Decide and document the why

Decision chosen + clear reasons. Especially: positive AND negative consequences, success conditions, signals that would justify revisiting.

5
Version in the repo

Markdown format in /docs/adr/. Numbered and dated. Remains consultable long after the protagonists have left the team.

Copyable Prompts
Complete ADR on a technical choice
You are a senior software architect. Formalize an ADR for this decision:nn**Context**: [PROBLEM TO SOLVE]n**Constraints**: [PERF, TEAM, BUDGET, TIMING]n**Options considered**: [LIST 3-5 OPTIONS]n**Decision chosen**: [CHOSEN OPTION]n**Current stack**: [TECH CONTEXT]nnProduce an ADR in Michael Nygard format:nn## Statusn[Proposed / Accepted / Deprecated / Superseded by X]nn## Contextn[3-5 paragraphs: problem, constraints, what triggered the reflection]nn## Options Consideredn### Option 1: [NAME]n- Prosn- Consn- Costs (learning, debt, infrastructure)nn### Option 2: [NAME]n[same]nn## Decisionn[Option chosen + clear reasons]nn## Consequencesn### Positiven[3-5 expected positive consequences]nn### Negativen[2-4 negative consequences or accepted tradeoffs]nn## Conditions to Revisitn[Signals that would justify re-questioning this decision in 12-24 months]nnMark [TO VERIFY] any uncertain numbers (performance, costs).
Multi-criteria technology comparison
For this choice: [TYPE OF TECH — e.g., message broker, database, frontend framework]nn**Context**: [DETAILS]n**Constraints**: [LIST]nnCompare these options on key criteria:nn[OPTION 1] vs [OPTION 2] vs [OPTION 3]nnCriteria:n1. **Performance** (latency, throughput, resources)n2. **Scalability** (horizontal, vertical, limits)n3. **Maturity and ecosystem** (stable versions, community, documentation)n4. **Learning curve** (current team, hiring)n5. **Lock-in and portability**n6. **Total cost** (licensing, infrastructure, operations)n7. **Security and compliance**nnFormat: comparative table with /10 scoring per criterion, then reasoned recommendation.
Audit of an existing ADR
Audit this ADR:nn[ADR]nnProduce:n1. **Strengths**: what's done well (rigor, clarity, completeness)n2. **Weaknesses**: what's missing (missing options, underestimated negative consequences, no plan B)n3. **Necessary updates**: given the evolution since writing, what has changed in the technical landscapen4. **Recommendation**: ADR still valid / needs updating / should be reconsiderednnStay constructive and factual.
Recommended tools
Claude Opus 4.5
Claude Opus 4.5
★ 4.9 (92) · 20 USD/mois

Claude Opus 4.5 : modèle premium d’Anthropic pour code, agents et tâches complexes en entreprise.

Why : Le meilleur reasoning sur les choix techniques complexes nécessitant la pesée multi-critères et l'anticipation des conséquences.

Claude AI
Claude AI
★ 4.9 (55) · Gratuit

Assistant conversationnel d’Anthropic axé sécurité et contexte long. Excellent pour rédaction, analyse, résumés, code et agents. Interface claire, bons résultats en français.

Why : Excellence sur la rédaction structurée et rigoureuse des ADR. Format Michael Nygard ou variante au choix.

Perplexity AI
Perplexity AI
★ 4.9 (211) · 20 USD/mois

Assistant de recherche IA qui fournit des réponses sourcées et vérifiables en temps réel.

Why : Pour benchmarker en temps réel avec sources fraîches (versions actuelles, retours d'expérience, comparaisons à jour).

Estimated ROI
Time Saved
70% on writing (30-60 min vs 2-3h)
Quality Gain
Consistently rigorous ADRs, negative consequences made explicit
Cost
€20-30/month
← Back to guide Architecte logiciel
This site is registered on wpml.org as a development site. Switch to a production site key to remove this banner.