/
DE

⚡ Promptolis Original · Coding & Development

📜 Architecture Decision Record Writer

Writes the ADR (Architecture Decision Record) that future engineers actually read: the context, the alternatives, the trade-offs, and the explicit consequences — instead of '~ this seemed good ~' wiki notes.

⏱️ 3 min to set up 🤖 ~70 seconds in Claude 🗓️ Updated 2026-04-28

Why this is epic

ADRs prevent the 'why did we do it this way?' confusion 18 months later. Most teams either don't write them or write 1-paragraph stubs nobody references. This Original writes the ADR that actually answers future questions.

Outputs the complete ADR: title, status, context, decision, alternatives considered with explicit trade-offs, consequences (positive + negative + risks), and the date/author. Calibrated to YOUR specific decision, not a generic template.

Includes the 'when this might need revisiting' section — critical because most ADRs go stale silently. Naming the conditions for re-evaluation makes them living documents.

Calibrated to 2026 ADR practices: stored in the repo (not Notion/wiki), Markdown format, sequential numbering, supersedes-replaces-deprecates relationships.

The prompt

Promptolis Original · Copy-ready
<role> You are an architecture documenter with 6+ years writing ADRs for engineering teams across SaaS, infra, OSS. You have written 100+ ADRs and reviewed 500+. You know which ADRs get referenced years later vs which gather dust. You are direct. You will tell a writer their decision section doesn't actually decide anything, that they're missing the alternative they obviously considered but didn't list, or that the consequences section is too rosy. You refuse to recommend ADRs for trivial decisions (use code reviews instead). </role> <principles> 1. ADRs answer WHY, not WHAT. 2. Always list alternatives + trade-offs. 3. Be honest about negative consequences. 4. Date + author + sequential number. 5. Status field tracks life cycle. 6. Store in repo, not wiki. 7. Reversals = new ADR superseding old. Never edit history. </principles> <input> <decision-being-made>{the architectural choice — e.g., 'Switch from Postgres to MongoDB for X service'}</decision-being-made> <context>{what's prompting this decision — current pain, scaling, new requirements}</context> <alternatives-considered>{the 2-4 options you evaluated}</alternatives-considered> <chosen-option>{which alternative + brief reason}</chosen-option> <trade-offs>{what you're explicitly accepting as downsides}</trade-offs> <reversibility>{easy / hard / one-way door}</reversibility> <author>{name + role}</author> <adr-number>{the next sequential number — e.g., ADR-0023}</adr-number> <scope>{single team / multiple teams / company-wide}</scope> <related-decisions>{prior ADRs this builds on or affects}</related-decisions> </input> <output-format> # ADR-NNNN: [Title — verb-led, decision-focused] ## Status Proposed | Accepted | Deprecated | Superseded by ADR-XXX | Replaces ADR-XXX ## Date [Date] — written by [Author], [Role] ## Context 2-4 paragraphs. The situation that's prompting this decision. Constraints, scale, pain points. What changed that requires a decision. ## Decision Clear statement of what was decided. 1-2 sentences. The 'we will do X' line. ## Alternatives Considered For each alternative (3-5 of them): - Brief description - Pros - Cons - Why not chosen ## Consequences ### Positive What this enables. Be specific. ### Negative What this costs. The trade-offs you knowingly accept. ### Risks Things that could make this decision wrong. What to watch for. ## Reversibility How hard is it to undo? Easy, hard, or one-way door. If hard: what would migration cost. ## When to Revisit The specific conditions that should trigger re-evaluation of this decision. ## Related ADRs Links to prior ADRs this depends on, supersedes, or affects. ## Scope Which teams/services this affects. ## Notes (optional) Additional context, references to external articles, internal docs. </output-format> <auto-intake> If input incomplete: ask for decision being made, context, alternatives considered, chosen option, trade-offs, reversibility, author, ADR number, scope, related decisions. </auto-intake> Now, write the ADR:
🚀 Open in ChatGPT ✨ Open in Claude 💎 Open in Gemini

Example: input → output

Here's how this prompt actually performs. Real input below, real output from Claude Opus 4.

📝 Input
<decision-being-made>Replace our self-hosted Postgres on EC2 with AWS RDS Postgres. Migration plan is documented separately; this ADR captures the architectural decision.</decision-being-made>
<context>Current state: Postgres 14 on a single EC2 instance, 600GB data, ~12K queries/sec peak. Manual backups via pg_dump. Manual upgrades. We've had 2 outages from disk-fill issues + 1 from a failed manual upgrade. Compliance audit upcoming Q3 requires automated backups + auto-recovery. Team capacity for DBA work is limited (0 dedicated DBA).</context>
<alternatives-considered>(1) Stay on EC2, hire dedicated DBA. (2) AWS RDS Postgres Multi-AZ. (3) Aurora Postgres. (4) Self-host on Kubernetes with operator (Cloud Native Postgres / Crunchy).</alternatives-considered>
<chosen-option>AWS RDS Postgres Multi-AZ. Best balance of operational ease + cost + compliance fit for our scale.</chosen-option>
<trade-offs>Higher monthly cost (~2x EC2 self-hosted). AWS lock-in (harder to migrate to GCP/other later). Less control over Postgres minor versions (auto-upgrades within Postgres 16). Some Postgres extensions not supported on RDS.</trade-offs>
<reversibility>Hard but possible. Rolling back to self-hosted requires 8+ weeks of work + downtime risk. Switching to a different cloud's managed Postgres is similarly hard.</reversibility>
<author>Sarah Chen, Tech Lead</author>
<adr-number>ADR-0023</adr-number>
<scope>All backend services that connect to our primary database (15 services).</scope>
<related-decisions>ADR-0008 (chose Postgres in 2023) — still valid. ADR-0015 (chose AWS as primary cloud) — relevant constraint.</related-decisions>
🤖 Output

ADR-0023: Migrate Primary Database from Self-Hosted Postgres to AWS RDS Multi-AZ

Status

Accepted

Date

2026-04-28 — written by Sarah Chen, Tech Lead

Context

Our primary Postgres database has been running on a single EC2 instance since the company's founding (~3 years). Initial choice (ADR-0008) made sense at small scale: low cost, full control, simple ops. We've now scaled past that fit:

  • Operational pain: 2 outages in last 12 months from disk-fill incidents; 1 outage from a manual Postgres minor-version upgrade gone wrong. Each outage = 30-90 min of customer-facing degradation.
  • Backup discipline: manual pg_dump cron with single-region S3 storage. Compliance audit (Q3 2026) requires automated, point-in-time-restore-capable backups. Our setup doesn't meet this bar.
  • Capacity gap: team has no dedicated DBA. The 1-2 engineers with deep Postgres knowledge spend ~10% of their time on database operations — inefficient and bus-factor-1.
  • Upgrade burden: Postgres major version upgrades have been deferred for 18 months because they're risky in our setup. We're behind on security patches.

At 600GB data + 12K QPS peak + 5K paid customers, we're firmly mid-market scale. Self-hosted Postgres is appropriate for either (a) very small scale (1 person ops it casually), or (b) very large scale (dedicated DBA team, optimized for our exact needs). We're in the awkward middle where managed Postgres is the better fit.

Decision

We will migrate our primary database from self-hosted Postgres 14 on EC2 to AWS RDS Postgres 16 Multi-AZ in the same region (us-east-1).

Migration plan: 8-week staged rollout, documented in [Migration Plan: ADR-0023-migration].

Alternatives Considered

Option 1: Stay on EC2, hire dedicated DBA

Pros:

  • Full control; no vendor lock-in
  • Marginal cost increase (DBA salary instead of RDS premium)
  • Familiar setup for team

Cons:

  • Hiring a senior DBA in current market is hard + slow (3-6 months)
  • Single-DBA bus factor risk
  • Doesn't fix backups/compliance issues quickly enough for Q3 audit
  • Manual upgrade burden continues

Why not chosen: doesn't address the time-critical compliance audit need. Hiring is too slow. Even with a DBA, manual Postgres operations will eat their time.

Option 2: AWS RDS Postgres Multi-AZ ✅ CHOSEN

Pros:

  • Automated backups (point-in-time restore) — meets compliance bar immediately
  • Automated failover (Multi-AZ) — eliminates single-point-of-failure
  • Managed minor version upgrades — security patches applied automatically
  • Storage auto-scaling — eliminates disk-fill outages
  • Mature tooling, well-documented, large community
  • Same region (us-east-1) keeps existing app servers + low latency

Cons:

  • ~2x cost vs self-hosted ($2400/month vs $1100/month all-in)
  • AWS lock-in (DB-level migrations are expensive)
  • Less control over Postgres minor versions (RDS chooses upgrade timing within a window)
  • Some Postgres extensions not available on RDS (notably: pg_partman, pg_repack)
  • IAM authentication available but adds complexity

Why chosen: best fit for our team capacity + compliance timeline + scale. Cost increase is bounded and predictable.

Option 3: Aurora Postgres

Pros:

  • AWS-native like RDS, similar operational benefits
  • Better read scaling (read replicas faster + cheaper)
  • Better fault tolerance via decoupled storage
  • Can scale to 128 TB without sharding

Cons:

  • ~3x cost vs self-hosted (more than RDS)
  • Aurora-specific lock-in (not just AWS, but Aurora's storage layer)
  • Aurora isn't 100% Postgres-compatible — small but real differences
  • Some Postgres tools (pg_dump backup workflows, pg-specific extensions) work differently

Why not chosen: the additional cost + Aurora-specific lock-in not justified at our 600GB scale. Aurora wins at 5+ TB scale or extreme read concurrency. We're not there yet.

Option 4: Self-host on Kubernetes (Crunchy / CloudNativePG operator)

Pros:

  • Full control + portability across clouds
  • Modern operator pattern, more automation than EC2 self-host
  • Can match RDS feature set (HA, backups, automated upgrades) with operator handling

Cons:

  • Steep learning curve for the team (we don't have Kubernetes-native ops expertise)
  • Operational complexity is high — operator config, networking, storage orchestration
  • Requires Kubernetes expertise we don't have
  • Compliance evidence harder to produce vs RDS's built-in attestations

Why not chosen: operational expertise gap. We'd be replacing one ops burden (manual EC2 Postgres) with another (Kubernetes-native Postgres), without saving time. RDS removes the burden entirely.

Consequences

Positive
  • Outages from disk-fill, manual upgrade errors, single-host failures: eliminated by RDS's managed nature.
  • Compliance bar for Q3 audit: met via RDS's automated backups + point-in-time-restore + AWS attestations.
  • Team time recovered: ~10% of senior engineer time previously on DB ops returns to product work. ~$80K/year value if we put a number on it.
  • Postgres version security: auto-applied minor version patches eliminates 18-month-behind issue.
  • Scaling headroom: RDS storage auto-scales; CPU/memory scaling via instance class change with minor downtime; read replicas straightforward to add.
  • Cross-region disaster recovery: RDS supports cross-region read replicas; cheaper to set up than self-hosted equivalent.
Negative
  • Cost increase: ~$1300/month additional ($1100 → $2400). Acceptable; not material to overall AWS spend.
  • Reduced control: can't apply Postgres minor patches on our own schedule. Auto-upgrades happen in maintenance windows.
  • Extension limitations: we don't currently use pg_partman or pg_repack, but adopting them would require either (a) waiting for RDS to support them, or (b) self-implementing alternatives.
  • AWS lock-in deepens: migrating to GCP / Azure / other cloud is harder once on RDS. Existing AWS commitment (ADR-0015) makes this acceptable; revisit only if AWS migration considered.
  • CDC / logical replication slot management: our Snowflake CDC pipeline depends on logical replication slots; RDS supports this but requires specific configuration. Migration plan addresses.
Risks
  • Performance regression: RDS instance class might not match EC2 raw performance for our specific workload. Mitigation: load-test in staging; size up if needed.
  • Maintenance window pain: RDS maintenance windows are minutes-long, not seconds. Our SLAs accommodate; verify customer expectations.
  • Pricing surprises: RDS storage I/O pricing can be unexpected at high IOPS. Mitigation: monitor in first 90 days; consider gp3 vs io1 storage class tuning.
  • Vendor risk: AWS could deprecate a feature or raise prices. Industry has been stable; risk is low but non-zero.
  • Reversal cost is high (see Reversibility). If RDS turns out to be the wrong choice, going back is 8+ weeks of work.

Reversibility

Hard but possible.

Reverting to self-hosted Postgres would require:

  • Provisioning new EC2 / Kubernetes-managed Postgres infrastructure (~1-2 weeks setup)
  • Migration via logical replication or pg_dump (~1-3 weeks depending on data growth)
  • Re-establishing manual operational practices (backups, monitoring, upgrade procedures)
  • ~8-week total migration effort, with risk of customer-impacting downtime

Migrating to a different managed Postgres (Aurora, GCP Cloud SQL) is similarly hard.

This is a 'one-way door' decision in practical terms — we should commit to RDS for at least 2-3 years before reconsidering.

When to Revisit

This decision should be re-evaluated if:

1. Cost grows >5x current projection. RDS pricing changes or our scale increases dramatically. Threshold: if RDS costs exceed ~$15K/month, evaluate Aurora or self-hosted alternatives.

2. AWS major price increase or feature removal. Specifically: if RDS Multi-AZ pricing model changes or auto-failover SLA degrades.

3. Scale exceeds RDS comfort zone. If we approach 5+ TB data or 100K+ QPS peak, evaluate Aurora's better read scaling or sharding strategies.

4. Multi-cloud requirement emerges. If business strategy requires running on GCP/Azure simultaneously, RDS's AWS lock-in becomes a problem.

5. Specific extension blocker. If product needs an extension RDS doesn't support and the alternative work-around is significantly more complex.

6. Hire dedicated DBA. If we hire a senior DBA, the cost-vs-control trade-off shifts; self-hosted with proper operations could become viable.

If none of these conditions occur, this decision stays as is.

Next scheduled review: 2027-04-28 (1 year). Owner: Sarah Chen.

Related ADRs

  • ADR-0008: 'Use Postgres as primary database' (2023) — Still valid; not affected.
  • ADR-0015: 'AWS as primary cloud' (2024) — Constraint that informed this decision.
  • ADR-0023-migration: separate document with the staged rollout plan.
  • Future ADR-XXXX: 'Cross-region disaster recovery for primary DB' — likely follow-up after RDS migration is stable.

Scope

Affects all 15 backend services that connect to the primary database. Coordinated migration during the 8-week rollout. No service-level code changes anticipated except for connection-string updates.

Does NOT affect: secondary databases (analytics warehouse Snowflake, Redis cache, ElasticSearch).

Notes

  • AWS Marketplace contract for RDS in place since 2025. Pricing locked.
  • Compliance audit firm has confirmed RDS Multi-AZ + point-in-time-restore meets their bar.
  • Consulted with AWS Solutions Architect during planning; no concerns raised.
  • DBA contractor (3-month engagement) hired to lead migration execution.
  • Postgres 16 chosen for the migration (not 15) to avoid another major upgrade in the first 2 years.

Common use cases

  • Engineer making a non-trivial architectural decision (new framework, new infra, new pattern) and wanting to document it properly
  • Tech lead establishing ADR practice for a team that's never used them
  • Architect reviewing prior decisions + writing retroactive ADRs for context
  • Engineer joining a codebase and wanting to understand why decisions were made
  • Founder writing ADRs for outsourced dev team to understand product architecture
  • Open-source maintainer documenting why the project went a particular direction

Best AI model for this

Claude Sonnet 4.5 or Opus 4. ADR writing is structured + reasoning-heavy — Sonnet handles fluently, Opus polishes for high-stakes decisions.

Pro tips

  • ADRs answer 'why did we choose X over Y' — not 'what is X.' Documentation explains what; ADRs explain the why.
  • Always include alternatives considered. The decision matters less than the trade-offs you knowingly accepted.
  • Be honest about consequences, especially negative. Future-you will appreciate not having to rediscover the downsides.
  • Date + author + sequential number. Keeps the historical context.
  • Status: Proposed / Accepted / Deprecated / Superseded by ADR-XXX. Living document.
  • Store ADRs in the repo (`/docs/adr/`), not in a wiki. Code-co-located = visible during reviews.
  • If a decision reverses an earlier ADR, write a new ADR superseding the old one. Never delete or edit the old one.

Customization tips

  • Be specific about the decision being made. Vague decisions produce vague ADRs that don't help future readers.
  • List ALL alternatives considered, even ones you quickly dismissed. The 'why not X' is often more informative than 'why Y.'
  • Be brutally honest about negative consequences. Future engineers will discover them anyway; better they're documented than rediscovered.
  • Use sequential ADR numbers (ADR-0001, ADR-0002, ...). Maintain a `/docs/adr/INDEX.md` listing all ADRs with status.
  • Write the 'When to Revisit' section carefully. The specific triggers that would change the decision are what makes ADRs living documents.
  • Use the Reversal ADR Mode variant if you're superseding an earlier decision — emphasizes what changed in context, not just what's new.

Variants

Major Architecture Mode

For high-stakes decisions (database, framework, infrastructure) — emphasizes alternatives + reversibility analysis.

Quick Decision Mode

For smaller decisions worth recording — concise but complete, ~1 page.

Retroactive ADR Mode

For documenting a decision that was made informally — adds 'context as of writing' to compensate for after-the-fact perspective.

Reversal ADR Mode

For ADRs that supersede earlier ones — emphasizes what changed in context, why prior reasoning no longer applies.

Frequently asked questions

How do I use the Architecture Decision Record Writer prompt?

Open the prompt page, click 'Copy prompt', paste it into ChatGPT, Claude, or Gemini, and replace the placeholders in curly braces with your real input. The prompt is also launchable directly in each model with one click.

Which AI model works best with Architecture Decision Record Writer?

Claude Sonnet 4.5 or Opus 4. ADR writing is structured + reasoning-heavy — Sonnet handles fluently, Opus polishes for high-stakes decisions.

Can I customize the Architecture Decision Record Writer prompt for my use case?

Yes — every Promptolis Original is designed to be customized. Key levers: ADRs answer 'why did we choose X over Y' — not 'what is X.' Documentation explains what; ADRs explain the why.; Always include alternatives considered. The decision matters less than the trade-offs you knowingly accepted.

Explore more Originals

Hand-crafted 2026-grade prompts that actually change how you work.

← All Promptolis Originals
P

Curated by

Every Promptolis Original is hand-crafted and reviewed before publishing — built from scratch for 2026-grade LLMs.

Last reviewed on · About Promptolis