核心参考文档（上）

这是「GSD 全景代码解析」专题的第 32 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

---

一、核心参考文档概览

GSD 的参考文档（Reference Documents）是上下文工程的核心载体。在前面的章节中，我们已经多次接触到这些文档——它们被 Agent 读取、被工作流引用、被门控系统校验。本文将聚焦三个最核心的参考文档：

文档	大小	职责	主要读者
checkpoints.md	~31KB	定义检查点系统的完整规范	所有 Agent
gates.md	~8KB	定义四大门控类型和执行流程	工作流、门控 Agent
planning-config.md	~23KB	规划阶段的全局配置	Planner、Plan-Checker

这三个文档合计超过 60KB，占据了 GSD 参考文档体系的大部分篇幅。理解它们的设计，就理解了 GSD 如何在没有硬编码逻辑的情况下，通过纯文本配置驱动复杂的协作流程。

---

二、checkpoints.md：检查点系统

2.1 检查点的定义

checkpoints.md 是 GSD 中最大的一份参考文档（约 31KB）。它定义了**检查点（Checkpoint）**的完整语义：在任务执行的关键节点上，系统必须暂停并验证当前状态是否满足继续执行的条件。

检查点的设计哲学源于航空和医疗行业的安全实践——在关键操作前执行强制性的状态确认。GSD 将这一概念引入软件开发：

## Checkpoint 定义

检查点是任务执行流中的强制性验证节点。每个检查点包含：
- **ID**：唯一标识符（如 CP-PLAN-01）
- **触发条件**：何时激活该检查点
- **验证标准**：通过检查点必须满足的条件
- **失败处理**：未通过时的处理策略
- **责任人**：负责执行验证的 Agent

2.2 检查点类型

checkpoints.md 中定义了三种检查点类型，分别对应不同的验证深度：

类型一：状态检查点（State Checkpoint）

验证系统当前状态是否符合预期，不修改任何数据：

### State Checkpoint: CP-EXEC-01

**触发条件**：Executor 完成代码实现后
**验证标准**：
1. 所有计划中的任务条目标记为完成
2. 修改的文件通过了语法检查
3. 没有未处理的合并冲突
**失败处理**：返回 Executor 修复问题
**责任人**：gsd-executor（自检）

类型二：质量检查点（Quality Checkpoint）

验证产出物是否达到质量标准，通常需要专门的验证 Agent：

### Quality Checkpoint: CP-QUAL-01

**触发条件**：代码审查工作流启动时
**验证标准**：
1. 代码符合项目编码规范
2. 所有修改都有对应的测试覆盖
3. 没有已知的安全漏洞模式
4. 性能影响在可接受范围内
**失败处理**：触发修复工作流
**责任人**：gsd-code-reviewer

类型三：安全检堙点（Safety Checkpoint）

验证操作不会对系统造成不可逆伤害：

### Safety Checkpoint: CP-SAFE-01

**触发条件**：涉及以下操作前
- 删除生产环境数据
- 修改关键配置文件
- 执行数据库迁移
**验证标准**：
1. 操作已备份可回滚
2. 已确认操作范围
3. 已获得用户明确授权
**失败处理**：中止操作，请求人工确认
**责任人**：gsd-security-auditor + 用户确认

2.3 检查点触发条件

checkpoints.md 中定义了多种触发机制，使检查点能够无缝集成到工作流中：

触发机制	说明	示例
Phase 边界触发	工作流阶段转换时自动触发	plan → execute 转换时触发 CP-PLAN-02
Agent 完成触发	特定 Agent 完成工作时触发	Executor 完成时触发 CP-EXEC-01
文件变更触发	检测到特定文件变更时触发	修改 *.config.js 时触发 CP-SAFE-01
时间触发	定时检查	长时间运行任务每 30 分钟触发 CP-STATE-01
手动触发	用户或 Agent 显式触发	/gsd checkpoint CP-QUAL-01

2.4 检查点与工作流的集成

检查点不是独立运行的，而是深度嵌入工作流的执行管道中：

