AI Prompts for Architecture Decision Records

Write an architecture decision record about our choice to
use PostgreSQL.

A team spent two weeks migrating away from a database, only to rediscover partway through the exact limitation that had made them choose it in the first place — a limitation the alternative also had. Nobody remembered why the original choice was made, because the reasoning was never written down. They repeated an old debate, made the same decision again, and wasted two weeks learning what a good record would have told them in five minutes. This is what architecture decision records prevent, and AI prompts for architecture decision records make them fast enough that teams actually write them. Let's tear down a weak ADR prompt and rebuild it.

Before: The Weak Prompt

Here's how most people generate an ADR:

Write an architecture decision record about our choice to use PostgreSQL.

You'll get a document. It'll state the decision, list some generic PostgreSQL benefits, and look official. But it captures almost none of what makes an ADR valuable — the specific context, the alternatives actually considered, and the tradeoffs accepted. It's a decision announcement, not a decision record.

⚡ Pro tip: An ADR that only records what you decided is nearly worthless. The value is in why — the context that forced the decision, the alternatives you weighed, and the downsides you knowingly accepted. Without the why, future teams can't tell whether the decision still applies when circumstances change.

Why It Fails

This prompt fails because an ADR's entire purpose is preserving the reasoning behind a decision, and the vague version captures the decision while losing the reasoning.

The missing context is the biggest gap. A decision makes sense only against the constraints that shaped it — the team's size, the expected scale, the deadline, the existing systems. "We chose PostgreSQL" means nothing in a year; "we chose PostgreSQL because we needed strong consistency, had a team that knew SQL, and expected moderate scale" tells a future team exactly when to revisit it.

The missing alternatives are the second gap. Half an ADR's value is documenting what you didn't choose and why. When the database team from the intro considered switching, an ADR listing "we rejected MongoDB because we needed transactions" would have ended their debate before it wasted two weeks.

The missing consequences are the third gap. Every architecture decision has downsides you accept knowingly. Recording them ("this means we'll need to manage schema migrations carefully") prevents a future team from treating a known, accepted tradeoff as a newly discovered problem.

⚠️ Common mistake: Writing ADRs that document the decision but not the alternatives rejected and why. The rejected options are often the most valuable part, because when someone later proposes switching to one of them, the ADR already contains the analysis of why it didn't fit — saving the team from re-litigating a settled question.

After: The Improved Prompt

Here's the rebuild that captures the reasoning:

Help me write an architecture decision record. Structure it: - Title and status (proposed/accepted/superseded). - Context: the specific situation and constraints forcing this decision (scale, team, deadlines, existing systems). - Decision: what we're choosing. - Alternatives considered: each option we weighed, with why we rejected it — be specific about the dealbreaker. - Consequences: what this makes easier, what it makes harder, and the tradeoffs we're knowingly accepting. - When to revisit: what would change that should make us reconsider this. Interview me by asking questions to fill each section — don't invent details I haven't given you.

What this does: It captures the full reasoning — context, rejected alternatives with their dealbreakers, accepted consequences, and revisit triggers — and the "interview me" instruction stops the model from fabricating plausible-sounding but false justifications.

Breaking Down Each Element

Each section earns its place in a way the weak version missed.

Context anchors the decision to its moment. It's what lets a future reader judge whether the decision still holds. Constraints change, and a decision that was right under old constraints may be wrong under new ones — but only if the old constraints are recorded.

Alternatives with specific dealbreakers are the anti-relitigating section. "We rejected X because it couldn't do Y, which we require" is a complete answer to anyone who later suggests X. This section alone would have saved the intro team their two weeks.

Consequences make tradeoffs explicit. By recording what you knowingly gave up, you prevent future confusion where an accepted downside gets mistaken for an oversight. It also keeps the decision honest — if you can't name any downsides, you probably haven't thought hard enough.

