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)
Use as Template
#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)

🧠 Why This Works

Technical decisions lose context over time—future developers wonder 'why was this done this way?' ADRs capture the reasoning, alternatives considered, and trade-offs at decision time, creating institutional memory that outlasts any team member.

📅 When to Use This Prompt

Use when making significant technical decisions (choosing a database, adopting a framework, changing architecture), when you need to document why you rejected alternatives, or when building a decision log for your engineering team.

🎯 What You'll Get

You'll receive a structured ADR document with context, decision, alternatives evaluated with pros/cons, consequences, and status—formatted to fit into your existing documentation system and easy for future engineers to find and understand.

🔗 Related Prompts

Coding & DevelopmentPremium

System Design Interview Simulator

Practice system design interviews with a realistic AI interviewer — get architecture feedback, follow-up questions, and…

system-designinterviewarchitecture
★4.9
advanced
Coding & DevelopmentPremium

Technical Documentation Writer

Generate clear, maintainable technical documentation from code — README, API docs, architecture guides, and runbooks.

codingdevelopmenttechnical
★4.7
intermediate