Prompting for Architecture Decision Records

TL;DR: An ADR captures a decision, its context, and its consequences, a format Michael Nygard defined in 2011 that AWS and a widely used GitHub template repo still use today. A model can draft the shape and ask good questions. It cannot know your actual constraints, so Context and Consequences still have to come from your team.

What Is an Architecture Decision Record, Really?

An architecture decision record is a short document, one per significant decision, that captures the decision itself, the forces that led to it, and what happens as a result. The format traces to a specific, findable source: Michael Nygard's November 2011 post, "Documenting Architecture Decisions", originally published on Relevance's blog and still live today on Cognitect's. Nygard defines it plainly: "An architecture decision record is a short text file in a format similar to an Alexandrian pattern. (Though the decisions themselves are not necessarily patterns, they share the characteristic balancing of forces.) Each record describes a set of forces and a single decision in response to those forces."

That's not a rebrand of "write good comments" or "keep a changelog." An ADR is specifically about the decision and the reasoning, not the implementation. AWS's own architectural decision record guidance puts the same point differently, fifteen years later: "One of the most powerful aspects of the ADR structure is that it focuses on the reason for the decision rather than how the team implemented it." Two independent sources, a decade apart, converge on the same claim, which is a stronger signal than either alone.

A decision between RAG, fine-tuning, and prompting for a given use case, covered separately in RAG vs fine-tuning vs prompting, is exactly the kind of architecturally significant choice Nygard had in mind: it affects cost, maintenance, and dependencies for years, not just the sprint you made it in. That's the test for whether something deserves an ADR at all, not every configuration change does.

Prompt Architects already has one ADR prompt inside a broader documentation-prompt library covering docstrings, READMEs, and changelogs too; if you want the full artefact-by-artefact set, that's the documentation prompt generator. This page goes deeper on the ADR specifically: its actual format history, how two widely used templates differ, and where prompting genuinely helps versus where it will quietly make things worse.

What Are the Parts, and Why Do Two Templates Disagree?

Nygard's original format has five named sections, and he's specific about what each one is for:

• Title — "These documents have names that are short noun phrases." Nygard's own example: "ADR 1: Deployment on Ruby on Rails 3.0.10".
• Context — "This section describes the forces at play, including technological, political, social, and project local." Nygard adds that it should be written in "value-neutral" language, stating tensions rather than resolving them.
• Decision — "This section describes our response to these forces. It is stated in full sentences, with active voice." Nygard's own example opening: "We will …"
• Status — a decision may be "proposed" if stakeholders haven't agreed with it yet, or "accepted" once they have; later, it may be marked "deprecated" or "superseded" once a subsequent ADR replaces it.
• Consequences — "This section describes the resulting context, after applying the decision." It covers positive, negative, and neutral effects alike, not only the upsides.

Nygard's format is deliberately terse: state the decision, note the forces, move on. A widely used extension, MADR (Markdown Architectural Decision Records), adds a step Nygard's original doesn't call out explicitly. MADR's own template inserts a Considered Options list between the context and the outcome, then a Pros and Cons of the Options section that runs through each rejected alternative individually, alongside a separate Decision Drivers list naming the forces that mattered most. If you want a record that shows its work, not just its conclusion, MADR's structure is built for exactly that, and it's the shape to reach for when "we considered three approaches" needs to survive in the document, not just in a Slack thread nobody can find again.

The practical difference shows up exactly where teams argue after the fact: MADR forces the alternatives onto the page, one subsection each, with their own pros and cons. Nygard's original leaves that entirely inside Context, as prose, at whatever length the author felt like giving it. Neither is wrong; they're solving for different failure modes. Pick MADR when the rejected options are themselves worth defending later; pick Nygard's original when brevity matters more than showing your work.

