doc-sys

doc-sys

用途

创建 系统需求（SYS） 文档——SDD 工作流中的第 6 层制品，用于定义技术系统需求，包括功能能力和质量属性。

层级：6

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

下游制品：REQ（第 7 层）、代码（第 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. 不要创建缺失的上游制品——跳过相关功能

创建 SYS 前，请阅读：

1. 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md
2. 上游 ADR：阅读约束系统的架构决策
3. 模板：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
4. 创建规则：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
5. 验证规则：ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
6. 质量门禁验证：ai_dev_ssd_flow/06_SYS/SYS_MVP_QUALITY_GATE_VALIDATION.md

何时使用此技能

以下情况使用 doc-sys：

• 已完成 BRD 至 ADR（第 1 至 5 层）
• 需要定义系统级技术需求
• 将架构决策转化为需求
• 规定系统的功能行为和质量属性
• 当前处于 SDD 工作流的第 6 层

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

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

模式：SYS-00_*.md

文档类型：索引、可追溯性矩阵、术语表、注册表、检查清单

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

SYS 专属指南

1. SYS MVP 结构（共 15 个部分）

MVP 模板：完整的 15 个部分结构请参见 ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md。

第 1 部分——系统定义：

• 文档控制、执行摘要、范围

第 2 部分——系统需求：

• 功能需求、质量属性

第 3 部分——系统规范：

• 接口规范、数据管理需求、测试和验证需求

第 4 部分——系统运维：

• 部署和运维需求、合规与监管需求

第 5 部分——验证与控制：

• 验收标准、风险评估、可追溯性、实施说明

2. 文档控制要求

必填字段（9 项必填）：

• 状态、版本、创建／最后更新日期、作者、评审者、负责人、优先级
• EARS 就绪度评分
• REQ 就绪度评分

格式：

| Item | Details |
|------|---------|
| **EARS-Ready Score** | ✅ 95% (Target: ≥90%) |
| **REQ-Ready Score** | ✅ 95% (Target: ≥90%) |

3. REQ 就绪度评分体系

用途：衡量 SYS 的成熟度，以及其推进至需求（REQ）分解阶段的就绪程度。

格式：✅ NN% (Target: ≥90%)

状态与 REQ 就绪度评分对应关系：

REQ 就绪度评分	要求的状态
≥90%	已批准
70-89%	审查中
<70%	草稿

评分标准：

• 需求分解清晰度（35%）：系统边界、功能分解、依赖关系、与 ADR 的一致性
• 质量属性量化（30%）：性能百分位数、可靠性 SLA、安全合规性、可扩展性指标
• 接口规范（20%）：外部 API（可供 CTR 使用）、内部接口、数据交换协议
• 实施就绪度（15%）：测试需求、部署／运维、监控／可观测性

质量门禁：评分低于 90% 时，禁止创建 REQ 制品。

4. 元素 ID 格式（强制）

模式：SYS.{DOC_NUM}.{HASH}（3 个部分，以点分隔）

元素类型	代码	示例
功能需求	01	SYS.02.0101
质量属性	02	SYS.02.0201
用例	11	SYS.02.1101
系统需求	26	SYS.02.2601

已移除的模式——请勿使用旧格式：

• ❌ FR-XXX → 使用 SYS.NN.01.SS
• ❌ QA-XXX → 使用 SYS.NN.02.SS
• ❌ UC-XXX → 使用 SYS.NN.11.SS
• ❌ SR-XXX → 使用 SYS.NN.26.SS

参考：ID_NAMING_STANDARDS.md

5. 系统组件分类

系统类型：

• API 服务：REST、GraphQL 或其他 API 接口
• 数据处理：ETL、流处理、批处理系统
• 集成服务：适配器、连接器、代理服务
• 支撑服务：缓存、消息传递、配置服务
• 基础设施组件：负载均衡器、网关、监控系统

关键性级别：

• 任务关键型：创造收入且停机 SLA <1 小时的系统
• 业务关键型：核心运营系统，停机 SLA <4 小时
• 运营支撑型：后台系统，停机 SLA <24 小时

