mcpField
D
doc-req

doc-req

github.com/vladm3105开发1753 次安装1 天前更新
代码仓库

关于 doc-req

doc-req 是用于 SDD 工作流第 7 层的技能，将系统需求拆解为符合 REQ v3.0 格式的原子化、可实施需求。它强调上游文档核验、累计追踪标签和双重就绪度评分，供后续实施与规格编写使用。

主要功能

  1. 01将系统需求拆解为原子化需求
  2. 02按 REQ v3.0 结构编写文档
  3. 03核验上游材料并添加追踪标签
  4. 04计算 SPEC 与 IMPL 就绪度评分
  5. 05遵循 ID、阈值及目录规范

适用场景

  1. 01完成 SYS 后准备实施级需求
  2. 02为需求补全来源及追踪关系
  3. 03检查 REQ 是否达到层级转换门槛

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-req

安装后在 Claude Code 中输入/doc-req确认已加载。

详细介绍

doc-req

用途

创建 原子需求（REQ） 文档——SDD 工作流中的第 7 层产物，采用 REQ v3.0 格式将系统需求拆解为可直接实施的原子需求。

层级：7

上游：BRD（第 1 层）、PRD（第 2 层）、EARS（第 3 层）、BDD（第 4 层）、ADR（第 5 层）、SYS（第 6 层）

下游产物：IMPL（第 8 层）、CTR（第 9 层）、SPEC（第 10 层）、代码（第 13 层）

前置条件

上游产物验证（关键）

创建本文档之前，你必须：

  1. 列出已有的上游产物：

    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ 2>/dev/null

  2. 在可追溯性标签中仅引用已有文档

  3. 仅在上游产物类型确实不存在时使用 null

  4. 绝不要使用 BRD-XXX 或 TBD 等占位符

  5. 不要创建缺失的上游产物——跳过相关功能

创建 REQ 之前，请阅读：

  1. 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游 SYS：阅读驱动此 REQ 的系统需求
  3. 模板：ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md
  4. 创建规则：ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md
  5. 验证规则：ai_dev_ssd_flow/07_REQ/REQ_MVP_SCHEMA.yaml
  6. 质量门验证：ai_dev_ssd_flow/07_REQ/REQ_MVP_QUALITY_GATE_VALIDATION.md
  7. 验证脚本：./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh

何时使用此技能

以下情况请使用 doc-req：

  • 已完成 BRD 到 SYS（第 1–6 层）
  • 需要将系统需求拆解为原子单元
  • 正在为实施（第 8 层及以上）做准备
  • 目标是达到 >=90% 的 SPEC 就绪度评分
  • 当前处于 SDD 工作流的第 7 层

保留 ID 豁免（REQ-00_*）

范围：ID 保留为 000 的文档完全免于验证。

匹配模式：REQ-00_*.md

文档类型：

  • 索引文档（REQ-00_index.md）
  • 可追溯性矩阵模板（REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md）
  • 词汇表、注册表、检查清单

理由：ID 保留为 000 的文档属于框架基础设施，并非需要可追溯性或质量门的项目产物。

验证行为：文件名匹配 REQ-00_* 模式时跳过所有检查。

REQ 专属指南

1. REQ MVP 格式（11 个必需章节）

关键：REQ MVP 使用精简的 11 章节结构

文档控制（必需——位于所有编号章节之前的第一节）

核心章节：

  1. 描述：原子需求 + SHALL/SHOULD/MAY 表述 + 上下文 + 场景
  2. 功能需求：核心能力 + 业务规则
  3. 接口规范：协议/ABC 定义 + DTO + REST 端点
  4. 数据模式：JSON Schema + Pydantic 模型 + 数据库模式
  5. 错误处理规范：异常目录 + 错误响应模式 + 熔断器配置
  6. 配置规范：YAML 模式 + 环境变量 + 验证
  7. 质量属性：性能目标（p50/p95/p99）+ 可靠性/安全性/可扩展性
  8. 实施指南：算法/模式 + 并发/异步 + 依赖注入
  9. 验收标准：>=15 项可衡量标准，涵盖功能/错误/质量/数据/集成
  10. 验证方法：BDD 场景 + 单元/集成/契约/性能测试
  11. 可追溯性：第 7 节格式，带累积标签（6 项必需）

