lockstep
5 min readNaman Jain

Engineering RFC template, with an example

A free engineering RFC template based on the Rust project's: each section explained, a filled-in example, and a review process with a final comment period.

An engineer posts an RFC for moving the monolith's auth into a separate service. It gets forty comments in two weeks, three competing counter-proposals, and no decision. A month later, half the team assumes it was approved and starts building against it; the other half assumes it died.

The template is rarely the problem. The process around it is. This guide gives a template based on the Rust project's, which many teams copy, and the parts of its process worth borrowing, from the Rust RFC repository, checked on 16 November 2026.

What an RFC is for

A request for comments proposes a significant change and asks for feedback before it's decided and built: a new public API, a data migration, a change to how the team works. It's a decision document with a review attached. For smaller, single decisions an ADR is lighter; for recording a full design, see the technical design document template.

The template

# RFC: [Title]

- Author: [Name]
- Decider: [Name]
- Status: Draft / In review / Final comment period / Accepted / Rejected / Postponed
- Comments close: [Date]
- Start date: [Date]

## Summary
[One paragraph.]

## Motivation
[The problem, with background and specific use cases. Why it matters.]

## Guide-level explanation
[Explain the change as if it already shipped, to the people who'll use it.
Examples first. What changes for them?]

## Reference-level explanation
[The technical design: how it works, how it interacts with existing
systems, and corner cases by example.]

## Drawbacks
[Why we should not do this.]

## Rationale and alternatives
[Why this design over others. What else was considered, and why not.
What happens if we do nothing.]

## Prior art
[How others solved this, good and bad.]

## Unresolved questions
[What this RFC should settle before acceptance, and what can wait.]

## Future possibilities
[Where this naturally leads.]

## Outcome
[Filled in at the end: decision, date, decider, and the reasoning.]

How to fill in each section

Motivation. Rust's template calls it one of the most important sections. Specific use cases do the persuading; general benefits don't.

Guide-level explanation. Write as if the change already exists and you're teaching it. This catches proposals that are clever to build and confusing to use.

Reference-level explanation. The technical design, detailed enough that interactions with other systems and corner cases are clear.

Drawbacks. Rust's README notes that RFCs that are disingenuous about drawbacks or alternatives tend to be poorly received. Name the real costs.

Rationale and alternatives. Include "do nothing." If doing nothing is acceptable, say why this is worth it anyway.

Unresolved questions. Separate what must be settled before acceptance from what can be settled during implementation.

Outcome. Not in Rust's template, because the merged or closed pull request records it. In a doc tool, add it, so the RFC states its own result.

A filled-in example (abridged)

# RFC: Cursor-based pagination for the public API

- Author: Arjun   Decider: Priya   Status: Accepted
- Comments close: 2026-10-20

## Summary
Replace offset pagination with opaque cursors on all list endpoints
in API v2.

## Motivation
Customers syncing large accounts see duplicates and gaps when records
change between pages. Offset queries over 50,000 rows take over 2 s.

## Guide-level explanation
List responses include next_cursor. Pass it as ?cursor= to get the
next page. Cursors are opaque and expire after 24 hours.

## Reference-level explanation
Cursors encode (sort key, id), signed. Queries use keyset pagination
on existing indexes. v1 offset endpoints are unchanged.

## Drawbacks
No jumping to page N. Two pagination styles during the v1 overlap.

## Rationale and alternatives
- Keep offsets with snapshot reads: fixes gaps, not slow deep pages.
- Page tokens with server state: works, but adds storage per client.
- Do nothing: sync complaints are the top API ticket category.

## Unresolved questions
- Cursor lifetime: 24 hours or 7 days? (Settled: 24 hours.)

## Outcome
Accepted 2026-10-21 by Priya. v2 only; v1 offsets stay until v1 sunset.

The process matters more than the template

What to borrow from Rust's process:

  • Discussion in one place. Rust keeps it on the pull request, and summarizes offline discussion there.
  • Changes as new commits. Don't rewrite history once people are reviewing.
  • An explicit disposition. A team member proposes merge, close, or postpone, usually after a summary comment of the state of the discussion and the main trade-offs.
  • A final comment period. After every team member signs off on the proposal, a ten-day window gives stakeholders a last chance to object. Most of the time it's quiet and the RFC is merged or closed.
  • Postponed is a real outcome. Not every good idea is right now.

Smaller teams can compress this: one named decider, a comment deadline, a short final call, and the outcome written at the top.

After acceptance

An accepted RFC is a set of decisions: cursor pagination, v2 only, 24-hour lifetime, v1 untouched. They need to reach the people building against them, including AI coding agents writing the next endpoint, who will otherwise copy the offset pattern they see in the existing code.

Where Lockstep fits

Lockstep captures decisions like these from documents, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply to the code being changed. When a later RFC changes a decision, the new version supersedes the old one and both stay visible.

See how it works.

Sources checked 16 November 2026

For recording the individual decisions an RFC produces, see architecture decision record examples. For who decides, see RACI vs DACI. For how RFCs compare with ADRs and design docs, see ADR vs RFC vs design doc vs PRD. For API conventions worth recording, see API design best practices. For running the review meeting, see the architecture review template.

Frequently asked questions

What is an engineering RFC?
A request for comments: a written proposal for a significant change, such as a new API, a migration, or a process change, shared so others can comment before it's decided and built. The term comes from the internet standards process; engineering teams adopted it for internal proposals.
What should an RFC include?
Rust's template uses: summary, motivation, guide-level explanation (how users will think about it), reference-level explanation (the technical design), drawbacks, rationale and alternatives, prior art, unresolved questions, and future possibilities.
What is the difference between an RFC and a design doc?
They overlap heavily. An RFC emphasizes the request for feedback and an explicit decision process, often with a comment deadline. A design doc emphasizes recording the design and its trade-offs. Many teams use one document for both.
What is a final comment period?
In the Rust RFC process, once trade-offs are discussed, a team member proposes a disposition (merge, close, or postpone) and, after every team member signs off, a ten-day final comment period begins so stakeholders can raise last objections before the decision.
How do I keep RFCs from stalling?
Name one owner and one decider, set a comment deadline, and record the outcome, including rejections. An RFC with no deadline and no decider collects comments indefinitely.

Keep reading