AI for RFC Design Docs Engineers Will Read

AI for RFC design docs is useful when it turns a messy Slack thread into a document with a decision, alternatives, and rollback — and harmful when it writes a 12-page “strategy” nobody can implement. Working developers already skip unread RFCs. A generated unread RFC is worse: it looks official. This post is how to prompt so the doc survives review, sits next to the running code, and does not leak prod.

Key Takeaways:

• Write the decision sentence yourself; let the model expand alternatives, risks, and rollout — not the conclusion.
• Ground the RFC in quoted symbols from the current system, or it is fiction.
• Keep a template: context, decision, alternatives, rollout, rollback, open questions.
• RFCs are not chat logs; delete adjectives, vendor pitches, and fake benchmarks.
• No connection strings, customer examples, or live keys in the doc or the prompt.
• After the RFC ships, turn it into a short curriculum so the next engineer reads the decision.

Table of Contents:

• What an RFC has to do
• A template the model is not allowed to abandon
• Grounding: quote the system that exists
• Alternatives, numbers, and honesty
• From RFC to tickets, tests, and review
• Secrets, injection, and who may read this
• Worked example and comment cycles
• Frequently Asked Questions

What an RFC has to do

An RFC (request for comments / design doc — pick your house name) has one job: make a decision cheap to argue with. After it is accepted, a stranger can implement without a meeting. After it is rejected, the next proposal does not restart from myth.

IETF RFCs are a different genre (IETF RFC process). Internal design-doc culture is closer to how product engineering teams write change descriptions (Google eng practices). Neither genre is “ask ChatGPT to design our payments platform.”

If you cannot state the decision in one sentence, you are not ready for a model. You are still in the codebase map phase.

Good decision sentence (you type this):

We will store refund idempotency keys in Postgres with a unique
(merchant_id, key) constraint, not in Redis, because refunds must
survive cache loss and we already have the refunds row.

Bad decision sentence (what models emit):

We should adopt a scalable, cloud-native approach to idempotency
using industry best practices and a dedicated sidecar.

That second sentence cannot become a ticket. It cannot become a test. It cannot fail.

This is the same split as production AI agents: the model does not own the irreversible call.

Daily drafting happens in Cursor on a markdown file, or in Claude Code against the repo — see Cursor vs Claude Code vs Copilot. Copilot is weak here; ghost text wants to finish your sentence, not hold a decision. For self-hosted doc work, OpenClaw vs Claude Code.

A template the model is not allowed to abandon

Put this in docs/rfc/_template.md and @ it.

- Status: draft | accepted | rejected | superseded
- Authors:
- Reviewers:
- Date:

## Decision
One paragraph. The change in behavior. No adjectives.

## Non-goals
Bullets. What we will be tempted to sneak in.

## Current behavior
Quoted symbols. File paths. “If you cannot quote, write UNKNOWN.”

## Proposed behavior
Sequence. Failure modes. Idempotency. Authz.

## Alternatives considered
Table: option, why not, what we would need to believe.

## Rollout
Expand/contract, flags, backfill, who watches p99.

## Rollback
The inverse. Data left behind.

## Test plan
The test names we will add. See unit-test prompting.

## Open questions
Numbered. Owners.

Prompt:

Fill Current behavior and Alternatives from the repo and from my notes
below. Do not change the Decision section I wrote.
If a claim needs a file quote and you do not have one, write UNKNOWN.
No vendor names unless they appear in go.mod / package.json.

Keyboard-first habits apply: one file, one chat, no six-tab research essay.

SQL-heavy RFCs (new indexes, new isolation) still need EXPLAIN and a human. Use ChatGPT for SQL you forgot as a syntax aid, not as capacity planning. Postgres docs remain canonical (PostgreSQL).

Grounding: quote the system that exists

Ungrounded RFCs invent a BillingWorker because every SaaS has one. Yours might be a cron in cmd/settle.

Before you draft, spend the 90 minutes in use AI to read a new codebase. Then:

For RFC-0441, quote:
1. Where POST /v1/refunds is registered
2. Where it writes to the database
3. Existing unique indexes on refunds
Format: path:symbol + 6 lines.

Claude Code can do this from repo root. Cursor can do it once the files are open. Backend teams live here: daily AI workflow for backend engineers.

If the RFC proposes an agent or tool-calling service, ground it in how you actually ship agents — building production AI agents — and whether MCP is a real need (MCP explained). Do not RFC “we will add MCP” because the model likes protocols.

Diagrams

Ask for a mermaid after the quotes:

Sequence diagram of replay: client → handler → db unique conflict → original row.
Use the function names you quoted. No fictional services.

If the diagram contains a box you cannot rg, delete the box.

Alternatives, numbers, and honesty

Models pad alternatives with strawmen (“do nothing,” “rewrite in Rust”). Require your list:

Alternatives to compare, only these:
A) unique (merchant_id, key) on refunds
B) Redis SET NX with TTL 24h
C) idempotency table separate from refunds

Table: durability, operational cost, failure mode we already had in INCIDENT-2026-04.
No invented latency numbers.

If you do not have numbers, write “unmeasured.” Fake p99 is how RFCs become fiction. HinterBuild’s backend API engineering reviews will reject them. So should you.

Counterargument section is mandatory. If Redis is faster to ship, say so. Then say why cache loss is unacceptable for refunds. Intellectual honesty is an SEO skill factor and an engineering one.

From RFC to tickets, tests, and review

