这是「GSD 全景代码解析」专题的第 47 篇。
在 第 19 篇 中，我们初步接触了 GSD 的质量门控体系，了解了门控如何嵌入各个工作流。在 第 32 篇 中，我们解析了 gates.md 的四大门控类型和 gate-prompts.md 的 Prompt 模板。但这些内容分散在不同章节，尚未形成统一的体系视角。
本文将站在体系高度，完整梳理 GSD 的质量门控架构：从四大 Gate 类型的设计哲学，到 gate-prompts.md 的 Prompt-as-Code 实践；从检查点（Checkpoint）的触发机制，到门控如何与钩子系统、Agent 验证共同构成 Defense in Depth 的纵深防御矩阵。理解这套体系，就理解了 GSD 如何在无人监督的自主执行中守住质量底线。
一、质量门控体系概述
1.1 门控不是可选项，是基础设施
在传统的 AI 辅助编程工具中，质量检查往往是"锦上添花"——有则更好，没有也行。GSD 采取了截然相反的态度：门控是工作流的基础设施，不是可选插件。
这一设计源于 GSD 的核心假设：当 Agent 获得文件系统的写入权限、Git 仓库的提交权限、乃至生产环境的部署权限时，任何质量缺陷的代价都会被放大。一个没有门控的自主 Agent，等同于一辆没有刹车的自动驾驶汽车。
GSD 的门控体系由三个核心组件构成：
flowchart TD
subgraph "门控基础设施"
A[gates.md
门控规则定义]
B[gate-prompts.md
LLM 交互模板]
C[checkpoints.md
检查点触发机制]
end
subgraph "执行层"
D[工作流编排器]
E[门控评估 Agent]
F[检查点触发器]
end
subgraph "防御层"
G[钩子系统
运行时监控]
H[Agent 自验证
执行时校验]
end
A --> D
B --> E
C --> F
D --> E
F --> E
E --> G
E --> H1.2 门控的两种语义
在 GSD 的术语体系中，"门控"有两层语义，初学者容易混淆：
| 语义 | 定义 | 对应文档 | 典型读者 |
|---|---|---|---|
| Gate（门控类型） | 四种 canonical 决策模式：Confirm/Quality/Safety/Transition | gates.md | 工作流设计者 |
| Quality Gate（质量门控实例） | 嵌入工作流的具体检查点，如"代码审查门控" | checkpoints.md + 工作流文件 | 执行时 Agent |
简单来说：gates.md 定义了"门有哪几种"，checkpoints.md 定义了"哪里需要设门"。两者配合，才构成完整的门控体系。
1.3 门控的决策结果
无论哪种门控类型，评估后的决策结果都统一为三种状态：
| 结果 | 含义 | 后续行为 |
|---|---|---|
| PASS（通过） | 所有条件满足，可以继续 | 记录日志，推进工作流 |
| BLOCK（阻塞） | 条件未满足，但可以修复 | 返回改进指引，等待修复后重试 |
| REJECT（拒绝） | 条件严重不满足，或存在不可逆风险 | 中止或回滚，必要时升级给人类 |
这三种状态与 第 39 篇 中 Phase Runner 的错误处理策略（Retry / Escalate / Abort）形成映射关系，确保门控决策能够被执行层正确消化。
二、四大 Gate 类型详解
gates.md（约 8KB）精确定义了四种 canonical gate types。这四种类型不是随意划分，而是覆盖了软件开发中所有关键的决策场景：从"要不要做"到"做得好不好"，从"安不安全"到"能不能进入下一阶段"。
2.1 Confirm Gate：确认门控
核心问题：这个操作是否应该执行？
Confirm Gate 是最"保守"的门控——它不对质量做判断，只要求明确授权。其决策逻辑极为严格：
## Confirm Gate
**目的**：在不可逆操作前获取明确授权
**决策逻辑**：
- 呈现当前操作的完整上下文
- 列出所有潜在风险
- 等待用户明确的 "yes/confirm/approve" 响应
- 任何其他响应都视为拒绝
**典型场景**：
- 删除生产数据库
- 部署到生产环境
- 执行大额资金操作
- 修改关键配置文件（如 payment gateway 凭证）Confirm Gate 的设计哲学是"不信任，要确认"（Don’t Trust, Confirm）。即使 Agent 有 99% 的把握某个操作是正确的，只要该操作属于 Confirm Gate 的管辖范围，就必须停下来等待人类拍板。
在 第 16 篇 中，我们见到了一个典型的 Confirm Gate 实例——Ready? Gate：在生成 PROJECT.md 之前，Agent 会暂停并询问用户"我们是否已充分理解需求？"，用户回答 "Keep exploring" 则继续深入，回答 "Ready" 则进入正式规划。这个设计确保了项目初始化不是草率的，而是充分共识后的产物。
2.2 Quality Gate：质量门控
核心问题：产出物是否达到了预设的质量标准？
Quality Gate 是 GSD 中使用最频繁的门控类型。它不依赖人类判断，而是通过量化指标自动做出决策：
## Quality Gate
**目的**：确保工作产出满足最低质量要求
**决策逻辑**：
1. 收集质量指标（测试覆盖率、代码复杂度、lint 分数等）
2. 与门控阈值对比
3. 全部达标 → 通过
4. 任一未达标 → 阻塞并返回改进建议
**可配置阈值**：
- `min_test_coverage: 80%`
- `max_cyclomatic_complexity: 10`
- `max_file_size: 500`
- `no_lint_errors: true`Quality Gate 的关键设计是**"标准前置"**：质量标准不是在验证时才临时制定的，而是在 PLAN.md 和 gates.md 中预先定义好的。这种设计避免了"标准漂移"——如果 Verifier 在验证时自行解释什么是"足够好"，不同运行之间就会产生不一致的判定。
在 第 25 篇 中，我们看到 gsd-code-reviewer 的审查判定与 gates.md 中的质量门控阈值深度联动：
# gates.md 中与代码审查相关的配置
quality_gate:
code_review:
min_coverage: 80
max_complexity: 10
no_critical_issues: true
max_review_rounds: 3Code Reviewer 不会说"这段代码看起来不错"，而是会说"测试覆盖率 85% ≥ 阈值 80%，通过；圈复杂度 12 > 阈值 10，阻塞"。这种量化语言消除了主观性，使质量判定可重复、可审计。
2.3 Safety Gate：安全门控
核心问题：这个操作会对系统造成不可逆伤害吗？
Safety Gate 评估的是风险等级，而非绝对的安全性。它承认"零风险"在工程实践中是不现实的，于是采用分级策略：
## Safety Gate
**目的**：防止对系统造成不可逆伤害
**决策逻辑**：
1. 识别操作的风险等级（Low/Medium/High/Critical）
2. 自动处理 Low/Medium 风险
3. High 风险需要额外的确认步骤
4. Critical 风险必须人工审批
**风险评级因素**：
- 影响范围（单文件 / 模块 / 系统）
- 可逆性（可回滚 / 部分回滚 / 不可逆）
- 数据敏感性（公开 / 内部 / 敏感 / 机密）Safety Gate 的风险评级矩阵是一个三维决策空间：
| 影响范围 | 可逆性 | 数据敏感性 | 风险等级 | 处理策略 |
|---|---|---|---|---|
| 单文件 | 可回滚 | 公开 | Low | 自动通过 |
| 模块 | 部分回滚 | 内部 | Medium | 自动通过，记录日志 |
| 系统 | 不可逆 | 敏感 | High | 触发 Confirm Gate |
| 系统 | 不可逆 | 机密 | Critical | 必须人工审批 |
在 第 27 篇 中，gsd-security-auditor 在执行安全审查时就是 Safety Gate 的具体执行者。它不会阻止所有"可能有问题"的代码，而是根据风险等级决定是自动修复、标记警告还是暂停工作流等待人工介入。
2.4 Transition Gate：转换门控
核心问题：当前阶段真的完成了吗？可以进入下一阶段了吗？
Transition Gate 控制的是阶段间转换。它与 Quality Gate 的区别在于：Quality Gate 检查"做得好不好"，Transition Gate 检查"能不能走"。
## Transition Gate
**目的**：确保阶段转换的前提条件全部满足
**决策逻辑**：
1. 检查源阶段的完成状态
2. 验证目标阶段的准入条件
3. 检查阶段间数据传递的完整性
4. 确认所有必要 Agent 已加载
**典型转换**：
- plan → execute：计划已批准且资源已分配
- execute → verify：实现已完成且自测通过
- verify → done：所有质量检查通过Transition Gate 的一个关键设计是数据完整性检查。在 plan → execute 转换时，Transition Gate 不仅检查 PLAN.md 是否存在，还会验证：
PLAN.md中引用的所有外部文件是否可访问STATE.md中的阶段标记是否与当前状态一致- 目标阶段需要的 Agent（如
gsd-executor）是否在上下文中可用
这种检查防止了"带着残缺计划进入执行"或"在没有 Verifier 的情况下进入验证"等结构性错误。
2.5 四大 Gate 的对比与选择
| 维度 | Confirm Gate | Quality Gate | Safety Gate | Transition Gate |
|---|---|---|---|---|
| 核心问题 | 该不该做？ | 做得好不好？ | 安不安全？ | 能进入下一步吗？ |
| 决策依据 | 人类授权 | 量化指标 | 风险等级 | 前置条件清单 |
| 自动/手动 | 必须人工 | 全自动 | 分级自动 | 全自动 |
| 失败行为 | 拒绝 | 阻塞+改进建议 | 按等级处理 | 阻断转换 |
| 典型位置 | 破坏性操作前 | 审查节点 | 安全敏感操作 | 阶段边界 |
| 对应 Agent | 工作流编排器 | Verifier / Code Reviewer | Security Auditor | Phase Runner |
三、gate-prompts.md 设计
3.1 Prompt-as-Code 理念
如果说 gates.md 是门控的"逻辑层"，那么 gate-prompts.md 就是门控的"表示层"。它定义了门控系统如何与 LLM 交互——不是通过硬编码的字符串拼接，而是通过可版本控制、可热更新、可审计的 Prompt 模板。
## Gate Prompt 结构
每个门控类型对应一个 Prompt 模板：
### Confirm Gate Prompt
```
你正在评估一个需要用户确认的操作。
操作描述：{{operation_description}}
潜在风险：{{risks}}
影响范围：{{impact_scope}}
请生成一个清晰、完整的确认请求，包含：
1. 操作摘要
2. 具体风险清单
3. 确认指令（明确告知用户如何确认或拒绝）
注意：用户必须明确说 "yes" 或 "confirm" 才能通过。
```
### Quality Gate Prompt
```
你正在执行质量检查。
检查项：{{check_items}}
实际指标：{{actual_metrics}}
阈值要求：{{thresholds}}
请评估每个检查项是否达标，输出格式：
- 通过的项：简要说明
- 失败的项：具体问题 + 改进建议
最终判断：PASS / FAIL
```gate-prompts.md 的设计体现了 GSD 的**提示词即代码（Prompt-as-Code）**理念：
- 可版本控制：Prompt 模板与代码一同提交到 Git，每次修改都有历史记录
- 可热更新：修改 Prompt 无需重启系统，下次门控触发时自动生效
- 可 A/B 测试：可以并行测试不同 Prompt 的效果，选择输出更稳定的版本
- 可审计：每次门控决策都保留了使用的 Prompt 版本，便于事后追溯
3.2 模板变量与上下文注入
gate-prompts.md 中的模板不是静态文本，而是带有变量的动态模板。变量替换由门控评估 Agent 在执行时完成：
### Safety Gate Prompt
```
你正在评估一个操作的安全风险。
操作类型：{{operation_type}}
目标文件：{{target_files}}
当前权限：{{current_permissions}}
环境标识：{{environment}} <!-- dev / staging / production -->
请根据以下矩阵评估风险等级：
- Low：只读操作，公开数据
- Medium：文件修改，内部数据
- High：配置变更，敏感数据
- Critical：数据删除/部署，机密数据
风险等级：____
处理建议：____
```关键设计细节：environment 变量的注入。同一个"删除临时文件"的操作，在 dev 环境下可能是 Low 风险，在 production 环境下可能是 High 风险。gate-prompts.md 通过环境变量动态调整评估标准，避免了"一刀切"的安全策略。
3.3 Prompt 的工程化管理
GSD 对 gate-prompts.md 的管理遵循与代码相同的工程规范：
版本标记：
<!-- gate-prompts.md -->
# Gate Prompts v2.3.1
# 最后更新：2026-04-20
# 变更记录：
# - v2.3.1: 优化 Quality Gate 的输出格式，增加"改进优先级"字段
# - v2.3.0: 新增 Safety Gate 的环境感知逻辑单元测试：
GSD 的测试套件中包含 Prompt 模板验证测试，确保：
- 所有模板变量都有对应的替换逻辑
- 模板渲染后的输出符合预期的 JSON/Markdown 结构
- 不会出现未闭合的标签或未替换的
{{variable}}
分级策略：
不同 tier 的项目可以使用不同版本的 gate-prompts.md。例如：
tier-1（个人项目）：使用宽松模板，减少阻塞tier-3（团队项目）：使用标准模板tier-5（生产系统）：使用严格模板，增加额外的确认步骤
四、检查点机制
4.1 检查点与门控的关系
在 第 32 篇 中，我们用一句话概括了检查点和门控的区别："检查点是路标，门控是关卡"。路标告诉你到了哪里，关卡决定你能不能继续走。
flowchart LR
subgraph "检查点 Checkpoint"
C1[CP-PLAN-01
计划完整性]
C2[CP-EXEC-01
实现完整性]
C3[CP-QUAL-01
代码质量]
end
subgraph "门控 Gate"
G1[Quality Gate
质量标准评估]
G2[Transition Gate
阶段转换检查]
end
C1 -->|触发| G1
C2 -->|触发| G1
C3 -->|触发| G1
C2 -->|触发| G2这种分离设计的优势在于解耦和复用：
- 一个检查点可以触发多个门控（如
CP-EXEC-01同时触发 Quality Gate 和 Transition Gate） - 一个门控可以被多个检查点复用（如 Quality Gate 在
CP-PLAN-01、CP-EXEC-01、CP-QUAL-01中都发挥作用）
4.2 检查点的触发机制
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 |
在 第 14 篇 中，我们见到了 execute-phase 中检查点的实际应用。当计划包含 type="checkpoint:*" 任务时，gsd-executor 会在检查点处精确停止并返回结构化状态：
## CHECKPOINT REACHED
**Type:** human-verify
**Plan:** 03-03
**Progress:** 2/3 tasks complete
### Completed Tasks
| Task | Name | Commit | Files |
| ---- | ---- | ------ | ----- |
| 1 | 搭建布局框架 | a1b2c3d | src/layout/... |
### Current Task
**Task 3:** Dashboard 组件集成
**Status:** awaiting verification
**Blocked by:** 需要用户确认视觉效果
### Checkpoint Details
[已构建内容、验证步骤、预期行为]
### Awaiting
[用户需要提供/执行的操作]这个结构化消息是检查点协议的精髓：它不仅告诉用户"我停下来了"，还提供了完整的上下文——已完成什么、当前在哪、需要什么、为什么需要。用户无需回溯对话历史，就能在检查点处无缝接续工作。
4.3 检查点的失败处理策略
checkpoints.md 定义了三种标准化的失败处理策略：
Retry（重试）
- 适用：临时性问题（如网络超时、文件锁定）
- 行为：返回上一步重新执行，最多重试 3 次
- 配置：
max_retries: 3,backoff: exponential
Escalate（升级）
- 适用：需要更多上下文或权限的问题
- 行为：将问题升级给更高级别的 Agent 或用户
- 配置：
escalate_to: gsd-planner | user
Abort（中止）
- 适用：无法自动恢复的致命错误
- 行为：保存当前状态，中止工作流，等待人工介入
- 配置：
save_state: true,notify: user
在 第 14 篇 的"偏差处理"中，我们看到 Retry 策略的实际运用：当 Executor 遇到未预见的问题时，它会尝试自动修复（Rule 1-3），这本质上就是 Retry 策略的实例化。
4.4 分层检查点体系
GSD 的检查点不是平铺的，而是具有清晰的层次结构，与门控的层次形成映射：
| 层次 | 检查点 ID | 触发时机 | 关联门控 |
|---|---|---|---|
| L0 | CP-INIT-01 | 项目初始化完成 | Transition Gate |
| L1 | CP-PLAN-01 | 计划制定完成 | Quality Gate |
| L2 | CP-EXEC-01 | 每个 Wave 完成 | Quality Gate + Safety Gate |
| L3 | CP-QUAL-01 | 阶段验证启动 | Quality Gate |
| L4 | CP-AUDIT-01 | 里程碑审计 | Confirm Gate + Safety Gate |
| L5 | CP-UAT-01 | UAT 验收 | Confirm Gate |
这种分层设计的优势在于问题早发现、资源合理分配、反馈延迟递减——越靠近开发的检查点，反馈越快；越靠近交付的检查点，检查越全面。
五、门控与 Defense in Depth 的关系
5.1 纵深防御：不是单一防线，而是多层矩阵
在 第 3 篇 中，我们首次接触了 Defense in Depth（纵深防御）的概念。在 第 44 篇 中，我们看到了钩子系统如何构成运行时的被动防御网。现在，让我们将门控体系放入 Defense in Depth 的完整框架中，看看各层防御如何协同工作。
flowchart TD
subgraph "L1: 规范层"
A[参考文档体系
REQUIREMENTS.md / PLAN.md / gates.md]
end
subgraph "L2: 编排层"
B[Phase Runner 生命周期钩子
before / after / around / onError]
C[工作流门控
Confirm / Quality / Safety / Transition]
end
subgraph "L3: Agent 层"
D[Agent 自验证
Plan-Checker / Verifier / Code Reviewer]
end
subgraph "L4: 运行时层"
E[运行时钩子
prompt-guard / read-guard / workflow-guard]
F[检查点协议
Checkpoint Protocol]
end
subgraph "L5: 基础设施层"
G[测试覆盖
≥70% 核心路径]
H[版本控制
Git 原子提交 / 回滚]
end
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
style A fill:#e1f5fe
style C fill:#fff3e0
style E fill:#e8f5e9门控体系（L2 编排层）处于 Defense in Depth 的核心位置。它上承规范层（gates.md 中定义的质量标准），下启 Agent 层（触发 Plan-Checker、Verifier 等验证 Agent），同时与运行时层紧密协作（检查点协议处理中断和恢复）。
5.2 各层防御的职责边界
| 层级 | 防御机制 | 主要职责 | 失败行为 | 与门控的关系 |
|---|---|---|---|---|
| L1 规范层 | 参考文档 | 定义"什么是对的" | 无法执行 | 门控的判定标准来源 |
| L2 编排层 | Phase Runner 钩子 | 阶段级流程控制 | 阻断阶段 | 门控的执行框架 |
| L2 编排层 | 工作流门控 | 质量/安全/转换决策 | PASS/BLOCK/REJECT | 本文核心 |
| L3 Agent 层 | Agent 自验证 | 产出物质量审查 | 返回修订 | 门控的评估执行者 |
| L4 运行时层 | 运行时钩子 | 工具级安全监控 | 警告记录 | 门控的补充监控 |
| L4 运行时层 | 检查点协议 | 人机协作中断 | 暂停等待 | 门控的人工介入通道 |
| L5 基础设施层 | 测试覆盖 | 自动化回归验证 | CI 失败 | 门控的量化指标来源 |
| L5 基础设施层 | 版本控制 | 变更追踪与回滚 | 可恢复 | 门控失败后的兜底 |
关键设计原则：任何一层发现问题都可以阻止缺陷向下游传播。如果一个 bug 逃过了 L3 Agent 的自验证，L4 的运行时钩子可能通过 gsd-read-guard 发现未读取文件的 Edit 操作；如果钩子也没发现，L5 的测试覆盖可能在回归测试中捕获它。门控体系的价值不在于"拦截所有问题"，而在于"不给问题逃逸的机会"。
5.3 门控矩阵：从文档到执行的映射
将 第 3 篇 中的门控矩阵与 第 19 篇 中的嵌入点结合，我们可以得到 GSD 完整的门控矩阵：
| 工作流 | 阶段 | Gate 类型 | 检查对象 | 失败行为 | Defense in Depth 层级 |
|---|---|---|---|---|---|
| new-project | 入口 | Pre-flight (Transition) | 项目结构合规 | 阻断，提示缺失文件 | L2 |
| plan-phase | 入口 | Pre-flight (Transition) | REQUIREMENTS.md、ROADMAP.md | 阻断，提示缺失文件 | L2 |
| plan-phase | 步骤 12 | Revision (Quality) | PLAN.md 质量 | 循环至 planner（最多 3 次） | L3 |
| plan-phase | 修订后 | Escalation (Confirm) | 未解决问题 | surfaced 给开发者 | L4 |
| execute-phase | 入口 | Pre-flight (Transition) | PLAN.md | 阻断，提示缺失计划 | L2 |
| execute-phase | Wave 完成 | Revision (Quality) | 代码审查、回归测试 | 返回修复 | L3 |
| execute-phase | 漂移检测 | Safety | Schema/Codebase Drift | 警告或阻断 | L4 |
| verify-work | 入口 | Pre-flight (Transition) | SUMMARY.md | 阻断，提示缺失摘要 | L2 |
| verify-work | 评估时 | Escalation (Confirm) | 未满足标准 | surfaced gap | L3 |
| next | 入口 | Abort (Safety) | Error state、checkpoints | 停止，输出诊断 | L2 |
这个矩阵揭示了 Defense in Depth 的一个关键特征：同一工作流中，不同阶段的门控类型和严格程度是动态变化的。例如 execute-phase 在入口使用严格的 Transition Gate（没有计划就不让进），在 Wave 完成时使用 Quality Gate（代码不好就修），在漂移检测时使用 Safety Gate（有风险就警告）。这种"松紧结合"的策略既保证了安全性，又避免了过度阻塞开发效率。
5.4 70% 测试覆盖线的意义
在 第 3 篇 中，我们提到 GSD 对关键路径有 70% 的测试覆盖要求。这个数字与门控体系有深层关联：
tests/workflow-size-budget.test.cjs 等工作流预算测试确保：
- 每个工作流文件不超过其 tier 的行数上限
- Agent 定义不超过 50K 字符（某些 runtime 的限制）
- CLI 模块的核心函数有单元测试覆盖
70% 覆盖线不是随意设定的数字，它对应着「核心编排逻辑 + 状态管理 + 安全校验」这三条关键路径的交集。低于此线意味着某个 gate 或 hook 可能在未经测试的情况下被绕过。在 Defense in Depth 的框架中，未经测试的防御层等于没有防御层。
六、总结
GSD 的质量门控体系是一套精心设计的多层决策基础设施，它通过四种 canonical gate types（Confirm/Quality/Safety/Transition）覆盖了软件开发中所有关键的决策场景，通过 gate-prompts.md 实现了 Prompt-as-Code 的工程化管理，通过检查点机制建立了人机协作的精确中断协议。
这套体系的核心设计原则可以总结为三点：
1. 标准前置，判定后置
质量标准在 gates.md 和 PLAN.md 中预先定义，而不是在验证时临时解释。这消除了主观性，确保了判定的一致性和可审计性。
2. 分层防御，协同拦截
门控不是孤立存在的。它与 Phase Runner 钩子、Agent 自验证、运行时钩子、测试覆盖共同构成 Defense in Depth 矩阵。任何一层发现问题都可以阻止缺陷向下游传播。
3. 人机协作，精确中断
检查点协议不是简单的"停下来问用户"，而是提供完整的上下文快照——已完成什么、当前在哪、需要什么、为什么需要。这种精确中断使人类能够在不丢失上下文的情况下接管决策。
下一篇预告： 第 48 篇《测试架构总览：三层测试金字塔与 23 个测试文件全景》
我们将进入「质量门控、测试与实战」章节，解析 GSD 的三层测试金字塔、23 个测试文件的组织结构，以及测试策略选择和覆盖率目标。敬请期待。