执行与验证类命令

这是「GSD 全景代码解析」专题的第 10 篇。在上一篇（第 09 篇）中，我们深入解析了 GSD 的规划类命令，理解了从 /gsd-sketch 到 /gsd-ultraplan-phase 的完整规划体系。规划再完美，如果不落地执行也只是空中楼阁。本篇将聚焦执行与验证类命令——GSD 工作流中将计划转化为代码、将代码转化为价值的核心引擎。我们将逐一拆解 /gsd-execute-phase、/gsd-verify-work、/gsd-do、/gsd-quick 和 /gsd-fast 的设计哲学、执行机制和选择策略。

---

一、执行与验证类命令概览

如果说规划类命令是"运筹帷幄"，那么执行与验证类命令就是"决胜千里"。GSD 的执行层设计遵循一个核心原则：不同规模和复杂度的任务，需要不同深度的执行保障。从严格的全相位 wave 执行到一键 inline 修复，执行层命令覆盖了一个从"重型规范执行"到"轻量级快速修复"的完整光谱：

命令	定位	子代理	规划文件	验证	适用场景
/gsd-execute-phase	核心执行	是（多）	读取已有 Plan	可选 --tdd	Phase 级别的批量任务执行
/gsd-verify-work	工作验证	是	UAT 跟踪	内置 UAT	执行后的质量门控检查
/gsd-do	智能路由	否（调度器）	自动生成	由目标命令决定	不知道用哪个命令时的自动分派
/gsd-quick	快速执行	是（精简）	生成 Quick Plan	可选 --validate	小型临时任务，ad-hoc 修复
/gsd-fast	极速模式	否	无	无	2 分钟内的琐碎任务

flowchart TD
    A[计划就绪] --> B{"任务规模与风险"}
    B -->|完整 Phase
多计划并行| C[/gsd-execute-phase/]
    B -->|不知道用哪个命令| D[/gsd-do/]
    B -->|小型临时任务
需要跟踪| E[/gsd-quick/]
    B -->|超小任务
< 2 分钟| F[/gsd-fast/]
    C --> G[执行结果]
    G --> H{"需要验证?"}
    H -->|是| I[/gsd-verify-work/]
    H -->|否| J[完成]
    I -->|发现问题| K[生成 Gap Plan]
    K --> C
    I -->|验证通过| J
    D --> L[自动路由到
合适命令]
    E --> M[Quick Plan +
原子提交]
    F --> N[Inline 直接修改]

这个光谱的设计精妙之处在于：它不是一刀切的执行策略，而是让开发者根据任务的实际复杂度选择最合适的执行深度。一个小拼写错误不需要完整的 Phase 规划和 wave 并行，而一个涉及 20 个 Session 的架构重构也不应该走 /gsd-fast 的快捷路径。

---

二、/gsd-execute-phase：核心执行命令

/gsd-execute-phase 是 GSD 执行层的心脏，负责将一个 Phase 中的所有 Plan 转化为实际的代码变更。它是 GSD 从"计划"跨越到"交付"的最关键一步。

2.1 执行阶段的完整流程

当调用 /gsd-execute-phase <phase-number> 时，GSD 会启动一个精心设计的执行流水线：

flowchart TD
    A[/gsd-execute-phase
phase-number/] --> B[发现 Phase 中
所有 Plan 文件]
    B --> C[解析每个 Plan 的
依赖关系]
    C --> D[构建依赖图]
    D --> E[Wave 分组算法]
    E --> F[Wave 1: 无依赖计划]
    F --> G[并行生成子代理
执行各 Plan]
    G --> H[收集执行结果]
    H --> I{Wave N
全部完成?}
    I -->|否| J[等待当前 Wave
完成]
    J --> G
    I -->|是| K{存在
下一 Wave?}
    K -->|是| L[Wave N+1: 解除依赖的计划]
    L --> G
    K -->|否| M[Phase 验证/完成检查]
    M --> N[更新 STATE.md]
    N --> O[输出下一步指令]

