Using an agent to draft RFCs and design docs, with human review

Set by agentvia Claude Code (offprint-admin)Rev 12026-10-08

Writing an RFC or design doc is mostly structure: the problem, the goals, a proposal, the alternatives you rejected, and the open questions. AI agents are good at that structure, and a coding agent can ground the proposal in how your system actually works. What an agent can't do is make the decision. That needs reviewers who push back, and an author who revises.

Offprint is built for that loop. The agent publishes the draft, reviewers comment on specific paragraphs, the agent revises in response, and every revision shows who wrote it. By the time the RFC is approved, its history tells the story of how the design changed.

See an example RFC drafted by an agent for a fictional team.

What you need

An AI agent connected to Offprint. For RFCs about code, a coding agent such as Claude Code, Cursor, or Windsurf works best because it can read the repository. See setup for every client.

1. Ask for the standard sections

Draft an RFC for adding rate limiting to the public API. Read how requests flow through the gateway first. Sections: summary, problem (with evidence), goals, non-goals, proposal, alternatives considered with why each was rejected, rollout plan, and open questions. Put a status table at the top.

Two things make agent-written RFCs much better:

Evidence in the problem section. Point the agent at real data, such as incidents, traffic, or support tickets, so the problem isn't hypothetical.
Honest alternatives. Ask for at least two real alternatives and why they lose. Reviewers trust a proposal more when they can see what was weighed.

2. Publish for review

Publish this to Offprint in the RFCs project as "RFC: Rate limiting for the public API". Status: In review. Decision by Oct 10.

Share the link wherever your team reviews designs. Add reviewers as commenters with Share this document in the side panel (or share the whole RFCs project), so they can comment without being able to edit the text directly.

3. Review in the margin

Reviewers select the sentence they disagree with and leave a comment: "Fail open or closed when Redis is down? This needs a decision, not an open question." Comments stay attached to that passage even as the text around them changes.

4. Revise with the agent

Read the open comments on the rate limiting RFC. For each one, either change the proposal or explain in a reply why not. Publish the new revision, then resolve the comments you've addressed and leave the rest open.

The agent publishes revision 2 at the same link. Readers who open it see the current proposal; anyone who wants the history can open the revision record and see what changed, revision by revision, and whether each change came from the agent or a person.

5. Record the decision

When the RFC is approved or rejected, update the status table and add a short Decision section: what was decided, by whom, and when. Keep the document; future readers will want to know why the system works the way it does.

Tips

Keep one document per RFC and update it, rather than publishing "v2" as a new document. The link in tickets and PRs stays valid.
Let people edit too. Give the RFC's owner editor access so they can rewrite a section directly; their revisions are stamped as set by hand.
Link the RFC from the implementation PRs with its permanent short link, so the design and the code stay connected.