辅助与调试命令 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 11 篇。

在 GSD 的完整命令体系中，除了贯穿项目生命周期的主流程命令（如 /gsd-new-project、/gsd-plan、/gsd-execute）外，还设计了一套精心打磨的辅助与调试命令。这些命令不直接参与功能交付，却在降低使用门槛、提升开发体验、保障代码质量方面扮演着不可替代的角色。

本文将逐一解析六个核心辅助命令的设计哲学与使用技巧：

命令	核心职责	使用频率
`/gsd-discuss-phase`	阶段讨论与决策提取	高
`/gsd-debug`	系统化调试与问题诊断	高
`/gsd-help`	命令参考与帮助系统	极高
`/gsd-settings`	工作流配置管理	中
`/gsd-stats`	项目统计与度量	中
`/gsd-code-review`	代码审查与质量保障	高

一、`/gsd-discuss-phase`：讨论阶段

/gsd-discuss-phase 是 GSD 规划流程的前置命令，用于在正式进入规划之前，通过自适应提问的方式，提取下游 Agent（researcher、planner）所需的实现决策。它的核心产出是 {phase_num}-CONTEXT.md，这份文件包含了足够清晰的决策，使得后续 Agent 无需再次询问用户即可行动。

1.1 多模式支持

GSD 为不同场景设计了多种讨论模式，通过命令参数灵活切换：

/gsd-discuss-phase <phase> [--all] [--auto] [--chain] [--batch] [--analyze] [--text] [--power]

参数	模式名称	行为描述
`--all`	全量讨论	跳过区域选择，交互式讨论所有灰色区域
`--auto`	自动模式	跳过交互式提问，Claude 自动选择推荐默认值
`--chain`	链式模式	交互式讨论后自动执行 plan + execute
`--batch`	批处理模式	批量处理问题
`--power`	强力模式	批量生成问题到文件 UI，用户可按自己的节奏回答
`--analyze`	假设分析	基于假设驱动的方式分析阶段上下文
`--text`	文本模式	纯文本交互，无富 UI

1.2 假设分析与头脑风暴

讨论阶段的核心价值在于识别并澄清"灰色区域"——那些尚未做出明确决策的实现细节。命令的工作流程如下：

flowchart TD
    A[加载 prior context
PROJECT.md / REQUIREMENTS.md / STATE.md] --> B[代码库侦察
可复用资产与模式]
    B --> C{灰色区域分析
跳过已决策项}
    C --> D[呈现剩余灰色区域
用户选择讨论项]
    D --> E[逐项深入讨论
直到用户满意]
    E --> F{范围蔓延?}
    F -->|是| G[重定向到 deferred ideas]
    F -->|否| H[生成 CONTEXT.md
锁定决策]
    G --> D

模式路由由 workflow.discuss_mode 配置控制：

discuss（默认）：标准讨论流程，执行 discuss-phase.md 工作流
assumptions：假设驱动模式，执行 discuss-phase-assumptions.md 工作流

设计亮点：--power 模式将批量问题生成到文件 UI，解决了传统交互式提问"一次只能回答一个"的痛点，特别适合复杂项目的前期需求梳理。

1.3 与规划/执行的关系

/gsd-discuss-phase 在整个 GSD 工作流中处于承上启下的位置：

sequenceDiagram
    actor U as 用户
    participant D as /gsd-discuss-phase
    participant C as CONTEXT.md
    participant P as /gsd-plan
    participant E as /gsd-execute

    U->>D: 指定阶段 + 选择模式
    D->>D: 加载 prior context
    D->>D: 识别灰色区域
    U->>D: 选择讨论项
    D->>U: 自适应提问
    U->>D: 回答决策
    D->>C: 生成阶段上下文
    C->>P: 为规划提供决策依据
    P->>E: 生成执行计划
    E->>U: 交付功能

成功标准（来自命令定义）：

[x] 已加载并应用 prior context（不重复询问已决策问题）
[x] 通过智能分析识别灰色区域
[x] 用户选择讨论区域
[x] 每个选中区域深入探索直至满意
[x] 范围蔓延被重定向到 deferred ideas
[x] CONTEXT.md 捕获的是具体决策，而非模糊愿景
[x] 用户清楚下一步行动

