这是「GSD 全景代码解析」专题的第 19 篇。在前面几篇文章中，我们深入解析了 execute-phase、plan-phase、new-project 等核心工作流的编排机制。如果说执行是 GSD 的"肌肉"，规划是它的"大脑"，那么验证与审计就是它的"免疫系统"——确保每一行交付的代码都经过严格检查，每一个里程碑都达到可发布的质量标准。

本文将聚焦 GSD 工作流编排层的质量保障机制，逐一拆解 verify-phase、audit-milestone、audit-uat 和 audit-fix 四个验证与审计工作流的设计哲学和实现细节。

---

验证与审计工作流

在 GSD 框架中，"写代码"只是交付流程的一半，另一半是验证代码是否正确、审计过程是否合规。GSD 通过四个专门的工作流来完成这一使命：

工作流	职责	触发时机
verify-phase	阶段级验证	每个 phase 执行完成后
audit-milestone	里程碑审计	Milestone 标记为完成时
audit-uat	用户验收测试审计	UAT 阶段完成后
audit-fix	修复审计	修复任务完成后

这四个工作流共同构成了 GSD 的质量门控体系（Quality Gate System），与 gates.md 中定义的质量标准深度集成。

---

一、verify-phase 工作流：阶段级质量把关

1.1 工作流定位

verify-phase.md 是 GSD 中最基础的验证工作流，其核心职责是：在一个 phase 的所有 Wave 执行完成后，系统性地验证该阶段的目标是否达成。

与 execute-phase 中的"过程验证"不同，verify-phase 做的是"结果验证"——它不关心代码是怎么写出来的，只关心代码是否满足阶段目标。

1.2 验证流程与检查点

verify-phase 的完整流程包含 6 个主要步骤：