"When to revisit" is the section most ADRs omit and the one that makes them living documents. It tells future teams the specific trigger — "if we exceed 10,000 writes per second" — that should reopen the decision, so they neither cling to it forever nor abandon it prematurely.

The "interview me" instruction is critical. Left to invent, the model writes plausible reasoning that isn't yours, which is worse than no ADR because it looks authoritative while being fiction.

⚡ Pro tip: Have the AI interview you to fill an ADR rather than generating one from a brief description. The model doesn't know your real constraints and alternatives, and if it invents them, you get a confident-sounding document full of reasoning that never happened. Questions extract your actual reasoning; generation fabricates a substitute.

Variations for Different Contexts

The skeleton adapts across decision types and roles.

A tech lead documenting a framework choice should emphasize the alternatives and team-fit constraints, since framework decisions are frequently reopened and the "why not the other one" analysis gets requested often.

A platform engineer recording an infrastructure decision should stress the consequences and revisit triggers, since infrastructure choices have long-lasting operational tradeoffs and clear scale-based reasons to reconsider.

A team adopting a new practice (not just a technology) can use the same structure for process decisions: "why we adopted trunk-based development" benefits from the same context-alternatives-consequences record as a technical choice.

Here's a reusable ADR prompt skeleton:

Interview me to write an ADR for [decision]. Ask questions to fill: context and constraints, the decision, alternatives considered with specific dealbreakers, consequences and accepted tradeoffs, and what would make us revisit this. Don't invent details — ask me for what you need.

What this does: The interview-driven, full-reasoning structure captures the why that makes an ADR valuable, without the fabrication risk of generating from a thin brief.

⚡ Pro tip: Include a "when to revisit" section in every ADR. It transforms the document from a historical record into a decision aid — future teams know exactly what changed circumstance should trigger a reconsideration, so they neither blindly follow an outdated choice nor needlessly overturn a sound one.

Save and Reuse This

The weak prompt gave you a decision announcement that helped no one in a year. The strong one gives you a real decision record — context, alternatives, consequences, and revisit triggers — that saves future teams from repeating settled debates. The difference is entirely in capturing the reasoning, not just the outcome.

That structure works for every architecture decision your team makes, which makes it worth standardizing. PromptABCD is built for this — store your interview-driven ADR skeleton, keep it consistent across the whole team so every decision gets recorded the same way, and reuse it the moment a significant choice comes up. Once the ADR structure is a saved template your whole team shares, decision-recording becomes fast enough that people actually do it. And a team that records its reasoning is a team that never spends two weeks rediscovering why it made a choice it already made once, which is exactly the kind of waste good documentation quietly prevents.

The reason ADRs get skipped, despite everyone agreeing they're valuable, is that writing them feels like overhead in the moment — the decision's already made, the team wants to build, and documenting the reasoning seems like a chore for a hypothetical future reader. The AI-interview approach attacks exactly this friction. Instead of facing a blank document and trying to reconstruct your own reasoning into prose, you answer a handful of pointed questions and get a structured record out. That drops the cost of writing an ADR from "a task I'll get to later" to "ten minutes right now," and the difference between those two is the difference between a team that has decision records and one that keeps rediscovering its own history.

⚡ Pro tip: Write the ADR at the moment of decision, not after. The reasoning is freshest right when you decide, and it fades fast — within weeks the specific alternatives you weighed and the constraints that drove the choice blur together. Capturing it immediately, while the AI interviews you, preserves detail that reconstruction later can never fully recover. An ADR written a month after the fact is already missing the nuance that makes it worth having.

Make immediate, interview-driven ADRs a team habit and you build an institutional memory that survives turnover, onboards new engineers faster, and quietly prevents the repeated debates that waste weeks. Every recorded decision is a gift to the future team — often a future version of yourselves — that turns "why on earth did we do it this way" from a mystery into a documented, still-valid answer. That accumulated reasoning is one of the most valuable and most neglected assets a team can build.