二、`/gsd-debug`：调试命令

调试是开发中最消耗上下文资源的环节之一。GSD 的 /gsd-debug 命令采用科学方法 + 子 Agent 隔离的架构，将调试会话从主上下文中剥离，每个调查获得全新的 200k 上下文窗口。

2.1 调试策略与流程

flowchart TD
    A[用户描述问题] --> B{解析子命令}
    B -->|list| C[列出活跃会话]
    B -->|status | D[查看会话摘要]
    B -->|continue | E[恢复指定会话]
    B -->|无子命令| F[收集症状]
    F --> F1[期望行为?]
    F1 --> F2[实际行为?]
    F2 --> F3[错误信息?]
    F3 --> F4[时间线?]
    F4 --> F5[如何复现?]
    F5 --> G[生成 slug
创建会话文件]
    G --> H[委派给
gsd-debug-session-manager]
    H --> I{诊断结果}
    I -->|ROOT CAUSE FOUND| J[ specialist_hint 分派 ]
    I -->|需继续| H
    J --> K[提供修复选项]

2.2 与 gsd-debugger Agent 的协作

调试命令采用双层 Agent 架构：

层级	Agent 类型	职责
调度层	主上下文（Orchestrator）	收集症状、创建会话、Checkpoint 管理
执行层	`gsd-debug-session-manager`	管理调试检查点/续接循环
调查层	`gsd-debugger`	使用科学方法调查 Bug

子命令详解：

/gsd-debug list                          # 列出所有活跃调试会话
/gsd-debug status <slug>                 # 打印会话完整摘要（不生成 Agent）
/gsd-debug continue <slug>               # 恢复指定会话
/gsd-debug --diagnose <issue desc>       # 仅诊断不修复，返回结构化根因报告
/gsd-debug <issue description>           # 标准调试流程（诊断 + 修复）

2.3 常见问题诊断

调试会话文件存储在 .planning/debug/{slug}.md，采用结构化 Markdown 格式，包含：

---
status: investigating
trigger: "用户描述的问题"
created: 2026-04-23
updated: 2026-04-23
---

## Current Focus
- hypothesis: "当前假设"
- test: "验证方法"
- expecting: "预期结果"
- next_action: "下一步行动"

## Evidence
- timestamp: 2026-04-23T10:00:00Z
  observation: "观察到的现象"

## Eliminated
- hypothesis: "已排除的假设"
  reason: "排除原因"

## Resolution
- root_cause: "根因"
- fix: "修复方案"
- verification: "验证结果"

关键设计决策：

上下文隔离：每个调试调查使用独立的 200k 上下文，避免主上下文被文件阅读和假设测试耗尽
持久化状态：会话文件在上下文重置后依然存在，支持随时续接
TDD 集成：读取 workflow.tdd_mode 配置，调试过程可与测试驱动开发联动
专家分派：当 gsd-debugger 返回 ROOT CAUSE FOUND 时，自动提取 specialist_hint 字段并调用对应技能（如 typescript-expert、swift-concurrency）

三、`/gsd-help`：帮助系统

帮助系统是降低 GSD 使用门槛的第一道防线。/gsd-help 的设计理念是**"零噪音参考"**——只输出命令参考内容，不做任何项目分析或下一步建议。

3.1 命令列表和用法说明

/gsd-help 从工作流文件 workflows/help.md 中读取并输出完整的 GSD 命令参考。输出内容涵盖：

核心命令：项目初始化、需求管理、规划执行
辅助命令：调试、统计、审查、配置
高级命令：Spike、Sketch、代码映射等
每个命令的参数格式和使用示例

3.2 上下文感知的帮助

虽然当前的 /gsd-help 实现是一个简单的薄分发层（thin dispatch layer），但 GSD 的命令设计本身具备上下文感知能力：

flowchart LR
    A[/gsd-help] --> B[读取 workflows/help.md]
    B --> C[输出完整命令参考]
    C --> D[用户]
    D --> E{需要深入了解?}
    E -->|是| F[/gsd-discuss-phase]
    E -->|是| G[/gsd-debug]
    E -->|是| H[/gsd-settings]

设计约束：/gsd-help 严格遵循"只输出参考，不做分析"的原则。命令定义中明确禁止输出：项目特定分析、Git 状态、下一步建议、任何超出参考本身的评论。

