质量门控

质量门控体系概述

PinableAgents 的质量门控是一套多维度的质量保障体系，贯穿从需求定义到代码交付的整个工作流。每个关键阶段都设有质量检查点（Gate），只有通过检查的交付物才能进入下一阶段。这一机制确保了最终产出的可靠性和一致性。

质量门控体系包含三个层级：

文档层 - 对需求文档（PRD）和架构设计文档进行结构化评分
规格层 - 通过 SPARV 标准验证实现规格的完整性和精确性
代码层 - 对代码实现进行多维度的质量审查

门控的核心理念是"左移质量"，即在开发流程的早期阶段发现和修复问题，而非在代码提交后才进行补救。统计数据表明，需求阶段发现的缺陷修复成本仅为代码阶段的十分之一。

质量门控不是阻碍开发效率的障碍，而是防止技术债务累积的保险机制。通过合理配置阈值，你可以在速度和质量之间找到适合团队的平衡点。

BMAD PRD 评分标准

在 BMAD 工作流中，产品经理智能体生成的 PRD 文档需要通过一个 100 分制的评分门控。评分由 10 个维度组成，每个维度满分 10 分。只有总分达到配置的阈值（默认 70 分）才能通过门控。

维度	满分	评分标准
完整性（Completeness）	10	所有必要章节是否齐全，包括背景、目标、用户故事、验收标准
清晰度（Clarity）	10	描述是否无歧义，术语是否统一定义，是否避免了模糊措辞
可测试性（Testability）	10	每个需求是否可验证，验收标准是否具体可量化
一致性（Consistency）	10	需求之间是否存在矛盾，优先级是否合理
可行性（Feasibility）	10	技术可行性是否经过评估，是否考虑了现有架构约束
范围界定（Scope）	10	范围是否明确，是否有清晰的"不做"列表
用户视角（User Focus）	10	是否从用户角度描述需求，用户故事是否遵循 INVEST 原则
非功能需求（NFR）	10	性能、安全、可用性、可维护性等非功能需求是否覆盖
依赖标注（Dependencies）	10	外部依赖、前置条件和风险是否明确标注
交付标准（Delivery Criteria）	10	上线标准、监控指标和回滚计划是否定义

# 手动触发 PRD 评分
pinable-agents gate prd-score --file docs/prd-user-auth.md

# 输出示例：
# PRD Scoring Report: docs/prd-user-auth.md
# ──────────────────────────────────────────
# Completeness:       8/10
# Clarity:            9/10
# Testability:        7/10
# Consistency:        9/10
# Feasibility:        8/10
# Scope:              6/10  ← 需要改进
# User Focus:         8/10
# NFR:                5/10  ← 需要改进
# Dependencies:       7/10
# Delivery Criteria:  6/10  ← 需要改进
# ──────────────────────────────────────────
# Total: 73/100 | Threshold: 70 | Status: PASSED

架构评审评分标准

架构设计文档同样采用 100 分制的评审机制。架构评审关注系统设计的合理性、可扩展性和技术选型的准确性。评分维度包括：

系统分解（15 分） - 模块划分是否合理，职责是否单一，边界是否清晰
接口设计（15 分） - API 契约是否完整，版本策略是否明确，错误处理是否规范
数据模型（15 分） - 数据结构是否满足查询需求，索引策略是否合理
可扩展性（10 分） - 是否为未来变更预留了扩展点，但避免过度设计
安全设计（10 分） - 认证授权方案是否完备，数据加密和传输安全是否考虑
容错设计（10 分） - 故障恢复策略、降级方案和超时处理是否定义
性能预估（10 分） - 关键路径的延迟预估、吞吐量设计和瓶颈分析
技术选型（10 分） - 工具和框架的选择是否有依据，是否考虑了团队熟悉度
依赖管理（5 分） - 第三方依赖的版本锁定和更新策略

SPARV 10 项规格门控

SPARV（Specification, Precision, Accuracy, Relevance, Validation）是 PinableAgents 用于验证实现规格的 10 项检查标准。每一项为通过/不通过的二元判定，要求全部 10 项通过才能放行。

序号	检查项	描述
1	需求追溯	每个实现单元都能追溯到具体的需求条目
2	接口一致	实际实现的接口与设计文档定义完全一致
3	错误处理	所有已知错误路径都有明确的处理逻辑
4	边界覆盖	输入参数的边界值和极端情况都有处理
5	安全合规	敏感数据处理符合安全规范，无硬编码密钥
6	性能基线	关键路径的响应时间在设定基线以内
7	日志规范	关键操作有适当级别的日志记录，不泄露敏感信息
8	配置外置	环境相关的值通过配置或环境变量注入，不硬编码
9	向后兼容	变更不破坏现有公开接口的行为契约
10	文档同步	代码变更对应的文档已同步更新

# 运行 SPARV 门控检查
pinable-agents gate sparv --scope src/auth/