6. 阈值注册表集成

目的：通过引用集中式阈值注册表，避免使用魔法数字。

@threshold 标签格式：

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

SYS 专用阈值类别：

类别	SYS 用法	示例键
perf.*	性能要求	perf.api.p95_latency
sla.*	正常运行时间和可用性目标	sla.uptime.target
timeout.*	熔断器、连接超时	timeout.circuit_breaker.threshold
resource.*	内存、CPU、存储限制	resource.memory.max_heap
limit.*	速率限制、连接限制	limit.connection.max_total

无效（硬编码值）：

• ❌ p95 latency: 200ms
• ❌ uptime: 99.9%

有效（注册表引用）：

• ✅ p95 latency: @threshold: PRD.NN.perf.api.p95_latency
• ✅ uptime: @threshold: PRD.NN.sla.uptime.target

标签格式约定（设计如此）

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

主要区别：

• @adr: ADR-033 → 指向文档 ADR-033_risk_limit_enforcement.md
• @brd: BRD.17.0101 → 指向文档 BRD-017.md 中的元素 01.01

累积标签要求

第 6 层（SYS）：必须包含第 1 至第 5 层的标签（BRD、PRD、EARS、BDD、ADR）

标签数量：5 个标签（@brd、@prd、@ears、@bdd、@adr）

格式：

## Traceability

**Required Tags** (Cumulative Tagging Hierarchy - Layer 6):

@brd: BRD.01.0103
@prd: PRD.01.0702, PRD.01.0715
@ears: EARS.01.2501, EARS.01.2502
@bdd: BDD.01.1401
@adr: ADR-033, ADR-045

上游来源：

• BRD-01
• PRD-01
• EARS-01 - EARS 类型代码：25
• BDD-01 - BDD 场景类型代码：14
• ADR-033

上游／下游产物

上游来源：

• BRD（Layer 1）- 业务需求
• PRD（Layer 2）- 产品功能
• EARS（Layer 3）- 正式需求
• BDD（Layer 4）- 测试场景
• ADR（Layer 5）- 架构决策（关键 - 定义约束）

下游产物：

• REQ（Layer 7）- 从 SYS 分解而来的原子需求
• Code（Layer 13）- 系统需求的实现

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

• @related-sys: SYS-NN - 共享系统上下文的 SYS 文档
• @depends-sys: SYS-NN - 必须先实现的 SYS

创建流程

步骤 1：阅读上游产物

尤其关注 ADR（Layer 5）——架构决策会约束系统需求。

步骤 2：预留 ID 编号

检查 docs/06_SYS/ 中下一个可用的 ID 编号。

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

• ✅ 正确：SYS-01、SYS-99、SYS-102
• ❌ 错误：SYS-001、SYS-009（无需多余的前导零）

步骤 3：创建 SYS 文件

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

位置：docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md

示例：docs/06_SYS/SYS-01_order_management/SYS-01_order_management.md

关键：切勿在 docs/06_SYS/ 中直接创建 SYS 文件，必须使用嵌套文件夹结构。

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

填写包括 EARS-Ready Score 和 REQ-Ready Score 在内的元数据。

步骤 5：定义系统需求

对于每项需求：

• 使用统一的元素 ID 格式（SYS.NN.xxxx）
• 指定输入、处理和输出（针对功能需求）
• 指定可衡量的标准（针对质量属性）
• 对所有定量值使用 @threshold 标签
• 引用上游 EARS/PRD
• 链接到 BDD 验证

步骤 6：创建系统流程

使用 Mermaid 图表（而非基于文本的图表）：

• 使用序列图表示交互
• 使用流程图表示逻辑
• 使用状态图表示工作流

步骤 7：记录技术约束

根据 ADR 决策：

• 列出每项约束
• 说明影响
• 定义验证方式

步骤 8：添加累积标签

包含全部 5 个上游标签（@brd、@prd、@ears、@bdd、@adr）。

步骤 9：创建／更新可追溯性矩阵