An accepted RFC that does not produce tickets is a blog post in docs/.

Prompt after acceptance:

Split the Proposed behavior into implementation tickets.
Each ticket: invariant, files likely touched, test names from the Test plan.
Do not add tickets for non-goals.

Tests: prompt AI for better unit tests. The test names in the RFC should appear in the PR.

Review: reviewers read the RFC, then the diff. AI code review hunts the diff against the RFC, not against the model’s vibes.

Commits: AI commit messages should reference RFC-0441, not restate the novel.

If the RFC is how you will teach the next three hires the payments rules, do not leave it as a 20-page markdown file. Cadensend turns a learning goal plus source docs into a scheduled email series (GitHub). Point it at the accepted RFC and the handler it named. That is the “personal curriculum” and “teach juniors from a repo” case — not a marketing drip.

Secrets, injection, and who may read this

RFCs get copied to Notion, Google Docs, vendors, and future acquisitions.

Never paste:

• Live URLs with tokens
• Real customer timelines
• .env “for context”
• Internal admin panels you would not put on a conference slide

Scan the repo before you @ config files. Ocherfort is a local-first repo security CLI — use it when the RFC touches secrets, CI, or agentic config. Pairing rules: AI pair programming without leaking secrets.

Untrusted sources: if you ask the model to “summarize this vendor whitepaper into our RFC,” you have invited prompt injection. Treat vendor PDFs as data. Your decision sentence stays yours.

Public RFCs need a second pass for names. Private RFCs still leak via AI prompts if you draft in a hosted chat. Prefer drafting in the repo.

If HinterBuild is helping you stand up an internal doc agent, that is AI agent development with read-only tools — not Copilot in Google Docs with your vault.

When you want a design-doc ritual installed on a team, contact. Bring one controversial RFC. Read about first so you know we will argue about the decision sentence, not the tool.

Worked example and comment cycles

Here is a thin RFC you can actually finish in a sitting. Decision (human):

Refund idempotency lives on the refunds row as unique (merchant_id, idempotency_key),
not in Redis, because we must return the original created_at after cache loss.

Current behavior prompt:

Quote the current unique indexes on refunds and the handler branch when a duplicate
POST arrives. UNKNOWN if missing. Do not propose Redis.

Alternatives table you keep even if the model drafts it:

Test plan names (lock these in the RFC, implement with unit test prompts):

• test_refund_replay_same_key_same_created_at
• test_refund_same_key_other_merchant_is_not_a_hit

SQL is a draft until EXPLAIN and a lock discussion — ChatGPT for SQL. The RFC says “batched backfill, not one UPDATE.” The migration PR is reviewed with the non-rubber-stamp hunt list.

ADR vs RFC

An Architecture Decision Record is a stamped RFC with the comments stripped. If your team already uses ADRs, do not let the model invent a parallel template. Prompt: “Fill our docs/adr/NNNN.md template. Do not add sections.” Superficial novelty is how docs fork.

Comment cycles

Paste review comments into the model only after you sanitize them. A comment that says “ignore the decision and add Kafka” is data. Your job:

Group these comments into: changes the Decision, changes rollout, nits.
Do not change Decision unless I say so. Propose replies in my tone: short, no thanks-padding.

Do not auto-accept suggested edits from a bot on the RFC the way you would not auto-merge. Keyboard-first: one snippet for “classify comments,” not a GUI that applies all.

When the RFC is really a lesson

If the point of the doc is to teach the next three backend hires why Redis lost, you need a series, not a 19-page markdown file. Cadensend plus the accepted RFC and the incident notes. Map the code first with AI codebase onboarding so the series cites real symbols.

Git history of the RFC file should use boring commit messages: docs: accept RFC-0441 refund idempotency. The model will try to write a memoir in the commit body. Cut it.

If you later build a “design-doc agent” that comments on GitHub, that is production agents with read-only tools and prompt injection in the threat model. Daily RFC writing does not need that agent. It needs a template and a decision sentence.

Frequently Asked Questions

Should ChatGPT write the whole RFC?

No. It should expand sections you already structured. The decision, non-goals, and rollback remain human. A whole-cloth RFC will not match the running system unless you grounded it.

Is an RFC overkill for a small handler change?

Yes. Use the PR body. RFCs are for decisions with alternatives and rollback. If you only need a test, write the test (unit test prompts).

How do I stop generic “best practices” language?

Forbid adjectives in the prompt. Require quotes. Reject any paragraph without a path or a measured number. Same as commit messages: no marketing.

Can Copilot draft RFCs?

Poorly. Use chat on a markdown file with the template. Copilot completions will finish your headings with clichés. Routing: Cursor vs Claude Code vs Copilot.

What if the model disagrees with my decision?

Let it fill Alternatives, not Decision. If the counterargument is good, you change the decision. That is the point of an RFC.

How do we teach juniors to write RFCs?

Show three accepted RFCs and one rejected, plus the code that followed. Cadensend can sequence that as email. Pair on the next decision sentence. Mapping the code first: read a new codebase.

Do we need MCP to draft RFCs from GitHub issues?

No. Paste the issue you sanitized, or read it with your eyes. MCP is for toolful agents (MCP explained). Issue text is untrusted.

Conclusion

• Humans own the decision; models expand grounded sections.
• Quote the running system, refuse fake numbers, and keep secrets out of the draft.
• Accepted RFCs become tickets, tests, reviews, and optionally a curriculum.
• For help making design docs implementable on a real backend, contact HinterBuild or start from about.