SuperAPI AI 工具集

sus-change-plan

编程与开发

查看项目

更新于 10-16 10:09

技能介绍

sus-change-plan 是一个用于在保留行为的前提下规划结构性变更的技能,属于 jcosta33/suspec 项目。其核心理念是「未经证实的保留无异于意外破坏」。

用途 该技能在明确请求规划时进入,或在人类选择 Suspec change-plan 工作流后进入。它面向重构、重写、迁移、升级、性能变更、schema 变更或大范围架构调整等需要保持现有行为的结构性变更场景。

方法 技能会通过原生选择器提出必要问题,或使用编号选项加 Other。问题设置上把推荐方案放在首位,提供三个真实可选的方案,二选一时提供两个,每个方案给出简明理由与成本。

技能会读取项目规则、持久决策、当前源码、测试和现状态地图。当大范围变更缺少经证实的地图时,会先把不熟悉或对变更关键的区域绘制为持久现状态,然后再规划。只有在变更相互隔离、当前地图已经证实、且不存在行为保留、分阶段切换或回滚风险时才会跳过。

技能会解析可逆约定。当涉及行为、公共契约、安全、成本、权限或不可逆操作时,强制将重大歧义转为明确的人工选择。在选择完成之前,阻塞相互依赖的波次。

产物 技能将 ~/.agents/artifacts/<workspace>/ 解析为绝对路径;<workspace> 从仓库或工作目录的 basename 推导。在该目录下写入 type: change-plan、唯一的 CHANGE-ID 以及并列链接的 sidecar。遇到冲突或工作区不明确时,给出人类可读的名称选项。写入被阻塞时,提供授权并重试、改用另一个中立于 agent 的用户目录,或取消。绝不覆盖,也不回退到仓库、厂商目录或临时路径。

本地源码引用相对产物写入。仅在运行时交接时使用绝对路径。

形态 使用最小的 frontmatter 形态:type: change-plan、id: CHANGE-{{slug}}、kind: refactor、preserves 列表。preserves 始终是列表。治理需求使用完整的 SPEC-id#AC-NNN,计划本地保证使用 PG-NNN。

只写承重章节:基线(当前状态、直接证据、使用的地图)、目标(最终结构、有意行为变更、保留行为)、保留保证(ID | 行为 | 如何验证)、转换波次(最小的有序变更,使构建和测试保持绿色;每个波次命名受影响表面、验证和回滚点)、切换/回滚(可观察的进入、完成、中止和恢复条件)、任务拆分(可派发的归属和依赖,或 None)。

用 frontmatter 的 kind 命名转换类型。在 preserves 下复用完整的治理需求引用;仅为没有需求 ID 的保留行为铸造计划本地 PG-NNN。

验证 要求金标准、差分或属性检查能够发现漂移。绿色的测试套件只证明其已执行的覆盖范围。

为每个兼容垫片指定路径、前向目标和机械移除条件。

统计源码、测试、生成代码、动态派发、注册表、配置和反射中的旧调用点;完成目标是在命名垫片之外为零。

记录每一次有意的重写差异。保留其余一切。

在前后使用同一个性能协议:工作负载、输入、环境、预热、样本、统计量、目标以及回归上限。

仅当消费者无法原子切换时才使用 schema 共存。

验证 frontmatter 和必需章节,依据源 spec 或计划保证解析每一个 preserves ID,并要求每个转换波次命名验证方式。

输出 交接前,在不改变契约、标识符、逐字源文本、证据或行为的前提下,削减重复、软化、仪式和结构膨胀。重新运行适用的检查。只返回变更计划和每个 sidecar 的可点击 Markdown 链接,使用紧凑的 ~/.agents/... 标签和完全展开的绝对目标。只解释阻塞、创建失败、验证不完整或不可逆操作确认。

关闭 一旦完全执行且没有下游步骤需要它,要求对产物及其 sidecar 做出唯一的人工处置:Delete、Leave 或 Promote。Promote 将临时材料移入项目自有永久位置。删除每个选中的路径并验证不存在;存留者会阻塞关闭。