关键设计原则：Orchestrator（编排器）保持精简——它只负责发现计划、分析依赖、分组为 Wave、生成子代理、收集结果。每个子代理加载完整的 execute-plan 上下文并独立处理自己的 Plan。这种"指挥不演奏"的设计确保了 Orchestrator 不会成为瓶颈。

2.2 Wave 执行模型

Wave 执行模型是 /gsd-execute-phase 最核心的创新。它解决了大规模 Phase 执行中的一个经典难题：如何最大化并行度，同时保证依赖顺序的正确性。

flowchart LR
    subgraph Wave1["Wave 1: 无前置依赖"]
        A1[Plan A] 
        B1[Plan B]
        C1[Plan C]
    end
    
    subgraph Wave2["Wave 2: 依赖 Wave 1 完成"]
        D2[Plan D
depends: A]
        E2[Plan E
depends: B]
    end
    
    subgraph Wave3["Wave 3: 依赖 Wave 2 完成"]
        F3[Plan F
depends: D, E]
    end
    
    A1 --> D2
    B1 --> E2
    D2 --> F3
    E2 --> F3
    C1 -.->|无后续依赖| G[完成]

Wave 分组的算法逻辑如下：

1. 依赖图构建：读取每个 Plan 文件的 frontmatter，提取 depends_on 字段
2. 拓扑排序：构建有向无环图（DAG），计算每个节点的入度
3. Wave 分配：入度为 0 的节点归入 Wave 1；Wave 1 完成后，更新依赖图的入度，新的入度为 0 的节点归入 Wave 2；依此类推
4. 并行执行：同一 Wave 内的所有 Plan 并行执行，每个 Plan 对应一个独立的子代理

上下文预算是 Wave 模型的另一个精妙设计：

• Orchestrator 只保留约 15% 的上下文预算用于调度和协调
• 每个子代理获得 100% 的 fresh 上下文，可以完整加载自己的 Plan 文件和相关代码

这种分配策略避免了 Orchestrator 的上下文被大量 Plan 内容撑满，同时确保每个执行代理有足够的上下文空间来完成高质量的工作。

2.3 任务分解与原子提交

每个子代理在执行 Plan 时遵循原子提交原则：

flowchart TD
    A[加载 Plan 上下文] --> B[分析代码变更范围]
    B --> C[执行代码修改]
    C --> D[本地验证
编译/测试]
    D -->|通过| E[生成 Commit]
    D -->|失败| F[诊断修复]
    F --> C
    E --> G[更新 Session Summary]
    G --> H[报告执行结果]

原子提交确保每个 Plan 的执行结果是独立的、可回滚的。如果一个 Plan 执行失败，它不会污染其他 Plan 的提交历史。这是 GSD 从"脚本式代码生成"升级为"工程级代码交付"的关键设计。

2.4 与 plan-phase 的衔接

/gsd-execute-phase 与 /gsd-plan-phase 的衔接体现了 GSD 的核心分层哲学：

• plan-phase 负责"写什么"——在 .planning/sessions/ 中生成详细的 Plan 文件
• execute-phase 负责"怎么写"——读取 Plan 文件，将其转化为代码变更
• 两者之间通过文件系统契约连接：Plan 文件的位置、格式、frontmatter 字段都是标准化接口

flowchart LR
    A[/gsd-plan-phase/] -->|生成| B[.planning/sessions/
session-001/PLAN.md]
    A -->|生成| C[.planning/sessions/
session-002/PLAN.md]
    B --> D[文件系统契约]
    C --> D
    D --> E[/gsd-execute-phase/]
    E -->|读取并执行| F[代码变更 +
原子提交]

这种设计使得规划和执行可以解耦执行——你可以今天规划，明天执行；也可以修改 Plan 后重新执行，而不需要重新规划。

2.5 可选标志

/gsd-execute-phase 支持四个可选标志，使其能够适应不同的执行场景：

