SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场doc-req

doc-req

编程与开发

查看项目

更新于 10-16 02:01

技能介绍

doc-req 是 vladm3105/aidoc-flow-framework 中 doc-flow 技能族的一员，作用于 SDD（规范驱动开发）工作流的第 7 层，负责生成原子需求（Atomic Requirements，REQ）文档。它的目标是把系统需求（SYS）分解为原子化、可实施的需求单元，为后续实现做好铺垫。

用途与定位 REQ 是 SDD 分层工作流的中间产物：上游为 BRD（第 1 层）、PRD（第 2 层）、EARS（第 3 层）、BDD（第 4 层）、ADR（第 5 层）、SYS（第 6 层）；下游为 IMPL（第 8 层）、CTR（第 9 层）、SPEC（第 10 层）以及代码（第 13 层）。当 BRD 至 SYS 已完成、需要将系统需求拆解为原子单元、准备进入实现阶段（第 8 层及以后），并希望达到 SPEC 就绪分数时，即适合使用该技能。

主要能力

  1. REQ MVP 11 章节结构：文档控制（必需，位于所有编号章节之前）以及 Description、Functional Requirements、Interface Specifications、Data Schemas、Error Handling Specifications、Configuration Specifications、Quality Attributes、Implementation Guidance、Acceptance Criteria、Verification Methods、Traceability。MVP 中不包含变更历史章节。
  2. 文档控制 11 个必需字段：Status、Version（语义化 X.Y.Z）、Date Created（ISO 8601）、Last Updated（ISO 8601）、Author、Priority（P 级别）、Category、Source Document、Verification Method、Assigned Team、SPEC-Ready Score、IMPL-Ready Score、Template Version（必须为 3.0）。
  3. 双就绪评分：每个 REQ 需同时计算 SPEC-Ready 与 IMPL-Ready 两项分数，SPEC-Ready 公式为（已完成章节 / 12）× 100%；两项均需不低于 90% 才能通过质量门禁。状态映射：不低于 90% 为 Approved；70–89% 为 In Review；低于 70% 为 Draft；双分数取较低者判定状态。
  4. 原子需求原则：单一职责（每条 REQ 只定义一个需求）、可度量（验收标准提供真/假结果）、自包含、SPEC-Ready（信息完整度不低于 90%）、模态语言（SHALL/SHOULD/MAY）。
  5. 元素 ID 格式：REQ.{DOC_NUM}.{HASH}，三段点分隔，如功能需求 REQ.02.0101、依赖 REQ.02.0501、验收标准 REQ.02.0601、原子需求 REQ.02.2701；不使用 AC-XXX、FR-XXX、R-XXX、REQ-XXX 等旧模式。
  6. 累积可追溯标签：第 7 层需包含来自第 1–6 层的 6 个标签（@brd、@prd、@ears、@bdd、@adr、@sys）。框架区分两种引用记法：短横线 TYPE-NN 用于 ADR、SPEC、CTR 等技术文档引用；点号 TYPE.NN.xxxx 用于 BRD、PRD、EARS、BDD、SYS、REQ、IMPL、TASKS 等文档内元素引用。
  7. 阈值注册表集成：对业务关键、可配置、跨文档共享的量化值（性能目标、超时、重试、限流等）使用 @threshold 标签引用集中注册表，避免硬编码“魔法数字”；标签形如 @threshold: PRD.NN.category.subcategory.key。
  8. 预留 ID 豁免：文件名匹配 REQ-00_* 的文档（索引、可追溯矩阵模板、术语表、注册表、清单等框架基础设施）完全豁免校验。

使用方式（创建流程） 步骤包括：读取上游产物（尤其 SYS）；在 docs/07_REQ/ 中查找并预留下一个可用 ID（编号从两位起，如 REQ-01、REQ-99、REQ-102）；创建 REQ 文件（强制使用嵌套文件夹，如 docs/07_REQ/REQ-NN_{slug}/REQ-NN_{slug}.md，或用 domain/subdomain 结构，可先执行 mkdir -p）；填写文档控制章节；补全全部 11 个章节；计算双就绪分数；添加 6 个累积标签；更新 ai_dev_ssd_flow/07_REQ/REQ-00_TRACEABILITY_MATRIX-TEMPLATE.md；运行校验脚本；提交文件与可追溯矩阵。校验命令示例：./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。

适用场景 适用于已完成第 1–6 层、需要把系统需求分解为原子需求、准备进入实现阶段、并追求 SPEC 就绪分数不低于 90% 的项目，覆盖 api、risk、data、ml、auth、tenant、billing 等按领域划分的需求组织方式。

限制与要求 REQ 文件不得直接置于 docs/07_REQ/ 根目录，必须使用嵌套文件夹；上游产物校验为关键前置，只能引用真实存在的文档，禁止使用 BRD-XXX、TBD 等占位符，也不得创建缺失的上游产物（应跳过相应功能）；超过 50KB 的大需求须使用章节文件格式 REQ-NN.S_section_title.md；校验含 20 项检查，分为 Tier 1 错误（阻断提交）、Tier 2 警告、Tier 3 信息三级；REQ 校验通过 pre-commit 钩子（req-core-validator、req-quality-gate、req-spec-ready-score）自动强制执行，也可手动运行。质量门禁涵盖结构合规、SPEC 就绪分数、元数据与标签、上游可追溯性、无占位文本、原子性、至少 15 条可度量验收标准、接口规范、数据模式、错误处理、配置规范、带 @threshold 的质量属性以及相关 REQ 之间的交叉链接。 关于具体收费、价格、平台支持范围等信息，资料中暂未提供。