Serial Studio 的 /ss-plan 技能详解:把已批准的 Spec 转化为可审查技术设计(plan.md)

原创2026-09-16 15:56:331,359 阅读
文章标签:桌面应用数据可视化物联网IoT协议嵌入式工业制造硬件开发

Serial Studio 的 /ss-plan 技能详解:把已批准的 Spec 转化为可审查技术设计(plan.md)

在 Serial Studio 的 spec-driven 开发工作流中,/ss-plan 是承接"WHAT & WHY"与"HOW"的关键一环:它把一份已经获得维护者批准的 spec.md,转化为一份包含具体文件清单、数据流、热路径/线程影响、方案权衡与测试计划的 plan.md。本指南以仓库中 .claude/skills/ss-plan/SKILL.md 为骨架,结合 spec 四阶段工作流文档、plan 模板 以及真实落地的 0001-composition-root plan 示例,完整讲解该技能的执行步骤、Gate 纪律与配套规则,并深入到仓库源码与文档层面说明每一步的验证依据。读完本文,你将理解如何在 Serial Studio 仓库中从零产出一份高质量、可审查、可执行的技术设计文档。

一、/ss-plan 在 spec-driven 工作流中的位置

Serial Studio 仓库约定:非平凡改动不再通过开放式聊天(prompt engineering)来"临场发挥",而是把意图沉淀为四份互相把关的审查工件,每个阶段都需人工批准后才进入下一阶段:

阶段 技能 产出物 关卡(Gate)
1. Specify /ss-spec spec.md —— WHAT & WHY:问题、目标、非目标、编号需求、验收标准、约束 维护者将 spec 标记为 approved
2. Plan /ss-plan plan.md —— HOW:受影响文件、数据流、热路径/线程影响、数据模型、API/QML、权衡、风险、测试计划 维护者批准设计
3. Tasks /ss-tasks tasks.md —— 有序、可逐项验证的检查清单 + Definition of Done 维护者批准任务拆分
4. Implement /ss-implement 逐任务产出的代码,tasks.md 保持最新 Definition of Done 达成;自审;sanitize

工件统一存放在 doc/claude/specs/ 下的编号目录中(如 0001-composition-root/),每个功能目录包含 spec.md、plan.md、tasks.md 三个阶段文档。/ss-plan 正是这条链上的 Phase 2,其核心职责一句话概括:把"我们同意做什么"变成"我们同意怎么做"。

相关技能链的完整说明见 doc/claude/spec-driven.md;工件目录的编号规则与状态生命周期见 doc/claude/specs/README.md。

二、前置条件(Preconditions):只有 approved 的 spec 才能被规划

/ss-plan 的启动门槛非常明确:对应的 doc/claude/specs/NNNN-slug/spec.md 必须存在,且其 frontmatter 中的 status: 为 approved。

如果 spec 仍处于 draft 状态,必须立即停下——先通过 /ss-spec 完成规范并让维护者批准,才能进入规划阶段。这与整个工作流的"门禁纪律"一脉相承:跳过门禁去规划一份未经审查的 spec,会重新引入"猜错了、很晚才发现"的失败模式。

status 生命周期在 doc/claude/specs/README.md 中有完整定义:

  • draft —— 正在编写,尚不构成契约;
  • approved —— 维护者已接受 spec,可以开始规划;
  • in-progress —— 实现进行中(由 /ss-implement 设置);
  • done —— 所有验收标准均已满足并验证;
  • shelved —— 放弃或延期,保留存档,编号不复用。

目录编号采用四位零填充、单调递增(0001、0002……),/ss-spec 负责计算下一个编号;编号即使被搁置也绝不复用。

三、执行流程:六步把 Spec 变成 Plan

/ss-plan 的 Procedure 由六个步骤组成,每一步都有明确的产出与纪律要求。

Step 1:完整阅读 spec

每一句需求(Requirement)和每一条验收标准(Acceptance Criterion)都是 plan 必须命中的靶心。/ss-plan 在此阶段不做设计、不写代码,先把 spec 的全部约束装入工作记忆——这是后续一切决策的输入。

Step 2:读取 ground truth——禁止凭记忆设计

这是该技能最强调的纪律:设计必须基于真实代码与最新文档,而非记忆中的模型。规划者需要按需读取以下资料:

  • architecture.md —— 全局架构索引,指向 doc/claude/architecture/ 下各子系统文档(dataflow、startup、io、project、scripting、dashboard、export 等);对于被本次改动触及的子系统,必须完整阅读对应文件;
  • common-mistakes.md —— 本仓库的"静默破坏"(silent breakage)清单,按子系统分组,规划者要识别本次改动暴露于哪些破坏类别;
  • code-style.md 与 directory-map.md —— 按需查阅代码风格与目录映射;
  • 如果改动触及数据热路径(hotpath),必须显式调用 ss-hotpath 技能,并完整阅读 FrameBuilder / CircularBuffer / FrameReader / Dashboard 相关代码(这是 CLAUDE.md 中的硬性规则);
  • 如果是新增驱动,则遵循 ss-new-driver 技能,并 grep 一个已有的 BusType 枚举值,找出所有需要注册的触点(touch-point),确保 plan 中的文件清单不是猜出来的。