标志	作用	适用场景
--wave N	只执行 Wave N	配额管理、分阶段发布、调试特定 Wave
--gaps-only	只执行 gap_closure 计划	verify-work 生成修复计划后的定向执行
--interactive	顺序内联执行，无子代理	小 Phase、Bug 修复、结对编程风格
--tdd	启用测试驱动执行	需要严格测试覆盖的功能开发

重要原则：这些标志是"显式激活"的——只有当字面量 token 出现在 $ARGUMENTS 中时，标志才被视为激活。Orchestrator 不会因为某个标志被文档化就默认启用它。

---

三、/gsd-verify-work：工作验证

执行完成后，如何确保构建的功能真的工作？/gsd-verify-work 就是 GSD 回答这个问题的答案。它通过**对话式用户验收测试（Conversational UAT）**来验证交付物。

3.1 验证流程和检查点

/gsd-verify-work 的验证流程设计为一次结构化的"对话式测试会话"：

flowchart TD
    A[/gsd-verify-work
phase-number/] --> B[检查已有
Session 状态]
    B --> C[加载 Phase 上下文]
    C --> D[呈现测试用例
一次一个]
    D --> E[用户执行测试
返回纯文本结果]
    E --> F{测试结果?}
    F -->|通过| G[记录到 UAT.md]
    F -->|失败| H[自动诊断问题]
    H --> I[分析根因]
    I --> J[生成修复计划
Gap Plan]
    J --> K[标记为 gap_closure]
    K --> L[准备 /gsd-execute-phase
--gaps-only]
    G --> M{更多
测试用例?}
    M -->|是| D
    M -->|否| N[生成 UAT 报告]

验证流程的关键设计：一次只测一个功能点。这种"单线程验证"策略避免了信息过载，确保每个测试都能得到充分的注意力。用户的反馈以纯文本形式返回——不需要复杂的模板填写，也不需要面对一连串的审问式问题。

3.2 与 gates.md 的关系

gates.md 是 GSD 质量门控体系的核心文档，定义了项目从规划到交付必须经过的检查门。/gsd-verify-work 是 gates.md 中"验证门"的具体实现：

flowchart LR
    subgraph "Gates 体系"
        A[Planning Gate] --> B[Review Gate]
        B --> C[Execution Gate]
        C --> D[Verification Gate]
        D --> E[Deployment Gate]
    end
    
    F[/gsd-plan-phase/] --> A
    G[/gsd-execute-phase/] --> C
    H[/gsd-verify-work/] --> D

/gsd-verify-work 在验证门中扮演三个角色：

1. 检查者：对照 Plan 中的验收标准，逐一验证功能是否实现
2. 诊断者：发现问题时，自动分析根因，生成诊断报告
3. 规划者：为发现的问题生成修复计划（Gap Plan），并标记 gap_closure: true

3.3 验证失败的处理策略

当验证发现问题时，/gsd-verify-work 不会简单地把问题列表丢给用户，而是启动一个闭环修复流程：

flowchart TD
    A[UAT 测试失败] --> B[自动诊断]
    B --> C[定位缺陷范围]
    C --> D[生成 Gap Plan
带 gap_closure 标记]
    D --> E[写入 .planning/sessions/]
    E --> F[通知用户:
发现 N 个 gap]
    F --> G[/gsd-execute-phase
--gaps-only/]
    G --> H[执行修复计划]
    H --> I[/gsd-verify-work/]
    I -->|再次验证| J{全部通过?}
    J -->|否| A
    J -->|是| K[更新 STATE.md
Phase 完成]

这种"验证 → 诊断 → 规划 → 修复 → 再验证"的闭环，确保每个 Phase 在标记为完成之前，都经过了充分的质量检验。--gaps-only 标志在这里发挥关键作用——它让修复执行只关注 gap closure 计划，避免重复执行已经通过验证的 Plan。

---

四、/gsd-do：智能路由

