Back to prompts
Coding & Developmentintermediate
0.0

Architecture Decision Record — Document Why, Not Just What

Stop forgetting why you made that technical decision 6 months ago. This prompt creates a complete ADR in 2 minutes.

Copy & Paste this prompt
You are a senior software architect who has maintained systems for 10+ years. You know that the most expensive technical debt is forgotten context — not bad code.

Create an Architecture Decision Record (ADR) for a technical decision I'm about to make (or already made).

The decision: [DESCRIBE THE TECHNICAL DECISION]
Context: [WHY IS THIS DECISION NEEDED NOW?]
Constraints: [TIMELINE, BUDGET, TEAM SIZE, EXISTING TECH STACK]
Stakeholders: [WHO CARES ABOUT THIS DECISION?]

Generate a complete ADR with:

1. TITLE — ADR-[NUMBER]: [Decision title in imperative mood]
2. STATUS — [Proposed / Accepted / Deprecated / Superseded]
3. CONTEXT — The forces at play, why we can't avoid this decision
4. DECISION — What we chose and a one-sentence summary a PM can understand
5. OPTIONS CONSIDERED — Minimum 3 alternatives with honest pros/cons for each:
   - Option A: [chosen] — Pros, Cons, Effort estimate
   - Option B: — Pros, Cons, Why rejected
   - Option C: — Pros, Cons, Why rejected
6. CONSEQUENCES — What changes? What becomes easier? What becomes harder?
7. RISKS — What could go wrong with this decision? Mitigation for each.
8. REVIEW DATE — When should we revisit this decision?
9. REVERSAL COST — How expensive is it to undo this decision? (Low/Medium/High/Irreversible)
#architecture#documentation#adr#technical-decisions

Works with

chatgptclaudecopilot

💡 Pro Tips

  • Write ADRs BEFORE implementing, not after
  • The 'Options Considered' section is the most valuable part for future you
  • Keep ADRs in your repo — they're as important as code

✨ Example Output

ADR-042: Use PostgreSQL Instead of MongoDB for User Data
STATUS: Accepted
CONTEXT: Our user data has strong relational patterns (users → orders → payments). MongoDB requires manual denormalization and consistency checks...
REVERSAL COST: HIGH — Data migration + ORM rewrite (~3 sprints)