flowchart TD
    subgraph "Plan Phase"
        P1[Planner 制定计划] --> CP1{CP-PLAN-01
计划完整性检查}
        CP1 -->|通过| P2[Plan-Checker 验证]
        CP1 -->|失败| P1
        P2 --> CP2{CP-PLAN-02
计划可行性检查}
        CP2 -->|通过| E[进入 Execute Phase]
        CP2 -->|失败| P1
    end

    subgraph "Execute Phase"
        E --> E1[Executor 执行任务]
        E1 --> CP3{CP-EXEC-01
实现完整性检查}
        CP3 -->|通过| V[进入 Verify Phase]
        CP3 -->|失败| E1
    end

    subgraph "Verify Phase"
        V --> V1[Verifier 验证]
        V1 --> CP4{CP-QUAL-01
质量检查点}
        CP4 -->|通过| D[任务完成]
        CP4 -->|失败| F[触发修复工作流]
        F --> E1
    end

这种集成模式的关键特性：

1. 非侵入式：检查点不修改工作流逻辑，只添加验证层
2. 可组合：多个检查点可以串联形成验证链
3. 可短路：严重失败可以直接终止工作流
4. 可恢复：失败后可以从最近的检查点恢复

2.5 检查点的失败处理策略

checkpoints.md 定义了三种标准化的失败处理策略：

## 失败处理策略

### Retry（重试）
- 适用：临时性问题（如网络超时、文件锁定）
- 行为：返回上一步重新执行，最多重试 3 次
- 配置：`max_retries: 3`, `backoff: exponential`

### Escalate（升级）
- 适用：需要更多上下文或权限的问题
- 行为：将问题升级给更高级别的 Agent 或用户
- 配置：`escalate_to: gsd-planner | user`

### Abort（中止）
- 适用：无法自动恢复的致命错误
- 行为：保存当前状态，中止工作流，等待人工介入
- 配置：`save_state: true`, `notify: user`

---

三、gates.md：门控系统

如果说 checkpoints.md 定义了"在哪里检查"，那么 gates.md 定义了"如何通过检查"。门控（Gate）是 GSD 中用于控制工作流流转的核心机制。

3.1 四大门控类型

gates.md 中精确定义了四种门控类型，每种对应不同的决策逻辑：

Confirm Gate（确认门控）

最简单的门控类型——需要显式确认才能继续：

## Confirm Gate

**目的**：在不可逆操作前获取明确授权
**决策逻辑**：
- 呈现当前操作的完整上下文
- 列出所有潜在风险
- 等待用户明确的 "yes/confirm/approve" 响应
- 任何其他响应都视为拒绝

**典型场景**：
- 删除生产数据库
- 部署到生产环境
- 执行大额资金操作

Quality Gate（质量门控）

验证产出物是否达到预设质量标准：

## Quality Gate

**目的**：确保工作产出满足最低质量要求
**决策逻辑**：
1. 收集质量指标（测试覆盖率、代码复杂度、lint 分数等）
2. 与门控阈值对比
3. 全部达标 → 通过
4. 任一未达标 → 阻塞并返回改进建议

**可配置阈值**：
- `min_test_coverage: 80%`
- `max_cyclomatic_complexity: 10`
- `max_file_size: 500`
- `no_lint_errors: true`

Safety Gate（安全门控）

评估操作的安全风险：

## Safety Gate

**目的**：防止对系统造成不可逆伤害
**决策逻辑**：
1. 识别操作的风险等级（Low/Medium/High/Critical）
2. 自动处理 Low/Medium 风险
3. High 风险需要额外的确认步骤
4. Critical 风险必须人工审批

**风险评级因素**：
- 影响范围（单文件 / 模块 / 系统）
- 可逆性（可回滚 / 部分回滚 / 不可逆）
- 数据敏感性（公开 / 内部 / 敏感 / 机密）

Transition Gate（转换门控）

控制阶段间转换的条件：

## Transition Gate

**目的**：确保阶段转换的前提条件全部满足
**决策逻辑**：
1. 检查源阶段的完成状态
2. 验证目标阶段的准入条件
3. 检查阶段间数据传递的完整性
4. 确认所有必要 Agent 已加载

**典型转换**：
- plan → execute：计划已批准且资源已分配
- execute → verify：实现已完成且自测通过
- verify → done：所有质量检查通过

3.2 门控的执行流程

