概述

目的：将需求相关的各类文档存入需求管理系统的正确路径，确保目录结构统一、可追溯

功能：

• 按文档类型自动决定存储路径，统一各 skill 产出文档的落盘位置
• 区分创建/更新/删除三类场景，给出对应的 req 命令操作流程
• 落盘后强制用 req list --id 验证添加/更新成功，失败必须修正重试
• 维护需求生命周期状态、文档关联、标签与依赖关系

使用场景：

• 任何 skill 生成需求相关文档后需要落盘时（设计文档、数据流图、验证报告、审查报告、实现报告等）
• 需要创建新需求目录并注册到 meta.json 时
• 需要更新需求状态、文档关联或废弃清理需求时

Requirement Doc Store（需求文档存储）

指导 AI 将需求相关的各类文档存入需求管理系统的正确路径，确保目录结构统一、可追溯。

核心原则

• 按文档类型分目录：不同阶段产出的文档放入不同子目录
• 中文命名：目录名和文件名使用中文，与 meta.json 中 feature 字段一致
• 命令操作元数据：禁止直接编辑 meta.json，必须通过 req 命令操作

配置约束

.requirements/config 文件定义了以下约束规则：

配置项	约束规则	示例
feature_categories	功能分类标签，多个分类用逗号分隔。必须包含一个功能分类标签	security,performance,integration
requirement_tags	标签可选值，必须从此配置中选取	feat,fix,refactor,tool,security,...

约束验证：

• --tags 或 --tag add/set 操作时，标签必须来自 requirement_tags 配置
• 创建需求时，必须包含一个 feature_categories 中的功能分类标签
• 违反约束会导致操作失败并显示错误信息

前置步骤：初始化配置

使用任何 req 命令前，必须先执行 req init 初始化项目配置文件 .requirements/config：

req init

命令行为：

• 自动向上查找项目根目录（含 .requirements 或 .git 的目录），确保在子目录中运行也能正确定位
• 生成 .requirements/config 和 .requirements/ 目录
• 如果配置文件已存在，提示使用 req init --force 覆盖

选项：

选项	说明
--force	强制覆盖已存在的配置文件，覆盖前自动备份旧配置为 config.bak
--yes	非交互模式，跳过确认提示，直接创建或覆盖

生成的默认配置模板：

# requirement-mgr 项目配置
# 由 req init 自动生成

storage_path=.requirements
feature_categories=
requirement_tags=
requirement_statuses=草案,已确认,设计中,实施中,已完成,已取消
requirement_roles=standalone,parent,child
id_prefix=REQ
id_digits=3
lock_timeout=5
backup_enabled=false

配置项说明：

配置项	说明	默认值
storage_path	需求文档存储根路径	.requirements
feature_categories	功能分类标签（逗号分隔）	空
requirement_tags	标签可选值（逗号分隔）	空
requirement_statuses	需求状态可选值，第一个为默认初始状态	草案,已确认,...
requirement_roles	需求角色可选值	standalone,parent,child
id_prefix	需求 ID 前缀	REQ
id_digits	ID 日期后序号位数	3
lock_timeout	文件锁超时秒数	5
backup_enabled	写入前是否备份 meta.json	false

---

场景判断

在存储文档前，先判断当前是「创建」还是「更新」：

场景	判别条件	处理方式
创建	需求目录不存在（{storage_path}/{category}/{date}-{feature}/ 不存在）	先用 req create 创建目录 + 注册 meta.json，再写入文档
更新	需求目录已存在，meta.json 中已有该条目	直接写入/覆盖文档，用 req update --docs add 注册关联
删除	需求目录已存在，需要废弃或清理	使用 req delete 删除条目和目录

---

创建场景（需求首次落盘）

Step C1：确认存储路径

1. 从 .requirements/config 读取 storage_path（默认 .requirements）
2. 确定需求名称（feature），用于目录名生成

Step C2：创建需求目录并注册

使用 req create 命令创建需求目录并写入 meta.json：

req create \
  --feature "{功能名称}" \
  --tags "{逗号分隔标签}" \
  [--depends-on "{REQ-XXX,REQ-YYY}"] \
  [--status {状态}]

