Reverse Documentation — The RFC That Would Have Produced This Code
Take this completed codebase. Generate the design doc as if it didn't exist yet. The RFC. The architecture review notes. The objections from a skeptical staff engineer. The compromises that produced these specific tradeoffs.
Why this exists
Most teams skip the RFC. The code ships, the Slack thread scrolls off, the original author rotates teams, and the reasoning is gone. What remains is a finished sentence with no paragraph behind it — every future maintainer has to guess at the why. Reverse documentation treats the codebase as the artifact and works backward to the design conversation that should have produced it.
What you get back
- An RFC reconstructed from the code as it actually exists — goals, non-goals, proposed design, rollout.
- Simulated review comments from skeptical staff engineers, each pointed at a specific decision the code reveals.
- The objections raised during review and how they were resolved — including the ones that lost.
- The specific tradeoffs the implementation makes visible: what was bought, what was paid, what was deferred.
When to reach for this pattern
Onboarding a new engineer into a system nobody wants to explain. Preparing for a major rewrite and needing to surface the constraints before you delete them. Documenting a service whose original authors are gone. Teaching architecture by example, using a real codebase as the textbook instead of a toy one.
Take this completed codebase and generate the design doc as if it
didn't exist yet. Write the RFC that would have led to this exact
implementation. The architecture review notes. The objections from
a skeptical staff engineer. The compromises that produced these
specific tradeoffs. Make it feel like a real design process — not
a victory lap.Paste this into Claude, Cursor, or Copilot. Change one thing that matters to you.
What I learned shipping it
- Most code ships without an RFC, and the reasoning evaporates the moment the PR merges — someone always has to reconstruct it later under worse conditions.
- Reverse-engineering the design conversation is more useful than after-the-fact prose, because the conversation is where the constraints live.
- The objections matter more than the proposal. A design doc without dissent is marketing copy.