How to Use AI to Draft RFC Documents for Proposed Open

Artificial intelligence has become a valuable assistant for open source maintainers and contributors drafting Request for Comments (RFC) documents. When proposing new features to open source projects, a well-structured RFC helps reviewers understand your proposal, its rationale, and implementation details. AI tools can accelerate this process significantly.

Understanding RFC Documents in Open Source Projects

RFC documents serve as formal proposals for changes to open source projects. Most large open source projects—including Kubernetes, Rust, and Django—have established RFC processes that require contributors to document their proposed changes before implementation begins.

A typical RFC includes several key sections: a summary of the proposed change, motivation for the change, detailed design, alternatives considered, and potential drawbacks. Writing these sections from scratch takes time, especially when you need to match the project’s specific RFC template and conventions.

Using AI to Structure Your RFC

AI tools excel at generating structured content based on your requirements. To get the best results, provide the AI with context about the project, its existing RFC process, and specific details about your proposed feature.

Start by explaining the project and its RFC template requirements:

I need to write an RFC for an open source project that uses the following RFC template:
1. Summary
2. Motivation
3. Detailed Design
4. Alternatives Considered
5. Drawbacks
6. Unresolved Questions

The project is a Python CLI tool for managing database migrations. I want to propose adding support for reversible migrations that can automatically generate both forward and backward migration scripts.

Please draft the RFC document following this template, focusing on a feature that allows developers to mark migrations as reversible and automatically generate rollback scripts.

The AI will generate a structured draft that you can then refine with specific implementation details.

Drafting the Motivation Section

The motivation section explains why the proposed change matters. This is where AI can help you articulate the problem your feature solves.

Provide the AI with specific pain points you’re experiencing:

The motivation for reversible migrations in our database migration tool:
- Developers currently must write rollback scripts manually
- Many teams skip writing rollbacks, making production rollbacks dangerous
- New contributors don't understand the expected rollback patterns
- Rollback scripts often become out of sync with forward migrations

Help me write a compelling motivation section that explains these problems with concrete examples.

AI can transform bullet points into flowing prose that clearly communicates the problem to reviewers.

Generating Technical Design Details

The detailed design section requires precise technical explanation. Here, AI serves as a collaborative partner rather than a complete solution generator. You provide the technical constraints and requirements, and AI helps structure the explanation.

I need help writing the detailed design section for reversible migrations. Here are the technical constraints:

1. The migration format is SQL files in a migrations/ directory
2. Each migration has an up.sql and optional down.sql file
3. We want to add a metadata table tracking migration reversibility
4. The CLI should detect reversible migrations automatically based on the presence of a _reversible marker
5. Rollback should use transactions to ensure atomicity

Please help me structure the detailed design section with these components:
- Database schema changes
- CLI command changes
- File naming conventions
- Error handling for failed rollbacks

This approach uses AI’s strength in organizing technical information while you provide the domain-specific constraints.

Creating Code Examples

Including working code examples strengthens any RFC. AI can generate example implementations, API signatures, or CLI output that demonstrates your proposed feature.

For the reversible migrations RFC, you might ask:

Generate example CLI output showing how a developer would use the new reversible migration feature. Include:
The command to create a new reversible migration
The generated migration files structure
The command to run a reversible migration
The automatic rollback command
Error output when rollback fails

AI can produce realistic CLI output that helps reviewers visualize the feature in action.

Documenting Alternatives and Drawbacks

Strong RFCs acknowledge alternatives and drawbacks. This demonstrates you’ve thought through the design thoroughly. AI can help brainstorm alternatives you might not have considered.

For the reversible migrations feature, what alternative approaches should we consider?
- Using a migration framework that handles reversibility automatically
- Requiring all migrations to be reversible by default
- Using a different file naming convention
- Storing rollback SQL in a separate database table instead of files
- Using a version control approach where rollbacks are generated on-demand

For each alternative, explain why it wouldn't work as well as the proposed approach.

Similarly, AI can help identify potential drawbacks:

What are the potential drawbacks of implementing automatic reversible migrations?
Consider:
- Performance implications of tracking reversibility metadata
- Edge cases where automatic rollback might not work correctly
- Developer confusion about what makes a migration "reversible"
- Database-specific SQL that might not have a clear reversal
- Breaking changes where no meaningful rollback is possible

Refining the RFC for Your Project