参数说明：

参数	必填	说明	示例
--feature	✅	功能名称（中文）	"用户认证模块"
--tags	—	标签，逗号分隔（默认 feat）	feat,security
--depends-on	—	依赖的需求 ID	REQ-001,REQ-002
--status	—	初始状态（默认 草案）	已确认

自动填充：id（自增）、created/updated（当前日期）、version（=1）、changelog（["初始创建"]）、commits（[]）、docs（[]）。

目录名自动生成为 {YYYY-MM-DD}-{feature前20字}/，存储路径为 {storage_path}/{feature_category}/{目录名}/。

meta.json 键名格式：{feature_category}/{目录名}（如 security/2026-06-12-用户认证模块），用于定位需求目录。

Step C3：写入文档

使用 write_to_file 写入 Markdown 文档，顶部必须包含 YAML frontmatter：

---
id: {REQ-NNN}                          # 由 req create 命令自动生成
feature: {功能名称}
status: {状态}                          # 可选值：草案、已确认、设计中、实施中、已完成、已取消
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
version: 1
tags: [{标签}]                          # 标签必须从 .requirements/config 的 requirement_tags 配置中选取
                                       # 必须包含一个功能分类标签（从 feature_categories 配置中选取）
                                       # 常见值：feat, fix, refactor, tool, integration, security, performance, ux, infra
                                       # 创建时自动验证：标签必须来自配置，且必须包含功能分类标签
depends_on: [{依赖 ID}]                 # 依赖的需求 ID 列表
author: AI
document_type: requirement             # 文档类型枚举（见下方文档类型表）
---

文档类型枚举（对应 docs 中的 type 字段）：

document_type	说明
requirement	需求描述文档
data_flow	数据模型与数据流图
design	技术设计文档
interaction	交互设计文档
review	审查/评审报告
demo	验证报告
test	测试相关文档
report	实现总结报告
slice	交付切片（砖头包 + 批次表，delivery-slicing 产出）

内嵌图不单独注册：文档中的 ASCII 图 / 文字树 / 表格等内嵌内容随所属文档落盘即可，不为图新建 document_type、不加 --docs 注册（data_flow 类型仅用于独立的数据模型 / 数据流图文档）。落盘版本中已有的内嵌内容（如界面 ASCII 图）不得省略——精简摘要场景同样适用（压缩文字细节可以，删图不行）；仅当用户明确要求把某张图单独存档时，才另存文件并按独立文档注册。

Step C4：验证创建结果（必须执行）

需求落盘后，必须使用 req 命令检查是否添加成功，不能只看 req create 的输出就认定完成：

req list --id {REQ-NNN}

验证要点：

• 命令退出码为 0，且能查到该需求条目
• id、feature、status、tags 与创建时传入的参数一致
• 需求目录 {storage_path}/{feature_category}/{目录名}/ 已生成，requirement.md 已写入其中

脚本/自动化场景建议用 JSON 输出做机器校验：

req list --id {REQ-NNN} --json

验证失败处理：如果查不到条目或字段不符，说明创建未成功（常见原因：标签不在 requirement_tags 中、缺少功能分类标签、config 未初始化）。根据 req create 的错误信息修正后重新执行，禁止在验证未通过的情况下继续后续步骤或宣告落盘完成。

Step C5：注册文档关联（可选）

如果除 requirement.md 外还写入了其他文档（如 data-flow.md），需要用 req update --docs add 注册：

req update {REQ-NNN} --docs add data-flow.md,data_flow

注册后再次执行 req list --id {REQ-NNN}，确认 docs 字段已包含新增文档。

---

更新场景（需求已存在，追加/覆盖文档）

Step U1：确认需求目录

req list --id {REQ-NNN}

根据输出中的需求目录名拼出完整路径：{storage_path}/{需求目录}/

Step U2：确定文档路径

根据文档类型映射表（见下方），确定目标文件路径。

design、demo、test、review 等子目录如不存在，先创建。

Step U3：写入/更新文档

使用 write_to_file 写入。如果是覆盖已有文档，更新 frontmatter 中的 updated 和 version 字段。如果是新增文档，按创建场景的 frontmatter 模板写入。