强制：更新可追溯性矩阵（docs/06_SYS/SYS-00_TRACEABILITY_MATRIX.md）

步骤 10：验证 SYS

运行验证命令（参见“验证”部分）。

步骤 11：提交更改

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

验证

验证检查（共 8 项）

检查项	类型	说明
CHECK 1	错误	必填文档控制字段（9 个字段）
CHECK 2	错误	ADR 合规性验证
CHECK 3	错误	REQ-Ready Score 验证（格式、阈值）
CHECK 4	错误	质量属性量化
CHECK 5	警告	系统边界
CHECK 6	警告	接口规范（CTR-ready）
CHECK 7	警告	上游可追溯性
CHECK 8	错误	元素 ID 格式合规性（统一的 3 段式）

验证层级

层级	类型	退出代码	操作
Tier 1	错误	1	提交前必须修复
Tier 2	警告	0	建议修复
Tier 3	信息	0	无需操作

提交前钩子

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

- id: sys-core-validator
  name: Validate SYS core checks (validator, framework library)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_core_validator_hook.sh
  stages: [pre-commit]

- id: sys-quality-gate
  name: Validate SYS quality gates
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_quality_gate_hook.sh
  stages: [pre-commit]

- id: sys-req-ready-score
  name: Validate SYS REQ-Ready score (≥90%)
  entry: bash ai_dev_ssd_flow/06_SYS/scripts/sys_req_ready_score_hook.sh
  stages: [pre-commit]

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

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

强制执行的质量门禁：

• ✅ SYS 结构合规性（MVP 的 15 个部分）
• ✅ 已批准状态的 REQ-Ready Score ≥90%
• ✅ 元数据和标签（sys、layer-6-artifact）
• ✅ 上游可追溯性（@brd、@prd、@ears、@bdd、@adr）
• ✅ 元素 ID 格式（SYS.NN.xxxx）
• ✅ 已批准文档中不得包含占位文本
• ✅ 系统图表（必须使用 Mermaid）
• ✅ 使用 @threshold 标签的可衡量需求
• ✅ 功能需求和质量属性覆盖情况

自动验证

# Per-document validation (Phase 1)
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/SYS-NN_{slug}/SYS-NN_{slug}.md --verbose

# Layer validation (Phase 2) - run when all SYS documents complete
python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py docs/06_SYS/ --verbose

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py --artifact SYS-01 --expected-layers brd,prd,ears,bdd,adr --strict

手动检查清单

• 包含 9 个必填字段的文档控制部分
• REQ-Ready 评分包含 ✅ 表情符号和百分比
• 需求使用统一的元素 ID 格式（SYS.NN.xxxx）
• 不包含旧版格式（FR-XXX、QA-XXX、UC-XXX、SR-XXX）
• 每项需求都有可衡量的标准
• 所有定量值都使用 @threshold 标签
• 系统流程使用 Mermaid 图表
• 记录 ADR 中的技术约束
• 包含累积标签：@brd、@prd、@ears、@bdd、@adr
• 每项需求都引用上游来源
• 为每项需求指定验证方法
• 更新可追溯性矩阵

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

重要：创建文档后立即执行此验证循环。验证通过前，不要继续创建下一份文档。

自动验证循环

LOOP:
  1. Run: python ai_dev_ssd_flow/06_SYS/scripts/validate_sys.py {doc_path} --verbose
  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

各层级的上游要求

当前层级	必需的上游标签	数量
SYS（第 6 层）	@brd、@prd、@ears、@bdd、@adr	5 个标签

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

问题	修复操作
缺少 @brd/@prd/@ears/@bdd/@adr 标签	添加并引用上游文档
标签格式无效	更正为 TYPE.NN.xxxx（3 段式）或 TYPE-NN 格式
旧版元素 ID（FR-XXX、QA-XXX 等）	转换为 SYS.NN.xxxx 格式
链接失效	根据当前位置重新计算路径
缺少可追溯性部分	从模板插入

验证代码参考

