Back to Details

doc-req

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-req

doc-req

Purpose

目的

Create Atomic Requirements (REQ) documents - Layer 7 artifact in the SDD workflow that decomposes system requirements into atomic, implementation-ready requirements using REQ v3.0 format.
Layer: 7
Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6)
Downstream Artifacts: IMPL (Layer 8), CTR (Layer 9), SPEC (Layer 10), Code (Layer 13)
创建**原子需求（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层）、Code（第13层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（CRITICAL）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    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. Reference only existing documents in traceability tags
  3. Use 
    null
     only when upstream artifact type genuinely doesn't exist
  4. NEVER use placeholders like 
    BRD-XXX
    or 
    TBD
  5. Do NOT create missing upstream artifacts - skip functionality instead
Before creating REQ, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream SYS: Read system requirements driving this REQ
  3. Template: 
    ai_dev_flow/07_REQ/REQ-MVP-TEMPLATE.md
  4. Creation Rules: 
    ai_dev_flow/07_REQ/REQ_CREATION_RULES.md
  5. Validation Rules: 
    ai_dev_flow/07_REQ/REQ_VALIDATION_RULES.md
  6. Validation Script: 
    ./ai_dev_flow/scripts/validate_req_template.sh
创建本文档前，您必须:
  1. 列出已有的上游工件:
    bash
    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_flow/07_REQ/REQ-MVP-TEMPLATE.md
  4. 创建规则: 
    ai_dev_flow/07_REQ/REQ_CREATION_RULES.md
  5. 验证规则: 
    ai_dev_flow/07_REQ/REQ_VALIDATION_RULES.md
  6. 验证脚本: 
    ./ai_dev_flow/scripts/validate_req_template.sh

When to Use This Skill

何时使用本技能

Use 
doc-req
when:
  • Have completed BRD through SYS (Layers 1-6)
  • Need to decompose system requirements into atomic units
  • Preparing for implementation (Layer 8+)
  • Achieving >=90% SPEC-readiness score
  • You are at Layer 7 of the SDD workflow
在以下场景使用
doc-req
:
  • 已完成从BRD到SYS的所有工件（第1-6层）
  • 需要将系统需求分解为原子单元
  • 为实现工作做准备（第8层及以上）
  • 要达到≥90%的SPEC就绪度评分
  • 处于SDD工作流的第7层

Reserved ID Exemption (REQ-00_*)

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

Scope: Documents with reserved ID 
000
are FULLY EXEMPT from validation.
Pattern: 
REQ-00_*.md
Document Types:
  • Index documents (
    REQ-00_index.md
    )
  • Traceability matrix templates (
    REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md
    )
  • Glossaries, registries, checklists
Rationale: Reserved ID 000 documents are framework infrastructure, not project artifacts requiring traceability or quality gates.
Validation Behavior: Skip all checks when filename matches 
REQ-00_*
pattern.
范围: 保留ID为
000
的文档完全豁免验证。
模式: 
REQ-00_*.md
文档类型:
  • 索引文档（
    REQ-00_index.md
    ）
  • 可追溯性矩阵模板（
    REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md
    ）
  • 术语表、注册表、检查清单
理由: 保留ID 000的文档属于框架基础设施，而非需要可追溯性或质量 gates的项目工件。
验证行为: 当文件名匹配
REQ-00_*
模式时，跳过所有检查。

REQ-Specific Guidance

REQ专属指南

1. REQ v3.0 Format (12 Required Sections)

1. REQ v3.0格式（12个必填章节）

CRITICAL: REQ v3.0 expanded from 7 to 12 sections
Document Control (MANDATORY - First section before all numbered sections)
Core Sections:
  1. Description: Atomic requirement + SHALL/SHOULD/MAY language + context + scenario
  2. Functional Requirements: Core capabilities + business rules
  3. Interface Specifications: Protocol/ABC definitions + DTOs + REST endpoints
  4. Data Schemas: JSON Schema + Pydantic models + Database schema
  5. Error Handling Specifications: Exception catalog + error response schema + circuit breaker config
  6. Configuration Specifications: YAML schema + environment variables + validation
  7. Quality Attributes: Performance targets (p50/p95/p99) + reliability/security/scalability
  8. Implementation Guidance: Algorithms/patterns + concurrency/async + dependency injection
  9. Acceptance Criteria: >=15 measurable criteria covering functional/error/quality/data/integration
  10. Verification Methods: BDD scenarios + unit/integration/contract/performance tests
  11. Traceability: Section 7 format with cumulative tags (6 required)
  12. Change History: Version control table
