Menu
验证产品文档（PRD、System Architecture、User Story）格式，检查关联完整性。 使用场景："验证需求文档"、"检查 PRD 格式"、"检查 User Story 关联"
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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 |
版本: 2.1.0 | 层级: Layer 2 (Business Skill) | 分类: Requirements Skills
使用场景:
不使用场景:
requirements-syncforgejo-syncstate-scanner| 功能 | 描述 |
|---|---|
| validate-prd | 验证 PRD 文档格式和必需节 |
| validate-architecture | 验证 System Architecture 文档格式 |
| validate-story | 验证 User Story 格式和字段 |
| validate-hierarchy | 验证文档层次结构和引用 |
| check-associations | 检查文档间双向关联 |
| validate-chain | 验证 PRD→Architecture→Stories 链路完整性 |
| coverage-analysis | 分析需求覆盖率 |
发现路径:
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
检查项:
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}]
检查项:
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}]
检查项:
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}]
检查项:
层次定义:
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}]
检查项:
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}]
分析项:
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%"
检查项:
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: []
为与 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 不应误报:
**状态** bold 形式 → 不匹配 (避免文本扫描噪音)> blockquote 锚 + **...** bold 包装 (双重保险)Status 合法值 (从所有模式抽取后做 normalization 校验):
Draft|Review|Active|Deprecated|Archived (大小写不敏感)draft|ready|in_progress|done|blocked (小写, snake_case)无效状态值: '{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: []
┌─────────────────────────────────────────────────────────────┐
│ 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 规范)standards/templates/prd-template.mdstandards/templates/user-story-template.mdstandards/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 验证 |
Aria 项目级配置加载器（内部基础设施）。 查找、解析、验证 .aria/config.json 并合并默认值。 此 Skill 不直接触发，由其他 Skills 引用以读取项目配置。
项目状态扫描与智能工作流推荐，十步循环的统一入口。 收集项目状态、分析变更、推荐最佳工作流、引导用户确认执行。 使用场景："查看项目当前状态"、"我要提交代码"、"开发新功能"
会话收尾 —— 在任意对话(含未走完十步循环的探索/调试/讨论 session)把"未交接成果" 固化为 handoff。**与十步循环正交平级的会话仪式**(非周期收尾): AI 先内省本对话出 未完成线程 + 待固化经验, 再用机械 autofill 交叉核验补漏, 写 docs/handoff/。leaf — 终结于写交接, 不拖入十步循环。 使用场景: "对话收尾" / "执行对话收尾" / "会话收尾" / "session closeout" / "收尾这次对话" / "写交接" / "写 handoff" / "收工" / "结束本次对话" / context 快满时主动收尾。 不适用 (用 phase-d-closer): "Phase D" / "周期收尾" / "归档 Spec" / "更新 cycle 进度" —— 那是开发周期收尾, 不是会话收尾。
Git 多远程 parity 检测与 push 验证的共享基础设施。 内部工具, 仅供其他 skills 引用。提供标准化 Bash/Python 执行脚本段 + 输出 JSON schema 契约。
任务到 Agent 的智能路由器，根据任务类型、文件路径自动选择最合适的 Agent。 使用场景：subagent-driver 需要为任务选择 Agent、不确定应该使用哪个 Agent
向 Aria 维护团队报告 Bug 或提交功能建议。自动收集环境信息， 自动路由到 Forgejo（内部用户）或 GitHub（外部用户）。 使用场景："报告 bug"、"report an issue"、"提交功能建议"、 "aria 有个问题想反馈"、"feature request"、"提 issue"、 "反馈问题"、"report bug to aria"