Plan Change 是一个面向 guardrails 项目的实现计划编写技能。它在需求、风险与设计已经存在、但尚未开始写代码的阶段使用,用于产出一份简短、可追溯的实现计划。
用途 该技能用于为 guardrails 项目中的一次变更编写实现计划。开始时应声明:“Using the plan-change skill to write the implementation plan.”
前置条件
- 本次变更所实现的 REQ 必须已存在于 SRS 中。可用 .guardrails/scripts/find-items.sh show ID 查看每个条目;若 ID 未定义,该命令会以退出码 1 和 NOT-FOUND 结束。若缺失,应先运行 grill-requirements。
- 计划引用的每个条目都应通过 find-items.sh show ID 读取,而不是整份读取 ledger 文件。
- 安全相关变更需具备 RMF 覆盖;若没有,应先运行 analyze-risks。
- 结构性变更需具备 SDD 条目;若没有,应先运行 design-architecture。
- 需要处于 worktree 中(worktree-discipline)。
主要能力与使用方式 计划面向没有上下文、判断力不可依赖的工程师编写:需要精确路径、步骤中的完整代码、带预期输出的精确命令。计划保存到变更 worktree 中的 docs/plans/YYYY-MM-DD-<topic>.md。
任务区内的围栏代码在合并时会被替换为指针(prune-plans.sh,merge-change 第 1 步),合并后的代码位于 squash commit 中。因此每一步的意图要用散文说明,每个偏差的原因要写入验证记录。以 red -> green 开头的行所在的围栏会被保留,以 inherited: 开头的行所在的围栏也会被保留。
计划开头必须包含强制头部:
<Change> Implementation Plan
Goal: <one sentence> Implements: <REQ/RC/SDD IDs this change delivers> Safety class: <from .guardrails/config.yaml, plus per-item overrides> Verification: <the verify_commands that must pass>
每个任务应是最小单元,拥有自己的测试循环:写失败测试、看到它失败、写最小实现、看到它通过、提交。
列出每个任务的追踪 ID。在计划中写出任务所写每个测试的精确 verifies: <IDs> 注解文本。
每个任务以文件和并行性开头:
T<N> — <title>
Files touched: <exact paths, one list, no globs> Parallel: yes | no (serial, after T<N>)
只有在文件集合不相交时才标记任务为并行。两个任务若触及同一文件则串行执行,无论看起来多独立:由文件集合决定,而非主观判断。
测试交付物要写成带测试代码的明确步骤,绝不写“稍后添加测试”。
在写入条目的步骤中铸造文档 ID。修改 SRS、RMF 或 SAD 条目的步骤要用 .guardrails/scripts/new-id.sh <PREFIX> 铸造其 ID 并说明。铸造的 ID 是最终值,计划中要写明。
不得写占位符。“TBD”“处理边界情况”“与任务 N 类似”都视为计划失败。
交接前自检
- Implements: 中的每个 ID 至少有一个任务的测试验证它。
- 每个任务的代码步骤展示真实代码、真实命令和预期输出。
- 跨任务使用的名称和签名保持一致。
- 每个任务都声明 Files touched: 和 Parallel:,且没有两个标记并行的任务命名同一文件。
交接执行 交给 develop-change(TDD)逐任务执行,然后 check-traceability 和 merge-change,其第 6a 步门禁为 verify-before-merge。
红旗提示
- “这两个任务独立,可以并行共享一个文件”——同一文件即串行,由文件集合决定。
- “测试可以放到后续任务”——每个任务包含自己的测试代码。
- “与任务 2 类似”——这是占位符,要把步骤写出来。
完成条件
- 计划保存在 docs/plans/ 下,含四个头部字段。
- 每个任务声明 Files touched:、Parallel:、其 verifies: 注解和测试代码。
- 第 9 步自检通过。
适用场景 适用于 guardrails 项目中在需求、风险与设计就绪后、编码前编写实现计划的场景,尤其强调可追溯性、最小任务单元与 TDD 流程。
限制 该技能依赖 guardrails 项目的特定脚本与目录结构(如 .guardrails/scripts/find-items.sh、new-id.sh、docs/plans/、worktree 等)。关于收费、价格、平台支持等信息,资料中暂未提供。