注意：REQ MVP 有意省略变更历史。

2. 文档控制要求（11 个必填字段）
字段格式示例
状态Approved/In Review/DraftApproved
版本语义化版本 X.Y.Z2.0.1
创建日期ISO 86012025-11-18
上次更新ISO 86012025-11-19
作者姓名/角色System Architect
优先级级别（P 级）High (P2)
类别类型Functional
源文档DOC-ID section X.Y.ZSYS-02 section 3.1.1
验证方法方法类型BDD + Integration Test
指派团队团队名称IB Integration Team
SPEC-Ready 分数带表情符号的格式>=90% (Target: >=90%)
IMPL-Ready 分数带表情符号的格式>=90% (Target: >=90%)
模板版本必须为 3.03.0
3. 双就绪度评分（SPEC-Ready + IMPL-Ready）

必须：每个 REQ 都必须计算两个分数

SPEC-Ready 分数公式：

SPEC-Ready Score = (Completed Sections / 12) * 100%

IMPL-Ready 分数：衡量实现方案文档的就绪程度

质量门禁：层级转换要求两个分数都 >=90%

状态与就绪分数的对应关系：

就绪分数所需状态
>= 90%Approved
70-89%In Review
< 70%Draft

注意：对于具有双分数的 REQ 文档，使用较低分数来确定状态。

示例：

## Readiness Scores

**SPEC-Ready Score**: >=95% (Target: >=90%)
**IMPL-Ready Score**: >=92% (Target: >=90%)

**Section Status**:
- [x] 1. Description
- [x] 2. Functional Requirements
- [x] 3. Interface Specifications
- [x] 4. Data Schemas
- [x] 5. Error Handling Specifications
- [x] 6. Configuration Specifications
- [x] 7. Quality Attributes
- [x] 8. Implementation Guidance
- [x] 9. Acceptance Criteria
- [x] 10. Verification Methods
- [x] 11. Traceability
- [ ] 12. Change History (In Progress)

**Readiness**: READY for SPEC/IMPL creation
4. 元素 ID 格式（必须）

模式：REQ.{DOC_NUM}.{HASH}（3 个以点分隔的段）

元素类型代码示例
功能需求01REQ.02.0101
依赖项05REQ.02.0501
验收标准06REQ.02.0601
原子需求27REQ.02.2701

已移除的模式——不要使用：

  • AC-XXX——使用 REQ.NN.06.SS
  • FR-XXX——使用 REQ.NN.01.SS
  • R-XXX——使用 REQ.NN.27.SS
  • REQ-XXX——使用 REQ.NN.27.SS

参考：ID_NAMING_STANDARDS.md - 交叉引用链接格式

5. 原子需求原则
  • 单一职责：每个 REQ 只定义一项需求
  • 可衡量：验收标准提供真/假结果
  • 自包含：无需外部上下文即可理解
  • SPEC-Ready：包含自动生成 SPEC 所需的全部信息（完整度 >=90%）
  • 情态用语：SHALL（绝对要求）、SHOULD（建议优先采用）、MAY（可选）
6. 领域/子领域组织

位置：项目文档目录下的 REQ/{domain}/{subdomain}/

领域：api/（外部集成）、risk/（风险管理）、data/（数据要求）、ml/（ML 要求）、auth/（安全）等。

格式：REQ-NN_descriptive_slug.md

示例：REQ-risk-limits-01_position_validation.md

标签格式约定（按设计）

SDD 框架使用两种不同的标记系统进行交叉引用：