gates.md 中定义了统一的门控执行流程，无论哪种门控类型都遵循相同的执行框架：

flowchart TD
    Start[门控触发] --> Load[加载 Gate 配置]
    Load --> Collect[收集评估数据]
    
    Collect --> Evaluate{执行评估}
    Evaluate -->|Confirm Gate| C1[呈现上下文
等待用户响应]
    Evaluate -->|Quality Gate| C2[收集质量指标
对比阈值]
    Evaluate -->|Safety Gate| C3[评估风险等级
应用对应策略]
    Evaluate -->|Transition Gate| C4[检查转换条件
验证状态完整性]
    
    C1 --> Decision{决策结果}
    C2 --> Decision
    C3 --> Decision
    C4 --> Decision
    
    Decision -->|通过| Pass[记录 Gate 通过
继续工作流]
    Decision -->|阻塞| Block[记录阻塞原因
返回改进指引]
    Decision -->|拒绝| Reject[记录拒绝原因
中止或回滚]
    
    Pass --> End[Gate 执行完成]
    Block --> End
    Reject --> End

3.3 gate-prompts.md 的作用

与 gates.md 配套使用的是 gate-prompts.md，它存储了门控系统与 LLM 交互的 Prompt 模板：

## Gate Prompt 结构

每个门控类型对应一个 Prompt 模板：

### Confirm Gate Prompt

你正在评估一个需要用户确认的操作。

操作描述：
潜在风险：
影响范围：

请生成一个清晰、完整的确认请求，包含：

1. 操作摘要
2. 具体风险清单
3. 确认指令（明确告知用户如何确认或拒绝）

注意：用户必须明确说 "yes" 或 "confirm" 才能通过。

### Quality Gate Prompt

你正在执行质量检查。

检查项：
实际指标：
阈值要求：

请评估每个检查项是否达标，输出格式：

• 通过的项：简要说明
• 失败的项：具体问题 + 改进建议

最终判断：PASS / FAIL

```

`gate-prompts.md` 的设计体现了 GSD 的**提示词即代码（Prompt-as-Code）**理念：

1. **可版本控制**：Prompt 模板与代码一同提交到 Git
2. **可热更新**：修改 Prompt 无需重启系统
3. **可 A/B 测试**：可以并行测试不同 Prompt 的效果
4. **可审计**：每次门控决策都保留了使用的 Prompt 版本

### 3.4 门控与检查点的关系

初学者容易混淆检查点和门控的概念。它们的关系如下：

| 维度 | Checkpoint | Gate |
|------|-----------|------|
| **本质** | 一个"位置标记" | 一个"决策机制" |
| **职责** | 定义"何时检查" | 定义"如何决策" |
| **执行** | 触发门控评估 | 执行具体的通过/阻塞逻辑 |
| **配置** | 在 checkpoints.md 中 | 在 gates.md 中 |
| **关系** | 一个检查点可以触发多个门控 | 一个门控可以被多个检查点复用 |

简言之：**检查点是"路标"，门控是"关卡"**。路标告诉你到了哪里，关卡决定你能不能继续走。

---

## 四、planning-config.md：规划配置

### 4.1 规划配置项详解

`planning-config.md`（约 23KB）是 GSD 中规划阶段的"宪法"，它定义了 Planner 和 Plan-Checker 的所有行为参数。这份文档之所以庞大，是因为它采用了**显式枚举所有配置项**的设计策略——每个配置项都有详细的说明、默认值、取值范围和示例。

#### 核心配置域

```markdown
## Planning Configuration

### 1. Plan Structure（计划结构）

控制生成计划的格式和粒度：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `plan.max_tasks` | 20 | 单个计划的最大任务数 |
| `plan.max_depth` | 3 | 任务嵌套的最大深度 |
| `plan.require_estimates` | true | 是否要求每个任务都有时间估算 |
| `plan.require_dependencies` | true | 是否要求显式声明任务依赖 |
| `plan.output_format` | "hierarchical" | 计划输出格式：hierarchical / flat / kanban |

估算配置

### 2. Estimation（估算）

