A Technical Design Doc Prompt That Holds the RFC Structure

A technical design doc prompt earns its keep when it stops every author from inventing a new doc structure. Context, the options you considered, why you picked one, what breaks, how you roll it out. Same shape every time, so reviewers know where to look. The hard part isn't writing prose. It's holding that structure across a long document without a section quietly going missing.

The tools online fall into two buckets. Conversational generators that ask you twenty questions and hand back a doc. Galleries of example RFCs from big companies, useful for inspiration, useless as a reusable prompt. Neither gives you a locked output contract you can run on every design, which is the thing that actually makes the docs comparable.

This covers a prompt that fixes the section order, the model behavior on long docs, and why the clarifying-question loop is usually a trap.

What you can do with this prompt

• Turn a rough proposal into a full RFC skeleton in one pass
• Force a real "alternatives considered" section instead of one option dressed up
• Score tradeoffs against named criteria so the decision is defensible
• Surface failure modes before code, not in the postmortem
• Mark unknowns as open questions instead of letting the model guess
• Keep every team doc in the same shape so reviews go faster

Why the structure drifts on long docs

A design doc is a long, multi-section artifact, and that's exactly where models get sloppy. Early sections come back rich and detailed. By section nine the model starts compressing, merging headings, or dropping a section it covered implicitly. You don't notice until a reviewer asks where the rollback plan went.

The fix is an output contract that lists every required section, placed where the model still pays attention to it. On long generations that means near the end of the prompt, not buried at the top.

Anatomy of the prompt

Variables
  {{proposal}}    — the rough feature or system idea
  {{constraints}} — known limits (stack, deadline, team size)
  {{criteria}}    — what to score options against (e.g. cost, risk, speed)

Prompt
  Role: staff engineer writing an RFC for design review.
  Task: turn {{proposal}} into a design doc. Produce at least two
  real alternatives scored against {{criteria}}. Mark anything you
  don't know from {{proposal}} or {{constraints}} as "OPEN QUESTION",
  never a guess.

Output contract (every section, in this order)
  1. Context and problem
  2. Goals / non-goals
  3. Proposed design
  4. Alternatives considered (>= 2, scored)
  5. Failure modes and mitigations
  6. Rollout and rollback plan
  7. Open questions

The "mark unknowns as OPEN QUESTION" rule is what makes the draft trustworthy. A model told to write a complete doc will fill gaps with confident invention. A model told to flag gaps hands you a map of what still needs a human decision.

How models behave on this specific job

Behavior on holding a long, multi-section doc, not on reasoning quality alone:

The honest read: GPT-4o reasons well inside a section but loses the macro structure on long docs, so the section contract has to stay near the end of the prompt where it still has weight. Claude holds structure better but will occasionally write two "alternatives" that are the same idea with different words. Read the alternatives section critically regardless of model.

1. Write the proposal rough

Drop the unpolished idea into {{proposal}}. A paragraph is enough. The prompt's job is to impose structure, so you don't need to pre-structure it.

2. State the constraints

{{constraints}} is where the real design lives. Stack, deadline, team size, the thing you can't change. The model can't infer your on-call rotation or your latency budget, so tell it.

3. Name the scoring criteria

{{criteria}} turns "this option is better" into "this option scores higher on cost and risk." Pick three. More than that and the table becomes noise.

4. Run and audit the alternatives

Go straight to the alternatives section. If the two options are the same idea twice, regenerate with a sharper criteria list. This section is the doc's reason to exist.

5. Resolve the open questions

The open-questions list is your to-do, not the model's failure. Each one is a decision a human has to make. Resolving them is the actual design work; the model just framed it.

Variables you'll set

An opinion worth holding

Skip the clarifying-question loop. The generators that ask you twenty questions before writing feel rigorous, but they stall the draft and the questions are usually things you'd have written into the doc anyway. A complete skeleton with gaps flagged as open questions beats an interrogation, because you can see the whole shape and fill the real decisions in context. Drafting is faster when you're editing a structure than when you're answering a quiz.

This is also why a reusable prompt beats a one-off. The section contract, the alternatives rule, the open-question convention all live in the prompt, not in the head of whoever wrote the doc last. New engineers inherit the standard for free.

Getting started

1. Copy the skeleton into your model.
2. Paste one real proposal into {{proposal}} and fill {{constraints}}.
3. Name three scoring criteria.
4. Run it, then audit the alternatives section for two genuinely distinct options.
5. Treat the open questions as your design to-do list.
6. For a workflow that scores tradeoffs and maps failure modes as a system, use a pack built for review, like the Technical Design Review Playbook.

Once the design is approved, the next step is turning it into guarded execution. The Spec-to-Code Harness takes a settled spec into a verified implementation plan, which picks up where the RFC leaves off. For the planning lens, the comparison of o3 vs Claude for planning covers which model holds a multi-step plan, and the spec-driven development walkthrough shows the handoff to an agent.