CRITICAL: REQ v3.0从7个章节扩展到12个章节
文档控制（MANDATORY - 所有编号章节之前的第一个章节）
核心章节:
  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个必填）
  12. 变更历史: 版本控制表格

2. Document Control Requirements (11 Mandatory Fields)

2. 文档控制要求（11个必填字段）

FieldFormatExample
StatusApproved/In Review/DraftApproved
VersionSemantic X.Y.Z2.0.1
Date CreatedISO 86012025-11-18
Last UpdatedISO 86012025-11-19
AuthorName/RoleSystem Architect
PriorityLevel (P-level)High (P2)
CategoryTypeFunctional
Source DocumentDOC-ID section X.Y.ZSYS-02 section 3.1.1
Verification MethodMethod typeBDD + Integration Test
Assigned TeamTeam nameIB Integration Team
SPEC-Ready ScoreFormat with emoji>=90% (Target: >=90%)
IMPL-Ready ScoreFormat with emoji>=90% (Target: >=90%)
Template VersionMust be 3.03.0
字段格式示例
状态Approved/In Review/DraftApproved
版本语义化X.Y.Z2.0.1
创建日期ISO 86012025-11-18
最后更新日期ISO 86012025-11-19
作者姓名/角色System Architect
优先级Level（P级别）High (P2)
分类类型Functional
源文档DOC-ID章节X.Y.ZSYS-02 section 3.1.1
验证方法方法类型BDD + Integration Test
分配团队团队名称IB Integration Team
SPEC就绪度评分带emoji的格式>=90% (Target: >=90%)
IMPL就绪度评分带emoji的格式>=90% (Target: >=90%)
模板版本必须为3.03.0

3. Dual Readiness Scoring (SPEC-Ready + IMPL-Ready)

3. 双重就绪度评分（SPEC-Ready + IMPL-Ready）

MANDATORY: Each REQ must calculate BOTH scores
SPEC-Ready Score Formula:
SPEC-Ready Score = (Completed Sections / 12) * 100%
IMPL-Ready Score: Measures readiness for implementation approach documentation
Quality Gate: Both scores >=90% required for layer transition
Status and Ready Score Mapping:
Ready ScoreRequired Status
>= 90%Approved
70-89%In Review
< 70%Draft
Note: For REQ documents with dual scores, use the LOWER score to determine status.
Example:
markdown
undefined
MANDATORY: 每个REQ必须同时计算两个评分
SPEC就绪度评分公式:
SPEC-Ready Score = (已完成章节数 / 12) * 100%
IMPL就绪度评分: 衡量实现方案文档的就绪程度
质量门: 两个评分均需≥90%才能进入下一层级
状态与就绪度评分映射:
就绪度评分要求的状态
>= 90%Approved
70-89%In Review
< 70%Draft
注意: 对于有双重评分的REQ文档，使用较低的评分来确定状态。
示例:
markdown
undefined

Readiness Scores

就绪度评分

SPEC-Ready Score: >=95% (Target: >=90%) IMPL-Ready Score: >=92% (Target: >=90%)
Section Status:
  • 1. Description
  • 2. Functional Requirements
  • 3. Interface Specifications
  • 4. Data Schemas
  • 5. Error Handling Specifications
  • 6. Configuration Specifications
  • 7. Quality Attributes
  • 8. Implementation Guidance
  • 9. Acceptance Criteria
  • 10. Verification Methods
  • 11. Traceability
  • 12. Change History (In Progress)
Readiness: READY for SPEC/IMPL creation
undefined
SPEC-Ready Score: >=95% (Target: >=90%) IMPL-Ready Score: >=92% (Target: >=90%)
章节状态:
  • 1. 描述
  • 2. 功能需求
  • 3. 接口规范
  • 4. 数据模式
  • 5. 错误处理规范
  • 6. 配置规范
  • 7. 质量属性
  • 8. 实现指南
  • 9. 验收标准
  • 10. 验证方法
  • 11. 可追溯性
  • 12. 变更历史（进行中）
就绪状态: 已准备好创建SPEC/IMPL文档
undefined

4. Element ID Format (MANDATORY)

4. 元素ID格式（MANDATORY）

