| name | requirements-validator |
| description | 验证产品文档（PRD、System Architecture、User Story）格式，检查关联完整性。
使用场景："验证需求文档"、"检查 PRD 格式"、"检查 User Story 关联"
|
| argument-hint | [--check-mode] |
| disable-model-invocation | false |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep |
Requirements Validator Skill
版本: 2.1.0 | 层级: Layer 2 (Business Skill) | 分类: Requirements Skills
快速开始
我应该使用这个 Skill 吗？
使用场景:
- 验证 PRD 文档格式是否符合模板
- 验证 System Architecture 文档格式
- 验证 User Story 格式是否完整
- 检查文档层次和引用关系
- 检查 PRD ↔ Story ↔ OpenSpec 关联
- 分析需求覆盖率
不使用场景:
- 同步状态到 UPM → 使用
requirements-sync
- 同步到 Forgejo → 使用
forgejo-sync
- 整体项目状态扫描 → 使用
state-scanner
核心功能
| 功能 | 描述 |
|---|
| validate-prd | 验证 PRD 文档格式和必需节 |
| validate-architecture | 验证 System Architecture 文档格式 |
| validate-story | 验证 User Story 格式和字段 |
| validate-hierarchy | 验证文档层次结构和引用 |
| check-associations | 检查文档间双向关联 |
| validate-chain | 验证 PRD→Architecture→Stories 链路完整性 |
| coverage-analysis | 分析需求覆盖率 |
执行流程
阶段 1: 文件发现
发现路径:
prd_pattern: "{module}/docs/requirements/prd-*.md"
architecture_pattern:
- "docs/architecture/system-architecture.md"
- "{module}/docs/ARCHITECTURE.md"
story_pattern: "{module}/docs/requirements/user-stories/US-*.md"
输出:
prd_files: [文件路径列表]
architecture_files: [文件路径列表]
story_files: [文件路径列表]
requirements_configured: true/false
阶段 2: PRD 验证
检查项:
required_sections:
- "## 文档目的"
- "## 产品定位"
- "## 功能范围"
subsections:
产品定位:
- 目标用户
- 核心价值
- 成功标准
功能范围:
- Must-have
- Nice-to-have
- Out of Scope
story_references:
- 检查 User Story 表格存在
- 提取 Story ID 列表
输出:
prd_valid: true/false
prd_issues: [{file, section, issue, severity}]
阶段 3: System Architecture 验证 (NEW)
检查项:
version_header:
required_fields:
- "Version" (X.Y.Z 格式)
- "Status" (Draft|Review|Active|Deprecated|Archived) — 提取按下方 Status i18n 6-pattern union form (与 state-scanner v1.17.2+ 机械等价)
- "Created" (YYYY-MM-DD 格式)
optional_fields:
- "Parent Document"
- "Last Updated"
required_sections:
- "## 1. Executive Summary" 或 "## 概述"
- "## Architecture Diagram" 或 "## 架构图"
- "## Module Boundaries" 或 "## 模块边界"
- "## Technology Decisions" 或 "## 技术决策"
diagrams:
- 至少包含一个 ASCII 图或 Mermaid 图
- 代码块类型: ```, ```mermaid, ```yaml
parent_reference:
- 如果是系统级架构，应引用 PRD
- 如果是模块级架构，应引用系统架构
version_history:
- 包含版本历史表格
输出:
architecture_valid: true/false
architecture_issues: [{file, section, issue, severity}]
阶段 4: User Story 验证
检查项:
header_fields:
- Story ID (格式: US-XXX)
- Status (draft/ready/in_progress/done/blocked) — 提取按下方 Status i18n 6-pattern union form
- Priority (HIGH/MEDIUM/LOW)
- Created (YYYY-MM-DD)
- Forgejo Issue (可选)
- Forgejo Milestone (可选)
story_format:
- "As a {role}"
- "I want {feature}"
- "So that {value}"
acceptance_criteria:
- 至少一个 Scenario
- Given/When/Then 格式
输出:
stories_valid: true/false
story_issues: [{file, field, issue, severity}]
阶段 5: 文档层次验证 (NEW)
检查项:
层次定义:
L0: docs/requirements/prd-*.md
L1: docs/architecture/system-architecture.md
L2: {module}/docs/requirements/prd-*.md, {module}/docs/ARCHITECTURE.md
L3: {module}/docs/architecture/*.md, shared/contracts/*.yaml
L4: 代码文档、指南
向上引用检查:
- L1 文档应引用 L0 PRD
- L2 文档应引用 L1 系统架构
- L3 文档应引用 L2 模块架构
孤立文档检查:
- 检测无引用的文档
循环引用检查:
- 检测 A→B→C→A 模式
输出:
hierarchy_valid: true/false
hierarchy_issues: [{file, issue, severity}]
阶段 6: 关联检查
检查项:
prd_to_story:
- PRD 中列出的 Story 文件是否存在
story_to_prd:
- Story 引用的 PRD 文件是否存在
story_to_openspec:
- Story 引用的 OpenSpec 是否存在
architecture_references:
- 架构文档引用的文件是否存在
- Parent Document 路径是否有效
输出:
associations_valid: true/false
association_issues: [{source, target, issue, severity}]
阶段 7: 覆盖率分析
分析项:
status_distribution:
draft: N
ready: N
in_progress: N
done: N
blocked: N
openspec_coverage:
with_openspec: N
without_openspec: N
coverage_rate: "X%"
architecture_coverage:
modules_with_architecture: N
modules_without_architecture: N
architecture_rate: "X%"
输出:
coverage:
total: N
by_status: {...}
with_openspec: N
without_openspec: N
coverage_rate: "X%"
architecture_coverage: "X%"
阶段 8: 需求链路验证 (NEW)
检查项:
chain_definition:
PRD (L0) → System Architecture (L1) → User Stories → OpenSpec
产品需求 系统架构设计 可实现需求单元 技术实现方案
prd_to_architecture:
检查:
- System Architecture 是否存在
- Architecture 是否引用 PRD (parent_prd 字段)
- PRD approved 时 Architecture 应该存在
时序约束:
- Architecture.created >= PRD.created
- Architecture.last_updated >= PRD.last_updated (如果 PRD 更新)
architecture_to_stories:
检查:
- User Stories 是否在 Architecture 之后创建
- Stories 的模块边界是否与 Architecture 一致
- Ready 状态的 Stories 数量是否合理
时序约束:
- Story.created >= Architecture.created
chain_status_consistency:
检查:
- PRD status=draft → Architecture 不应是 active
- Architecture status=draft → Stories 不应是 in_progress/done
- Architecture status=outdated → 阻止新 Stories 进入 ready
openspec_linkage:
检查:
- Ready Stories 是否有关联的 OpenSpec
- OpenSpec 是否引用正确的 Story
输出:
chain_validation:
chain_valid: true/false
prd_to_architecture:
valid: true/false
issues: []
architecture_to_stories:
valid: true/false
issues: []
status_consistency:
valid: true/false
issues: []
openspec_linkage:
valid: true/false
issues: []
Status 字段提取规范 (i18n alignment)
为与 state-scanner v1.17.2+ 的 collector 行为保持机械等价, Status 字段
按以下 6 个模式顺序匹配 (来源: aria/skills/state-scanner/references/state-snapshot-schema.md
第 142-153 行 _STATUS_PATTERNS, Source-of-Truth):
| # | 模式 | 示例 |
|---|
| 1 | **Status**[：:]\s*X | **Status**: Active |
| 2 | **状态**[：:]\s*X | **状态**：pending |
| 3 | >\s***Status**[：:]\s*X | > **Status**: done |
| 4 | (#{1,6}\s+)?Status[：:]\s*X | ## Status: Reviewed |
| 5 | |\s*(Status|状态)\s*|\s*X\s*| | | Status | active | |
| 6 | >\s*.*?**(Status|状态)**[：:]\s*X | > **优先级**：P0 | **状态**：pending |
i18n 关键点: 模式 1-4 的字符类 [：:] 同时接受 ASCII 半角 U+003A 和全角 U+FF1A
(中文 IME 默认输入). 模式 6 处理 inline blockquote 多 meta 行 (Kairos 项目 US-009-tts-voice-clone.md 实际样本).
Negative case 不应误报:
- prose 中提到"状态"二字但非
**状态** bold 形式 → 不匹配 (避免文本扫描噪音)
- 模式 6 要求同时
> blockquote 锚 + **...** bold 包装 (双重保险)
Status 合法值 (从所有模式抽取后做 normalization 校验):
- PRD/Architecture:
Draft|Review|Active|Deprecated|Archived (大小写不敏感)
- User Story:
draft|ready|in_progress|done|blocked (小写, snake_case)
- normalization 失败 → ERROR
无效状态值: '{X}'
为何 6 个模式而非更多: 来源 Spec state-scanner-i18n-status-regex 在 v1.17.2 落地时通过实际项目样本审计确定 6 个覆盖 99%+ 的中英文文化习惯写法. 不再扩展, 防止 over-fitting.
验证模式
| 模式 | 描述 | 用途 |
|---|
full | 完整验证 (所有检查) | 迭代规划、提交前检查 |
quick | 快速验证 (仅必需字段) | 日常开发 |
check | 只读模式 (不修改文件) | CI/CD 检查 |
architecture | 仅架构文档验证 | 架构审查 |
hierarchy | 仅层次结构验证 | 文档重构后验证 |
chain | 需求链路验证 | PRD→Architecture→Stories 完整性检查 |
输出格式
validation_result:
mode: "full|quick|check|architecture|hierarchy|chain"
timestamp: "2026-01-01T10:00:00+08:00"
prd:
valid: true/false
files_checked: N
issues: []
architecture:
valid: true/false
files_checked: N
issues: []
stories:
valid: true/false
files_checked: N
issues: []
hierarchy:
valid: true/false
layers_checked: [L0, L1, L2, L3]
issues: []
associations:
valid: true/false
issues: []
chain_validation:
chain_valid: true/false
prd_to_architecture:
valid: true/false
issues: []
architecture_to_stories:
valid: true/false
issues: []
status_consistency:
valid: true/false
issues: []
openspec_linkage:
valid: true/false
issues: []
coverage:
total: N
by_status:
draft: N
ready: N
in_progress: N
done: N
blocked: N
with_openspec: N
without_openspec: N
coverage_rate: "X%"
architecture_coverage: "X%"
summary:
errors: N
warnings: N
info: N
overall_valid: true/false
严重级别
| 级别 | 含义 | 示例 |
|---|
error | 必须修复 | 缺少必需字段、文件不存在、循环引用 |
warning | 建议修复 | 格式不规范、缺少可选节、孤立文档 |
info | 信息提示 | 缺少 OpenSpec 关联、建议添加图表 |
使用示例
完整验证
用户: 验证所有需求文档
助手执行:
1. 发现 docs/ 下的所有产品文档
2. 验证 PRD 格式
3. 验证 System Architecture 格式
4. 验证所有 Story 格式
5. 验证文档层次结构
6. 检查关联完整性
7. 生成覆盖率报告
输出:
validation_result:
prd:
valid: true
files_checked: 2
architecture:
valid: true
files_checked: 3
stories:
valid: false
files_checked: 8
issues:
- file: "US-003-xxx.md"
field: "Status"
issue: "无效状态值: 'pending'"
severity: error
hierarchy:
valid: true
layers_checked: [L0, L1, L2]
coverage:
total: 8
with_openspec: 5
coverage_rate: "62.5%"
architecture_coverage: "100%"
架构验证
用户: 验证系统架构文档
助手执行:
1. 发现 docs/architecture/ 和 */docs/ARCHITECTURE.md
2. 验证版本头信息
3. 验证必需章节
4. 验证架构图存在
5. 验证引用完整性
输出:
validation_result:
mode: "architecture"
architecture:
valid: true
files_checked: 3
issues:
- file: "backend/docs/ARCHITECTURE.md"
section: "Technology Decisions"
issue: "建议添加决策原因"
severity: warning
层次验证
用户: 验证文档层次结构
助手执行:
1. 构建文档层次树
2. 检查向上引用
3. 检测孤立文档
4. 检测循环引用
输出:
validation_result:
mode: "hierarchy"
hierarchy:
valid: false
layers_checked: [L0, L1, L2, L3]
issues:
- file: "mobile/docs/architecture/old-design.md"
issue: "孤立文档: 未被任何文档引用"
severity: warning
- file: "backend/docs/ARCHITECTURE.md"
issue: "缺少向上引用: 应引用 system-architecture.md"
severity: error
需求链路验证
用户: 验证需求链路完整性
助手执行:
1. 检查 PRD → Architecture 链路
2. 检查 Architecture → Stories 链路
3. 检查状态一致性
4. 检查 OpenSpec 关联
输出:
validation_result:
mode: "chain"
chain_validation:
chain_valid: false
prd_to_architecture:
valid: false
issues:
- issue: "PRD 已 approved 但 Architecture 不存在"
severity: error
suggestion: "创建 System Architecture 文档"
architecture_to_stories:
valid: true
issues: []
status_consistency:
valid: false
issues:
- issue: "Architecture status=outdated 但有 Stories 是 in_progress"
severity: warning
suggestion: "更新 Architecture 或暂停开发"
openspec_linkage:
valid: true
issues: []
与其他 Skills 的关系
┌─────────────────────────────────────────────────────────────┐
│ state-scanner (Layer 3) │
│ │ │
│ ▼ 调用 │
│ requirements-validator (Layer 2) ◄── 本 Skill │
│ │ │
│ ▼ 输出供 │
│ requirements-sync (Layer 2) ── 使用验证结果更新 UPM │
└─────────────────────────────────────────────────────────────┘
相关文档
- 规范:
standards/core/documentation/product-doc-hierarchy.md (文档层次规范)standards/core/documentation/system-architecture-spec.md (System Architecture 规范)
- PRD 模板:
standards/templates/prd-template.md
- Story 模板:
standards/templates/user-story-template.md
- 目录结构:
standards/templates/requirements-directory-structure.md
版本历史
| 版本 | 日期 | 变更 |
|---|
| 2.1.0 | 2026-01-04 | 添加需求链路验证 (阶段 8)，支持 PRD→Architecture→Stories 完整性检查 |
| 2.0.0 | 2026-01-02 | 添加 System Architecture 验证、文档层次验证 |
| 1.0.0 | 2026-01-01 | 初始版本 - PRD/Story 验证 |