四、`/gsd-settings`：配置管理

GSD 的强大之处在于其高度可配置性。/gsd-settings 提供交互式配置界面，管理整个工作流的 Agent 行为和模型配置。

4.1 全局配置与项目配置

GSD 采用层级配置体系：

flowchart TD
    A[配置读取] --> B{配置来源}
    B -->|全局| C[~/.claude/get-shit-done/config.json]
    B -->|项目级| D[.claude/get-shit-done/config.json]
    B -->|环境变量| E[GSD_* 环境变量]
    B -->|命令行| F[--flag 参数]
    C --> G[合并配置]
    D --> G
    E --> G
    F --> G
    G --> H[最终生效配置]

4.2 配置优先级

GSD 的配置遵循**"就近原则"**，优先级从高到低：

命令行参数（如 --depth=deep）
环境变量（GSD_* 前缀）
项目级配置（.claude/get-shit-done/config.json）
全局配置（~/.claude/get-shit-done/config.json）
内置默认值

4.3 常用配置项

/gsd-settings 通过交互式 5 问题提示完成配置：

配置项	说明	可选值
`model`	主力模型	claude-sonnet-4, claude-opus-4, gpt-4o, 等
`research`	研究 Agent 模型	同上
`plan_check`	规划检查开关	true / false
`verifier`	验证 Agent 模型	同上
`branching`	分支策略	auto / manual / disabled

配置流程自动化处理：

检查配置文件是否存在，不存在则创建默认配置
读取当前配置并解析
交互式展示 5 个问题，预选中当前值
解析用户回答并合并到配置
写入配置文件
显示确认信息和快捷命令参考

五、`/gsd-stats`：统计信息

/gsd-stats 是 GSD 的"仪表盘"命令，提供项目健康度和工作流效率的量化视图。

5.1 项目统计

项目级统计包括：

阶段进度：已完成 / 进行中 / 待启动的阶段数量
计划执行指标：任务完成率、延期率、取消率
需求完成度：REQUIREMENTS.md 中需求的实现状态

5.2 会话统计

会话级统计追踪当前工作会话的状态：

当前活跃阶段
本会话执行的命令历史
上下文使用量估算

5.3 性能指标

Git 相关的性能指标：

提交频率和代码变更量
分支活动情况
代码审查覆盖率

/gsd-stats
# 输出示例：
# ┌─────────────────────────────────────────────┐
# │           GSD Project Statistics            │
# ├─────────────────────────────────────────────┤
# │  Phases:  3 completed | 1 active | 2 pending│
# │  Tasks:   24 done | 5 in progress | 1 blocked│
# │  Requirements: 87% satisfied               │
# │  Commits: 142 (last 7 days: 23)            │
# │  Code Review Coverage: 78%                 │
# └─────────────────────────────────────────────┘

实现说明：/gsd-stats 是一个薄分发层，核心逻辑委托给 workflows/stats.md 工作流，由其读取 .planning/ 目录下的阶段文件、SUMMARY.md 和 Git 历史来生成统计报告。

六、`/gsd-code-review`：代码审查

代码审查是 GSD 质量保障体系的重要一环。/gsd-code-review 将审查工作委托给专门的 gsd-code-reviewer Agent，根据指定深度分析代码中的 Bug、安全漏洞和质量问题。

6.1 审查流程

flowchart TD
    A[/gsd-code-review ] --> B[阶段验证]
    B --> C{配置门检查
workflow.code_review}
    C -->|disabled| D[跳过审查]
    C -->|enabled| E[文件范围确定]
    E --> E1[--files 参数]
    E1 -->|提供| F[使用指定文件]
    E1 -->|未提供| E2[读取 SUMMARY.md]
    E2 -->|有文件列表| F
    E2 -->|无| E3[Git diff 回退]
    E3 --> F
    F --> G{空范围?}
    G -->|是| H[跳过并提示]
    G -->|否| I[生成 Agent 提示]
    I --> J[生成 gsd-code-reviewer]
    J --> K[生成 REVIEW.md]
    K --> L[内联总结发现]

6.2 与 gsd-code-reviewer Agent 的协作

审查深度可通过参数或配置灵活调整：

