# Dwf Requirement

> 当用户需要把想法、需求说明、产品需求、项目背景、Markdown、纯文本或本地文档整理成 DWF 工作流风格的需求文档时，必须使用本技能。它负责收集和澄清需求，按 references/requirements_template.md 生成目标 spec 目录下 `01-需求/需求文档.md`，并请求用户确认。适用于“生成需求文档”“整理 PRD”“先写需求文档”“把需求规范化”“抽离需求阶段”等场景。可独立运行，也可作为 dwf-orchestrator 编排的工作流的一部分（state.json 中存在 `status: active` 且 `current_step: requirements` 的 spec 时进入工作流模式）。

- Skill: `xiao0916/dwf-requirement` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add xiao0916/dwf-requirement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiao0916/dwf-requirement/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: xiao0916 (https://skillmd.com/u/xiao0916)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiao0916/dwf-requirement

---


# dwf-requirement

本技能用于把零散需求整理成 DWF 工作流的需求文档。它只负责需求捕获与需求文档生成；独立运行时不启动完整开发工作流，工作流模式下按 `.dwf/state.json` 继续当前阶段。

<HARD-GATE>
以下规则不可违反：

1. **只生成需求文档。**
   本技能默认只创建或更新目标 spec 目录下 `01-需求/需求文档.md`。不创建其它阶段文档或代码。

2. **目标 spec 目录由运行模式决定，不由本技能臆造。**
   - 工作流模式：读取 `.dwf/state.json`，在 `specs` 数组中找 `status: "active"` 且 `current_step: "requirements"` 的 spec，以 `.dwf/specs/{spec.name}` 作为目标 spec 目录。
   - 独立模式：`.dwf/state.json` 不存在或不存在满足条件的 active spec。用 `question` 询问用户目标目录，默认提议 `.dwf/specs/{今日日期}-{seq}-feat-{从用户输入提取的描述}`，其中 `seq` 扫描 `.dwf/specs/` 现有 spec 目录名中的最大序号 +1（无则 001），由用户确认或修改。

3. **独立模式下不要创建或推进 `.dwf/state.json`。**
   独立模式只写目标 spec 目录下的需求文档与该 spec 的 `_meta.json`（如该 spec 目录为本技能创建）。不要把项目推进到 design、breakdown、plans、todos 或 code。只有工作流模式下才在用户确认后更新 state.json 中该 spec 的 `current_step`。

4. **不要创建完整工作流目录。**
   除目标 spec 目录下的 `01-需求/` 外，不要主动创建 `02-设计稿/`、`03-需求分析/`、`04-技术方案/`、`05-实现清单/`。项目代码目录由用户/dwf-coding 决定，本技能不创建。

5. **确认前不要覆盖已有文档。**
   如果目标 spec 目录下 `01-需求/需求文档.md` 已存在，先读取并告知用户已有文档，询问是保留、修改还是替换。用户确认前不要覆盖。

6. **全程使用中文。**
   除非用户明确要求使用其他语言，所有与用户的交互、需求澄清问题、生成文档、标题、标签、表格内容、说明文字、测试记录和产物说明都必须使用中文。代码、文件路径、命令、API 名、技术术语、第三方库名和用户提供的原文内容可以保留英文。

</HARD-GATE>

## 触发后流程

### 1. 探查上下文

- 检查 `.dwf/state.json` 是否存在，确定运行模式（见步骤 2）。
- 判断用户输入来源：长文本、本地文件路径、外部链接、简短想法或口头描述。
- 如果用户提供本地文件路径，读取文件内容后整理为需求依据。
- 如果用户提供外部文档链接，根据链接类型使用相应技能读取。例如飞书文档使用 `lark-doc`，网页文档使用 `web-access`。
- 如果用户只给出简短想法，先澄清会影响需求结构和验收标准的最少信息。

### 2. 判断运行模式与目标 spec 目录

读取 `.dwf/state.json`：

- **工作流模式**：在 `specs` 数组中找到 `status: "active"` 且 `current_step: "requirements"` 的 spec。目标 spec 目录为 `.dwf/specs/{spec.name}/`。
  - 如该目录下 `01-需求/需求文档.md` 已存在，先读取并按“已有文档处理”执行。
  - 需求文档完成并经用户确认后，把该 spec 的 `current_step` 更新为 `"design"`、把 `requirements` 追加到 `confirmed_stages`，并同步其 `_meta.json` 与顶层 `updated_at`。
  - 遵循 dwf-orchestrator 的确认机制，不跳过用户确认。

- **独立模式**：`.dwf/state.json` 不存在，或不存在满足条件的 active spec。
  - 用 `question` 询问用户目标 spec 目录，默认提议 `.dwf/specs/{今日日期}-{seq}-feat-{描述}`（描述从用户输入提取，`seq` 扫描 `.dwf/specs/` 现有 spec 目录名中的最大序号 +1，无则 001），由用户确认或修改。如用户选择别的目录，以用户输入为准。
  - 如目标 spec 目录不存在，创建它及其下 `01-需求/`。
  - 在该 spec 目录下写一份初始 `_meta.json`（`name` 为目录名、`status: "active"`、`current_step: "requirements"`、`is_shared_context: false`、`shared_ref: null` 等）。
  - 不要创建 `.dwf/state.json`，不推进完整工作流。
  - 需求文档完成后请求用户确认，确认后停止。

### 3. 判断输入来源

根据用户提供的信息选择处理方式：

- **完整需求文档或长文本：** 直接提取项目名称、背景、目标、用户角色、范围、功能需求、非功能需求、约束、依赖、风险和验收标准。
- **本地文件路径：** 读取文件内容后整理为需求文档。
- **外部文档链接：** 根据链接类型使用相应技能读取。例如飞书文档使用 `lark-doc`，网页文档使用 `web-access`。
- **简短想法或口头描述：** 先澄清需求，不要急于生成文档。

### 4. 澄清缺失信息

如果信息不足，按“一次一个问题”的方式追问。优先澄清会影响文档结构和验收标准的内容：

1. 项目名称或一句话概述。
2. 背景与业务价值。
3. 目标用户与角色。
4. 目标端：PC 端、移动端或双端。
5. 范围内和范围外内容。
6. 核心用例和主流程。
7. 功能性需求与优先级。
8. 非功能性需求。
9. 约束、假设、依赖与风险。
10. 整体验收标准。

不要一次抛出大量问题。若可以基于上下文合理假设，先明确写入“假设”，并把不确定项放入“待确认事项”。

### 5. 生成需求文档

读取 `references/requirements_template.md`，按模板生成中文需求文档。保存到目标 spec 目录下：

```text
{目标 spec 目录}/01-需求/需求文档.md
```

生成规则：

- 保留 YAML frontmatter，包括 `project`、`version`、`author`、`date`、`status` 和 `revision`。
- 新文档的 `status` 默认为 `draft`。
- `date` 使用当前日期。
- `version` 初始为 `1.0.0`。
- `revision` 记录“初始版本”。
- 文档必须包含业务流程图，使用 Mermaid 表达主流程；如果信息不足，生成合理的高层流程，并在“待确认事项”中标注需要确认的分支。
- 功能性需求使用 `FR-1`、`FR-2` 编号。
- 非功能性需求使用 `NFR-1`、`NFR-2` 编号。
- 优先级使用 MoSCoW：必须、应该、可以、不会。
- 验收条件必须可观察或可测试。

### 6. 请求用户确认

生成文档后，向用户展示保存位置和简要摘要，并请求确认：

- 如果用户确认，说明需求文档已完成。
- 如果用户提出修改意见，直接更新目标 spec 目录下 `01-需求/需求文档.md`，保持 `status: draft`，并再次请求确认。
- 如果用户明确要求标记为已确认，将 frontmatter 中的 `status` 改为 `confirmed`，并在 `revision` 中追加确认记录。

确认完成后：

- 独立模式：停止，不自动进入设计稿、需求分析、技术方案、实现清单或编码。
- 工作流模式：更新该 spec 的 `current_step` 为 `"design"`、把 `requirements` 追加到 `confirmed_stages`，同步 `_meta.json` 与 `updated_at`，由 dwf-orchestrator 推进。

## 已有文档处理

如果目标文件已存在：

1. 读取 `{目标 spec 目录}/01-需求/需求文档.md`。
2. 总结当前文档的项目名称、版本、状态和主要内容。
3. 询问用户要如何处理：
   - 保留现有文档，仅查看或总结。
   - 基于现有文档修改。
   - 替换为新需求文档。
4. 只有用户明确选择修改或替换后，才能写入文件。

修改已有文档时：

- 保留原有结构，除非用户要求重写。
- 更新 `date`。
- 如用户确认这是新版本，递增 `version` 并追加 `revision` 条目。
- 不要创建 `需求文档-v2.md` 之类的新版本文件，除非用户明确要求。

## 完成前检查

结束前确认：

- 只创建或更新了目标 spec 目录下 `01-需求/需求文档.md`。
- 独立模式下没有创建 `.dwf/state.json`。
- 独立模式下没有创建除目标 spec 目录 `01-需求/` 外的其它阶段目录。
- 独立模式下没有推进后续阶段。
- 工作流模式下只在用户确认后更新该 spec 的 `current_step` 为 `design`。
- 文档内容为中文。
- 文档包含 frontmatter。
- 文档包含背景、目标、用户角色、范围、用例、功能性需求、非功能性需求、约束、依赖、风险、验收标准和待确认事项。
- 已说明保存路径和下一步需要用户确认的事项。