Pattern: 
REQ.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeExample
Functional Requirement01REQ.02.01.01
Dependency05REQ.02.05.01
Acceptance Criteria06REQ.02.06.01
Atomic Requirement27REQ.02.27.01
REMOVED PATTERNS - Do NOT use:
  • AC-XXX
    - Use 
    REQ.NN.06.SS
  • FR-XXX
    - Use 
    REQ.NN.01.SS
  • R-XXX
    - Use 
    REQ.NN.27.SS
  • REQ-XXX
    - Use 
    REQ.NN.27.SS
Reference: 
ID_NAMING_STANDARDS.md
- Cross-Reference Link Format
模式: 
REQ.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，点分隔）
元素类型编码示例
功能需求01REQ.02.01.01
依赖项05REQ.02.05.01
验收标准06REQ.02.06.01
原子需求27REQ.02.27.01
已移除的模式 - 请勿使用:
  • 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. Atomic Requirement Principles

5. 原子需求原则

  • Single Responsibility: Each REQ defines exactly one requirement
  • Measurable: Acceptance criteria provide true/false outcomes
  • Self-Contained: Understandable without external context
  • SPEC-Ready: Contains ALL information for automated SPEC generation (>=90% completeness)
  • Modal Language: SHALL (absolute), SHOULD (preferred), MAY (optional)
  • 单一职责: 每个REQ仅定义一个需求
  • 可衡量: 验收标准需提供明确的真假结果
  • 自包含: 无需外部上下文即可理解
  • SPEC就绪: 包含自动生成SPEC所需的全部信息（完整性≥90%）
  • 模态语言: 使用SHALL（强制）、SHOULD（推荐）、MAY（可选）

6. Domain/Subdomain Organization

6. 领域/子领域组织

Location: 
REQ/{domain}/{subdomain}/
within project docs directory
Domains: 
api/
(external integrations), 
risk/
(risk management), 
data/
(data requirements), 
ml/
(ML requirements), 
auth/
(security), etc.
Format: 
REQ-NN_descriptive_slug.md
Example: 
REQ-risk-limits-01_position_validation.md
存储位置: 项目文档目录下的
REQ/{domain}/{subdomain}/
领域: 
api/
（外部集成）、
risk/
（风险管理）、
data/
（数据需求）、
ml/
（ML需求）、
auth/
（安全）等
格式: 
REQ-NN_descriptive_slug.md
示例: 
REQ-risk-limits-01_position_validation.md

Tag Format Convention (By Design)

标签格式约定（设计规范）

The SDD framework uses two distinct notation systems for cross-references:
NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - references to files/documents
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKSHierarchical artifacts - references to elements inside documents
Key Distinction:
  • @adr: ADR-033
    -> Points to the document 
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.03
    -> Points to element 01.03 inside document 
    BRD-017.md
SDD框架使用两种不同的标记系统进行交叉引用:
标记法格式适用工件用途
短横线TYPE-NNADR, SPEC, CTR技术工件 - 指向文件/文档的引用
点TYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS分层工件 - 指向文档内部元素的引用
关键区别:
  • @adr: ADR-033
    -> 指向文档
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.03
    -> 指向文档
    BRD-017.md
    内部的元素01.03

Cumulative Tagging Requirements

累积标签要求

Layer 7 (REQ): Must include tags from Layers 1-6 (BRD, PRD, EARS, BDD, ADR, SYS)
Tag Count: 6 tags (@brd, @prd, @ears, @bdd, @adr, @sys)
Format:
markdown
undefined
第7层（REQ）: 必须包含第1-6层的标签（BRD、PRD、EARS、BDD、ADR、SYS）
标签数量: 6个标签（@brd, @prd, @ears, @bdd, @adr, @sys）
格式:
markdown
undefined

Traceability

可追溯性

Required Tags (Cumulative Tagging Hierarchy - Layer 7):
markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.01.01, SYS.01.02.07
Upstream Sources:
  • BRD-01
  • PRD-01
  • EARS-01
  • BDD-01
  • ADR-033
  • SYS-01
Downstream Artifacts:
  • IMPL-NN (to be created) - Implementation approach
  • CTR-NN (to be created) - Data contracts
  • SPEC-NN (to be created) - Technical specifications