控制任务时间估算的行为：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `estimate.unit` | "hour" | 估算单位：minute / hour / day / story_point |
| `estimate.buffer_ratio` | 0.2 | 缓冲时间比例（20%） |
| `estimate.confidence_levels` | ["high", "medium", "low"] | 置信度级别 |
| `estimate.min_confidence_for_commit` | "medium" | 可承诺的最低置信度 |

依赖配置

### 3. Dependency（依赖）

控制任务依赖关系的管理：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `dependency.allowed_types` | ["blocks", "depends_on", "relates_to"] | 允许的依赖类型 |
| `dependency.detect_cycles` | true | 是否自动检测循环依赖 |
| `dependency.max_chain_length` | 10 | 最长依赖链长度 |

资源配置

### 4. Resource（资源）

控制资源分配策略：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `resource.track_assignee` | true | 是否跟踪任务负责人 |
| `resource.max_parallel_tasks` | 5 | 最大并行任务数 |
| `resource.consider_availability` | false | 是否考虑 Agent 可用性 |

质量标准配置

### 5. Quality（质量）

控制计划本身的质量门槛：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `quality.min_test_tasks_ratio` | 0.3 | 测试任务最小比例（30%） |
| `quality.require_documentation_tasks` | true | 是否要求文档任务 |
| `quality.require_review_tasks` | true | 是否要求审查任务 |
| `quality.forbid_undefined_tools` | true | 是否禁止未定义的工具使用 |

4.2 Absent = Enabled 原则的体现

planning-config.md 是 GSD Absent = Enabled 设计原则最典型的体现。这一原则的核心思想是：

如果某个配置项在配置文件中不存在，则启用其默认的、最安全的、最通用的行为。

换句话说，配置项的"缺席"（Absent）等价于"启用默认功能"（Enabled），而不是"禁用"（Disabled）。

这一原则在 planning-config.md 中有三层体现：

第一层：配置项的默认值设计

## Default Value Philosophy

每个配置项的默认值都遵循以下优先级：
1. **安全优先**：默认行为不会导致数据丢失或系统损坏
2. **完整优先**：默认行为倾向于生成更完整的计划而非更精简的
3. **显式优先**：默认行为鼓励显式声明而非隐式推断

示例：
- `plan.require_dependencies: true` —— 默认要求显式声明依赖
- `quality.require_review_tasks: true` —— 默认要求包含审查任务
- `dependency.detect_cycles: true` —— 默认启用循环依赖检测

第二层：配置文件的自解释性

## Self-Documenting Config

planning-config.md 中的每个配置项都包含：
- 完整说明
- 默认值
- 可选值列表
- 使用示例
- 相关配置项的交叉引用

这意味着即使某个配置项被删除，阅读相邻配置项的说明也能推断出被删除项的默认行为。

第三层：渐进式配置

## Progressive Configuration

新用户可以从零配置开始：
1. 不修改任何配置 → 使用全套默认行为（最安全、最完整）
2. 逐渐添加覆盖 → 只修改需要定制的项
3. 完全自定义 → 覆盖大部分配置项

这与传统系统的"默认关闭所有功能"形成鲜明对比。

4.3 配置优先级

planning-config.md 还定义了配置值的解析优先级，确保当多个来源提供同一配置时，系统能正确决策：

flowchart BT
    subgraph "配置来源（从高到低优先级）"
        A1[命令行参数
--plan-max-tasks=10]
        A2[环境变量
GSD_PLAN_MAX_TASKS=10]
        A3[项目级配置
.gsd/planning-config.local.md]
        A4[用户级配置
~/.gsd/planning-config.md]
        A5[系统默认
planning-config.md]
    end

    A1 -->|最高优先级| Merge[配置合并]
    A2 --> Merge
    A3 --> Merge
    A4 --> Merge
    A5 -->|最低优先级| Merge
    
    Merge --> Final[最终生效配置]

优先级的具体规则：

## Configuration Precedence Rules

1. **命令行参数**（最高优先级）
   - 格式：`--config.key=value`
   - 适用：一次性覆盖，不影响持久配置

2. **环境变量**
   - 格式：`GSD_PLAN_MAX_TASKS=10`
   - 适用：CI/CD 环境、容器部署

3. **项目级本地配置**（`.gsd/planning-config.local.md`）
   - 适用：项目特定的配置，不提交到版本控制
   - 场景：本地开发环境的特殊设置