flowchart TD
    subgraph Prep["① 前置准备"]
        P1["加载 STATE.md
获取阶段目标"] --> P2["加载 gates.md
获取质量标准"]
    end

    subgraph Check["② 检查点执行"]
        C1["Goal Verification
目标达成检查"] --> C2["Test Suite Check
测试套件检查"]
        C2 --> C3["Schema Consistency
Schema 一致性检查"]
        C3 --> C4["Documentation Check
文档完整性检查"]
    end

    subgraph Gate["③ 质量门控"]
        G1{所有检查通过?}
    end

    subgraph Result["④ 结果处理"]
        G1 -->|"是"| R1["生成 VERIFY.md
标记阶段完成"]
        G1 -->|"否"| R2["生成 ISSUE.md
进入修复流程"]
        R2 --> R3["触发 audit-fix
修复审计"]
    end

    Prep --> Check --> Gate --> Result

各检查点的具体职责：

检查点	验证内容	失败处理
Goal Verification	阶段目标中定义的每个 deliverable 是否完成	标记未完成项，生成修复任务
Test Suite Check	单元测试、集成测试通过率是否达标	列出失败测试，分析失败原因
Schema Consistency	数据库 schema、API 契约是否与计划一致	检测 drift，生成迁移任务
Documentation Check	代码注释、API 文档、CHANGELOG 是否同步	标记缺失文档，生成补充任务

1.3 与 gates.md 的集成

verify-phase 并非独立运行，而是深度依赖 gates.md 中定义的质量标准：

sequenceDiagram
    participant VP as verify-phase
    participant G as gates.md
    participant TS as "Test Suite"
    participant DB as "Schema Registry"
    participant Out as VERIFY.md

    VP->>G: 读取阶段质量标准
    G-->>VP: 返回阈值（测试覆盖率 ≥80%、API 兼容性等）

    VP->>TS: 执行测试套件
    TS-->>VP: 返回测试报告

    VP->>DB: 检查 schema 一致性
    DB-->>VP: 返回 drift 报告

    VP->>VP: 综合评估所有指标

    alt 全部达标
        VP->>Out: 生成 VERIFY.md（PASSED）
    else 部分未达标
        VP->>Out: 生成 VERIFY.md（FAILED + issues）
    end

gates.md 中定义的质量门控是可配置的，不同项目、不同阶段可以有不同的阈值：

# gates.md 示例片段
phase_verification:
  test_coverage_threshold: 80
  api_compatibility: strict
  documentation_required: true
  schema_drift_tolerance: none

milestone_audit:
  security_scan: required
  performance_benchmark: required
  code_review_coverage: 100

1.4 验证失败的处理

当 verify-phase 检测到质量问题时，不会直接修改代码，而是遵循**"记录问题 → 生成修复任务 → 审计修复"**的闭环流程：

1. 记录问题：在 VERIFY.md 中详细记录每个失败的检查点、失败原因、影响范围
2. 生成修复任务：根据问题类型，自动生成对应的修复任务（如 fix-test-coverage、fix-schema-drift）
3. 进入修复流程：将修复任务交给 audit-fix 工作流处理
4. 重新验证：修复完成后，重新触发 verify-phase

这种设计确保了问题不会被掩盖，修复不会被遗漏。

---

二、audit-milestone：里程碑审计

2.1 里程碑完成标准

在 GSD 中，Milestone 是比 Phase 更高层次的聚合单位。一个 Milestone 通常包含多个 Phase，代表一个可独立交付的功能模块或版本节点。

audit-milestone 的审计标准比 verify-phase 更严格：

flowchart LR
    subgraph PhaseLevel["Phase 级别"]
        P1[verify-phase]
        P2["测试通过"]
        P3["文档完整"]
    end

    subgraph MilestoneLevel["Milestone 级别"]
        M1[audit-milestone]
        M2["所有 Phase 通过"]
        M3["跨 Phase 集成测试"]
        M4["性能基准测试"]
        M5["安全扫描通过"]
        M6["代码审查 100%"]
    end

    PhaseLevel --> MilestoneLevel

Milestone 的完成标准包括：

标准	说明	自动化程度
所有子 Phase 的 VERIFY.md 为 PASSED	前置条件	全自动
跨 Phase 集成测试通过	验证模块间协作	全自动
性能基准达标	响应时间、吞吐量等	半自动（需基线对比）
安全扫描无高危漏洞	SAST/DAST 扫描	全自动
代码审查覆盖率 100%	所有变更经过 review	全自动（记录检查）
用户文档已更新	面向用户的指南同步	半自动（AI 辅助检查）

2.2 审计流程

audit-milestone 的审计流程采用**"分层递进"**策略：

flowchart TD
    A["开始 Milestone 审计"] --> B{所有子 Phase
已通过验证?}
    B -->|"否"| C["终止审计
返回 Phase 修复"]
    B -->|"是"| D["执行集成测试套件"]
    D --> E{集成测试通过?}
    E -->|"否"| F["生成集成问题报告"]
    E -->|"是"| G["执行性能基准测试"]
    G --> H{性能达标?}
    H -->|"否"| I["生成性能优化任务"]
    H -->|"是"| J["执行安全扫描"]
    J --> K{无高危漏洞?}
    K -->|"否"| L["生成安全修复任务"]
    K -->|"是"| M["检查代码审查记录"]
    M --> N{覆盖率 100%?}
    N -->|"否"| O["标记未审查变更"]
    N -->|"是"| P["生成 AUDIT.md"]
    P --> Q{全部通过?}
    Q -->|"是"| R["标记 Milestone 完成"]
    Q -->|"否"| S["进入修复审计流程"]

关键设计点：

• 前置检查：如果子 Phase 未全部通过，直接终止审计，避免浪费资源
• 渐进式执行：每个检查点失败后即生成报告，不继续后续检查（除非配置为"全量模式"）
• 审计独立性：audit-milestone 由独立的 gsd-auditor Agent 执行，避免"自己审自己"

2.3 审计报告

audit-milestone 的输出是一份结构化的 AUDIT.md 文件：

# Milestone Audit Report

## 基本信息
- Milestone: v1.0-user-authentication
- 审计日期: 2026-04-24
- 审计 Agent: gsd-auditor
- 结果: PASSED_WITH_NOTES

## 检查结果

| 检查项 | 状态 | 详情 |
|--------|------|------|
| Phase 验证 | ✅ PASSED | 3/3 Phases 通过 |
| 集成测试 | ✅ PASSED | 42/42 通过 |
| 性能基准 | ⚠️ NOTE | 响应时间 120ms（阈值 100ms），建议优化 |
| 安全扫描 | ✅ PASSED | 无高危/严重漏洞 |
| 代码审查 | ✅ PASSED | 100% 覆盖率 |

## 建议
- 登录接口响应时间接近阈值，建议在下一 Milestone 中优化

## 签名
- 审计 Agent: gsd-auditor
- 人类确认: [待确认]

---

三、audit-uat：用户验收测试审计

3.1 UAT 流程

UAT（User Acceptance Testing，用户验收测试）是 GSD 交付流程中最接近真实用户的验证环节。audit-uat 工作流负责审计 UAT 过程的完整性和结果的可信度。

flowchart LR
    subgraph UATFlow["UAT 流程"]
        U1["准备 UAT 环境"] --> U2["执行验收用例"]
        U2 --> U3["记录用户反馈"]
        U3 --> U4["分类问题优先级"]
    end

    subgraph Audit["审计节点"]
        A1[audit-uat]
    end

    UATFlow --> Audit

audit-uat 的审计重点不是"功能是否正确"（这是 verify-phase 的职责），而是：

1. UAT 环境是否与生产环境一致
2. 验收用例是否覆盖了需求文档中的全部场景
3. 用户反馈是否被正确分类和追踪
4. 阻塞性问题是否已解决或已接受风险

3.2 验收标准检查

audit-uat 对验收标准的检查采用**"需求追溯（Requirements Traceability）"**方法：

flowchart TD
    A["加载 REQUIREMENTS.md"] --> B["提取所有 acceptance criteria"]
    B --> C["加载 UAT 测试记录"]
    C --> D["匹配 criteria 与测试用例"]
    D --> E{每个 criteria
都有对应测试?}
    E -->|"否"| F["标记遗漏的验收标准"]
    E -->|"是"| G["检查测试结果"]
    G --> H{所有 criteria 通过?}
    H -->|"否"| I["分类失败：阻塞/严重/轻微"]
    H -->|"是"| J["生成 UAT-AUDIT.md"]

验收标准的三级分类：

级别	定义	处理策略
阻塞（Blocker）	核心功能不可用，影响发布	必须修复，重新 UAT
严重（Critical）	重要功能有缺陷，有 workaround	建议修复，可接受风险则记录
轻微（Minor）	体验问题，不影响功能	记录为已知问题，后续版本处理

audit-uat 的独特之处在于它会审计 UAT 过程本身——确保测试不是走过场，反馈不是被忽视。

---

四、audit-fix：修复审计

4.1 修复验证流程

当 verify-phase、audit-milestone 或 audit-uat 发现问题后，会进入修复流程。修复完成后，audit-fix 工作流负责验证修复本身是否正确、是否引入了新的问题。

flowchart TD
    A["接收修复任务"] --> B["加载原始问题报告"]
    B --> C["审查修复方案"]
    C --> D{修复方案合理?}
    D -->|"否"| E["要求重新设计修复"]
    D -->|"是"| F["执行回归测试"]
    F --> G{回归测试通过?}
    G -->|"否"| H["标记回归失败"]
    G -->|"是"| I["检查修复范围"]
    I --> J{是否过度修复?}
    J -->|"是"| K["建议精简修复范围"]
    J -->|"否"| L["生成 FIX-AUDIT.md"]

audit-fix 的三重检查：

1. 方案审查：修复是否针对根因，而非症状
2. 回归测试：修复是否破坏了原有功能
3. 范围审查：修复是否引入了不必要的变更（过度修复）

4.2 回归测试

回归测试是 audit-fix 的核心环节。GSD 的回归测试策略分为两个层次：

flowchart LR
    subgraph L1["第一层：受影响范围"]
        A1["识别修改的文件"] --> A2["运行相关单元测试"]
    end

    subgraph L2["第二层：全量保护"]
        B1["运行完整测试套件"] --> B2["性能基准对比"]
    end

    L1 --> L2

• 第一层（快速反馈）：仅运行与修改文件相关的测试，快速验证修复本身
• 第二层（全面保护）：运行完整测试套件，确保没有引入回归问题

audit-fix 会根据修复的风险等级决定执行哪一层：

风险等级	判断依据	回归测试范围
低	单行注释修改、文档更新	第一层即可
中	局部逻辑修改、配置变更	第一层 + 相关集成测试
高	核心模块修改、接口变更	第一层 + 第二层全量

---

五、质量门控在工作流中的位置

5.1 门控的嵌入点

质量门控（Quality Gates）不是独立的工作流，而是嵌入在各个工作流中的检查点。在 GSD 的工作流体系中，门控分布在以下位置：

flowchart TD
    subgraph NewProject["new-project"]
        N1["项目初始化"] --> N2["门控: 项目结构合规"]
    end

    subgraph PlanPhase["plan-phase"]
        P1["计划生成"] --> P2["门控: 计划可执行性"]
    end

    subgraph ExecutePhase["execute-phase"]
        E1["Wave 执行"] --> E2["门控: 原子提交检查"]
        E2 --> E3["门控: 代码审查"]
        E3 --> E4["门控: 回归测试"]
    end

    subgraph VerifyPhase["verify-phase"]
        V1["阶段验证"] --> V2["门控: 目标达成"]
        V2 --> V3["门控: 测试覆盖率"]
    end

    subgraph MilestoneAudit["audit-milestone"]
        M1["里程碑审计"] --> M2["门控: 集成测试"]
        M2 --> M3["门控: 安全扫描"]
    end

    subgraph UATAudit["audit-uat"]
        U1["UAT 审计"] --> U2["门控: 验收标准"]
    end

    subgraph FixAudit["audit-fix"]
        F1["修复审计"] --> F2["门控: 回归测试"]
    end

    NewProject --> PlanPhase --> ExecutePhase --> VerifyPhase --> MilestoneAudit --> UATAudit
    ExecutePhase -.-> FixAudit
    VerifyPhase -.-> FixAudit
    MilestoneAudit -.-> FixAudit

5.2 门控的层次结构

GSD 的质量门控具有清晰的层次关系：

层次	门控名称	所属工作流	检查频率
L0	项目结构门控	new-project	一次性
L1	计划可执行性门控	plan-phase	每阶段一次
L2	代码审查门控	execute-phase	每 Wave 一次
L2	回归测试门控	execute-phase	每 Wave 一次
L3	阶段目标门控	verify-phase	每 Phase 一次
L3	测试覆盖率门控	verify-phase	每 Phase 一次
L4	集成测试门控	audit-milestone	每 Milestone 一次
L4	安全扫描门控	audit-milestone	每 Milestone 一次
L5	验收标准门控	audit-uat	每版本一次
L6	修复回归门控	audit-fix	每次修复后

这种分层门控设计的优势在于：

• 问题早发现：低级门控（如代码审查）在每次提交时运行，问题在引入时即被发现
• 资源合理分配：高级门控（如安全扫描）运行频率低但覆盖全面
• 反馈延迟递减：越靠近开发的门控，反馈越快；越靠近交付的门控，检查越全面

---

六、验证与审计的自动化策略

6.1 自动化程度分级

GSD 将验证与审计任务按可自动化程度分为四类：

flowchart LR
    subgraph Auto["全自动"]
        A1["单元测试执行"]
        A2["代码覆盖率统计"]
        A3["Schema 一致性检查"]
        A4["安全扫描"]
    end

    subgraph Semi["半自动"]
        S1["测试用例生成"]
        S2["代码审查辅助"]
        S3["文档完整性检查"]
        S4["性能基线对比"]
    end

    subgraph Human["人工决策"]
        H1["UAT 验收结论"]
        H2["风险接受判断"]
        H3["发布审批"]
    end

    subgraph Hybrid["人机协作"]
        M1["审计报告生成"]
        M2["问题优先级排序"]
        M3["修复方案建议"]
    end

    Auto --> Semi --> Hybrid --> Human

类别	示例	实施策略
全自动	测试执行、覆盖率统计、安全扫描	CI/CD 流水线集成，零人工干预
半自动	用例生成、审查辅助、文档检查	AI 生成 + 人工确认
人机协作	报告生成、优先级排序	AI 分析 + 人工决策
人工决策	验收结论、发布审批	AI 提供信息，人类做最终决定

6.2 自动化执行策略

在实际项目中，GSD 推荐以下自动化执行策略：

策略一：提交时触发（Pre-commit / CI）

# 每次代码提交时自动执行
- 代码格式检查（lint）
- 单元测试（受影响范围）
- 静态类型检查

策略二：Wave 完成时触发（execute-phase 内置）

# 每个 Wave 执行完成后自动执行
- 代码审查门控
- 回归测试门控
- Schema Drift 检查

策略三：Phase 完成时触发（verify-phase）

# 每个 Phase 结束后自动执行
- 目标达成验证
- 测试覆盖率检查
- 文档完整性检查

策略四：Milestone 完成时触发（audit-milestone）

# 每个 Milestone 结束后自动执行
- 集成测试
- 性能基准测试
- 安全扫描

策略五：修复完成后触发（audit-fix）

# 每次修复任务完成后自动执行
- 修复验证
- 回归测试
- 修复范围审查

6.3 检查点协议（Checkpoint Protocol）

对于无法全自动化的检查点，GSD 使用**检查点协议（Checkpoint Protocol）**来管理人工介入：

sequenceDiagram
    participant WF as "工作流"
    participant CP as "检查点"
    participant Human as "人类用户"
    participant Resume as "恢复执行"

    WF->>CP: 到达检查点
    CP->>Human: 展示当前状态 + 决策选项
    Human->>CP: 做出决策（通过/拒绝/修订）
    CP->>Resume: 记录决策 + 上下文
    Resume->>WF: 恢复工作流执行

检查点协议的核心设计原则：

1. 状态持久化：检查点的所有上下文信息写入文件，工作流可以随时中断和恢复
2. 决策可追溯：每个检查点的决策都被记录，便于后续审计
3. 默认安全：如果检查点超时未响应，默认行为是"暂停"而非"继续"

---

七、验证与审计工作流的协作关系

四个验证与审计工作流并非孤立运行，它们通过文件系统和工作流触发器形成一个有机的质量保障网络：

flowchart TD
    E["execute-phase
执行阶段"] --> V["verify-phase
阶段验证"]
    V -->|"通过"| M["audit-milestone
里程碑审计"]
    V -->|"失败"| F1["audit-fix
修复审计"]
    M -->|"通过"| U["audit-uat
UAT 审计"]
    M -->|"失败"| F2["audit-fix
修复审计"]
    U -->|"通过"| D["发布"]
    U -->|"失败"| F3["audit-fix
修复审计"]
    F1 --> V
    F2 --> M
    F3 --> U

    style E fill:#e1f5fe
    style V fill:#fff3e0
    style M fill:#fff3e0
    style U fill:#fff3e0
    style F1 fill:#ffebee
    style F2 fill:#ffebee
    style F3 fill:#ffebee
    style D fill:#e8f5e9

这个网络的运作逻辑非常清晰：

• 执行驱动验证：每次 execute-phase 完成后自动触发 verify-phase
• 失败驱动修复：任何验证失败都进入 audit-fix 流程
• 修复驱动重验：修复完成后自动重新触发上层验证
• 层级递进：只有下层验证全部通过，才能进入上层审计

---

总结

验证与审计工作流是 GSD 框架中不可或缺的质量保障基础设施。它们的设计理念可以概括为三句话：

1. 验证分层，问题早现——从代码提交到版本发布，多层门控确保问题在引入的最早阶段被发现
2. 审计独立，标准统一——由独立 Agent 执行审计，避免"自己审自己"的利益冲突
3. 失败闭环，修复可追溯——任何验证失败都进入标准化的修复审计流程，确保问题得到彻底解决

verify-phase、audit-milestone、audit-uat 和 audit-fix 四个工作流，配合 gates.md 中定义的质量标准，共同构成了 GSD 的免疫系统——它不直接产生价值，但确保产生的价值是可靠、可用、可维护的。

下一篇预告： 第 20 篇《代码审查与修复工作流》

我们将聚焦 GSD 的代码审查机制（code-review）和修复工作流（fix-phase），探讨 AI 驱动的代码审查策略和修复任务的分派逻辑。 敬请期待。