**Element Type Codes for Tags**:
- EARS: Type 25 (formal requirement)
- BDD: Type 14 (scenario)
- SYS: Type 01 (functional), 02 (quality attribute), 26 (system req)
必填标签（累积标签层级 - 第7层）:
markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.01.01, SYS.01.02.07
上游来源:
  • BRD-01
  • PRD-01
  • EARS-01
  • BDD-01
  • ADR-033
  • SYS-01
下游工件:
  • IMPL-NN（待创建）- 实现方案
  • CTR-NN（待创建）- 数据契约
  • SPEC-NN（待创建）- 技术规范

**标签的元素类型编码**:
- EARS: 类型25（正式需求）
- BDD: 类型14（场景）
- SYS: 类型01（功能）、02（质量属性）、26（系统需求）

Threshold Registry Integration

阈值注册表集成

Purpose: Prevent magic numbers by referencing centralized threshold registry.
目的: 通过引用集中式阈值注册表避免魔法数字。

When @threshold Tag is Required

何时需要@threshold标签

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
:
  • 业务关键值（合规限制、SLA）
  • 可配置值（超时时间、速率限制、重试策略）
  • 跨文档共享的值（性能目标）
  • 质量属性相关值（p50/p95/p99延迟、吞吐量限制）
  • 错误处理配置（断路器、重试次数）

@threshold Tag Format

@threshold标签格式

markdown
@threshold: PRD.NN.category.subcategory.key
Examples:
  • @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
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-Specific Threshold Categories

REQ专属阈值分类

CategoryREQ UsageExample Key
perf.*
Performance acceptance criteria
perf.api.p95_latency
timeout.*
Circuit breaker, connection configs
timeout.circuit_breaker.reset
retry.*
Retry policy configurations
retry.max_attempts
limit.*
Rate limits, resource limits
limit.api.requests_per_second
resource.*
Memory, CPU constraints
resource.memory.max_heap
分类REQ用途示例Key
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

Magic Number Detection

魔法数字检测

Invalid (hardcoded values):
  • p95 response time: 200ms
  • max_retries: 3
  • rate_limit: 100 req/s
Valid (registry references):
  • 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
无效（硬编码值）:
  • p95响应时间: 200ms
  • 最大重试次数: 3
  • 速率限制: 100 req/s
有效（注册表引用）:
  • p95响应时间: @threshold: PRD.NN.perf.api.p95_latency
  • 最大重试次数: @threshold: PRD.NN.retry.max_attempts
  • 速率限制: @threshold: PRD.NN.limit.api.requests_per_second

Upstream/Downstream Artifacts

上游/下游工件

Upstream Sources:
  • BRD (Layer 1) - Business requirements
  • PRD (Layer 2) - Product features
  • EARS (Layer 3) - Formal requirements
  • BDD (Layer 4) - Test scenarios
  • ADR (Layer 5) - Architecture decisions
  • SYS (Layer 6) - System requirements (PRIMARY SOURCE)
Downstream Artifacts:
  • IMPL (Layer 8) - Implementation approach (optional)
  • CTR (Layer 9) - Data contracts (optional)
  • SPEC (Layer 10) - Technical specifications
  • Code (Layer 13) - Implementation
Same-Type Document Relationships (conditional):
  • @related-req: REQ-NN
    - REQs sharing domain context
  • @depends-req: REQ-NN
    - REQ that must be implemented first
上游来源:
  • BRD（第1层）- 业务需求
  • PRD（第2层）- 产品功能
  • EARS（第3层）- 正式需求
  • BDD（第4层）- 测试场景
  • ADR（第5层）- 架构决策
  • SYS（第6层）- 系统需求（主要来源）
下游工件:
  • IMPL（第8层）- 实现方案（可选）
  • CTR（第9层）- 数据契约（可选）
  • SPEC（第10层）- 技术规范
  • Code（第13层）- 实现代码
同类型文档关系（可选）:
  • @related-req: REQ-NN
    - 共享领域上下文的REQ
  • @depends-req: REQ-NN
    - 必须先实现的REQ

Creation Process

创建流程

Step 1: Read Upstream Artifacts

步骤1: 阅读上游工件

Especially focus on SYS (Layer 6) - system requirements to decompose.
重点关注SYS（第6层）——需要分解的系统需求。

Step 2: Reserve ID Number

步骤2: 预留ID编号

Check 
ai_dev_flow/REQ/
for next available ID number.
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • ✅ Correct: REQ-01, REQ-99, REQ-102
  • ❌ Incorrect: REQ-001, REQ-009 (extra leading zero not required)