# 输出示例：
# SPARV Gate Check: src/auth/
# [PASS] 1. 需求追溯 - 所有函数均有对应 story ID 注释
# [PASS] 2. 接口一致 - 3 个 API 端点与设计文档匹配
# [FAIL] 3. 错误处理 - handleTokenRefresh() 缺少网络超时处理
# [PASS] 4. 边界覆盖 - 输入验证覆盖所有声明的约束
# ...
# Result: 9/10 PASSED | Status: BLOCKED

代码审查质量清单

代码审查门控使用结构化的清单来确保审查的全面性和一致性。审查者（无论是智能体还是人工）需要逐项确认以下检查点：

功能正确性

实现是否完整满足需求描述
边界条件和异常路径是否正确处理
业务逻辑是否与验收标准对齐

代码质量

命名是否清晰表达意图
函数长度是否合理（建议不超过 40 行）
嵌套层级是否在 3 级以内
是否存在重复代码可以提取

安全性

用户输入是否经过验证和消毒
是否存在 SQL 注入、XSS 等常见漏洞
敏感数据是否加密存储和传输

测试覆盖率要求

不同工作流对测试覆盖率有不同的要求：

工作流	行覆盖率	分支覆盖率	关键路径覆盖
essentials	60%	50%	必须
do	70%	60%	必须
omo	75%	65%	必须
bmad	80%	70%	必须

自动化检查与人工评审

质量门控分为自动化检查和人工评审两类。自动化检查由系统在工作流执行过程中自动触发，包括格式验证、静态分析、测试运行和覆盖率统计。人工评审则由团队成员或高级智能体在关键节点手动执行，聚焦于自动化工具难以覆盖的领域，如设计合理性、业务逻辑正确性和用户体验评估。

建议的分工策略：

自动化 - 格式检查、lint 规则、类型检查、测试运行、覆盖率统计、安全扫描
人工/高级智能体 - 架构评审、PRD 评分、业务逻辑验证、性能设计评估

自定义质量阈值

所有质量门控的阈值都可以通过配置文件调整。这让团队可以根据项目阶段和成熟度灵活设定标准。

{
  "quality_gates": {
    "prd_score_threshold": 70,
    "architecture_score_threshold": 65,
    "sparv_required_pass": 10,
    "code_review": {
      "max_function_length": 40,
      "max_nesting_depth": 3,
      "require_error_handling": true
    },
    "test_coverage": {
      "line_coverage_min": 70,
      "branch_coverage_min": 60
    },
    "strict_mode": false
  }
}

将 strict_mode 设为 true 时，任何门控失败都会立即中断工作流。设为 false 时，系统会生成警告但继续执行，适合项目初期逐步引入质量标准的场景。

质量指标仪表盘

PinableAgents 桌面端提供了质量指标仪表盘，实时展示项目的质量趋势。仪表盘包含以下模块：

门控通过率 - 过去 30 天内各门控的通过率趋势图
评分分布 - PRD 和架构评审的分数分布直方图
常见失败项 - 最频繁触发的门控失败项排名
修复时间 - 从门控失败到修复通过的平均时间

实战：质量门控失败与修复

以下是一个完整的门控失败与修复流程示例。假设团队正在开发用户认证功能，PRD 评分门控未通过：

# 1. 工作流在 PRD 评分阶段阻塞
# pinable-agents run bmad --task "实现用户 OAuth2 认证"
# [GATE BLOCKED] PRD Score: 62/100 (threshold: 70)
# Failed dimensions: NFR (4/10), Scope (5/10), Delivery Criteria (3/10)

# 2. 查看详细的评分报告
pinable-agents gate report --latest

# 3. 根据报告修复 PRD
# - NFR: 补充性能要求（登录响应 < 500ms）和安全要求（密码哈希算法）
# - Scope: 添加"不做"列表（本期不支持 SAML、不支持多因素认证）
# - Delivery Criteria: 定义上线标准和监控告警规则

# 4. 重新提交评分
pinable-agents gate prd-score --file docs/prd-user-auth-v2.md
# [GATE PASSED] PRD Score: 81/100

# 5. 工作流继续执行

CI/CD 流水线集成

质量门控可以集成到 CI/CD 流水线中，作为合并请求的必要检查项。

# .github/workflows/quality-gate.yml
name: Quality Gate
on: [pull_request]
jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PinableAgents CLI
        run: npm install -g @pinable/agents-cli
      - name: Run SPARV Gate
        run: pinable-agents gate sparv --scope src/ --ci
      - name: Run Code Review Gate
        run: pinable-agents gate review --diff origin/main...HEAD --ci
      - name: Check Test Coverage
        run: pinable-agents gate coverage --threshold 70 --ci

质量门控的最终目标不是追求完美的分数，而是建立团队对质量的共识和持续改进的习惯。从低阈值开始，随着团队成熟度的提升逐步提高标准，才是可持续的质量策略。

目录