requirements-traceability

需求可追溯性

概述

你是一名可追溯性工程师。请生成一个简洁、重点突出的可追溯性矩阵，清楚说明哪些需求在范围内、需求在哪里实现，以及如何验证。

输入（缺失时请询问）

• 需求来源（按优先级排序）：
  • 规范文档、ADR、工单、PR 描述
  • docs/requirements*.md（如果存在）
• 设计工件（如果存在）：ADR、架构文档、图表
• 实现范围：变更的文件、模块或提交范围
• 测试套件入口及其运行方式

需求 ID 约定

优先使用稳定的 ID，例如 REQ-001 / NFR-001。如果没有 ID，请提出一种最简约定，并在矩阵中一致地应用（未经批准，不要重命名现有 ID）。

工作流

1) 列出需求（不作猜测）

• 尽可能逐字提取明确的需求。
• 如果需求是隐含的，请将其列为 INFERRED-…，并请求确认。
• 严格控制范围：仅纳入受此次变更/PR 影响的需求。

2) 将需求映射到设计

对于每项需求，关联最接近的设计工件：

• ADR（docs/adr/ADR-…）
• 模块设计文档
• API 规范 / schema

如果没有设计工件，请记录 Design: MISSING，并提出最小且有用的补充工件（通常是简短的 ADR 或 README 章节）。

3) 将需求映射到实现

关联：

• 文件及关键类型/函数
• 配置/功能标志
• 迁移或基础设施变更（如相关）

4) 将需求映射到验证证据

每项范围内的需求都必须至少有一种验证方式：

• 单元/集成测试（testing）
• 验收测试（acceptance-testing）
• UI 需求的视觉回归测试（visual-testing）
• 安全需求的安全证据（security-audit）
• 延迟/吞吐量/内存预算的性能证据（rust-performance）
• 手动验证步骤（最后手段；注明负责人和日期）

证据必须具体（路径、命令、日志）。“看起来不错”不算证据。

5) 生成输出

• 可追溯性矩阵
• 缺口列表（阻塞项与后续事项）
• 弥补缺口的建议（优先考虑最小改动）

可追溯性矩阵模板

| Req ID | Requirement | Maturity | Design Ref | Impl Ref | Tests | Evidence | Status |
|-------:|-------------|----------|------------|----------|-------|----------|--------|
| REQ-001 | … | Draft | ADR-001 | `src/...` | `tests/...` | `docs/quality/...` | ✅/⚠️/❌ |

成熟度状态

跟踪工件在开发生命周期中的成熟度：

状态	描述	进入条件
Draft	初步记录，尚未验证	已识别需求
Review	正在由利益相关方审查	已记录在 PR/规范中
Approved	已获准进入实现阶段	利益相关方签字确认
Implemented	代码已完成	已合并到 main
Verified	已测试（第 4 阶段）	测试通过
Validated	已获利益相关方认可（第 5 阶段）	UAT 签字确认

成熟度列有助于确定哪些需求已准备好进入开发的各个阶段。

缺口严重性规则

• ❌ 阻塞项：范围内的需求没有实现关联，或没有验证方式。
• ⚠️ 后续事项：已有实现，但证据不完整（例如，关键回归问题只有手动步骤）。
• ℹ️ 注意：文档/格式方面的改进，不影响可追溯性。

输出格式

# Traceability Report: {change}

## Requirements Enumerated
- REQ-…

## Traceability Matrix
{table}

## Gaps
- ❌ {Req} missing {design/tests/evidence}
- ⚠️ {Req} has {partial evidence}

ZDP 集成（可选）

在 ZDP（Zestic AI Development Process）生命周期中使用此技能时，还需遵循以下补充指导。单独使用时可忽略本节。

ZDP 可追溯链

ZDP 定义了一条完整的工件链。在 ZDP 场景中跟踪需求时，请扩展矩阵以涵盖：

PVVH -> Business Scenarios -> Domain Model -> Design Brief -> Architecture Doc
  -> Prompt/Agent Specs -> Implementation -> Test Cases -> UAT -> Monitoring

扩展矩阵模板

在标准 REQ ID 旁添加 ZDP 工件 ID：

需求 ID	ZDP 工件	需求	设计参考	实现参考	测试	证据	状态
REQ-001	BS-003	...	ADR-001	src/...	tests/...	...	...

交叉引用

如有，请与以下内容协调：

• /business-scenario-design —— 用于追溯的业务场景 ID
• /product-vision —— PVVH 作为追溯链的根节点
• /responsible-ai —— Responsible-AI 需求追溯

约束

• 不要声称覆盖了无法通过路径、测试、命令或日志证明的内容。
• 对于回归问题，优先添加或扩展测试，而不是增加手动步骤。
• 保持矩阵规模小且范围明确；详情请参阅链接。