Step U4：注册文档关联

废弃字段说明：--data-flow 参数已废弃，请使用 --docs add 替代。

文档落盘后，使用 req update --docs 注册到 meta.json：

添加文档关联：

req update {REQ-NNN} --docs add {相对路径},{类型}

删除文档关联：

req update {REQ-NNN} --docs remove {相对路径}

批量覆盖文档关联：

req update {REQ-NNN} --docs set {路径1},{类型1};{路径2},{类型2}

文档类型映射：

文档	--docs add 参数
需求分析	requirement.md,requirement
技术设计	design/DESIGN.md,design
数据流/模型	design/data-flow.md,data_flow
子需求拆分	sub-requirements/SR-XX-{名称}.md,requirement
交付切片（砖头包）	sub-requirements/{SR-XX}-{名称}/slice.md,slice
交付切片（批次表）	sub-requirements/INDEX.md,slice
集成合流（拼接报告）	sub-requirements/INTEGRATION.md,slice
mock 台账	sub-requirements/MOCK_LEDGER.md,slice
交互设计	design/interaction-design.md,design
设计评审	design/design-review.md,review
Demo 验证	demo/verify-report.md,demo
测试计划	test/test-plan.md,test
测试报告	test/test-report.md,test
代码审查	review/code-review.md,review
质疑审查	review/challenge-report.md,review
实现报告	report.md,report
API 设计	api/INDEX.md,design
API 模块	api/{module}.md,design
场景推演	review/scenario-rehearsal.md,rehearsal
前端集成指南（总览）	frontend-guide/INDEX.md,frontend_guide
前端 API 文档	frontend-guide/api/{module}.md,frontend_guide
前端调用流程	frontend-guide/flow/{scene}.md,frontend_guide

Step U5：更新需求状态（如需要）

需求阶段推进时，同步更新状态和变更记录：

# 评审通过
req update {REQ-NNN} \
  --status 已确认 --changelog "需求评审通过"

# 进入设计（注册设计文档）
req update {REQ-NNN} \
  --status 设计中 --docs add design/DESIGN.md,design --changelog "开始技术设计"

# 开始开发
req update {REQ-NNN} \
  --status 实施中 --commit {git_hash}

# 验收完成
req update {REQ-NNN} \
  --status 已完成 --changelog "功能验收通过"

Step U5.1：管理标签

标签管理支持增删改操作：

# 添加标签
req update {REQ-NNN} --tag add {标签名}

# 删除标签
req update {REQ-NNN} --tag remove {标签名}

# 覆盖标签列表
req update {REQ-NNN} --tag set {标签1},{标签2},{标签3}

约束规则：

• 标签必须从 .requirements/config 的 requirement_tags 配置中选取
• 不能删除最后一个标签
• 必须包含一个功能分类标签（从 feature_categories 配置中选取）
• 功能分类标签唯一性：feature_categories 中的标签只能有一个，不能添加第二个
• 功能分类标签变更限制：功能分类标签创建后不能删除或更改，如需更改分类必须删除并重新创建需求

Step U5.2：更新功能名称

req update {REQ-NNN} --feature "{新功能名称}"

Step U6：追加关联 commit

req update {REQ-NNN} --commit {git_hash}

Step U7：管理依赖关系

# 添加依赖
req update {REQ-NNN} --depends-on add REQ-XXX

# 移除依赖
req update {REQ-NNN} --depends-on remove REQ-XXX

# 覆盖依赖列表
req update {REQ-NNN} --depends-on set REQ-XXX,REQ-YYY

Step U8：验证更新（必须执行）

任何更新操作（状态、文档关联、标签、依赖、commit 等）完成后，必须使用 req 命令检查是否生效：

req list --id {REQ-NNN}

验证要点：

• 状态、标签、依赖与本次更新内容一致
• --docs add 注册的文档出现在 docs 列表中
• version 已递增、changelog 含本次变更记录（如提供了 --changelog）

验证失败处理：字段与预期不符时，根据 req update 的错误信息修正后重试，不得跳过验证直接宣告更新完成。

---

删除场景（需求废弃或清理）

Step D1：预览删除

使用 --dry-run 预览删除操作，确认影响范围：