/gsd-code-review 2                          # 标准深度审查第 2 阶段
/gsd-code-review 2 --depth=quick            # 快速模式（约 2 分钟）
/gsd-code-review 2 --depth=deep             # 深度模式（约 15-30 分钟）
/gsd-code-review 2 --files src/auth.ts,src/api.ts  # 指定文件列表

深度	描述	耗时	适用场景
`quick`	仅模式匹配	~2 分钟	快速扫描、预提交检查
`standard`	逐文件分析 + 语言特定检查	~5-15 分钟	常规阶段审查（默认）
`deep`	跨文件分析 + 导入图和调用链	~15-30 分钟	关键模块、安全审查

输出产物：

{padded_phase}-REVIEW.md：按严重程度分类的审查发现
内联摘要：直接在对话中展示关键发现和建议

审查流程中的门控机制：

阶段验证：确保阶段存在且有效
配置门：检查 workflow.code_review 是否启用
空范围检查：如果无文件可审查，优雅跳过

七、辅助命令的价值：降低门槛，提升体验

GSD 的辅助命令系统体现了**"复杂在系统，简单在用户"**的设计哲学。让我们通过一个完整的开发场景来感受这些命令的协同价值：

sequenceDiagram
    actor U as 开发者
    participant H as /gsd-help
    participant S as /gsd-settings
    participant D as /gsd-discuss-phase
    participant St as /gsd-stats
    participant De as /gsd-debug
    participant C as /gsd-code-review

    U->>H: 刚接触 GSD，查看可用命令
    H->>U: 输出完整命令参考

    U->>S: 配置工作流偏好
    S->>U: 交互式完成 5 项配置

    U->>D: 开始第 3 阶段，讨论实现方案
    D->>U: 自适应提问，澄清灰色区域
    U->>D: 确认决策
    D->>U: 生成 03-CONTEXT.md

    U->>St: 查看项目统计
    St->>U: 阶段进度 60%，需求完成度 85%

    Note over U,De: 开发过程中遇到 Bug
    U->>De: 描述问题
    De->>U: 生成调试会话，委派 gsd-debugger
    De->>U: 根因定位：时区处理逻辑错误
    U->>De: 确认修复
    De->>U: 完成调试，会话归档

    Note over U,C: 阶段开发完成
    U->>C: 审查第 3 阶段代码
    C->>U: 生成 03-REVIEW.md
    C->>U: 发现 2 个中等风险项，建议修复

核心价值总结

可发现性（Discoverability）：/gsd-help 让新用户能在 30 秒内了解 GSD 的全部能力，消除"我不知道这个命令存在"的痛点。
可配置性（Configurability）：/gsd-settings 将工作流从"一刀切"变为"量身定做"，适应不同团队规模和项目类型的需求。
可调试性（Debuggability）：/gsd-debug 的科学方法 + 子 Agent 隔离架构，让复杂问题的诊断不再受上下文窗口限制。
可度量性（Measurability）：/gsd-stats 提供项目健康度的量化反馈，帮助团队识别瓶颈和优化工作流。
可审查性（Reviewability）：/gsd-code-review 将质量保障内建到工作流中，而非依赖事后的人工审查。
可协商性（Negotiability）：/gsd-discuss-phase 在规划前充分澄清需求，减少"做出来才发现不对"的返工成本。

结语

GSD 的辅助命令并非"锦上添花"的装饰，而是整个工作流可用性工程的关键组成部分。它们共同构成了一个自洽的生态系统：

帮助系统解决"我不知道"的问题
配置系统解决"不适合我"的问题
调试系统解决"出错了怎么办"的问题
统计系统解决"进度如何"的问题
审查系统解决"质量够吗"的问题
讨论系统解决"需求清楚吗"的问题

这些命令与主流程命令相辅相成，让 GSD 从一套"能工作的命令集合"进化为一个"开发者愿意每天使用的完整工作流"。

下一篇预告：在了解了 GSD 的全部命令后，我们将在第 12 篇《命令设计模式与最佳实践》中深入探讨 GSD 命令系统背后的设计模式——薄分发层、工作流委托、Agent 编排、门控机制等核心架构决策，以及这些模式如何支撑起整个系统的可扩展性和可维护性。敬请期待！

一、/gsd-discuss-phase：讨论阶段