用途
create-rfc 用于为需要跨团队评审和共识的重大技术提案创建结构化的 RFC(Request for Comments)文档。RFC 比 ADR(架构决策记录)更重,适用于以下情况:提案影响多个团队、引入新基础设施、改变核心抽象,或影响范围大到需要在承诺前获得结构化反馈。
主要能力
该技能提供一套完整的工作流:
- 阅读项目上下文:读取 .chalk/docs/engineering/ 中已有的架构文档、ADR 和先前的 RFC,理解当前系统状态,使提案建立在已有决策之上而非与之矛盾。
- 确定下一个 RFC 编号:列出 .chalk/docs/engineering/ 中匹配 rfc.md 模式的文件,找到最大编号并加 1;若不存在 RFC,则从 1 开始。
- 澄清提案范围:从参数和对话上下文中识别具体技术变更、动机(为何是现在)、受影响的团队和系统,并判断是否适合用 RFC(若为单团队决策且影响范围有限,建议改用 ADR)。范围模糊或过宽时向用户询问澄清。
- 调研设计空间:调查代码库中与提案交互的现有模式、.chalk/docs/engineering/ 中约束或影响设计的先例、至少 2 种备选方案,以及已知风险、失败模式和运维问题。
- 起草 RFC:使用规定的格式撰写完整 RFC,要求具体且有立场,诚实记录权衡。
- 制定评审计划:指定评审人、所需反馈和推荐评审周期。标准提案默认 5 个工作日,影响核心基础设施的提案默认 10 个工作日。
- 写入文件:保存到 .chalk/docs/engineering/<n>rfc<proposal_slug>.md。
- 确认:告知用户 RFC 已创建、路径、一句话提案摘要和推荐评审时间线。
使用方式
文件命名约定为 <number>_rfc_<snake_case_proposal>.md,例如:
- 5_rfc_migrate_to_event_driven_architecture.md
- 9_rfc_unified_authentication_service.md
- 14_rfc_adopt_feature_flags_platform.md
RFC 格式包含以下章节:标题(RFC-<number>: <Proposal Title>)、最后更新日期、状态(Draft | In Review | Accepted | Rejected | Withdrawn | Superseded by)、评审周期(开启/关闭日期、决策方法、必需评审人)、摘要、动机(问题陈述、为何是现在、目标与非目标)、详细设计(架构概览含 Mermaid 图、关键设计决策、API/接口变更、数据模型变更、迁移策略、运维考量)、缺点、备选方案、什么都不做、未解决问题、未来可能性、参考资料。
适用场景
- 影响多个团队的技术变更
- 引入新基础设施组件
- 改变核心抽象或 API 契约
- 需要迁移现有系统
- 需要带截止日期的结构化评审周期
限制与规则
该技能明确区分 RFC 与 ADR:单团队实现决策、已知库/工具之间的选择适合用 ADR;若不确定,先写 ADR,若评审者认为需要更多讨论再升级为 RFC。
评审周期指南:团队级基础设施变更 3-5 个工作日(团队负责人批准);跨团队 API 或数据模型变更 5-7 个工作日(受影响团队共识);核心基础设施或平台变更 7-10 个工作日(架构评审 + 指定批准人);组织级流程变更 10+ 个工作日(带明确超时的惰性共识)。
写作质量规则要求:摘要让 VP 仅读摘要即可理解提案;动机先讲问题而非解决方案;详细设计具体到另一位工程师无需额外设计会议即可实现;缺点至少列出 2 个;未解决问题必须包含当前倾向。
反模式包括:为琐碎决策写 RFC、没有缺点章节、混合多个提案、没有未解决问题、解决方案优先的动机、无限评审周期、文档中的委员会设计、没有迁移策略。