Domain-based naming: 
REQ-domain-subdomain-NN
查看
ai_dev_flow/REQ/
获取下一个可用的ID编号。
ID编号约定: 以2位数字开头，仅在需要时扩展位数。
  • ✅ 正确: REQ-01, REQ-99, REQ-102
  • ❌ 错误: REQ-001, REQ-009（不需要前导零）
基于领域的命名: 
REQ-domain-subdomain-NN

Step 3: Create REQ File

步骤3: 创建REQ文件

Nested Folder Rule (MANDATORY): ALL REQ documents MUST use nested folders regardless of document size.
Location Options:
  • Standard: 
    docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md
  • Domain-based: 
    docs/07_REQ/{domain}/REQ-NN_{slug}/REQ-NN_{slug}.md
  • Subdomain: 
    docs/07_REQ/{domain}/{subdomain}/REQ-NN_{slug}/REQ-NN_{slug}.md
On-Demand Folder Creation: Before saving the document, create the target directory:
bash
undefined
嵌套文件夹规则（MANDATORY）: 无论文档大小，所有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
按需创建文件夹: 保存文档前，先创建目标目录:
bash
undefined

Create target directory (ALWAYS use nested folder)

创建目标目录（始终使用嵌套文件夹）

mkdir -p docs/07_REQ/REQ-NN_{slug}/
mkdir -p docs/07_REQ/REQ-NN_{slug}/

OR for domain-based structure

或者基于领域的结构

mkdir -p docs/07_REQ/{domain}/REQ-NN_{slug}/

**CRITICAL**: Never create REQ files directly in `docs/07_REQ/` without a nested folder structure.

**Domain Selection**: Use domain from project configuration or upstream SYS context:
- Financial: `risk/`, `trading/`, `collection/`, `compliance/`, `ml/`
- SaaS: `tenant/`, `subscription/`, `billing/`, `workspace/`
- Generic: `api/`, `auth/`, `data/`, `core/`, `integration/`

**Section Files**: For large requirements (>50KB), use Section Files format: `REQ-NN.S_section_title.md` (S = section number).
mkdir -p docs/07_REQ/{domain}/REQ-NN_{slug}/