标记格式工件用途
连字符TYPE-NNADR、SPEC、CTR技术工件——引用文件/文档
点号TYPE.NN.xxxxBRD、PRD、EARS、BDD、SYS、REQ、IMPL、TASKS层级工件——引用文档内的元素

主要区别：

  • @adr: ADR-033 -> 指向文档 ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.0103 -> 指向文档 BRD-017.md 内的元素 01.03

累积标记要求

第 7 层（REQ）：必须包含第 1–6 层（BRD、PRD、EARS、BDD、ADR、SYS）的标记

标记数量：6 个标记（@brd、@prd、@ears、@bdd、@adr、@sys）

格式：

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 7):
```markdown
@brd: BRD.01.0103
@prd: PRD.01.0702
@ears: EARS.01.2501
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045
@sys: SYS.01.0101, SYS.01.0207

上游来源：

下游工件：

  • IMPL-NN（待创建）- 实现方案
  • CTR-NN（待创建）- 数据契约
  • SPEC-NN（待创建）- 技术规范

**Element Type Codes for Tags**:
- EARS: Type 25 (formal requirement)
- BDD: Type 14 (scenario)
- SYS: Type 01 (functional), 02 (quality attribute), 26 (system req)

## Threshold Registry Integration

**Purpose**: Prevent magic numbers by referencing centralized threshold registry.

### When @threshold Tag is Required

Use `@threshold` for ALL quantitative values that are:
- Business-critical (compliance limits, SLAs)
- Configurable (timeout values, rate limits, retry policies)
- Shared across documents (performance targets)
- Quality attribute-related (p50/p95/p99 latencies, throughput limits)
- Error handling configurations (circuit breaker, retry counts)

### @threshold Tag Format

```markdown
@threshold: PRD.NN.category.subcategory.key

示例：

  • @threshold: PRD.035.perf.api.p95_latency
  • @threshold: PRD.035.timeout.circuit_breaker.threshold
  • @threshold: PRD.035.retry.max_attempts
  • @threshold: PRD.035.limit.api.requests_per_second
REQ 专用阈值类别
类别REQ 用途示例键
perf.*性能验收标准perf.api.p95_latency
timeout.*熔断器、连接配置timeout.circuit_breaker.reset
retry.*重试策略配置retry.max_attempts
limit.*速率限制、资源限制limit.api.requests_per_second
resource.*内存、CPU 限制resource.memory.max_heap
魔法数字检测

无效（硬编码值）：

  • p95 response time: 200ms
  • max_retries: 3
  • rate_limit: 100 req/s

有效（注册表引用）：

  • p95 response time: @threshold: PRD.NN.perf.api.p95_latency
  • max_retries: @threshold: PRD.NN.retry.max_attempts
  • rate_limit: @threshold: PRD.NN.limit.api.requests_per_second

上游/下游工件

上游来源：

  • BRD（第 1 层）- 业务需求
  • PRD（第 2 层）- 产品功能
  • EARS（第 3 层）- 正式需求
  • BDD（第 4 层）- 测试场景
  • ADR（第 5 层）- 架构决策
  • SYS（第 6 层）- 系统需求（主要来源）

下游工件：

  • IMPL（第 8 层）- 实现方案（可选）
  • CTR（第 9 层）- 数据契约（可选）
  • SPEC（第 10 层）- 技术规范
  • 代码（第 13 层）- 实现

同类型文档关系（有条件）：

  • @related-req: REQ-NN - 共享领域上下文的 REQ
  • @depends-req: REQ-NN - 必须优先实现的 REQ

创建流程

步骤 1：阅读上游工件

尤其关注 SYS（第 6 层）——需要分解的系统需求。

步骤 2：预留 ID 编号

检查 docs/07_REQ/，确定下一个可用的 ID 编号。

ID 编号约定：从 2 位数字开始，仅在需要时扩展位数。

  • ✅ 正确：REQ-01、REQ-99、REQ-102
  • ❌ 错误：REQ-001、REQ-009（无需额外添加前导零）