代码	描述	严重程度
XDOC-001	未找到引用的需求 ID	ERROR
XDOC-002	缺少累积标签	ERROR
XDOC-003	未找到上游文档	ERROR
XDOC-006	标签格式无效	ERROR
XDOC-007	累积标签链中存在缺口	ERROR
XDOC-009	缺少可追溯性部分	ERROR

质量门禁

阻塞：是 - 第 1 阶段验证通过且错误数为 0 前，无法继续创建 REQ。

常见问题

1. 需求含糊不清：必须可衡量（不要写“快”，而要写“P95 <50ms”）
2. 缺少 ADR 约束：系统需求必须遵循 ADR 决策
3. 基于文本的图表：只能使用 Mermaid，不要使用 ASCII 艺术图或代码块
4. 缺少累积标签：第 6 层必须包含全部 5 个上游标签
5. 没有验证方法：每项需求都需要测试方法
6. 旧版元素 ID：使用 SYS.NN.xxxx，不要使用 FR-XXX/QA-XXX/SR-XXX
7. 硬编码值：使用 @threshold 标签，不要使用魔法数字
8. REQ-Ready 评分格式错误：必须包含 ✅ 表情符号和百分比

---

下游创建指南

根据 SYS 创建 REQ

REQ 分解规则：

1. 每项 SYS 功能需求 → 3-7 个原子 REQ 文件
2. 每个 SYS 质量属性类别 → 每个类别 2-4 个原子 REQ 文件
3. 每个 SYS 接口 → 每个接口 1-3 个原子 REQ 文件

针对 SYS 验证 REQ：

• 所有 REQ 能力都必须处于 SYS 系统边界内
• 所有 REQ 验收标准都必须满足 SYS 退出标准
• 所有 REQ 质量属性目标都必须达到或超过 SYS 阈值

创建接口 CTR：

• 当 SYS 指定外部 API 合约时，创建 CTR 文档
• CTR 需求必须与 SYS 接口规范完全一致

---

下一项技能

创建 SYS 后，使用：

doc-req - 创建原子需求（第 7 层）

REQ 将：

• 将 SYS 分解为原子需求
• 包含全部 6 个上游标签（从 @brd 到 @sys）
• 使用 REQ v3.0 格式（12 个部分）
• 达到 ≥90% SPEC 就绪度

参考文档

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

如需补充文档，请创建：

• BRD-REF：业务背景文档
• ADR-REF：系统架构指南、QA 属性目录

相关资源

• 模板：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md（主要依据）
• SYS 创建规则：ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md
• SYS 验证规则：ai_dev_ssd_flow/06_SYS/SYS_MVP_SCHEMA.yaml
• SYS README：ai_dev_ssd_flow/06_SYS/README.md
• 共享标准：.claude/skills/doc-flow/SHARED_CONTENT.md

章节划分指南（适用于超过 25K 个 token 的文档）：

• 遵循 ai_dev_ssd_flow/06_SYS/SYS-MVP-TEMPLATE.md 中的拆分规则
• 参考：ai_dev_ssd_flow/ID_NAMING_STANDARDS.md（基于章节拆分文件）

快速参考

SYS 目的：定义系统级技术要求

层级：6

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

REQ 就绪度评分：“Approved”状态要求 ≥90%

元素 ID 格式：SYS.NN.xxxx（FR=01、QA=02、UC=11、SR=26）

主要章节：

• 系统要求（统一的元素 ID）
• 系统流程（Mermaid 图表）
• 技术约束（来自 ADR）

重要提示：所有量化值都必须使用 @threshold 标签

下一步：doc-req

---

版本历史

版本	日期	变更	作者
1.2	2026-03-06	添加质量门验证参考和 pre-commit hooks 章节	System
1.1	2026-02-27	将 frontmatter 迁移至 metadata；将 SYS 规范引用统一为 ai_dev_ssd_flow；移除不存在的章节模板引用；使验证命令与 validate_sys.py 保持一致	System
1.0	2026-02-08	初始技能定义，采用 YAML frontmatter 标准化	System