req delete {REQ-NNN} --dry-run

Step D2：确认删除

交互式确认删除（默认）：

req delete {REQ-NNN}

输出会显示：

• 需求详情（ID、名称、目录、状态）
• 反向依赖（哪些需求依赖了当前需求）
• 警告信息（如果有反向依赖将被清理）

Step D3：自动化删除

在脚本中自动化删除（跳过确认）：

req delete {REQ-NNN} --force

删除操作会：

1. 清理所有反向依赖引用
2. 删除 meta.json 中的条目
3. 删除整个需求目录

---

目录结构

{feature_category}/
└── {date}-{功能名称}/
    ├── requirement.md              # 需求分析报告
    ├── report.md                   # 实现报告
    ├── parent-requirement.md       # 父需求文档（子需求拆分的全局层）
    ├── sub-requirements/           # 需求子需求（.md 文件）+ 交付切片（目录）——见下方命名区分
    │   ├── SR-01-{名称}.md         # 需求子需求（requirement-mining 子需求拆分，单文件）
    │   ├── INDEX.md                # 交付批次表（delivery-slicing）
    │   ├── MOCK_LEDGER.md          # mock 台账（delivery-slicing 建、integration-merge 核销）
    │   ├── INTEGRATION.md          # 拼接报告（integration-merge）
    │   └── SR-01-{名称}/           # 交付砖头包（delivery-slicing，目录，含 6 件套）
    │       ├── slice.md
    │       ├── ownership.md
    │       ├── contract/
    │       ├── out-of-scope.md
    │       ├── verify/
    │       └── handoff.md
    ├── api/
    │   ├── INDEX.md                # API 总览（接口清单+错误码+通用约定）
    │   ├── users.md                # 用户模块 API
    │   └── orders.md               # 订单模块 API
    ├── design/
    │   ├── DESIGN.md               # 技术设计文档
    │   ├── data-flow.md            # 数据流/数据模型
    │   ├── interaction-design.md   # 交互设计
    │   └── design-review.md        # 设计评审报告
    ├── demo/
    │   ├── verify-report.md        # 验证报告
    │   └── [demo 代码文件]
    ├── test/
    │   ├── test-plan.md            # 测试计划
    │   └── test-report.md          # 测试报告
    ├── review/
    │   ├── code-review.md          # 代码审查报告
    │   └── challenge-report.md     # 质疑/二次审查报告
    └── frontend-guide/
        ├── INDEX.md                # 总览
        ├── api/
        │   ├── user-api.md         # 用户模块 API 文档
        │   └── order-api.md        # 订单模块 API 文档
        └── flow/
            ├── user-register.md    # 场景：用户注册调用流程
            └── order-create.md     # 场景：订单创建调用流程

sub-requirements/ 下的命名区分（两者可共存，勿混用）：

• SR-XX-{名称}.md = 需求子需求（requirement-mining 子需求拆分，单文件，用户视角）
• SR-XX-{名称}/ = 交付砖头包（delivery-slicing，目录，代码视角，含 6 件套）
• 两者编号可相同也可不同（砖头与子需求非 1:1）；编号来源分别为各自 skill 的产出，不要假设一一对应

示例：

security/
└── 2026-06-12-用户认证模块/
    ├── requirement.md
    └── design/
        └── DESIGN.md

存储路径映射

文档类型	来源 Skill	存储路径
需求分析	requirement-mining	requirement.md
子需求拆分（父文档）	requirement-mining 子需求拆分	parent-requirement.md
子需求拆分（子需求）	requirement-mining 子需求拆分	sub-requirements/SR-XX-{名称}.md
交付切片（砖头包 + 批次表）	delivery-slicing	sub-requirements/{SR-XX}-{名称}/ + sub-requirements/INDEX.md
技术设计	design-craft	design/DESIGN.md
数据流/模型	data-flow-model	design/data-flow.md
交互设计	interaction-design	design/interaction-design.md
设计评审	design-review	design/design-review.md
Demo 验证	demo-verify	demo/verify-report.md + 代码
测试计划	-	test/test-plan.md
测试报告	-	test/test-report.md
代码审查	code-review	review/code-review.md
质疑审查	challenger	review/challenge-report.md
实现报告	需求完成时	report.md
API 设计（索引）	api-design	api/INDEX.md
API 设计（模块）	api-design	api/{module}.md
场景推演	scenario-rehearsal	review/scenario-rehearsal.md
前端集成指南（总览）	frontend-api-guide	frontend-guide/INDEX.md
前端 API 文档（模块）	frontend-api-guide	frontend-guide/api/{module}.md
前端调用流程（场景）	frontend-api-guide	frontend-guide/flow/{scene}.md

