Serial Studio 的 /ss-plan 技能详解:把已批准的 Spec 转化为可审查技术设计(plan.md)
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 的行为边界:
- 不写代码。plan 描述改动,不实现改动。Phase 2 的产出物只有
plan.md一份文档。 - 规划中暴露的问题如果改变 spec,必须回去修订
spec.md并重新确认,而不是静默偏离既定范围。 - 遵守 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 应当同时满足:
- 完整性——模板九段结构无留白,尤其是热路径章节有显式答案;
- 准确性——所有文件路径经 grep 确认,触点在源码中真实存在;
- 决策性——权衡以"推荐 + 一行理由"呈现,而非枚举;决定性的约束从 spec 中提前抽出;
- 可验证性——每条验收标准都映射到一条可运行的检查;
- 纪律性——只写文档不写代码,发现 spec 问题回溯修订,文件清单即契约边界。
这正是 spec-driven 工作流区别于传统 prompt engineering 的根本:契约从"agent 是否猜对了"变成"我们在写代码之前,是否以书面形式达成了共识"。/ss-plan 让这个共识以可审查、可恢复、可随代码长期存续的工件形态落地——半途而废的功能是三个文件(spec/plan/tasks)而非一段丢失的聊天记录,任何新会话或新协作者都能无缝接手。