Every open source project has specific conventions for RFCs. Review existing merged RFCs in your project to understand the expected format and tone. AI can adapt its output to match these conventions once you provide examples.

Provide the AI with the project’s existing RFCs:

Here are three example RFCs from our project that were accepted. Notice the style, level of detail, and format. Please draft my new RFC following the same patterns:

[Provide examples from 2-3 existing RFCs]

This ensures your AI-generated draft matches project expectations.

Real RFC Examples and Patterns

Study existing RFCs from major projects to understand tone and structure:

# RFC Example: Rust RFC 2019-12
## Title: Stabilize the Async/Await Syntax

### Summary
This RFC proposes stabilizing async/await syntax for futures-based
concurrency in Rust 2018 edition.

### Motivation
Current closure-based approach requires understanding advanced type system
features. Async/await syntax makes asynchronous code feel natural.

### Detailed Design
- Add `async` keyword to function definitions
- Add `await` postfix operator for future execution
- Error handling through standard Result type
- Cancellation via drop semantics

### Alternatives Considered
1. Macro-based approach (deemed too complex)
2. Generators + yield (insufficient for error handling)
3. Callback-based API (original approach, poor ergonomics)

### Drawbacks
- Compiler complexity increases
- New surface area for potential bugs
- Learning curve for developers unfamiliar with futures

When you provide AI tools with 2-3 examples of accepted RFCs, the quality of generated output improves dramatically.

RFC Template for Common Patterns

Create project-specific templates that AI tools can use:

# RFC Template for {PROJECT_NAME}

## Summary
One paragraph describing what this RFC proposes. Keep it 1-2 sentences.

## Motivation
Why do we need this change? What problems does it solve? Include specific
use cases that motivate the change. Quantify impact where possible.

## Detailed Design
The core of the RFC. Include:
- New API signatures or configuration format
- Database schema changes if applicable
- Behavioral changes to existing features
- Migration path for existing users

Include code examples showing before/after.

## Alternatives Considered
List other approaches and explain why they're insufficient compared to
the proposed design. Demonstrate that the proposed approach is optimal.

## Drawbacks and Limitations
Be honest about trade-offs. What functionality might this remove?
What performance implications exist? What future constraints does this
introduce?

## Unresolved Questions
What aspects remain unclear? What aspects might need further discussion
during implementation?

## Implementation Timeline
Estimate effort and timeline. Break into phases if complex.
- Phase 1: Core implementation (~2 weeks)
- Phase 2: Documentation (~1 week)
- Phase 3: Testing and feedback (~1 week)

Using a consistent template across all RFCs accelerates both writing and review.

AI Tool Recommendations for RFC Writing

Claude Code: Best for complete RFC generation from requirements. Excels at writing motivation sections that articulate problems clearly.

GitHub Copilot: Good for filling in code examples and API signatures once you’ve drafted motivation and design sections.

Cursor: Excellent for iterative RFC refinement through conversation. If you have a rough draft, Cursor’s chat interface helps you strengthen weak sections.

GPT-4: Good at alternative analysis. Provide your main proposal, and ask GPT-4 to generate compelling alternatives you may not have considered.

Converting RFC Feedback to Implementation

Once your RFC is accepted, AI tools help convert feedback into refined specifications:

RFC Feedback received:
1. "Unclear how this handles edge case X"
2. "Performance implications not addressed"
3. "Migration path needs more detail for existing users"

Prompt to AI:
"Based on this RFC feedback, help me expand the following sections:

1. Edge case handling for X (add 3 specific code examples)
2. Performance analysis section (benchmark comparisons with current approach)
3. Detailed migration guide (step-by-step for users with existing setup)

Maintain the same technical tone and depth as the original RFC."

The AI generates expanded sections that directly address reviewer concerns.

Best Practices for AI-Assisted RFC Writing

Getting good results from AI requires providing clear context and iterating on the output. Here are practical tips:

Provide complete context upfront. Include the RFC template, project background, and your specific feature requirements in the initial prompt. This reduces the need for multiple clarification rounds.

Review critically. AI generates plausible content that may contain inaccuracies, especially around technical details. Always verify the generated content matches your intended design.

Iterate incrementally. Generate sections one at a time rather than asking for a complete RFC in a single prompt. This allows you to refine each section before moving to the next.

Maintain your voice. Use AI to structure and draft, but add your own analysis and insights. The best RFCs reflect the author’s deep understanding of the problem space.

Built by theluckystrike — More at zovo.one