**CRITICAL**: 绝不要直接在`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 = 章节编号）

Step 4: Fill Document Control Section

步骤4: 填写文档控制章节

Complete metadata with all 11 required fields plus Document Revision History table.
完成包含11个必填字段的元数据，以及文档修订历史表格。

Step 5: Complete All 12 Required Sections

步骤5: 完成所有12个必填章节

Critical: REQ v3.0 requires all 12 sections for >=90% SPEC-readiness
  1. Description: Atomic requirement + SHALL/SHOULD/MAY language
  2. Functional Requirements: Core capabilities + business rules
  3. Interface Specifications: APIs, endpoints, contracts, Protocol/ABC class
  4. Data Schemas: Models, validation, constraints, Pydantic/dataclass
  5. Error Handling Specifications: Error codes, recovery, exception definitions
  6. Configuration Specifications: Settings, feature flags, YAML config
  7. Quality Attributes: Performance, security, scalability with thresholds
  8. Implementation Guidance: Technical approach, patterns
  9. Acceptance Criteria: >=15 measurable criteria
  10. Verification Methods: BDD scenarios, tests
  11. Traceability: Cumulative tags (6 tags)
  12. Change History: Version control table
Critical: REQ v3.0需要完成所有12个章节才能达到≥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个标签）
  12. 变更历史: 版本控制表格

Step 6: Calculate Readiness Scores

步骤6: 计算就绪度评分

Count completed sections and calculate both SPEC-Ready and IMPL-Ready percentages.
Quality Gate: Both scores must achieve >=90%
统计已完成的章节数，计算SPEC就绪度和IMPL就绪度百分比。
质量门: 两个评分均需达到≥90%

Step 7: Add Cumulative Tags

步骤7: 添加累积标签

Include all 6 upstream tags (@brd through @sys).
包含所有6个上游标签（@brd至@sys）。

Step 8: Create/Update Traceability Matrix

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

MANDATORY: Update 
ai_dev_flow/REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md
MANDATORY: 更新
ai_dev_flow/REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md

Step 9: Validate REQ

步骤9: 验证REQ

bash
./ai_dev_flow/scripts/validate_req_template.sh ai_dev_flow/REQ/REQ-NN_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact REQ-NN --expected-layers brd,prd,ears,bdd,adr,sys --strict
bash
./ai_dev_flow/scripts/validate_req_template.sh ai_dev_flow/REQ/REQ-NN_*.md

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact REQ-NN --expected-layers brd,prd,ears,bdd,adr,sys --strict

Step 10: Commit Changes

步骤10: 提交变更

Commit REQ file and traceability matrix.
提交REQ文件和可追溯性矩阵。

Validation

验证

Validation Checks (20 Total)

验证检查项（共20项）

CheckDescriptionType
CHECK 1Required 12 sectionsError
CHECK 2Document Control (11 fields)Error
CHECK 3Traceability structureError/Warning
CHECK 4Legacy (deprecated)Info
CHECK 5Version format (X.Y.Z)Error
CHECK 6Date format (ISO 8601)Error
CHECK 7Priority format (P1-P4)Warning
CHECK 8Source document formatWarning
CHECK 9SPEC-Ready ScoreError/Warning
CHECK 10Template Version (3.0)Error
CHECK 11Change HistoryError/Warning
CHECK 12Filename/ID formatError
CHECK 13Resource tag (Template 2.0)Error
CHECK 14Cumulative tagging (6 tags)Error
CHECK 15Complete upstream chainError
CHECK 16Link resolutionError/Warning
CHECK 17Traceability matrixWarning
CHECK 18SPEC-Ready contentWarning
CHECK 19IMPL-Ready ScoreError
CHECK 20Element ID format complianceError
检查项描述类型
CHECK 1必填的12个章节是否存在错误
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格式合规性错误

Validation Tiers

验证层级

TierTypeExit CodeDescription
Tier 1Errors1Blocking - must fix before commit
Tier 2Warnings0Quality issues - recommended to fix
Tier 3Info0Informational - no action required
层级类型退出码描述
Tier 1错误1阻塞性 - 必须修复才能提交
Tier 2警告0质量问题 - 建议修复
Tier 3信息0参考信息 - 无需操作

Automated Validation

自动化验证

bash
undefined
bash
undefined

Validate single file

验证单个文件

./scripts/validate_req_template.sh docs/REQ/REQ-NN_slug.md
./scripts/validate_req_template.sh docs/REQ/REQ-NN_slug.md

Validate all REQ files

验证所有REQ文件

find docs/REQ -name "REQ-*.md" -exec ./scripts/validate_req_template.sh {} ;
find docs/REQ -name "REQ-*.md" -exec ./scripts/validate_req_template.sh {} ;

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact REQ-NN
--expected-layers brd,prd,ears,bdd,adr,sys
--strict
undefined
python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact REQ-NN
--expected-layers brd,prd,ears,bdd,adr,sys
--strict
undefined

Manual Checklist

手动检查清单

  • Document Control section at top with 11 required fields
  • All 12 required sections completed
  • SPEC-Ready Score >=90%
  • IMPL-Ready Score >=90%
  • Template Version = 3.0
  • Section 3: Interface Specifications with Protocol/ABC class
  • Section 4: Data Schemas with Pydantic/dataclass models
  • Section 5: Error Handling with exception definitions
  • Section 6: Configuration with YAML schema
  • Section 7: Quality Attributes with @threshold references
  • Section 9: >=15 acceptance criteria
  • Cumulative tags: @brd through @sys (6 tags) included
  • Each requirement atomic (single responsibility)
  • Acceptance criteria testable and measurable
  • Traceability matrix updated
  • 顶部有包含11个必填字段的文档控制章节
  • 所有12个必填章节已完成
  • SPEC就绪度评分≥90%
  • IMPL就绪度评分≥90%
  • 模板版本=3.0
  • 第3章：接口规范包含Protocol/ABC类
  • 第4章：数据模式包含Pydantic/dataclass模型
  • 第5章：错误处理包含异常定义
  • 第6章：配置包含YAML模式
  • 第7章：质量属性包含@threshold引用
  • 第9章：≥15个验收标准
  • 累积标签：包含@brd至@sys（6个标签）
  • 每个需求都是原子化的（单一职责）
  • 验收标准可测试、可衡量
  • 可追溯性矩阵已更新

Diagram Standards

图表标准

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: 
ai_dev_flow/DIAGRAM_STANDARDS.md
and 
mermaid-gen
skill.
所有图表必须使用Mermaid语法。禁止使用基于文本的图表（ASCII艺术、框线图）。 参考: 
ai_dev_flow/DIAGRAM_STANDARDS.md
和
mermaid-gen
技能。

Common Pitfalls

常见陷阱

  1. Incomplete sections: All 12 sections mandatory for SPEC-readiness
  2. Missing new sections: Sections 3-7 are new in v3.0 - don't skip them
  3. Low readiness scores: Both SPEC-Ready and IMPL-Ready must achieve >=90%
  4. Non-atomic requirements: Each REQ must be single, testable unit
  5. Missing cumulative tags: Layer 7 must include all 6 upstream tags
  6. Vague acceptance criteria: Must be measurable and testable
  7. Hardcoded values: Use @threshold references, not magic numbers
  8. Legacy element IDs: Use 
    REQ.NN.TT.SS
    format, not AC-XXX or FR-XXX
  9. Status/score mismatch: Status must match the LOWER of the two scores
  1. 章节不完整: 所有12个章节都是SPEC就绪度的必填项
  2. 遗漏新增章节: 第3-7章是v3.0新增的——不要跳过
  3. 就绪度评分过低: SPEC就绪度和IMPL就绪度都必须≥90%
  4. 非原子需求: 每个REQ必须是单一、可测试的单元
  5. 缺失累积标签: 第7层必须包含所有6个上游标签
  6. 模糊的验收标准: 必须可衡量、可测试
  7. 硬编码值: 使用@threshold引用，不要用魔法数字
  8. 遗留元素ID: 使用
    REQ.NN.TT.SS
    格式，不要用AC-XXX或FR-XXX
  9. 状态/评分不匹配: 状态必须与较低的评分匹配

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（MANDATORY - 无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation.
CRITICAL: 文档创建后立即执行此验证循环。

Automatic Validation Loop

自动验证循环

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
LOOP:
  1. 运行: python scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复: 回到LOOP（重新验证）
  3. 如果警告已修复: 回到LOOP（重新验证）
  4. 如果存在无法修复的问题: 记录以便手动审核，继续
  5. 如果验证通过: 标记为VALIDATED，继续

Validation Command

验证命令

bash
undefined
bash
undefined

Per-document validation (Phase 1)

单文档验证（阶段1）

python ai_dev_flow/scripts/validate_cross_document.py --document docs/REQ/REQ-NN_slug.md --auto-fix
python ai_dev_flow/scripts/validate_cross_document.py --document docs/REQ/REQ-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all REQ documents complete

层级验证（阶段2）- 所有REQ文档完成后运行

python ai_dev_flow/scripts/validate_cross_document.py --layer REQ --auto-fix
undefined
python ai_dev_flow/scripts/validate_cross_document.py --layer REQ --auto-fix
undefined

Layer-Specific Upstream Requirements

层级专属上游需求

This LayerRequired Upstream TagsCount
REQ (Layer 7)@brd, @prd, @ears, @bdd, @adr, @sys6 tags
当前层级必填上游标签数量
REQ（第7层）@brd, @prd, @ears, @bdd, @adr, @sys6个标签

Auto-Fix Actions (No Confirmation Required)

自动修复操作（无需确认）

IssueFix Action
Missing @brd/@prd/@ears/@bdd/@adr/@sys tagAdd with upstream document reference
Invalid tag formatCorrect to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken linkRecalculate path from current location
Missing traceability sectionInsert from template
问题修复动作
缺失@brd/@prd/@ears/@bdd/@adr/@sys标签添加上游文档引用
无效的标签格式修正为TYPE.NN.TT.SS（4段）或TYPE-NN格式
链接失效根据当前位置重新计算路径
缺失可追溯性章节从模板插入

Validation Codes Reference

验证代码参考

CodeDescriptionSeverity
XDOC-001Referenced requirement ID not foundERROR
XDOC-002Missing cumulative tagERROR
XDOC-003Upstream document not foundERROR
XDOC-006Tag format invalidERROR
XDOC-007Gap in cumulative tag chainERROR
XDOC-009Missing traceability sectionERROR
代码描述严重程度
XDOC-001引用的需求ID未找到错误
XDOC-002缺失累积标签错误
XDOC-003上游文档未找到错误
XDOC-006标签格式无效错误
XDOC-007累积标签链存在缺口错误
XDOC-009缺失可追溯性章节错误

Quality Gate

质量门

Blocking: YES - Cannot proceed to IMPL/SPEC creation until Phase 1 validation passes with 0 errors.
阻塞性: 是 - 阶段1验证必须通过且无错误，才能继续创建IMPL/SPEC文档。

Next Skill

下一个技能

After creating REQ, use:
doc-spec
 (or optionally 
doc-impl
/
doc-ctr
first) - Create Technical Specifications (Layer 10)
The SPEC will:
  • Reference this REQ as upstream source
  • Include all 7 upstream tags (@brd through @req)
  • Use YAML format
  • Define implementation contracts
  • Achieve 100% implementation-readiness
创建REQ后，使用:
doc-spec
（或可选先使用
doc-impl
/
doc-ctr
）- 创建技术规范（第10层）
SPEC文档将:
  • 引用本REQ作为上游来源
  • 包含所有7个上游标签（@brd至@req）
  • 使用YAML格式
  • 定义实现契约
  • 达到100%的实现就绪度

Reference Documents

参考文档

REQ artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.
For supplementary documentation needs, create:
  • BRD-REF: Business context and domain glossaries
  • ADR-REF: Technical reference guides and architecture summaries
REQ工件不支持REF文档。根据SDD框架，参考文档仅限于BRD和ADR类型。
如需补充文档，可创建:
  • BRD-REF: 业务上下文和领域术语表
  • ADR-REF: 技术参考指南和架构摘要

Related Resources

相关资源

  • Template: 
    ai_dev_flow/07_REQ/REQ-MVP-TEMPLATE.md
    (primary authority)
  • REQ Creation Rules: 
    ai_dev_flow/07_REQ/REQ_CREATION_RULES.md
  • REQ Validation Rules: 
    ai_dev_flow/07_REQ/REQ_VALIDATION_RULES.md
  • REQ README: 
    ai_dev_flow/07_REQ/README.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
Section Templates (for documents >50KB):
  • Index template: 
    ai_dev_flow/07_REQ/REQ-SECTION-0-TEMPLATE.md
  • Content template: 
    ai_dev_flow/07_REQ/REQ-SECTION-TEMPLATE.md
  • Reference: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
    (Section-Based File Splitting)
  • 模板: 
    ai_dev_flow/07_REQ/REQ-MVP-TEMPLATE.md
    （主要权威来源）
  • REQ创建规则: 
    ai_dev_flow/07_REQ/REQ_CREATION_RULES.md
  • REQ验证规则: 
    ai_dev_flow/07_REQ/REQ_VALIDATION_RULES.md
  • REQ README: 
    ai_dev_flow/07_REQ/README.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
章节模板（适用于>50KB的文档）:
  • 索引模板: 
    ai_dev_flow/07_REQ/REQ-SECTION-0-TEMPLATE.md
  • 内容模板: 
    ai_dev_flow/07_REQ/REQ-SECTION-TEMPLATE.md
  • 参考: 
    ai_dev_flow/ID_NAMING_STANDARDS.md
    （基于章节的文件拆分）

Quick Reference

快速参考

REQ Purpose: Atomic, implementation-ready requirements
Layer: 7
Tags Required: @brd, @prd, @ears, @bdd, @adr, @sys (6 tags)
Format: REQ v3.0 (12 sections)
Quality Gate: SPEC-Ready Score >=90% AND IMPL-Ready Score >=90%
Element ID Format: 
REQ.NN.TT.SS
  • Functional Requirement = 01
  • Dependency = 05
  • Acceptance Criteria = 06
  • Atomic Requirement = 27
Removed Patterns: AC-XXX, FR-XXX, R-XXX, REQ-XXX
Document Control Fields: 11 required (+ Template Version = 3.0)
Status/Score Mapping: >=90% Approved, 70-89% In Review, <70% Draft
File Size Limits: >50KB use section files
Next: doc-spec (or optionally doc-impl/doc-ctr first)
REQ目的: 原子化、可直接实现的需求
层级: 7
必填标签: @brd, @prd, @ears, @bdd, @adr, @sys（6个标签）
格式: REQ v3.0（12个章节）
质量门: SPEC就绪度评分≥90% 且 IMPL就绪度评分≥90%
元素ID格式: 
REQ.NN.TT.SS
  • 功能需求 = 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）

Version History

版本历史

VersionDateChangesAuthor
1.02026-02-08Initial skill definition with YAML frontmatter standardizationSystem
版本日期变更作者
1.02026-02-08初始技能定义，标准化YAML前置内容System