这一步骤的价值在于:plan 是"写在纸上的契约",如果它建立在一个过时的心理模型上,比没有 plan 更糟(plan 模板的引言原话:a plan grounded in a stale mental model is worse than no plan)。

Step 3:复制模板并撰写 plan

进入实际产出阶段,第一条命令是复制模板:

cp doc/claude/specs/templates/plan.md doc/claude/specs/NNNN-slug/plan.md

NNNN-slug 与 spec 目录同名,即 plan 与 spec 同目录存放,通过相对链接相互引用。复制后必须填满每一个章节——尤其注意:

  • Hotpath & threading impact 章节是必填项:即使答案是"无影响",也必须显式作答,而不是留白或跳过;
  • Affected subsystems & files 章节必须列出具体文件路径,且这些路径必须通过 grep 确认存在,而不是靠猜。

plan.md 模板 定义了完整的九段式结构,这是产出物的"骨架":

章节 要求
Approach(一段话) 3–5 句话讲清:构建什么、插在哪里、为什么选这个形状而不是备选方案;这是审查者最先读的摘要
Affected subsystems & files 具体路径表格(文件 + 变更说明),每个将新建/编辑的文件一行;新枚举值或驱动必须覆盖每一个需要注册的 switch/列表
Architecture & data flow 数据与控制如何在改动中流动:命名对象、signals/slots、线程;引用 architecture.md 章节而非重新推导
Hotpath & threading impact 必填。是否触及 hotpath(FrameReader/CircularBuffer/FrameBuilder/Dashboard draw/span 快车道);是否新增跨线程 signal/slot;是否新增热路径缓存标志的输入;时间戳所有权确认
Data model & persistence Frame.h Keys:: 新增(单一事实来源)、schema/writer 版本、widgetSettings/项目 JSON 形态、Sessions DB schema、legacy 别名回退;说明旧文件读取的迁移路径
API / SDK surface 新增/变更的 API handler(注册于 CommandHandler::initializeHandlers())、EnumLabels.cpp slug、生成 SDK、脚本 apiCall 可达性;商业功能置于 #ifdef BUILD_COMMERCIAL 之后
QML / UI 新组件、喂给它们的 model、ComboBox 恢复竞态防护、主题/玻璃表面、字体自适应;无 UI 则写 None
Tradeoffs & alternatives considered 决策表(Decision / Options / Chosen + why),前置呈现审查者可能做不同选择的点
Risks & mitigations 可能回归或破坏的内容及防御手段,包含 common-mistakes 中本次改动暴露的静默破坏类别
Test & verification plan 把每条验收标准映射到具体检查:tests/scripts/ JS 用例、pytest tests/...、--benchmark-hotpath、code-verify.py、qt-cpp-review、sanitize-commit.py

Step 4:先发散,再收敛(Diverge before you converge)

在设计定型之前,先在对话中勾勒 2–3 个"有名有姓"的候选方案——每个方案一个名字加一行描述。这是 doc/claude/j-space.md 中"命名透镜(Named lenses)"纪律的具体落地:给不同的方案起不同的名字,会加载不同的工作空间内容,促使模型真正思考差异;针对真实备选方案做出的设计,优于"第一个看起来可行的方案"。

随后收敛:推荐一个方案,并给出一行理由(推荐,而非枚举)。

Step 5:把权衡前置为决策(Surface tradeoffs as decisions)

在 plan 的 Tradeoffs 表格中,凡是两个合理设计在"重要的事情"上分叉(性能 vs 简洁、保真 vs 可读、范围),都要显式列为一个决策,包含选项、推荐与一行理由。这里有两个硬性要求:

  • 推荐,不要枚举——审查者需要的是建议,不是清单;
  • 从 spec 中把决定性的约束提前抽出来——不要在实现阶段才发现。

Step 6:把每条验收标准映射到检查

Test & verification plan 必须逐条将 spec 中的 Acceptance Criteria 映射到具体的检查手段:pytest 文件、tests/scripts/ 单元、--benchmark-hotpath 门禁,或维护者在运行应用中的某项观察。保证"验收标准 ↔ 可运行检查"一一对应,是 plan 可执行性的基石。

四、Gate:写完 plan 就停下

/ss-plan 的产出边界非常清晰:写完 plan.md 后立即停止,将设计——尤其是权衡表与热路径答案——提交给维护者审查。在维护者批准之前,绝对禁止运行 /ss-tasks。

这正是整个工作流的核心哲学(见 doc/claude/spec-driven.md):

"执行之前先有一份可见的 plan,就是契约本身;换一种方案的成本,正是在这里变得最便宜。"

一份设计错误如果在 plan.md 阶段被发现,改掉的成本近乎为零;如果拖到 600 行的 diff 里才暴露,代价就完全不同了。门禁纪律还要求:每个阶段都以上一阶段的工件为事实来源,如果后续阶段发现更早的工件有误(规划暴露了坏需求、实现暴露了缺任务),必须回去修订更早的文档并重新确认,而不是静默偏离——过期的 spec 比没有 spec 更糟。