按领域命名：REQ-domain-subdomain-NN

步骤 3：创建 REQ 文件

嵌套文件夹规则（强制）：所有 REQ 文档都必须使用嵌套文件夹，无论文档大小。

位置选项：

  • 标准：docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md
  • 按领域：docs/07_REQ/{domain}/REQ-NN_{slug}/REQ-NN_{slug}.md
  • 子领域：docs/07_REQ/{domain}/{subdomain}/REQ-NN_{slug}/REQ-NN_{slug}.md

按需创建文件夹：保存文档之前，先创建目标目录：

# Create target directory (ALWAYS use nested folder)
mkdir -p docs/07_REQ/REQ-NN_{slug}/
# OR for domain-based structure
mkdir -p docs/07_REQ/{domain}/REQ-NN_{slug}/

重要：绝不能在 docs/07_REQ/ 中直接创建 REQ 文件，而不使用嵌套文件夹结构。

领域选择：使用项目配置或上游 SYS 上下文中的领域：

  • 金融：risk/、trading/、collection/、compliance/、ml/
  • SaaS：tenant/、subscription/、billing/、workspace/
  • 通用：api/、auth/、data/、core/、integration/

章节文件：对于大型需求（>50KB），使用章节文件格式：REQ-NN.S_section_title.md（S = 章节编号）。

步骤 4：填写文档控制部分

填写元数据，包括所有 11 个必填字段以及文档修订历史表。

步骤 5：完成全部 11 个必填部分

重要：REQ MVP 要求包含全部 11 个部分，才能达到 >=90% 的 SPEC 就绪度

  1. 描述：原子化需求 + SHALL/SHOULD/MAY 语言
  2. 功能需求：核心能力 + 业务规则
  3. 接口规范：API、端点、契约、Protocol/ABC 类
  4. 数据架构：模型、验证、约束、Pydantic/dataclass
  5. 错误处理规范：错误代码、恢复、异常定义
  6. 配置规范：设置、功能标志、YAML 配置
  7. 质量属性：带阈值的性能、安全性、可扩展性
  8. 实现指南：技术方案、模式
  9. 验收标准：>=15 条可衡量的标准
  10. 验证方法：BDD 场景、测试
  11. 可追溯性：累积标签（6 个标签）

注意：REQ MVP 刻意省略了变更历史。

步骤 6：计算就绪度分数

统计已完成的部分，并计算 SPEC 就绪度和 IMPL 就绪度百分比。

质量门禁：两个分数都必须达到 >=90%

步骤 7：添加累积标签

包含全部 6 个上游标签（@brd 至 @sys）。

步骤 8：创建/更新可追溯性矩阵

必须执行：更新 ai_dev_ssd_flow/07_REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md

步骤 9：验证 REQ
./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh docs/07_REQ/REQ-NN_*/REQ-NN_*.md

python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py --artifact REQ-NN --expected-layers brd,prd,ears,bdd,adr,sys --strict
步骤 10：提交更改

提交 REQ 文件和可追溯性矩阵。

验证

验证检查（共 20 项）
检查项描述类型
CHECK 1必填的 11 个部分错误
CHECK 2文档控制（11 个字段）错误
CHECK 3可追溯性结构错误/警告
CHECK 4旧版（已弃用）信息
CHECK 5版本格式（X.Y.Z）错误
CHECK 6日期格式（ISO 8601）错误
CHECK 7优先级格式（P1-P4）警告
CHECK 8源文档格式警告
CHECK 9SPEC 就绪度分数错误/警告
CHECK 10模板版本（3.0）错误
CHECK 11变更历史错误/警告
CHECK 12文件名/ID 格式错误
CHECK 13资源标签（模板 2.0）错误
CHECK 14累积标签（6 个标签）错误
CHECK 15完整的上游链错误
CHECK 16链接解析错误/警告
CHECK 17可追溯性矩阵警告
CHECK 18SPEC 就绪内容警告
CHECK 19IMPL 就绪度分数错误
CHECK 20元素 ID 格式合规性错误
验证级别
级别类型退出代码描述
级别 1错误1阻止提交——提交前必须修复
级别 2警告0质量问题——建议修复
级别 3信息0参考信息——无需操作
提交前钩子