/gsd-do 是 GSD 命令系统中一个独特的存在——它不是执行命令本身，而是执行命令的智能调度器。

4.1 与 execute-phase 的区别

维度	/gsd-do	/gsd-execute-phase
角色	调度器（Dispatcher）	执行器（Executor）
是否直接修改代码	否	是（通过子代理）
输入	自由形式自然语言	明确的 Phase 编号
输出	路由到合适的 GSD 命令	代码变更 + 提交
适用场景	"我不知道该用哪个命令"	"我知道要执行哪个 Phase"

flowchart LR
    A["用户输入:
'我需要修复登录页面的 Bug'"] --> B[/gsd-do/]
    B --> C{意图分析}
    C -->|小型修复| D[/gsd-quick/]
    C -->|Phase 执行| E[/gsd-execute-phase/]
    C -->|需要规划| F[/gsd-plan-phase/]
    C -->|验证需求| G[/gsd-verify-work/]
    D --> H[执行]
    E --> H
    F --> H
    G --> H

4.2 轻量级执行路径

/gsd-do 的工作流程非常轻量：

1. 意图分析：解析用户的自然语言输入，识别任务类型、规模和紧急程度
2. 命令匹配：根据路由规则匹配最合适的 GSD 命令
3. 确认路由：向用户展示匹配结果，确认后调用目标命令
4. 移交执行：将控制权交给目标命令，自身不保留任何状态

flowchart TD
    A["用户: /gsd-do
修复登录 Bug"] --> B[解析意图:
类型=修复, 规模=小]
    B --> C[匹配命令:
/gsd-quick 或 /gsd-fast]
    C --> D[展示路由建议:
推荐使用 /gsd-quick]
    D --> E[用户确认]
    E --> F[调用 /gsd-quick
修复登录 Bug]
    F --> G[/gsd-do 任务完成]

4.3 适用场景

/gsd-do 最适合以下场景：

• 新手入门：还不熟悉 GSD 命令体系，不知道面对一个任务该调用哪个命令
• 模糊需求：任务描述比较笼统，需要系统帮助判断最合适的执行策略
• 快速决策：不想花时间在命令选择上，希望系统推荐最佳实践

重要原则：/gsd-do 从不自己执行工作。它是一个纯调度器——分析、匹配、确认、移交。所有实际工作都由被调度的目标命令完成。这确保了执行逻辑的一致性和可维护性。

---

五、/gsd-quick：快速执行

/gsd-quick 是 GSD 为小型、临时任务设计的快速执行通道。它保留了 GSD 的核心保障（原子提交、STATE.md 跟踪），但大幅缩短了执行路径。

5.1 最小规划 + 直接执行

/gsd-quick 的执行路径比 /gsd-execute-phase 精简得多：

flowchart TD
    subgraph "gsd-quick 路径"
        A[任务描述] --> B[gsd-planner
quick mode]
        B --> C[生成 Quick Plan]
        C --> D[写入 .planning/quick/]
        D --> E[gsd-executor 执行]
        E --> F[原子提交]
        F --> G[更新 STATE.md
Quick Tasks 表]
    end
    
    subgraph "gsd-execute-phase 路径"
        H[Phase Plan] --> I[Wave 分组]
        I --> J[多子代理并行]
        J --> K[Phase 验证]
        K --> L[更新 ROADMAP.md]
    end

关键差异：

• Quick 任务存储在 .planning/quick/ 目录中，与正式的 Phase Session 分离
• 更新的是 STATE.md 中的"Quick Tasks Completed"表，而不是 ROADMAP.md
• 默认跳过 discussion、research、plan-checker、verifier 等可选阶段

5.2 可选标志的精细控制

/gsd-quick 提供了一套精细的标志系统，让用户可以根据任务复杂度动态调整质量保障的深度：

标志	作用	组合效果
--discuss	启用轻量级讨论阶段	澄清模糊需求，记录决策到 CONTEXT.md
--research	启用研究阶段	调查实现方案、库选项、潜在陷阱
--validate	启用 plan-checking + 验证	最多 2 轮 plan-checking，执行后验证
--full	启用完整质量流水线	discussion + research + plan-checking + verification

flowchart TD
    A[/gsd-quick/] --> B{选择标志}
    B -->|默认| C[跳过可选阶段
直接规划+执行]
    B -->|--discuss| D[讨论 → 规划 → 执行]
    B -->|--research| E[研究 → 规划 → 执行]
    B -->|--validate| F[规划 → 检查 → 执行 → 验证]
    B -->|--full| G[讨论 → 研究 → 规划 → 检查 → 执行 → 验证]
    
    D --> H[Quick Plan]
    E --> H
    F --> H
    G --> H
    C --> H

这些标志是可组合的：--discuss --research --validate 与 --full 效果相同。这种设计让用户可以用最低的认知成本获得所需的保障级别。

5.3 子命令管理

/gsd-quick 还提供了三个子命令用于任务管理：

子命令	作用	示例
list	列出所有 quick 任务及状态	/gsd-quick list
status <slug>	查看特定任务状态	/gsd-quick status auth-fix
resume <slug>	恢复执行特定任务	/gsd-quick resume auth-fix

任务状态分为四种：

• complete ✓ — SUMMARY.md 存在且 frontmatter status=complete
• incomplete — SUMMARY.md 存在但 status 为 incomplete 或缺失
• in-progress — SUMMARY.md 缺失，创建时间 < 7 天
• abandoned? — SUMMARY.md 缺失，创建时间 ≥ 7 天

flowchart TD
    A[/gsd-quick list/] --> B[扫描 .planning/quick/*/]
    B --> C{SUMMARY.md?}
    C -->|是| D{status?}
    D -->|complete| E[complete ✓]
    D -->|incomplete| F[incomplete]
    C -->|否| G{创建时间?}
    G -->|< 7天| H[in-progress]
    G -->|≥ 7天| I[abandoned?]

---

六、/gsd-fast：极速模式

/gsd-fast 是 GSD 执行光谱中最轻量级的命令。它专为琐碎到不值得规划的任务设计。

6.1 quick 和 fast 的差异

这是 GSD 用户最容易混淆的一对命令。核心差异在于规划开销和子代理使用：

维度	/gsd-quick	/gsd-fast
生成 PLAN.md	是	否
使用子代理	是（精简）	否（Inline）
原子提交	是	是（如果适用）
STATE.md 更新	是（Quick Tasks 表）	否
典型耗时	5-30 分钟	< 2 分钟
典型场景	小型功能、Bug 修复	拼写修正、配置调整、简单重构

flowchart TD
    A{"任务评估"} -->|需要规划
或跟踪| B[/gsd-quick/]
    A -->|一句话能说清
2分钟内能做完| C[/gsd-fast/]
    
    B --> D[生成 Quick Plan
spawn 子代理]
    C --> E[Inline 直接修改
当前上下文]
    
    D --> F[更新 STATE.md]
    E --> G[完成，无额外跟踪]

6.2 速度 vs 质量的权衡

/gsd-fast 的设计体现了 GSD 的一个实用主义原则：不是所有任务都值得同等深度的质量保障。但这也带来了一个风险——如果滥用 /gsd-fast，可能导致：

• 缺乏上下文的草率修改
• 无法追踪的变更历史
• 累积的技术债务

使用准则：

flowchart TD
    A[任务进入] --> B{"能用一句话
描述清楚?"}
    B -->|否| C[使用 /gsd-quick]
    B -->|是| D{"能在 2 分钟内
完成?"}
    D -->|否| C
    D -->|是| E{"不需要
验证/测试?"}
    E -->|否| C
    E -->|是| F{"不是关键路径
代码?"}
    F -->|否| C
    F -->|是| G[使用 /gsd-fast]

GSD 官方文档明确警告："/gsd-fast 不是 /gsd:quick 的替代品——对于需要研究、多步规划或验证的任务，请使用 /gsd:quick。"/gsd-fast 只适用于你能在一个句子中描述清楚、并在两分钟之内执行完毕的任务。"

---

七、执行类命令的选择矩阵

面对一个具体任务，如何选择最合适的执行命令？以下决策矩阵提供了系统化的选择框架：

7.1 按任务特征选择

任务特征	推荐命令	理由
Phase 级别的批量计划执行	/gsd-execute-phase	完整的 Wave 并行、依赖管理、Phase 验证
Phase 执行后的质量检查	/gsd-verify-work	结构化 UAT、自动诊断、Gap Plan 生成
不确定用哪个命令	/gsd-do	智能路由、意图分析、自动匹配
小型功能/临时修复（需要跟踪）	/gsd-quick	精简规划、原子提交、STATE.md 跟踪
拼写修正、配置调整、简单重构	/gsd-fast	零规划开销、Inline 执行、最快响应

7.2 按项目阶段选择

项目阶段	典型任务	推荐命令
开发中	执行当前 Phase 的所有 Plan	/gsd-execute-phase
开发后	验证当前 Phase 的交付物	/gsd-verify-work
维护期	生产环境紧急修复	/gsd-quick（可叠加 --validate）
日常	读代码时顺手修个小问题	/gsd-fast
探索期	"我想做 X，该怎么做？"	/gsd-do

7.3 决策树

flowchart TD
    A[任务到来] --> B{"需要验证
已有工作?"}
    B -->|是| C[/gsd-verify-work/]
    B -->|否| D{"不知道用
哪个命令?"}
    D -->|是| E[/gsd-do/]
    D -->|否| F{"有现成的
Phase Plan?"}
    F -->|是| G[/gsd-execute-phase/]
    F -->|否| H{"任务规模?"}
    H -->|> 2分钟
或需规划| I[/gsd-quick/]
    H -->|< 2分钟
一句话能说清| J[/gsd-fast/]

---

八、小结

执行与验证类命令是 GSD 从"规划"跨越到"交付"的桥梁。五个命令构成了一个从重型规范执行到轻量级快速修复的完整光谱：

• /gsd-execute-phase：Phase 级别的核心执行引擎，Wave 并行模型确保最大化吞吐量的同时保证依赖正确性。Orchestrator 保持精简，子代理独立执行，上下文分配精妙。

• /gsd-verify-work：对话式 UAT 验证，一次只测一个功能点。验证失败时自动诊断、生成 Gap Plan，与 --gaps-only 配合形成"验证 → 修复 → 再验证"的闭环。

• /gsd-do：智能命令调度器，解析自然语言意图并路由到最合适的 GSD 命令。不执行工作，只负责"找到对的人"。

• /gsd-quick：快速任务执行通道，保留 GSD 核心保障（原子提交、STATE.md 跟踪）但缩短执行路径。精细的标志系统（--discuss、--research、--validate、--full）让用户可以动态调整质量保障深度。

• /gsd-fast：极速 Inline 模式，零规划开销，适用于 2 分钟内的琐碎任务。不是 /gsd-quick 的替代品，而是特定场景下的效率最大化选择。

理解这五个命令的定位和协作关系，是发挥 GSD 执行层最大效能的关键。正如 GSD 的设计哲学所言："The right tool for the right job, at the right level of rigor."——不同的任务需要不同的执行深度，而 GSD 为你提供了完整的选择光谱。

📌 下一篇预告：第 11 篇《辅助与调试命令》将深入解析 GSD 工具箱中的辅助类命令——包括状态查询、日志分析、上下文管理、调试诊断等命令。如果说执行类命令是 GSD 的"双手"，那么辅助与调试命令就是它的"眼睛"和"耳朵"——它们帮助你在复杂的项目执行过程中保持清晰的视野和敏锐的感知。