五、Rules:三条不可违背的边界

SKILL.md 末尾列出三条规则,约束着 /ss-plan 的行为边界:

  1. 不写代码。plan 描述改动,不实现改动。Phase 2 的产出物只有 plan.md 一份文档。
  2. 规划中暴露的问题如果改变 spec,必须回去修订 spec.md 并重新确认,而不是静默偏离既定范围。
  3. 遵守 Trust Contract:plan 的文件清单本身就是"车道"——清单之外的任何文件改动,必须先在对话中明确提出,绝不能悄悄混进 /ss-implement 的实现阶段。这对应 common-mistakes.md 中"Process & Trust"一节反复强调的边界:任何与用户请求无关的文件改动,都会消耗审查者的审计成本,并侵蚀信任。

六、真实案例剖析:Plan 0001——Composition Root

仓库中已有大量真实落地的 plan 可供对照学习,其中 0001-composition-root/plan.md 是一个典型的完整范例,充分体现了上述步骤与模板的用法:

  • Approach 用一段话概括了整体策略:将 Misc::ModuleManager 形式化为组合根(composition root),把零散的 X::instance() 调用点转化为捕获的依赖成员,分七个门控阶段(S1–S7)推进;
  • Affected subsystems & files 给出了精确到文件的表格,例如 app/src/Misc/ModuleManager.cpp(新增 instantiateCoreModules())、scripts/code_verify_rules.py(新增 arch-singleton-instance 顾问规则)等,并标注了阶段归属(S2 done / S3 / S4 / S5 / S6);
  • Hotpath & threading impact 显式作答:仅 S6 触及热路径且以基准门控;明确"无新增跨线程 signal/slot";指出 S6 将 m_operationMode 变为缓存标志后,其变更信号必须接入刷新槽,否则 onFrameReady 中的模式分支会静默失效——这正是 common-mistakes.md 中"缓存热路径标志"条目的直接应用;
  • Tradeoffs 表格列出五个决策(整体形态、ProjectModel 与 AppState 的构造顺序、叶子捕获机制、热路径改造时机、守卫强度),每行都是"选项 + 选定 + 一行理由";
  • Test & verification plan 区分了"agent 可运行的静态检查"(documentation-verify.py、code-verify.py --check、grep 对称性配方)与"维护者运行的集成/热路径检查"(三种操作模式启动、--benchmark-hotpath 七档对比基线)。

这个案例展示了真实 plan 如何把模板的每一项要求落到具体仓库对象上,也印证了 Step 2 中"grep 确认触点、不靠猜"的纪律。

七、与相邻技能的协作关系

/ss-plan 并非孤立存在,它与仓库中的一组技能构成完整的 spec-driven 工具链:

  • 上游 /ss-spec:产出并批准 spec,是 /ss-plan 的唯一合法输入;
  • 下游 /ss-tasks:消费已批准的 plan,拆解为有序任务清单(模板见 tasks.md 模板,要求"一个任务 = 一个聚焦、可审查的变更",含 Files / Does / Verify / Deps 字段与 Definition of Done);
  • 横向支撑:ss-hotpath(热路径规则与 256 kHz 吞吐门禁)、ss-new-driver(新驱动注册触点)、qt-cpp-review(C++ 评审)、ss-cpp-modern、ss-docs、ss-ai-audit 等技能在 plan 的编写与后续验证阶段按需介入。

值得一提的是 /ss-plan 明确要求:触及热路径时必须显式调用 ss-hotpath,因为热路径代码是本仓库风险最高的区域——违反其硬性规则(如 Qt::DirectConnection 要求、禁止分配、SPSC 无锁、缓存标志接线)导致的不是编译错误,而是静默的帧丢失。这也是为什么 plan 模板把 "Hotpath & threading impact" 设为必填章节:每次改动都必须给出显式答案,而不是等帧停止流动后才被发现。

八、结语:一份好 plan 的验收标准

回顾 /ss-plan 的完整流程,一份合格的 plan.md 应当同时满足:

  1. 完整性——模板九段结构无留白,尤其是热路径章节有显式答案;
  2. 准确性——所有文件路径经 grep 确认,触点在源码中真实存在;
  3. 决策性——权衡以"推荐 + 一行理由"呈现,而非枚举;决定性的约束从 spec 中提前抽出;
  4. 可验证性——每条验收标准都映射到一条可运行的检查;
  5. 纪律性——只写文档不写代码,发现 spec 问题回溯修订,文件清单即契约边界。

这正是 spec-driven 工作流区别于传统 prompt engineering 的根本:契约从"agent 是否猜对了"变成"我们在写代码之前,是否以书面形式达成了共识"。/ss-plan 让这个共识以可审查、可恢复、可随代码长期存续的工件形态落地——半途而废的功能是三个文件(spec/plan/tasks)而非一段丢失的聊天记录,任何新会话或新协作者都能无缝接手。

登录后查看全文
Serial-Studio