Update RFC
本技能用于更新已有 RFC,让工程师能够理解当前设计、已经实现的内容,以及哪些部分仍未验证;在纳入具体实现证据的同时保留其身份与已达成共识的意图。工作集中在单个文档内,术语放在靠近结尾的位置,必要时后接引用章节;保持其 Rust 风格结构或仓库既有格式。
这是公开仓库。应使用公开证据或可独立开发、适合公开评审的材料。受限研究不应进入检出目录;移除链接或署名并不能使内部发现变得可发布。位置与约定参见 RFC 索引。
调用方式
在明确指示更新 RFC 时运行,包括“verify, archive, and update the RFC”这类组合请求。归档之后,如果该工作尚未被请求,可以提示“Would you like to update the RFC?”。仅归档本身不构成运行本技能的授权。这些指引不会安装钩子,也不会修改其他归档工作流。
定位 RFC 与证据
阅读仓库指引、目标 RFC 以及提供的实现引用。在未指定具体 RFC 时,依据既有链接与仓库约定定位相关 RFC。仅当存在多个看似合理、且范围实质性不同的文档时才提问。若没有匹配的 RFC,报告该情况并保持文件不变;在有用时可建议 create-rfc。保留不相关的编辑,更新已有的带编号文件,而不是创建替代 RFC。
确定实现边界:变更或提交范围、相关代码与配置、验证结果以及环境。本地 diff 只能证明本地工作,不能证明已合并或已部署。优先聚焦阅读受影响的接口与行为,而不是做全仓库审计。
存在 OpenSpec 时,检查相关 proposal、design、delta specs、tasks 以及可用的验证发现。对已归档的变更,定位实际归档并检查对应的规范规格。要确认其与代码的映射,而不是依据归档目录或已勾选的任务列表推断完成。OpenSpec 是可选的;代码、diff、测试和其他设计记录同样支持该工作流。除非另行请求,本技能不会替用户验证或归档 OpenSpec 变更。
在受影响的 RFC 声明与证据之间建立工作对照:未变化、按设计实现、实现方式不同、部分实现、推迟或仍未知。该对照保留在工作上下文或必要的私有笔记中,不形成新的伴随设计文档。
让意图与实现对齐
本技能通常在实现已被验证之后运行。使用既有证明:OpenSpec 规格与验证发现、其他文档、PR、代码以及已记录的测试或运行时结果。检查这些证据能确立什么及其范围;不要发起新的实现验证或重跑测试。若验证缺失、含糊或矛盾,暂停受影响的更新,请人澄清或提供既有证明。绝不能仅凭代码推断某项检查已通过。
区分以下属性:
已实现:行为存在于已检查的代码或配置中。
已验证:具名检查在所述条件下实际执行了该行为。
已部署:证据确立其在具名环境中可用。
PoC:观察结果确立其在原型条件下的可行性;其余生产要求仍保持原有状态。
这些是相互独立的属性,而不是自动递进的阶段。已合并的 PR、已归档的变更或成功的冒烟测试,并不能证明所有验收标准或生产就绪。相关时,保留关于缺失的授权、并发、生命周期、迁移或运维检查的发现。
当证据清晰时,直接更新例行细节:字段名、路由形态、组件位置、配置以及已解决的技术问题。如果实现与已达成共识的产品或安全要求相矛盾,描述该差异并询问它是有意的设计变更还是缺陷。不要为了让要求与代码一致而静默重定义要求。在该决定待定期间,继续不受影响的更新。在提供的上下文中已获批准的决定无需再次批准。
仅更新已实现变更所涉及、且有既有证据支持的部分。把已解决调查与开放问题的答案并入相关设计章节,然后删除这些待办问题条目;不要保留带删除线的问题或解决日志。对于部分回答的问题,仅保留未解决的部分。保留未被触及的设计以及已规划但未实现的范围。
编辑当前的工程快照
一并更新受影响的正文、API 与资源示例、Mermaid 图、不变量、校验说明、未解决问题与术语。检查对重命名概念与变更流程的下游引用。架构使用组件图,流程使用序列图,生命周期行为使用状态图;保留有用的边界,避免无关的平台内部细节。
把结论整合到它们所属的位置。当有助于区分已交付行为与计划范围时,保留简明的实现状态或校验章节。遵循 RFC 既有的引用政策。对于没有引用政策的仓库 RFC,除非用户要求外部引用,读者可见的引用保持在仓库内。外部来源可以确立证据;把相关结论并入,并将其出处保留在工作上下文或必要的私有笔记中。用描述性链接在重要主张附近引用仓库文件、已记录的检查或固定版本的源码修订。原始哈希与来源清单不进入正文。在相关主张处说明局限,而不是在全文重复注意事项。
RFC 应当读起来像一份工程师今天就能使用、无需原始对话或研究文档的设计。保持其从提案、用户可见行为到技术细节的推进顺序。使用直接语言与具体示例,让每条规则或理由只有一个明确归属。移除已被取代的假设与已解决的占位内容。保留仍能解释有意义权衡的理由。把执行时序、调试弯路与访谈历史留在叙述之外;仓库历史可以保留更早版本。术语保留在 RFC 中,而不是单独的术语表或上下文文档。
对于将已接受 RFC 视为不可变的仓库,遵循其修订约定。不要仅因实现出现分歧就重写冻结的 RFC;确定允许的更新机制,并在其造成重大范围选择时询问。
审查与交接
审查 diff,检查是否有丢失的要求、被改变的确切接口、无依据的完成声明,以及示例、图与正文之间的不一致。确认更新保持了阅读顺序与引用政策,并在不删除实质性局限的前提下合并重复内容。在可行时检查变更的链接与示例语法;在有工具时校验 Mermaid。这些是文档检查,不是对实现的新一轮验证。当现有实现证明不足时,暂停并询问人。
最后说明 RFC 位置、实质性更新、已检查的证据,以及任何仍需决定的剩余差异。若证据支持无需变更,报告该结论,而不是制造编辑。有证据支持的例行更新无需重新启动完整的设计访谈。
除非获得发布授权,保持变更在本地。提交/推送、共享文档写入、创建 PR、实现修复、部署以及向他人发送消息都是独立动作;可复用已就同一动作与范围给出的授权。