How to Prompt AI to Write a Design Doc
Most AI design docs are padding. Here is the six-section prompt, a stress-test follow-up, and a worked example that survive real engineering review.
How to Prompt AI to Write a Design Doc
Ask an AI model for "a design doc" and you get padding: an executive summary that restates the title, a goals section with no numbers, and a chosen approach with no alternatives considered. The fix is not a better model, it is a prompt that names the six sections a real design doc needs and refuses to let the model skip the two it always skips: what this doesn't solve, and how to roll it back.
Below is that prompt, the follow-up question that does most of the actual work, and a condensed worked example.
Why the default output is padding, not a decision record
A design doc exists so a reviewer who wasn't in your head can find the weak point before it ships. A generic prompt doesn't produce that, for a specific reason: the model doesn't know what your team already agrees on, so it hedges everywhere instead of committing anywhere.
No constraints stated, so none get respected. Ask for "a design for a rate limiter" and you get the textbook answer, not the one that fits your traffic pattern and your two-person team's on-call reality.
Alternatives get one throwaway line. Without being told to, the model writes the chosen approach and calls the section "options considered" without considering any.
Confidence is invented, not earned. A generic prompt returns a confident-sounding doc even when the underlying tradeoff is genuinely close. It will not tell you that unless asked directly.
Non-goals and rollback are the first casualties. They take real thought and don't make the doc look more finished, so a model optimizing for a satisfying-looking answer drops them first.
The six sections that make it useful
Give the model this list as a required structure, not a suggestion:
Problem and constraints. What's actually broken or missing, and the hard limits (team size, timeline, existing stack) that rule options out before you compare them.
Options considered. At least two real ones, each with a genuine tradeoff, not a straw-man option built to lose.
Chosen approach and why. The decision, tied explicitly back to the constraints in section one.
Non-goals. What this change deliberately does not attempt to solve, so nobody reads scope into it later.
Rollback plan. What you actually do if this ships and turns out to be wrong.
Open questions for reviewers. The two or three things you are genuinely unsure about, stated as questions, not buried in the prose.
The prompt
Write a design doc for [describe the problem in two or three sentences, including any hard constraints: team size, timeline, existing stack, compliance requirements].
Use exactly these six sections: Problem and Constraints, Options Considered, Chosen Approach and Why, Non-Goals, Rollback Plan, Open Questions for Reviewers.
Options Considered must include at least two genuinely viable approaches, not a strawman. State the real tradeoff of each, including the one you didn't pick.
In Chosen Approach, connect the decision explicitly back to the constraints stated above.
In Open Questions, list only things you are actually uncertain about. If there are none, say so rather than inventing filler questions.
Keep it under 700 words. This is a decision record, not a proposal deck.
The stress-test follow-up, where most of the value is
The first draft is a starting point, not a finished doc. Before you send it to reviewers, run one more prompt against it:
Read the design doc above as a skeptical senior engineer who did not write it. List the three most likely ways this could fail in production, ranked by likelihood. For each, state what specifically in the doc fails to address it.
This works because it changes the model's role from author to critic, and critics catch what authors miss. The output is usually where the real editing happens: a rollback plan that assumes a clean revert when the schema actually changed, or a chosen approach that quietly depends on a service that doesn't have the uptime this feature needs.
A worked example, condensed
Problem: a public API is getting hammered by a handful of accounts, degrading response times for everyone else. Constraints: two-person team, no budget for a managed API gateway, ships this sprint.
Options Considered, as the model returned them: a fixed per-key request cap with Redis, which is simple and cheap but treats a legitimate traffic spike the same as abuse; and a sliding-window cap with a burst allowance, which handles spikes better but adds a second moving part to monitor. Chosen Approach: the sliding-window version, because the constraint that actually mattered was "don't page a two-person team over a legitimate traffic spike," not implementation simplicity. That line only appears because the constraint was stated up front. For the implementation details once you've settled on an approach, see our guide to adding rate limiting to an AI-built app.
Where this still goes wrong
Three failure modes to watch for even with a good prompt. First, a doc that reads as more settled than the team actually is, because confident prose is what the model defaults to. If your team is genuinely split on an approach, say that explicitly in the prompt rather than letting the doc paper over it.
Second, treating the output as final. The stress-test follow-up exists because a first draft that looks finished is exactly the one that skips the hard question. Read it like you didn't write it, and be honest about which of its three predicted failure modes you'd actually catch in code review versus which would ship quietly.
Third, copying constraints from an old doc instead of restating them. Teams reuse a working prompt across projects, which is fine, but the constraints section is the one part that has to be rewritten every time. A rate limiter design and a database migration design fail for completely different reasons, and a doc that inherits the wrong constraints will confidently solve the wrong problem.
Frequently asked questions
How long should a design doc be for a small team?
Short enough that a reviewer reads the whole thing. Under 700 words covers most feature-level decisions; save the longer format for genuinely architectural changes. The six-section prompt above naturally caps length because it forces substance over padding.
Should I let the AI pick the chosen approach, or just describe the options?
Let it propose one, but treat the choice as a draft, not a verdict. The value of Options Considered is that you can see the tradeoff and overrule it. An AI that only lists options without picking one pushes the hardest part of the work back onto you for no reason.
What if my team doesn't do formal design docs?
Use this for anything non-trivial you'd otherwise decide in a Slack thread and regret not writing down. A rough version beats no version, and the format is short enough that it doesn't need to become process to be worth doing. If you want a version tuned for after something breaks instead of before you build it, see our guide to prompting AI to write a postmortem.
Can I reuse this prompt for an architecture decision record (ADR)?
Yes, with one change: rename "Chosen Approach and Why" to "Decision" and add a "Status" field (proposed, accepted, superseded). ADRs and design docs are close enough in structure that the same six-part skeleton covers both; only the surrounding ceremony differs. The same discipline applies to writing the operational side of a decision. See our guide to prompting AI to write a runbook.
For more on getting useful, specific output instead of confident-sounding filler, see our guide to prompt engineering fundamentals.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
