validation-pipeline

验证流水线

用途

运行结构化验证流水线，按顺序执行各步骤，在遇到阻塞性失败时实施门禁，并生成评分报告。使用 .claude/helpers/validation-pipeline.cjs 执行 13 个需求验证步骤（BMAD-003）。

激活条件

• 验证需求文档时
• 运行结构化质量门禁时
• 评估文档的完整性、可测试性或可追溯性时
• 通过 /validation-pipeline 调用时

快速开始

# Validate a requirements document (all 13 steps)
/validation-pipeline requirements docs/requirements.md

# Validate with specific steps only
/validation-pipeline requirements docs/requirements.md --steps format-check,completeness-check,invest-criteria

# Continue past blocking failures
/validation-pipeline requirements docs/requirements.md --continue-on-failure

# Output as JSON
/validation-pipeline requirements docs/requirements.md --json

工作流

步骤 1：读取目标文档

读取用户指定的文件。如果用户未提供文件，请向其索取。

Read the target document using the Read tool.
Store the content for pipeline execution.

步骤 2：选择流水线

根据用户的请求选择合适的流水线：

流水线	步骤数	用途
requirements	13	需求文档、PRD、用户故事

可在 .claude/helpers/validation-pipeline.cjs 中添加其他流水线。

步骤 3：执行流水线

流水线辅助程序（.claude/helpers/validation-pipeline.cjs）负责执行：

1. 顺序执行 — 按顺序运行各步骤，每个步骤都会接收之前步骤的结果
2. 门禁实施 — 阻塞性步骤失败时会停止流水线（除非使用 --continue-on-failure）
3. 逐步评分 — 每个步骤都会生成 0-100 分的评分，并附带发现和证据
4. 加权汇总 — 总体评分采用各类别权重（格式=10%，内容=30%，质量=25%，可追溯性=20%，合规性=15%）

需求流水线步骤（共 13 个）

#	步骤 ID	类别	严重性	检查内容
1	format-check	格式	阻塞	标题、必需章节、文档长度
2	completeness-check	内容	阻塞	必填字段已填写，包含验收标准
3	invest-criteria	质量	警告	独立、可协商、有价值、可估算、小规模、可测试
4	smart-acceptance	质量	警告	具体、可衡量、可实现、相关、有时限
5	testability-score	质量	警告	每项需求是否都可测试？
6	vague-term-detection	内容	信息	标记“应该”“可能”“各种”“等等”等词语
7	information-density	内容	信息	每句话都切中要点，不含填充内容
8	traceability-check	可追溯性	警告	存在需求到测试的映射关系
9	implementation-leakage	质量	警告	需求不规定具体实现方式
10	domain-compliance	合规性	信息	与领域模型保持一致
11	dependency-analysis	可追溯性	信息	已识别跨需求依赖关系
12	bdd-scenario-generation	质量	警告	能否为每项需求生成 Given/When/Then 场景
13	holistic-quality	合规性	阻塞	整体一致性，无矛盾

步骤 4：报告结果

将流水线结果整理为结构化报告：

# Validation Report: Requirements Pipeline

**Overall**: PASS/FAIL/WARN | **Score**: 85/100 | **Duration**: 42ms

## Step Results
| # | Step | Status | Score | Findings | Duration |
|---|------|--------|-------|----------|----------|
| 1 | Format Check | PASS | 100 | 0 | 2ms |
| 2 | Completeness | WARN | 60 | 2 | 5ms |
...

## Blockers
- (blocking findings listed here)

## All Findings
- [HIGH] Missing acceptance criteria: Requirement US-104 has no AC
- [MEDIUM] Vague term: "should" used 5 times without specifics
...

步骤 5：记录经验

流水线执行完毕后，记录结果以供学习：

// Store validation pattern
memory store --namespace validation-pipeline --key "req-validation-{timestamp}" --value "{score, findings_count, halted}"

参数

参数	类型	默认值	说明
pipeline	字符串	requirements	要运行的流水线类型
file	字符串	必需	要验证的文档路径
--steps	字符串	全部	要运行的步骤 ID，以逗号分隔（例如：format-check,completeness-check）
--continue-on-failure	布尔值	false	跳过阻塞性门禁
--json	布尔值	false	以 JSON 而非 Markdown 格式输出
--metadata	对象	{}	提供给各步骤的附加上下文

集成点

• qe-requirements-validator agent — 将结构化验证委派给此流水线
• qe-quality-gate agent — 使用此流水线评估门禁
• YAML Pipelines — 可将验证步骤作为工作流操作调用
• MCP — 可通过 pipeline_validate 工具访问

输出架构

流水线会生成一个 PipelineResult 对象（参见 schemas/output.json）：

{
  pipelineId: string;
  pipelineName: string;
  overall: 'pass' | 'fail' | 'warn';
  score: number;           // 0-100 weighted average
  steps: StepResult[];     // per-step details
  blockers: Finding[];     // blocking findings
  halted: boolean;
  haltedAt?: string;       // step ID where halted
  totalDuration: number;
  timestamp: string;
}

错误处理

• 步骤抛出异常 — 记录为 FAIL，并标记为严重发现；流水线根据严重程度继续运行或停止
• 找不到文件 — 报告错误，不运行流水线
• 文档为空 — 格式检查步骤会将其识别为阻止性失败