REQ 验证通过提交前钩子自动强制执行：

- id: req-core-validator
  name: Validate REQ core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_core_validator_hook.sh
  stages: [pre-commit]

- id: req-quality-gate
  name: Validate REQ quality gates
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_quality_gate_hook.sh
  stages: [pre-commit]

- id: req-spec-ready-score
  name: Validate REQ SPEC-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/07_REQ/scripts/req_spec_ready_score_hook.sh
  stages: [pre-commit]

手动执行（用于在不提交的情况下进行测试）：

pre-commit run req-core-validator --all-files
pre-commit run req-quality-gate --all-files
pre-commit run req-spec-ready-score --all-files

强制执行的质量门禁：

  • ✅ REQ 结构合规性（11 个 MVP 部分）
  • ✅ 已批准状态的 SPEC 就绪度分数 ≥90%
  • ✅ 元数据和标签（req、layer-7-artifact）
  • ✅ 上游可追溯性（@brd、@prd、@ears、@bdd、@adr、@sys——6 个标签）
  • ✅ 已批准文档中不得包含占位文本
  • ✅ 原子化需求（单一职责）
  • ✅ 可衡量的验收标准（≥15 条标准）
  • ✅ 包含 Protocol/ABC 类的接口规范
  • ✅ 数据架构（Pydantic/JSON Schema）
  • ✅ 错误处理规范
  • ✅ 配置规范（YAML 架构）
  • ✅ 带有 @threshold 标签的质量属性
  • ✅ 相关 REQ 之间的交叉链接
自动化验证
# Validate single file
./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh docs/07_REQ/REQ-NN_slug/REQ-NN_slug.md

# Validate all REQ files
find docs/07_REQ -name "REQ-*.md" -exec ./ai_dev_ssd_flow/07_REQ/scripts/validate_req_template.sh {} \;

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py \
  --artifact REQ-NN \
  --expected-layers brd,prd,ears,bdd,adr,sys \
  --strict
手动检查清单
  • 顶部包含 Document Control 部分，含 11 个必填字段
  • 已完成全部 11 个必填部分
  • SPEC 就绪度评分 >=90%
  • IMPL 就绪度评分 >=90%
  • Template Version = 3.0
  • 第 3 节：接口规范，包含 Protocol/ABC 类
  • 第 4 节：数据架构，包含 Pydantic/dataclass 模型
  • 第 5 节：错误处理，包含异常定义
  • 第 6 节：配置，包含 YAML 架构
  • 第 7 节：质量属性，包含 @threshold 引用
  • 第 9 节：至少 15 条验收标准
  • 包含累积标签：@brd 到 @sys（6 个标签）
  • 每项需求均为原子需求（单一职责）
  • 验收标准可测试且可衡量
  • 已更新可追溯性矩阵
图表标准

所有图表都必须使用 Mermaid 语法。禁止使用基于文本的图表（ASCII 艺术、框线图）。 参见：ai_dev_ssd_flow/DIAGRAM_STANDARDS.md 和 mermaid-gen 技能。

常见问题

  1. 部分内容不完整：SPEC 就绪必须包含全部 11 个部分
  2. 缺少新增部分：第 3 至 7 节是 v3.0 中新增的部分，不要跳过
  3. 就绪度评分低：SPEC 就绪度和 IMPL 就绪度都必须达到 >=90%
  4. 非原子需求：每项 REQ 都必须是单一、可测试的单元
  5. 缺少累积标签：第 7 层必须包含全部 6 个上游标签
  6. 验收标准模糊：必须可衡量且可测试
  7. 硬编码值：使用 @threshold 引用，而非魔法数字
  8. 旧版元素 ID：使用 REQ.NN.xxxx 格式，而非 AC-XXX 或 FR-XXX
  9. 状态/评分不匹配：状态必须与两个评分中较低者一致