Both templates, plus eleven more variants (from arc42's format to a Y-statement notation to one built around Planguage), live in a single, actively maintained community repository on GitHub, alongside Nygard's own linked as its primary source. This isn't a niche convention: adr.github.io's own list of ADR coverage names the Azure Well-Architected Framework as a current adopter, and AWS publishes a full ADR process of its own inside its Prescriptive Guidance docs, independent of Nygard's site or the GitHub repo. Three organizations, none of them copying from the other two, arrived at the same core structure: context, decision, consequences.

Can AI Write the Context and Consequences Sections for You?

Not honestly, and this is the part worth being direct about rather than glossing over.

A model reading your codebase can describe what the code does. It can even produce something that reads like Context: a paragraph naming plausible-sounding forces, a Decision stated in the right tense, a Consequences section with a mix of upsides and downsides. All of that can be fluent and still be fabricated, because the actual forces at play, the political constraint that ruled out one option, the team's actual risk tolerance, the fact that you tried the "obvious" approach eighteen months ago and it fell over in production, are not in the diff. They were never written down anywhere a model can read them.

This matters more for an ADR than for almost any other artefact a model might help you write, because of what an ADR is for. It exists to be read years later by someone who wasn't in the room, specifically to answer "what were they thinking?" A generated Context section that invents a plausible-sounding tension nobody actually weighed doesn't just waste a reader's time the way a generic docstring might. It actively misleads the next person who trusts it, at exactly the moment they're trying to decide whether the original reasoning still holds. A document that looks authoritative and is wrong about the "why" is worse than an empty folder, because an empty folder at least doesn't lie to you.

The same logic covers Consequences, for a slightly different reason: consequences are things that happen after a decision is lived with. Asking a model to write the Consequences section for a decision that hasn't shipped yet isn't retrieval, it's prediction dressed up as documentation. Where the model genuinely helps is narrower than "write my ADR," and worth naming precisely.

Where the Model Actually Helps: Three Concrete Prompts

1. Interview you before it drafts anything, instead of guessing.

The failure mode above happens because a model asked to "write an ADR" fills gaps with plausible invention. The fix is to make it ask instead of fill:

I'm about to write an ADR for the decision below. Before drafting
anything, generate the questions a future maintainer would ask about it,
in priority order. Cover at minimum: what alternatives we considered and
why each was rejected, what has to remain true for this decision to
still be correct, what would make us reverse it, and who outside this
team is affected.

Ask me one question at a time and wait for my answer before asking the
next. Do not draft the ADR, and do not answer your own questions.

DECISION (one line):
<paste>

The "one at a time, wait for my answer" instruction matters as much as the question list itself. A model asked for ten questions at once will happily generate all ten and then, left unsupervised, start answering a few of them for you unless you explicitly forbid it.

2. Draft the alternatives-considered section from your raw notes.

This is where MADR's structure earns its keep: it gives the model an explicit shape for the part your team actually did the hard thinking on, instead of collapsing it into one sentence in the Context section.

Turn my notes below into a "Considered Options" section for an ADR,
following the MADR structure: one subsection per option, each with a
short description and then a bulleted list of concrete pros and cons.

Use only what I give you. If a pro or con isn't something I stated
explicitly, do not include it, guess at it, or infer it from what the
option is (for example, do not add "more expensive" for a cloud service
just because it's a cloud service). Where you think a real trade-off is
missing, list it separately under "Questions for me" instead of filling
it in.

MY NOTES ON THE OPTIONS WE CONSIDERED:
<paste>

3. Review an existing ADR for unstated assumptions.

Once an ADR exists, a model is genuinely useful as a second reader, specifically for internal consistency, not for re-litigating whether the decision was right.

Read the ADR below as a skeptical reviewer, not as an editor. Report,
with a direct quote for each:

1. Any claim in Decision or Consequences that isn't supported by
   anything stated in Context.
2. Any consequence that seems foreseeable given the Context but isn't
   listed.
3. Whether the Status matches what the document itself describes (for
   example, marked "accepted" while the text describes an unresolved
   disagreement).

Do not suggest a different decision. Only report gaps between what the
document claims and what it actually supports.

ADR:
<paste>

That third prompt does something a human reviewer often skips under time pressure: a line-by-line check that the stated reasoning actually supports the stated conclusion, rather than a read for tone and formatting. It's a genuinely good fit for a model, because it's pattern-matching within a fixed document, not judgment about your architecture. AWS's own ADR review process describes a review meeting that opens with "10 to 15 minutes" of dedicated silent reading before anyone discusses the document; a model doing the same pass first, flagging candidates for discussion in advance, doesn't replace that conversation but can make those minutes more productive. The same "read as a skeptical reviewer, not an editor" instinct is the backbone of a good code review prompt too, covered in how to prompt for a genuinely useful code review.

What Should You Never Ask a Model to Do With an ADR?

Never ask it to back-fill Context purely from the code or the diff, and never let it invent a decider's name, a date, or a trade-off you didn't actually supply. If a section needs information you haven't given it, the correct output is a question, not a plausible guess dressed up as a fact. The documentation prompt generator linked above covers this same principle across every artefact type, not just ADRs: a docstring, a README, and a changelog each have their own version of "the model can't know what it wasn't told."

A Status Lifecycle Most Teams Get Wrong

Nygard's original scheme is a small, fixed set of states on purpose: proposed, accepted, deprecated, or superseded with a pointer to what replaced it. The part teams get wrong is what happens once a decision changes. Nygard is specific about the mechanics, too: "ADRs will be numbered sequentially and monotonically. Numbers will not be reused." A number that skips or gets reassigned is itself a sign the history has been tampered with.

AWS's own guidance is unambiguous about this: "When the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the team accepts the new ADR, it supersedes the previous ADR." Not "edit the old one." Not "delete it and write a new one." The old record stays, marked superseded, precisely because its existence is itself evidence that the question was asked and answered once already. Delete it, and the next person who has the same idea has no way to know it was already tried and reversed.

Where Prompt Architects Fits, and Where It Doesn't

We don't store your ADRs, generate them from your repository, or have any view into your decision history; the /features page lists prompt enhancement, libraries, prompt history, and the browser extension, and nothing that reads or writes architecture documentation. What the MCP server at mcp.prompt-architects.com/mcp does is sharpen the prompt text itself, the interview prompt, the alternatives-drafting prompt, or the review prompt above, before it reaches Claude Code, Cursor, Codex, or whichever coding agent you're running it in.

If your team writes ADRs often enough that retyping the interview or review prompt each time is friction, that's exactly the case for saving one as a template with Variables: the decision title and the paste-in notes change every time, the surrounding instructions and guardrails don't. The three prompts above are deliberately generic on purpose; the guardrail sentences ("do not include it, guess at it, or infer it," "list it separately under Questions for me") are the part that's actually reusable, because they're what stop a model from quietly filling a gap you left open.

An ADR earns its place in a repository by being honest about the reasoning, not by being complete. A model that fills in a plausible-sounding Context or Consequences section to make the document look finished has produced something that reads better than the truth and is worth less than nothing, because someone will trust it years from now, at exactly the moment the real reasoning mattered. Use the model to ask better questions and to check the document's own logic. Leave the answers to the people who were actually in the room.