需求生命周期状态流

草案 ──→ 已确认 ──→ 设计中 ──→ 实施中 ──→ 已完成
  │        │         │         │
  └────────┴─────────┴─────────┴──→ 已取消（终态）

状态	含义	典型过渡
草案	初建，尚未评审	create 默认
已确认	评审通过	→ 设计中
设计中	设计文档编写中	→ 实施中
实施中	开发编码	→ 已完成
已完成	验收通过	终态
已取消	废弃保留	终态

查询功能

使用 req list 进行需求查询和依赖分析：

基本查询

# 列出所有需求
req list

# 精确查询需求详情
req list --id {REQ-NNN}

# JSON 格式输出（适合脚本消费）
req list --json

筛选查询

# 按状态筛选
req list --status {状态}

# 按标签筛选（可重复，AND 关系）
req list --tag {标签1} --tag {标签2}

# 按功能分类筛选
req list --category {feature_category}

# 按日期范围筛选
req list --from {YYYY-MM-DD} --to {YYYY-MM-DD}

# 模糊搜索功能名称
req list --search "{关键词}"

依赖分析

# 展示依赖树
req list --id {REQ-NNN} --deps

# 展示依赖树（指定深度）
req list --id {REQ-NNN} --deps --deps-depth 3

# 查看反向依赖（谁依赖了我）
req list --id {REQ-NNN} --rev-deps

输出控制

# 自定义显示列
req list --columns id,feature,status,tags

# 禁用颜色
req list --no-color

行为边界

• 命令操作元数据：frontmatter 和 meta.json 必须通过 req 命令操作，禁止手动拼接路径写入
• 不创建需求目录：需求目录由 req create 命令创建
• 只处理已存在的需求：必须有对应的 meta.json 条目
• 持久化后验证：任何创建或更新操作后，必须用 req list --id {REQ-NNN} 检查是否添加/更新成功（条目存在、字段与预期一致）；验证失败时必须修正重试，禁止未验证通过就宣告落盘完成

参考

• 需求管理系统完整指南：docs/requirement-mgr-guide.md
• 命令参考：docs/command-reference.md
• 配置指南：docs/configuration.md

集成 skill 清单

以下 skill 已集成需求管理，在落盘阶段自动调用 req 命令更新 meta.json：

Skill	优先级	集成类型	产出文档路径
design-craft	P0	写入型	design/DESIGN.md + 子文档
data-flow-model	P0	写入型	design/data-flow.md
implementation-report	P0	写入型	report.md
work-breakdown	P1	写入型	design/work-breakdown.md
delivery-slicing	P1	写入型	sub-requirements/{SR-XX}-{名称}/ + sub-requirements/INDEX.md
integration-merge	P1	写入型	sub-requirements/INTEGRATION.md
interaction-design	P1	写入型	design/interaction-design.md
design-review	P1	读写型	design/design-review.md
code-change-impact	P1	读写型	review/code-change-impact.md
code-review	P2	读写型	review/code-review.md
challenger	P2	读写型	review/challenge-report.md
demo-verify	P2	写入型	demo/verify-report.md + 代码
review-panel	P2	读写型	review/review-panel.md
api-design	P1	写入型	api/INDEX.md + api/{module}.md
scenario-rehearsal	P1	读写型	review/scenario-rehearsal.md
frontend-api-guide	P1	写入型	frontend-guide/INDEX.md + frontend-guide/api/{module}.md + frontend-guide/flow/{scene}.md

写入型：skill 产出文档后自动调用 req update --docs add 注册并更新状态。 读写型：skill 执行前自动调用 req list 获取需求上下文作为参照，完成后写入报告。