4. **项目级共享配置**（`.gsd/planning-config.md`）
   - 适用：项目团队的共享配置
   - 场景：提交到 Git，团队统一规范

5. **用户级配置**（`~/.gsd/planning-config.md`）
   - 适用：用户个人的全局偏好
   - 场景：个人的默认模型选择、主题偏好

6. **系统默认**（`planning-config.md`，最低优先级）
   - 适用：所有未被覆盖的配置项
   - 场景：作为完整参考文档和 fallback

这种分层设计的好处：

• 灵活性：不同场景使用不同优先级的配置来源
• 可复现性：项目级配置提交到 Git，确保团队协作一致性
• 个性化：用户级配置不影响项目，满足个人偏好
• 安全性：命令行和环境变量可以覆盖一切，方便紧急处理

4.4 planning-config.md 的文档双重身份

planning-config.md 在 GSD 中具有独特的双重身份：

1. 作为代码：它是配置系统的权威来源，被解析器读取并生效
2. 作为文档：它是配置项的完整参考手册，供用户和 Agent 查阅

## Dual Nature of planning-config.md

这份文件既是机器可解析的配置，也是人类可阅读的文档：

- **机器读取**：解析器提取 `key: value` 对作为运行时配置
- **人类阅读**：Markdown 格式和表格提供了完整的说明上下文
- **Agent 学习**：Planner Agent 读取此文件以了解配置约束

这种设计避免了"配置与文档不同步"的经典问题——因为它们是同一个文件。

---

五、三大文档的协作关系

checkpoints.md、gates.md 和 planning-config.md 并非独立存在，它们在工作流中形成了紧密的协作关系：

flowchart LR
    subgraph "Reference Documents"
        PC[planning-config.md
规划配置]
        CP[checkpoints.md
检查点定义]
        G[gates.md
门控定义]
        GP[gate-prompts.md
门控 Prompt]
    end

    subgraph "Workflow Execution"
        P[Planner] -->|读取配置| PC
        P -->|生成计划| E[Executor]
        
        E -->|到达检查点| CP
        CP -->|触发| G
        G -->|使用| GP
        GP -->|返回结果| G
        G -->|决策| E
    end

    style PC fill:#e1f5fe
    style CP fill:#e8f5e9
    style G fill:#fff3e0
    style GP fill:#fce4ec

协作流程说明：

1. Planner 阶段：Planner 读取 planning-config.md，根据配置约束生成计划
2. Plan-Checker 阶段：Plan-Checker 使用 planning-config 中的质量标准检查计划
3. Execute 阶段：Executor 在执行过程中到达 checkpoints.md 定义的检查点
4. Gate 评估：检查点触发 gates.md 中定义的门控，门控使用 gate-prompts.md 中的 Prompt 模板与 LLM 交互
5. 决策流转：门控通过则继续执行，阻塞则返回改进，拒绝则中止

---

六、小结

本文深入解析了 GSD 上下文工程与参考体系中的三份核心文档：

1. checkpoints.md（31KB）：定义了检查点系统的完整规范，包括三种检查点类型（State/Quality/Safety）、多种触发条件和失败处理策略。检查点作为"路标"，在工作流的关键节点上强制执行状态验证。

2. gates.md（~8KB）：定义了四大门控类型（Confirm/Quality/Safety/Transition）和统一的执行流程。门控作为"关卡"，控制着工作流的流转决策。配套的 gate-prompts.md 将 Prompt 作为一等公民进行管理。

3. planning-config.md（23KB）：规划阶段的完整配置参考，涵盖计划结构、估算、依赖、资源和质量五大配置域。它是 Absent = Enabled 原则最典型的实践——未配置即启用安全默认值。

这三份文档共同构成了 GSD 的"神经系统"：检查点负责感知状态，门控负责决策流转，规划配置负责定义行为边界。它们都是纯 Markdown 文件，却通过精妙的结构设计，驱动着复杂的 AI Agent 协作流程。

---

下一篇预告： 第 33 篇《核心参考文档（下）》——继续深入解析 session-state.md、context-management.md、tool-registry.md 等剩余核心参考文档，以及它们如何共同支撑 GSD 的上下文工程体系。