Why this is hard to get right
The Problem With Writing ADRs From Memory
Maria is a senior engineer at a Series B startup. Her team just spent three weeks evaluating message queue options. They debated Kafka, SQS, RabbitMQ, and a home-rolled Redis solution. Everyone has opinions. The architecture review meeting is tomorrow.
Her manager asks her to write up the ADR before end of day so the team can review it async.
Maria opens a blank document and types the title. Then she stares at it.
She knows the decision. She knows why they chose SQS + SNS. But the moment she tries to write it down formally, the structure falls apart. She can't remember if the ADR template uses "Context" before "Decision" or after. She's not sure how much detail to put in the "Alternatives" section. She's worried the "Consequences" section will read like a marketing pitch instead of an honest tradeoff analysis.
She tries asking an AI assistant: "Write an ADR for choosing our new message queue. Make it clear and include pros and cons."
The output is generic and useless. It describes Kafka as "highly scalable" and SQS as "easy to manage." It lists no real numbers. The Alternatives section reads like a Wikipedia summary. The Consequences section is three bullet points that could apply to any infrastructure decision made anywhere.
She spends 45 minutes editing. The resulting ADR still feels thin. Reviewers will ask questions she should have preempted.
The root problem isn't her knowledge. It's that ADRs require very specific inputs — scale numbers, operational constraints, team capabilities, failure modes, rollout plan — and none of those were in her original prompt. The AI filled the gaps with generic content because it had no choice.
When Maria structures her prompt with the actual context — 8,000 msgs/sec peak, a 99.9% SLO, a team of four, a three-month delivery window, and real concerns about on-call burden — the AI produces an ADR she can circulate immediately. The Rationale section defends the decision with the same numbers the team argued over. The Consequences section addresses the ordering trade-offs they actually debated. The Open Questions section captures the two items they still need to resolve.
She saves two hours and ships a review-ready artifact. The reviewers ask one clarifying question instead of six. The decision gets approved the same day.
That's the difference a structured prompt makes for ADR drafting. Not a better tool — better inputs.
Common mistakes to avoid
Omitting System Scale and Load Numbers
Telling the AI to 'choose a scalable solution' without specifying peak throughput, message volume, or SLO targets produces generic recommendations. Always include measurable numbers — messages per second, latency budgets, uptime targets — so the AI can weigh options against your actual operating conditions, not hypothetical ones.
Listing Only the Chosen Option
Skipping alternatives makes the ADR look like a rubber stamp, not a decision. Reviewers need to see that you considered other paths. Provide at least two real alternatives you actually evaluated — with enough detail for the AI to honestly compare them — or your ADR won't survive a serious architecture review.
Forgetting Operational Constraints
Ignoring team size, on-call load, and delivery timelines leads to an ADR that recommends a solution your team can't actually operate. State your constraints explicitly: three engineers, no dedicated ops, 90-day runway. The AI will then surface tradeoffs that matter — like whether Kafka on MSK is realistic for a team without Kafka expertise.
Not Specifying the ADR Template or Format
Every organization uses a slightly different ADR structure. If you don't specify sections — Context, Decision, Alternatives, Rationale, Consequences, Open Questions — the AI invents its own structure. Name every required section in your prompt so the output maps directly to your team's review process and doesn't need reformatting.
Skipping Failure Modes and Rollout Plan
An ADR without a rollout plan is a design document, not a decision record. Reviewers want to know what happens when the new system fails. Explicitly ask for failure modes, replay strategy, and a rollout sequence. Without this instruction, AI-generated ADRs almost always end at 'Consequences' and leave rollout to a follow-up document nobody writes.
Using the Wrong Audience Setting
Writing 'explain this clearly' without specifying the audience forces the AI to guess. A staff engineer and a VP of Engineering need very different levels of technical depth. Declare your audience and their expertise level — senior engineers, neutral tone, no marketing language — so the Rationale section reads like peer documentation, not a sales pitch.
The transformation
Write an ADR for choosing our new message queue. Make it clear and include pros and cons.
You’re a staff software engineer. Draft an ADR in **Markdown** for this decision: 1. **Context:** We run a B2B SaaS on AWS. 12 services publish events. Peak 8,000 msgs/sec. 99.9% SLO. 2. **Decision needed:** Choose **SQS + SNS** or **Kafka (MSK)** for async events. 3. **Audience & tone:** Senior engineers. Direct, neutral, no marketing. 4. **ADR format:** Title, Status, Context, Decision, Alternatives (2), Rationale, Consequences, Rollout Plan, Open Questions. 5. **Constraints:** 3-month delivery, team of 4, on-call load must not increase. Call out cost, ops burden, ordering needs, replay strategy, and failure modes.
Why this works
Persona and Audience Alignment
The After Prompt opens with 'You're a staff software engineer' and specifies 'Senior engineers. Direct, neutral, no marketing.' This dual persona setup — assigning a role to the AI and naming the human readers — calibrates vocabulary, assumed knowledge, and tone simultaneously. Without it, the AI defaults to generic technical writing that satisfies no specific audience.
Measurable Inputs Eliminate Guessing
The After Prompt specifies 8,000 msgs/sec peak throughput and a 99.9% SLO rather than vague terms like 'high volume' or 'reliable.' Concrete numbers anchor the AI's comparison of SQS + SNS vs. Kafka to your actual operating environment. Generic inputs produce generic comparisons; real numbers produce real tradeoff analysis.
Enforced Template Structure
The After Prompt lists every required section: Title, Status, Context, Decision, Alternatives, Rationale, Consequences, Rollout Plan, Open Questions. Naming the template prevents the AI from inventing its own structure and ensures the output maps directly to your team's review checklist. You get a consistent artifact, not a creative interpretation of what an ADR should look like.
Explicit Evaluation Criteria
The After Prompt ends with a direct instruction: 'Call out cost, ops burden, ordering needs, replay strategy, and failure modes.' This evaluation criteria list tells the AI exactly what dimensions to compare across alternatives. Without it, the AI selects its own comparison axes — usually the most generic ones — and misses the factors your team actually cares about.
Real Constraints Drive Honest Tradeoffs
The After Prompt states 3-month delivery, team of 4, on-call load must not increase. These constraints force the AI to surface operational risk — for example, flagging that self-managed Kafka may be realistic for a larger team but not for four engineers without Kafka expertise. Constraints transform a theoretical comparison into a decision your team can actually execute.
The framework behind the prompt
Why Architecture Decision Records Matter — and Why They're Hard to Write
Architecture Decision Records were formalized by Michael Nygard in 2011 as a lightweight method for capturing the reasoning behind significant technical decisions. The core insight: code explains what was built, but not why. Without a written record, architectural context disappears when engineers leave, and teams repeat expensive debates years later.
A well-formed ADR typically follows a structure close to Nygard's original template: Title, Status, Context, Decision, Consequences. Many teams extend this with Alternatives, Rationale, and Rollout Plans — moving closer to what RFC (Request for Comments) documents provide in open-source communities.
The challenge with AI-generated ADRs connects to a broader principle in prompt engineering: specificity drives output quality. Research on large language models consistently shows that vague instructions produce hedged, generic output, while structured prompts with concrete constraints produce targeted, defensible content. This mirrors the RISEN framework (Role, Instructions, Steps, End goal, Narrowing) — each element reduces the AI's degrees of freedom and forces it toward your specific context.
ADRs also benefit from few-shot prompting principles: providing the AI with the specific evaluation dimensions you care about (ordering guarantees, replay strategy, ops burden) functions like providing labeled examples. The AI uses these dimensions as column headers for an implicit comparison matrix, producing analysis that maps directly to your decision criteria.
The STAR method (Situation, Task, Action, Result) also applies here. Structuring your Context section as a mini-STAR — here's our current situation, here's the problem it creates, here's what we need to decide — gives the AI the narrative arc it needs to write a Rationale that feels like a reasoned argument, not a list of facts.
Finally, ADRs serve a knowledge management function that extends well beyond the immediate decision. Teams that maintain ADRs reduce onboarding time, accelerate incident post-mortems, and make future architectural changes with more confidence. The time you invest in a well-prompted ADR today pays dividends every time a new engineer asks 'why did we build it this way?'
Prompt variations
You are a senior software architect. Draft an Architecture Decision Record in Markdown for the following decision:
Context: We run a single-tenant e-commerce platform built as a Rails monolith. The app handles 500 orders per day. We are experiencing deployment bottlenecks because all four developers deploy to the same codebase.
Decision needed: Whether to extract the Order Management module as a standalone microservice or keep it in the monolith and improve deployment processes with feature flags.
Audience: Mid-level engineers and one non-technical CTO. Use plain English where possible.
Required sections: Title, Status (Proposed), Context, Decision, Alternatives (2), Rationale, Consequences, Rollout Plan, Open Questions.
Constraints: 2 engineers available, 6-week window, no dedicated DevOps.
Highlight deployment risk, inter-service communication overhead, team readiness, and rollback strategy.
You are a principal engineer specializing in distributed systems. Draft a production-grade ADR in Markdown for the following decision:
Context: We operate a globally distributed B2B platform serving customers in the US, EU, and APAC. Current setup: single Aurora PostgreSQL primary in us-east-1 with read replicas. We're hitting 180ms p99 read latency for EU customers and facing GDPR data residency requirements for EU data.
Decision needed: Choose between (1) Aurora Global Database with EU writer failover, (2) CockroachDB with geo-partitioning, or (3) separate regional databases with application-level routing.
Audience: Staff and principal engineers, plus a security lead reviewing GDPR compliance.
Required sections: Title, Status, Context, Decision, Alternatives (3), Rationale, Consequences, Compliance Impact, Rollout Plan (phased), Open Questions.
Constraints: 12-week delivery, team of 6, zero-downtime migration required, existing ORM must remain compatible.
Address: replication lag, write conflict resolution, data residency enforcement, failover RTO, cost delta at 10TB scale, and operational runbook requirements.
You are a senior API platform architect. Draft an Architecture Decision Record in Markdown for the following decision:
Context: We provide a public REST API used by 340 third-party integrations. We ship breaking changes 3-4 times per year. Currently we use URL path versioning (v1, v2). Partners complain about upgrade friction and we have two deprecated versions still receiving 15% of traffic.
Decision needed: Choose between (1) continuing URL path versioning with a stricter sunset policy, (2) switching to header-based versioning, or (3) adopting API evolution principles (additive-only changes, no versioning).
Audience: Product managers, partner engineering leads, and one VP of Partnerships. Minimize jargon. Emphasize partner impact.
Required sections: Title, Status, Context, Decision, Alternatives (3), Rationale, Partner Impact, Consequences, Migration Plan, Open Questions.
Constraints: Cannot break existing integrations, 90-day partner notice policy, two engineers available for migration tooling.
Highlight partner upgrade effort, internal maintenance burden, documentation requirements, and deprecation enforcement mechanisms.
When to use this prompt
Product Managers Aligning Technical Tradeoffs
Turn a rough decision into an ADR that explains impacts, risks, and rollout steps for stakeholders.
Engineering Leads Standardizing Decisions
Create consistent ADRs across teams so reviews focus on tradeoffs, not missing context.
Customer Success Teams Needing Clear Internal Notes
Document backend choices that affect SLAs, incident response, and customer commitments.
Researchers Comparing Solution Approaches
Capture assumptions, alternatives, and open questions before you run experiments or pilots.
Pro tips
- 1
Define success metrics first so the ADR defends the decision with numbers.
- 2
Specify your rollout plan so reviewers can judge risk, not just design.
- 3
List 2–3 realistic alternatives so the rationale feels credible and complete.
- 4
Add operational constraints so the AI addresses on-call load and monitoring needs.
Most AI-generated ADRs pass a friendly review but collapse under a skeptical one. Here are techniques to harden your ADR before it goes out:
Pre-load the steelman argument. In your prompt, add: 'In the Rationale section, include the strongest argument against the chosen option and explain why you rejected it anyway.' This forces the AI to anticipate the most obvious objection — and your reviewers will notice you addressed it.
Require cost estimates. Add: 'Include a rough monthly cost estimate for each alternative at our stated scale. Use public pricing where available.' Even ballpark numbers dramatically improve the credibility of the Consequences section.
Separate reversibility from consequences. Ask the AI to flag each consequence as either reversible or irreversible. Reviewers care most about decisions that are hard to undo — making this explicit helps them focus attention appropriately.
Chain your ADRs. If this decision depends on a previous one, reference it in your prompt: 'This ADR assumes the decisions made in ADR-012 (monorepo structure) and ADR-017 (AWS as primary cloud). Do not relitigate those choices.' This prevents scope creep in the Alternatives section and keeps the review focused.
Request a one-sentence summary. Ask the AI to add a TL;DR at the top: one sentence stating the decision and the primary reason. Engineering leads often read only this line before deciding whether to dive deeper.
Architecture Decision Records originated in software, but the format translates to any domain where documented, reasoned decisions matter.
Data Engineering: ADRs for pipeline architecture, storage format selection (Parquet vs. Delta Lake), and orchestration tooling (Airflow vs. Prefect). Include data volume, freshness SLA, and downstream consumer count as your measurable inputs.
Platform and DevOps: ADRs for CI/CD toolchain selection, container orchestration strategy, and secret management approaches. Operational burden and mean time to recovery are the key evaluation axes.
Security: ADRs for authentication protocol selection, encryption-at-rest strategy, and third-party dependency vetting. These require a Compliance Impact section covering relevant standards (SOC 2, ISO 27001, GDPR).
Machine Learning: ADRs for model serving infrastructure, feature store selection, and retraining cadence. Add model latency budget and inference cost per prediction as measurable constraints.
Embedded and Hardware-Adjacent Systems: ADRs for communication protocol selection (MQTT vs. AMQP), firmware update strategy, and hardware abstraction layer design. Power consumption and memory footprint often function as hard constraints equivalent to throughput in distributed systems.
In every variation, the same principle holds: measurable constraints produce honest tradeoffs. Swap out the specific numbers for your domain and the prompt structure remains the same.
An ADR isn't a one-time artifact. It moves through a defined lifecycle, and your prompts should match the lifecycle stage.
Status: Proposed. Use the After Prompt structure to generate the initial draft. The goal is a complete, review-ready document that defends a recommendation with evidence.
Status: Accepted. After review, you may need to revise based on feedback. Prompt the AI with: 'Revise this ADR to incorporate the following reviewer feedback: [paste comments]. Maintain the original structure. Do not change the decision or the primary rationale unless I instruct you to.' This prevents the AI from rewriting sections that don't need to change.
Status: Deprecated / Superseded. When a future decision overrides an existing ADR, you need a Superseded-By note and a brief changelog. Prompt: 'Add a Status update to this ADR indicating it is superseded by ADR-031. Write a two-sentence summary of what changed and why the original decision no longer applies.'
Storing and linking ADRs. The most common storage patterns are a /docs/adr directory in the repo (numbered sequentially, e.g., 0042-message-queue-selection.md) or a dedicated Confluence space with a consistent template. Whichever you use, always include a link to related ADRs in the Open Questions or Consequences section — the AI will do this automatically if you list related decision numbers in your prompt.
When not to use this prompt
Don't use this prompt pattern for decisions that are already obvious or trivially reversible. If your team has unanimous agreement and no meaningful alternatives, writing an ADR is overhead, not value. Save the format for decisions with real tradeoffs and lasting consequences.
Avoid AI-generated ADRs for decisions involving sensitive security or compliance architecture without expert human review. The AI can structure the document, but it cannot audit your threat model or verify regulatory interpretation. Always have a qualified engineer review the Compliance Impact and Consequences sections before they become organizational record.
Don't use this pattern when the decision hasn't been made yet. An ADR is a record of a decision, not a tool for making one. If your team is still in active debate, use a design doc or RFC format instead — both are better suited to open-ended exploration.
- Use a design doc when you need to explore options without committing
- Use an RFC when you need structured community input before deciding
- Use an ADR only after the decision is made and you need to document the reasoning
Also avoid this approach for trivially short decisions. If the entire rationale fits in a Slack message, a Slack message is the right artifact.
Troubleshooting
The Alternatives section reads like a Wikipedia summary with no real comparison
Add a structured comparison instruction to your prompt: 'For each alternative, provide: (1) a one-paragraph technical description, (2) how it performs against each constraint listed above, and (3) two specific reasons it was not chosen.' This forces the AI to compare alternatives against your actual requirements rather than writing generic overviews.
The Rationale section sounds like a vendor pitch, not an engineering judgment
Add this line: 'Write the Rationale as a senior engineer explaining a tradeoff to a peer — not as a vendor selling a product. Acknowledge the two most significant disadvantages of the chosen option explicitly.' If the output still sounds promotional, follow up with: 'Rewrite the Rationale section using only facts and constraints from the Context section.'
The Consequences section is too short and misses operational risks
Expand your evaluation criteria instruction. Instead of a general request, list specific risk categories: 'Address each of the following in the Consequences section: monitoring and alerting changes, on-call playbook updates, cost delta at peak load, data loss risk during cutover, and team training requirements.' Generic instructions produce generic output — named categories produce specific content.
The output doesn't match our internal ADR template structure
Paste your exact template section headers into the prompt with a note: 'Use only these sections in this exact order: [paste your headers]. Do not add or rename any sections.' If your template uses custom terminology — like 'Decision Outcome' instead of 'Decision' — include one example line showing the expected format so the AI understands the naming convention.
Open Questions are too vague or obvious — they don't capture real unresolved items
Seed the Open Questions section with one or two real unresolved items from your team's discussion. Add to your prompt: 'Start the Open Questions section with these two unresolved items from our review: [paste your actual questions]. Then add 2-3 related questions the team should resolve before implementation.' Seeding with real context produces specific, actionable follow-up questions.
How to measure success
How to Evaluate Your AI-Generated ADR
Before you circulate an ADR, run it through this checklist:
Content completeness:
- All required sections are present and in the correct order
- The Context section includes at least one measurable system characteristic (throughput, latency, SLO, team size)
- At least two real alternatives appear, each with genuine disadvantages listed
Rationale quality:
- The Rationale defends the decision using the constraints you provided — not generic best practices
- The two strongest arguments against the chosen option are acknowledged explicitly
- No section reads like vendor marketing language
Operational coverage:
- The Consequences section addresses failure modes, not just benefits
- A rollout plan or phased implementation sequence is present
- On-call and monitoring impacts are named specifically
Review readiness:
- A non-author engineer can read the ADR and understand the decision without asking clarifying questions
- Open Questions are specific and actionable — each one names who is responsible for resolving it
- The document is under 800 words (if longer, it likely needs to be split into two ADRs)
Now try it on something of your own
Reading about the framework is one thing. Watching it sharpen your own prompt is another — takes 90 seconds, no signup.
Turn your architecture decision into a review-ready ADR with honest tradeoffs and a rollout plan — in minutes.
Try one of these
Frequently asked questions
A well-structured ADR typically runs 400 to 800 words in Markdown. Shorter than that and the Rationale section lacks enough detail to defend the decision. Longer risks burying the key conclusion. If your AI output exceeds 1,000 words, instruct it to consolidate the Alternatives and Consequences sections to two to three bullet points each.
This prompt structure works for any architectural decision with real tradeoffs: frontend framework selection, authentication strategy, data modeling approach, CI/CD toolchain, monorepo vs. multi-repo — any choice with long-term consequences. The key is always the same: provide measurable context, name real alternatives, and specify constraints. The domain doesn't matter; the inputs do.
List your required sections explicitly in the prompt. For example: 'Use these sections in order: Title, Status, Problem Statement, Considered Options, Decision Outcome, Pros and Cons, Implementation Notes.' You can also add: 'Follow the format used in Michael Nygard's original ADR proposal' or reference your internal wiki structure. The AI will adapt to whatever section names you specify.
This happens when your constraints aren't explicit enough. Add a line like: 'Do not recommend based on industry popularity. Evaluate strictly against the constraints listed above.' Then restate your binding constraints — team size, delivery window, on-call limits — immediately before the evaluation criteria. This forces the AI to weight your reality over general best practices.
Always include your decision. An ADR documents a decision already made — it's not a decision-making tool. Specify the chosen option in the prompt and ask the AI to write the Rationale section defending it honestly, including acknowledged tradeoffs. Letting the AI choose produces a recommendation document, not an Architecture Decision Record.
Add this line to your prompt: 'For each alternative, list at least two genuine disadvantages. Do not soften tradeoffs with qualifiers like 'minor' or 'manageable'.' You can also instruct: 'Write the Consequences section as a senior engineer would to a peer — not as a vendor selling a product.' This prevents the AI from defaulting to promotional language in technical documentation.
Include a specific instruction in your prompt: 'Add an Open Questions section listing 3 to 5 unresolved items that must be answered before implementation begins.' Then seed it with one or two real open questions from your discussion. For example: 'We haven't decided who owns the dead-letter queue monitoring.' The AI will use those as anchors and surface related gaps you may have missed.