创建后验证（强制执行——无需确认）

重要：创建文档后，立即执行此验证循环。

自动验证循环
LOOP:
  1. Run: python scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed
验证命令
# Per-document validation (Phase 1)
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/07_REQ/REQ-NN_slug/REQ-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all REQ documents complete
python ai_dev_ssd_flow/scripts/validate_cross_document.py --layer REQ --auto-fix
各层上游要求
当前层必需的上游标签数量
REQ（第 7 层）@brd、@prd、@ears、@bdd、@adr、@sys6 个标签
自动修复操作（无需确认）
问题修复操作
缺少 @brd/@prd/@ears/@bdd/@adr/@sys 标签添加标签并引用上游文档
标签格式无效更正为 TYPE.NN.xxxx（三段式）或 TYPE-NN 格式
链接失效根据当前位置重新计算路径
缺少可追溯性部分从模板插入
验证代码参考
代码描述严重性
XDOC-001未找到引用的需求 ID错误
XDOC-002缺少累积标签错误
XDOC-003未找到上游文档错误
XDOC-006标签格式无效错误
XDOC-007累积标签链存在缺口错误
XDOC-009缺少可追溯性部分错误
质量门禁

阻塞：是——在第一阶段验证通过且错误数为 0 之前，不得继续创建 IMPL/SPEC。

下一项技能

创建 REQ 后，使用：

doc-spec（或可选地先使用 doc-impl/doc-ctr）——创建技术规范（第 10 层）

SPEC 将：

  • 将此 REQ 作为上游来源引用
  • 包含全部 7 个上游标签（@brd 到 @req）
  • 使用 YAML 格式
  • 定义实现契约
  • 达到 100% 实现就绪度

参考文档

REQ 工件不支持 REF 文档。根据 SDD 框架，参考文档仅限于 BRD 和 ADR 类型。

如需补充文档，请创建：

  • BRD-REF：业务背景和领域词汇表
  • ADR-REF：技术参考指南和架构摘要

相关资源

  • 模板：ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md（主要依据）

  • REQ 创建规则：ai_dev_ssd_flow/07_REQ/REQ-MVP-TEMPLATE.md

  • REQ 验证规则：ai_dev_ssd_flow/07_REQ/REQ_MVP_SCHEMA.yaml

  • REQ README：ai_dev_ssd_flow/07_REQ/README.md

  • 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md

  • 章节拆分参考（适用于大于 50KB 的文档）：

  • 参考：ai_dev_ssd_flow/ID_NAMING_STANDARDS.md（按章节拆分文件）

快速参考

REQ 目的：原子化、可直接用于实现的需求

层级：7

必需标签：@brd、@prd、@ears、@bdd、@adr、@sys（6 个标签）

格式：REQ MVP（11 个章节）

质量门槛：SPEC 就绪度评分 >=90% 且 IMPL 就绪度评分 >=90%

元素 ID 格式：REQ.NN.xxxx

  • 功能需求 = 01
  • 依赖项 = 05
  • 验收标准 = 06
  • 原子化需求 = 27

已移除的模式：AC-XXX、FR-XXX、R-XXX、REQ-XXX

文档控制字段：必需 11 项（+ 模板版本 = 3.0）

状态/评分映射：>=90% 已批准，70-89% 审核中，<70% 草稿

文件大小限制：>50KB 时使用章节文件

下一步：doc-spec（也可先选择 doc-impl/doc-ctr）

版本历史

版本日期变更作者
1.22026-03-06添加质量门槛验证参考和提交前钩子章节System
1.12026-02-27更新为 REQ v3.0 格式（11 个章节、SPEC 就绪度评分）System
1.02026-02-08初始技能定义，采用 YAML frontmatter 标准化System

评论

支持 Markdown