SuperAPI AI 工具集

create-rfc

写作与研究

查看项目

更新于 10-16 22:54

技能介绍

用途

create-rfc 用于调研、访谈并撰写一份工程 RFC。触发场景是:被要求创建 RFC,或从一个想法、笔记、已有草稿出发对 RFC 做实质性开发。产出目标是单一、自成一体、能够让未参与对话的工程师直接评审的 RFC。

该技能的边界明确:研究负责确立事实,访谈负责解决关键决策;全程维护同一份文档;技能在 RFC 评审环节结束,不包含实现或发布。

主要能力

  • 建立起点:阅读给定材料、相关仓库指引与既有 RFC 约定,识别问题、受众、约束、已定决策和关键缺口。若提供已有草稿,则以其为起始产物,保留其中已被接受的决策,聚焦矛盾或缺失的推理。
  • 文档位置约定:在仓库内使用 docs/rfcs/NNN-title.md,并向 docs/rfcs/README.md 添加条目,编号从 001 起选择下一个可用编号;在仓库外则使用合适的、用户可见的工作目录。后续修订保持在同一文件中。若目标位置为共享位置,在获授权发布前准备私有副本。
  • 初始 RFC:以已确立的事实和明确标记的开放问题形成初稿,作为单一设计文档使用,不再单独创建术语表、上下文文档、ADR 或研究报告。术语放在接近结尾处,其后在需要时放参考文献部分。
  • 分轮次调研与访谈:把设计梳理为决策及其依赖关系;每轮只问前置条件已定的、相互独立的关键问题,推迟依赖未答问题的问题。使用可控批量、稳定的问题编号、具体场景,并给出推荐答案及其主要权衡。适用时使用宿主的问题工具,否则用聊天。允许用户提出不同答案。
  • 事实调研:就事实性问题自行调查,先阅读相关代码、一手文档和可用的已连接来源,再让用户消解不确定性。在有帮助且可用时使用有界的独立研究代理,否则直接调研。综合与决策留在主导者手中,不把产品决策交给研究代理。
  • 小规模可逆实验:可用于解决设计问题,但需说明实验检验什么、保留既有工作与数据,并在证据足以回答后停止。重大环境搭建或实现前先询问;外部变更须在明确授权范围内。仅收到 RFC 请求并不授权部署原型、修改共享系统或联系他人。
  • 区分证据层级:区分来源支持的能力、观察到的行为、提议的设计、未验证的集成。来自单一构建或夹具的证据只能证明被实际检验过的部分。研究出处留在工作上下文或必需的私有笔记中。
  • 即时更新:每次回答后立刻更新 RFC 并重算未决事项,把用户的更正反映到正文、图和示例中,保留当前设计而非追加访谈记录。无新证据或矛盾时,不重开已定选择。
  • 深挖重点:围绕行为、范围、接口和有意义的权衡;常规且可逆的实现细节用工程判断决定;需要实现才能验证的技术检查留在未决问题中,并说明解决它所需的具体证据。

撰写要求

面向同行工程师写作:起草或重构时先读模板;先讲提案及其影响,再解释问题,并通过具体场景讲解用户可见行为,之后才引入实现细节。语言直接、平实,段落连贯。在有助于评估契约、权衡或失败模式处加入技术细节;领域特定术语在术语部分定义。示意性的 schema 字段或路由在选定前标注为暂定。

引用策略:仓库 RFC 中,面向读者的引用保持在该仓库内,除非用户要求外部引用。外部文档、会议和问题跟踪器可用于研究,但应把其中相关决策和推理并入文档,使读者无需打开它们即可理解提案。在关键论断附近使用指向仓库文件或固定源码修订的描述性链接。原始哈希、本地检出路径和来源清单放在工作笔记而非正文中。在仓库外工作时适用用户的引用策略。

图示:当图比文字更能清楚表达关系时使用 Mermaid——架构用组件视图,以子图表示有意义的归属或部署边界,折叠内部与提案无关的平台;请求、回调和后台流程用时序图,标明处理程序在哪里执行、持久化在哪里发生;生命周期转换和终止状态用状态图。在有助于阐明契约处包含代码、资源或 API 示例,并保持示例与权限、身份、生命周期和错误语义一致。不要为了给图命名而虚构既有的框架或组件。仅在概念确实可比较时使用表格,不用表格替代解释性正文。

文档形态:写的是所提议设计的快照。每条规则或理由只有一个明确归属处,其他位置只保留理解流程所需的简短重述。仅在能解释真实工程权衡时保留备选方案。从面向读者的 RFC 中移除已放弃的实现评论、对话历史、重复的防御性对比和任务管理限制。把实质性局限本地化,并区分已接受行为、实现问题和未来工作。当有助于阅读顺序时,可合并或省略模板小节;篇幅随评审者需要评估的决策数量伸缩。

完成与评审

访谈完成的标志是:关键决策已解决,或经用户同意被明确推迟,且剩余技术问题都有具体验证标准。不要把沉默当作同意。

最终做一次编辑性检查,视角是未看过本对话的工程师:确认提案与理由能独立成立、引用符合所选策略、重复的证据或告诫已合并。将结果与已接受的需求、确切接口、图、示例、术语和验收检查逐项比对,确保压缩后设计仍完整。在可行时验证本地链接和示例语法,有工具时验证或渲染图。如存在重要验证局限,如实说明,不得暗示某项检查已经运行。在能带来有意义信心时,使用有界的独立评审。

把完整 RFC 呈现给用户评审,指明剩余决策或技术缺口,询问是否捕捉到了共识理解,并修订同一产物直到达成。对常规草稿编辑不要求逐次批准。实现、提交/推送、创建 PR 和共享发布是独立动作,各自需要授权;已给出的授权应予遵守。

适用场景与限制

适用于需要从零散材料产出一份可独立评审的工程 RFC 的场合,尤其是仓库内遵循既有 RFC 约定的场景。限制包括:技能止于评审,不执行实现或发布;不创建额外的术语表、上下文文档、ADR 或研究报告;需要环境搭建、实现或外部变更时必须先获授权;文档中应避免把单一构建的证据扩大为普遍结论。关于收费、价格、支持平台等具体信息,资料中暂未提供。