# Dev Workflow

> 结构化开发工作流，强制按步骤执行：需求文档 → 设计稿 → 需求拆解 → 技术方案（提供多个方案供用户选择）→ 实现清单 → 编码 → 需求迭代。当用户想要启动新项目、构建功能、实现需求，或需要系统化的开发流程时使用此技能。即使用户没有明确说'工作流'，只要用户表达了从零开始开发一个功能或系统的意图并希望按步骤系统化推进，就应使用此技能。触发短语包括'开始项目'、'实现这个功能'、'帮我构建'、'我需要一个工作流'、'开发这个'、'需求拆解'、'给几个技术方案选'。用户提供需求文档（飞书、markdown、纯文本）并希望转为系统化开发时也应触发。

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

---


<HARD-GATE>
本技能通过 `.dwf/state.json` 追踪严格的分阶段工作流。以下规则不可违反：

1. **禁止未经确认的自动推进。** 每个阶段转换都必须使用 `question` 工具获取用户明确确认，不得仅用纯文本询问。如果用户没有选择确认选项或明确回复确认，不得进入下一阶段。

2. **禁止直接修改代码。** 当 `current_step` 为 `code` 或 `done` 时，任何对 `06-code/` 目录或项目代码的修改都必须走迭代流程，无一例外。这包括：bug 修复、小幅调整、文案修改、配置变更——无论多小。

3. **禁止跳过阶段。** 用户说"直接写代码"或"这只是个小 bug"不是跳过流程的理由。正确做法是引导用户进入迭代流程。

4. **每次调用必须先读 state.json。** 在生成任何内容或执行任何动作之前，首先读取 `.dwf/state.json` 以确定当前所处阶段。然后严格按照该阶段的要求行动。

5. **全程使用中文。** 所有与用户的交互（包括 `question` 工具的选项和标题）、所有生成的文档（需求文档、设计稿、需求拆解文档、技术方案、实现清单）、以及文档中的标题/标签/说明，必须使用中文。仅代码、文件路径、技术术语（如 React、Vue、API）等本身无法翻译的内容可以使用英文。

违反以上任何一条都是对工作流的破坏。
</HARD-GATE>

# dev-workflow 工作流

一个严格按顺序执行的工作流，将需求逐步转化为可交付的代码。每个阶段必须完成并经用户确认后才能进入下一阶段。

## 核心原则

**任何阶段在上一个阶段经用户确认之前都不能开始。** 这是不可协商的。如果用户试图跳过，请引导他们回到当前未确认的阶段。

## 编程规范与模板

编码相关阶段必须读取并遵循 `references/coding_standards.md`。该文件是本技能输出规范代码的统一来源，覆盖执行前分析、代码风格、React 前端约定、任务执行和验证要求。

当项目从零创建且技术方案选择 React 前端时，优先使用 `assets/` 中的模板作为 `06-code/` 的基础：

| 目标端 | 模板目录 | 用途 |
|------|------|------|
| PC 端 | `assets/react-pc/` | React PC 项目模板 |
| 移动端 | `assets/react-mobile/` | React Mobile 项目模板 |
| 通用能力 | `assets/shared/` | 可复用配置、类型、hooks、utils、请求封装等 |

使用模板时，只复制与选定端和技术方案匹配的源码与配置；不要复制无关端模板，不要把 `dist/` 构建产物当作后续开发源码，除非用户明确要求。

## 确认机制

每个需要用户确认的步骤，必须使用 `question` 工具进行交互，不得仅用纯文本询问。`question` 工具提供结构化的选项，确保用户明确做出决策。

所有 `question` 调用默认启用自定义输入（`custom: true`），用户可以在选项之外输入自由文本。各场景的标准问题格式详见 `references/question_templates.md`，包含以下场景：

| 场景 | 用途 |
|------|------|
| 阶段文档确认 | 各阶段文档的审阅确认 |
| 设计稿方式选择 | 阶段 2 选择设计稿获取方式 |
| 技术方案选择确认 | 阶段 4 在多个技术方案中选定其一 |
| 迭代命名确认 | 迭代步骤 1 确认迭代名称 |
| 迭代影响范围确认 | 迭代步骤 1 确认受影响的阶段列表 |
| 工作流完成 | 工作流完成后的后续操作 |
| 新项目风险确认 | 用户选择"启动新项目"后的二次风险告知与确认 |

> **重要：** 如果用户选择"启动新项目"，**不得立即执行**。必须先进行二次风险告知与确认（参照 `references/question_templates.md` → 新项目风险确认），只有用户在二次确认中明确选择"确认删除并重启"后，才执行「重新开始」流程。

## 状态追踪

工作流在 `.dwf/state.json` 中追踪其状态。每次调用时首先读取此文件，以确定用户当前所处的阶段。

状态值及其含义：

| 状态 | 含义 |
|---|---|
| `init` | 工作区尚未初始化（瞬态，不持久化；状态文件一旦写入即为 `requirements`） |
| `requirements` | 需求文档已生成，等待用户确认 |
| `design` | 设计稿已收集/生成/记录，等待用户确认（可跳过） |
| `breakdown` | 需求拆解文档已生成，等待用户确认 |
| `plans` | 技术方案已生成（≥2 个），等待用户选择并确认 |
| `todos` | 实现清单已生成，等待用户确认 |
| `code` | 准备执行实现清单，正在编码 |
| `done` | 所有任务已完成 |
| `iteration` | 处于迭代模式，检查 iteration 子对象获取详细阶段进度 |

**如果 `.dwf/state.json` 不存在**，说明工作流尚未启动，从阶段 1 开始。

### state.json 结构

```json
{
  "current_step": "requirements",
  "project_name": "项目名称",
  "iteration_count": 0,
  "design_skipped": false,
  "selected_plan": null,
  "created_at": "2026-06-24T10:00:00",
  "updated_at": "2026-06-24T10:00:00"
}
```

### 迭代状态结构

当工作流进入迭代模式时，`state.json` 会新增 `iteration` 子对象：

```json
{
  "current_step": "iteration",
  "project_name": "项目名称",
  "iteration_count": 0,
  "design_skipped": false,
  "selected_plan": "方案A",
  "iteration": {
    "name": "bugfix-修复样式问题",
    "dir": "07-需求迭代/2026-06-24-bugfix-修复样式问题",
    "affected_stages": ["requirements", "todos"],
    "current_substep": "requirements",
    "confirmed_stages": []
  },
  "created_at": "2026-06-24T10:00:00",
  "updated_at": "2026-06-25T14:30:00"
}
```

- `iteration.name` 为迭代名称，格式 `{type}-{描述}`，在进入迭代时由 AI 提议、用户确认。
- `iteration.dir` 为迭代文档的保存目录，相对于工作区根目录，格式 `07-需求迭代/{date}-{type}-{描述}`。
- `iteration.affected_stages` 为本次迭代需要更新的阶段列表，按阶段顺序排列。由 AI 分析并提出，用户确认或调整。
- `iteration.current_substep` 为当前正在处理的阶段，每完成一个阶段的确认后推进到下一个受影响阶段。
- `iteration.confirmed_stages` 为已确认的阶段列表，确认后追加，用于断点恢复。

通用字段说明：

- `project_name` 为项目名称，在初始化时由用户提供或从需求文档中提取。
- `iteration_count` 记录已完成的迭代次数，首次迭代进行中为 0，完成后递增。
- `design_skipped` 标记设计稿阶段是否被跳过。
- `selected_plan` 记录用户在技术方案阶段选定的方案（如 `"方案A"`），迭代时不重置。
- `created_at` 为工作流首次创建时间，`updated_at` 为最近一次状态变更时间。
- 写入 `state.json` 时务必更新 `updated_at` 为当前时间。

## 目录结构

文档目录存储在工作区根目录下，状态追踪文件存储在 `.dwf/` 中：

```
工作区根目录/
├── .dwf/
│   └── state.json                              # 当前阶段状态
├── 01-需求文档/
│   └── 需求文档.md                              # 需求文档
├── 02-设计稿/
│   ├── 设计稿.md                                # 设计稿说明（含链接等）
│   └── images/                                  # 设计稿图片
├── 03-需求拆解文档/
│   └── 需求拆解文档.md                          # 需求拆解文档
├── 04-技术方案/
│   └── 技术方案.md                              # 技术方案（含多个并列方案）
├── 05-实现清单/
│   └── 实现清单.md                              # 实现清单
├── 06-code/                                     # 实际项目代码
│   └── ...
└── 07-需求迭代/
    └── 2026-06-24-bugfix-修复样式问题/          # 迭代目录（date-type-描述）
        ├── 需求文档/                             (受影响时才包含)
        ├── 设计稿/                               (受影响时才包含)
        ├── 需求拆解文档/                         (受影响时才包含)
        ├── 技术方案/                             (受影响时才包含)
        └── 实现清单/                             (受影响时才包含)
```

## 阶段

### 阶段 0：自检（每次调用必执行）

1. 读取 `.dwf/state.json`（如存在）。
2. 根据 `current_step` 确定当前阶段。
3. 如果用户请求涉及代码修改且 `current_step` 为 `code` 或 `done`，必须告知用户将进入迭代流程，不得直接修改代码。
4. 按照当前阶段的要求行动，不得跳过。

### 阶段 1：初始化 & 捕获需求

**进入条件：** `state.json` 不存在，或状态为 `init`。

1. 创建 `.dwf/` 目录及 `state.json`，并在工作区根目录创建文档子目录：`01-需求文档/`、`02-设计稿/`、`02-设计稿/images/`、`03-需求拆解文档/`、`04-技术方案/`、`05-实现清单/`、`06-code/`、`07-需求迭代/`。
2. 写入 `.dwf/state.json`，内容为：
   ```json
   {
     "current_step": "requirements",
     "project_name": "<项目名称>",
     "iteration_count": 0,
     "design_skipped": false,
     "selected_plan": null,
     "created_at": "<当前时间>",
     "updated_at": "<当前时间>"
   }
   ```
3. 根据用户输入判断需求获取方式：
   - **用户提供完善的需求文档**（markdown / 飞书文档 / Google docs / 纯文本 / 图片）：
     - 读取并提取需求内容。飞书文档 URL 使用 `lark-doc` 技能读取；网页文档使用 `web-access` 技能读取；本地文件直接读取。
     - 按 `references/requirements_template.md` 模板归一化为需求文档。
   - **用户提供大概的需求说明：**
      - 提出澄清性问题，**一次一个问题**（优先多选），多轮迭代直到理解：要构建什么（目标、范围、边界）、为什么做（背景与业务价值）、谁是用户/角色、目标端、关键约束与假设、依赖与风险、验收标准。
      > 编码准则：遵循 karpathy-guidelines「Think Before Coding」——显式陈述假设，不确定时发问，不隐藏困惑。
      - 按 `references/requirements_template.md` 模板生成需求文档。
4. 保存到 `01-需求文档/需求文档.md`。
5. 使用 `question` 工具向用户展示文档并请求确认（参照 `references/question_templates.md` → 阶段文档确认）。
6. **等待用户确认。** 在用户明确确认之前，不要进入阶段 2。
   - 如果用户选择"需要修改"或输入修改意见：直接修改 `01-需求文档/需求文档.md`，更新 `updated_at`，并再次使用 `question` 工具请求确认。
   - 只有在用户选择"确认"后：更新 `.dwf/state.json` 的 `current_step` 为 `"design"` 和 `updated_at`，然后推进。

### 阶段 2：设计稿

**进入条件：** `state.json` 存在且 `current_step` 为 `design`。

1. 使用 `question` 工具向用户收集设计稿信息（参照「确认机制 → 设计稿方式选择」格式）。
2. 根据用户回复处理：
   - **用户提供链接或图片：**
     - 将链接记录到 `设计稿.md` 中；如为图片，保存到 `02-设计稿/images/` 目录。
     - 如为 Figma 等在线设计稿链接，尝试下载截图保存到 `images/`；若下载失败，仅记录链接并告知用户。
     - 按照 `references/design_template.md` 中的模板生成设计稿说明文档，保存到 `02-设计稿/设计稿.md`。
   - **用户选择由 AI 生成：**
     - 读取 `01-需求文档/需求文档.md`，结合用户的设计思路生成设计方案。
     - 分析项目类型（PC 端 / 移动端 / 双端），确定设计维度和规范。
     - 按照 `references/design_template.md` 中的模板生成设计文档，包含：整体布局和页面结构说明、关键页面的设计描述（布局、配色、字号、间距等视觉规范）、交互说明、设计规范（颜色体系、字体体系、间距体系、组件规范）。
     - 生成设计稿图片（PNG）保存到 `02-设计稿/images/` 目录（机制：渲染 HTML/CSS mockup 为 PNG；如不适用则使用 `nanobanana-skill` 生成）。
     - 保存设计文档到 `02-设计稿/设计稿.md`。
     - 更新 `state.json` 的 `design_skipped` 为 `false`。
   - **用户选择跳过：**
     - 在 `02-设计稿/设计稿.md` 中记录"设计稿阶段已跳过"。
     - 更新 `state.json` 的 `design_skipped` 为 `true`。
3. 使用 `question` 工具向用户展示结果并请求确认（参照 `references/question_templates.md` → 阶段文档确认）。
4. **等待用户确认。**
   - 如果用户选择"需要修改"或输入修改意见：修改后再次使用 `question` 工具请求确认。
   - 只有在用户选择"确认"后：更新 `.dwf/state.json` 的 `current_step` 为 `"breakdown"` 和 `updated_at`，然后推进。

### 阶段 3：需求拆解文档

**进入条件：** `state.json` 存在且 `current_step` 为 `breakdown`。

1. 读取 `01-需求文档/需求文档.md`；若 `design_skipped` 为 false，同时读取 `02-设计稿/设计稿.md`。
2. 结合需求文档和设计稿进行功能拆解，按照 `references/breakdown_template.md` 中的模板生成文档，覆盖：
   - **目标端：** PC 端 / 移动端 / 双端。
   - **页面与功能拆解：** 按页面分别列出每个页面的端、依赖与功能模块；跨页面共享模块单独归类。
   - **素材/依赖清单：** 需要用户提供哪些素材（如 API 密钥、账号、第三方服务凭证、图片素材等）。
   - **范围边界：** 明确不在本次实现内的部分。
3. 保存到 `03-需求拆解文档/需求拆解文档.md`。
4. 使用 `question` 工具向用户展示文档并请求确认（参照 `references/question_templates.md` → 阶段文档确认）。
5. **等待用户确认。**
   - 如果用户选择"需要修改"或输入修改意见：直接修改 `03-需求拆解文档/需求拆解文档.md`，更新 `updated_at`，并再次使用 `question` 工具请求确认。
   - 只有在用户选择"确认"后：更新 `.dwf/state.json` 的 `current_step` 为 `"plans"` 和 `updated_at`，然后推进。

### 阶段 4：生成技术方案

**进入条件：** `state.json` 存在且 `current_step` 为 `plans`。

1. 读取 `01-需求文档/需求文档.md` 和 `03-需求拆解文档/需求拆解文档.md`；若 `design_skipped` 为 false，同时读取 `02-设计稿/设计稿.md`。
2. 分析代码库（如果存在），了解当前架构、约定和模式。
3. 读取 `references/coding_standards.md`，并在方案中说明编码规范、验证策略和模板使用方式；如果是从零创建 React 前端项目，至少一个方案应优先基于 `assets/react-pc/` 或 `assets/react-mobile/` 模板。
4. 按照 `references/plans_template.md` 中的模板生成技术方案，**必须提供至少 2 个并列方案**。每个方案包括：
   - 框架/技术栈选型及其理由
   - 需要的第三方库
   - 后端接口需求（需要后端提供哪些接口、接口字段定义）
   - 数据模型变更
   - 受影响的文件和模块
   - 编程规范与模板使用说明
   - 风险评估和缓解策略
   - 优劣对比
5. 在 `04-技术方案/技术方案.md` 中包含所有方案及方案对比表，更新 `updated_at`。
6. 使用 `question` 工具向用户展示方案并请求选择（参照「确认机制 → 技术方案选择确认」格式，按实际方案数量追加选项）。
7. **等待用户选择。**
   - 如果用户选择"需要修改"或输入修改意见：直接修改 `04-技术方案/技术方案.md`，更新 `updated_at`，并再次使用 `question` 工具请求确认。
   - 只有在用户选择某个方案后：在 `.dwf/state.json` 的 `selected_plan` 记录所选方案（如 `"方案A"`），更新 `current_step` 为 `"todos"` 和 `updated_at`，然后推进。

### 阶段 5：生成实现清单

**进入条件：** `state.json` 存在且 `current_step` 为 `todos`。

1. 同时读取 `01-需求文档/需求文档.md`、`03-需求拆解文档/需求拆解文档.md` 和 `04-技术方案/技术方案.md`（以 `selected_plan` 指定的方案为主）。
2. 读取 `references/coding_standards.md`，将其中的编码规范、模板使用和验证要求转化为实现清单中的执行约束。
3. 将选定方案分解为具体的、有序的任务，遵循 `references/todos_template.md` 中的模板。任务要求：
   - **尽可能拆分，不要一次性实现某个功能或页面**（例如一个页面应拆为骨架、组件A、组件B、状态接入、接口联调、样式等独立任务）。
   - 足够具体，可以无歧义地执行。
   - 按依赖关系排序（前面的任务为后面的任务解除阻塞）。
   - 分配优先级（必须/应该/可以/不会，MoSCoW）。
   - 每个任务都必须包含“编码规范检查”和“验证标准”，确保 coding 阶段能逐项核对。
4. 保存到 `05-实现清单/实现清单.md`，更新 `updated_at`。
5. 使用 `question` 工具向用户展示实现清单并请求确认（参照 `references/question_templates.md` → 阶段文档确认）。
6. **等待用户确认。**
   - 如果用户选择"需要修改"或输入修改意见：直接修改 `05-实现清单/实现清单.md`，更新 `updated_at`，并再次使用 `question` 工具请求确认。
   - 只有在用户选择"确认"后：更新 `.dwf/state.json` 的 `current_step` 为 `"code"` 和 `updated_at`，然后推进。

### 阶段 6：编码执行

**进入条件：** `state.json` 存在且 `current_step` 为 `code`。

1. 读取 `05-实现清单/实现清单.md` 和 `04-技术方案/技术方案.md`（以 `selected_plan` 指定的方案为主）。
2. 读取 `references/coding_standards.md`。如果 `06-code/` 尚无项目代码且选定方案基于 React 模板，先按目标端使用 `assets/react-pc/` 或 `assets/react-mobile/` 初始化代码，并按需合并 `assets/shared/`。
3. 在 `06-code/` 目录下按顺序逐个执行任务。每完成一个任务，按实现清单中的“编码规范检查”和“验证标准”核对，再在 `05-实现清单/实现清单.md` 中将其标记为已完成。
4. 如果某个任务暴露了使方案或需求失效的问题，暂停执行并通知用户。不要悄然偏离。
5. 所有任务完成后，写入 `.dwf/state.json` 为 `{"current_step": "done", ...}` 并更新 `updated_at`。
6. 总结所做的工作以及任何后续事项，并使用「确认机制 → 工作流完成」格式向用户询问后续操作。

## 迭代机制

### 触发条件

以下任一情况出现时，必须进入迭代流程：

- 用户提出新功能需求
- 用户报告 bug 或请求 bug 修复
- 用户请求对现有代码做任何修改（包括配置调整、文案修改、样式微调等）
- 用户提出性能优化、重构等改进需求
- 用户请求对现有功能做任何增删改

**无论修改大小，都必须走迭代。一行代码的修改也必须经过迭代确认。**

### 迭代命名

迭代目录命名为 `{date}-{type}-{描述}`，例如 `2026-06-24-bugfix-修复样式问题`。`type` 采用 conventional-commit 风格前缀：`feat`（新功能）、`bugfix`（修复）、`refactor`（重构）、`perf`（性能）、`style`（样式）、`docs`（文档）、`chore`（杂项）。AI 根据用户描述提议格式化名称，用户确认。

### 迭代流程

迭代流程与初始流程一样，遵循严格的逐步确认原则。每个受影响阶段的文档必须逐一经过用户确认后，才能进入下一个阶段。

#### 迭代步骤 1：初始化 & 影响分析

1. 根据用户描述提议迭代名称（`{type}-{描述}`），使用 `question` 工具请用户确认名称。
2. 创建 `07-需求迭代/{date}-{type}-{描述}/` 目录。
3. 分析变更影响了哪些阶段，提出受影响阶段列表。阶段按以下顺序排列：
   - `requirements` → `design` → `breakdown` → `plans` → `todos`
   - 仅包含受影响的阶段；如果 `design_skipped` 为 true，则自动排除 `design`。
4. 使用 `question` 工具向用户确认受影响阶段（参照「确认机制 → 迭代影响范围确认」格式）。
5. **等待用户确认。** 用户可以增删阶段。
   - 如果用户选择"需要调整"或输入调整意见：根据反馈调整 `affected_stages` 列表，再次使用 `question` 工具请求确认。
   - 用户确认后：更新 `.dwf/state.json`：
     ```json
     {
       "current_step": "iteration",
       "project_name": "<项目名称>",
       "iteration_count": <当前值>,
       "design_skipped": <当前值>,
       "selected_plan": <当前值>,
       "iteration": {
         "name": "<type>-<描述>",
         "dir": "07-需求迭代/<date>-<type>-<描述>",
         "affected_stages": ["<阶段1>", "<阶段2>", ...],
         "current_substep": "<第一个受影响阶段>",
         "confirmed_stages": []
       },
       "created_at": "<保持不变>",
       "updated_at": "<当前时间>"
     }
     ```

#### 迭代步骤 2-N：逐步确认受影响阶段

对于 `affected_stages` 中的每个阶段，**严格按照列表顺序**，逐一执行（若 `affected_stages` 为空，跳过本步骤，直接进入迭代最终步骤）：

1. 根据当前 `iteration.current_substep`，读取已确认阶段和初始流程阶段文档作为上下文，生成该阶段的迭代文档。
2. 按照 `references/` 中对应模板生成文档，保存在 `{iteration.dir}/{阶段子目录}/{文件名}` 下（阶段子目录映射见下表）。
3. 使用 `question` 工具向用户展示迭代文档并请求确认（参照「确认机制 → 阶段文档确认」格式，header 为"迭代文档审阅"）。技术方案阶段同样需提供 ≥2 个方案供用户选择。
4. **等待用户确认。**
   - 如果用户选择"需要修改"或输入修改意见：直接修改对应文档，更新 `updated_at`，并再次使用 `question` 工具请求确认。
   - 用户确认后：
     - 将该阶段添加到 `iteration.confirmed_stages`。
     - 如果该阶段为 `plans`，将用户选定的方案写入 `state.json` 的 `selected_plan`。
     - 推进 `iteration.current_substep` 到 `affected_stages` 中的下一个阶段。
     - 更新 `updated_at`。
     - 如果还有下一个受影响阶段，回到步骤 1 继续处理。
     - 如果所有受影响阶段已确认，进入迭代最终步骤。

#### 迭代最终步骤：实施变更

1. 所有受影响阶段的文档已确认。
2. 读取 `references/coding_standards.md`。
3. 读取本次迭代已确认的 `技术方案/` 与 `实现清单/`（位于 `iteration.dir` 下，若该阶段受影响）作为实施依据；未受影响的阶段沿用主目录（`04-技术方案/`、`05-实现清单/`）文档。在 `06-code/` 中实施变更。迭代实施必须只改本次确认的受影响范围，不顺手改进无关代码。
4. 完成后，更新 `.dwf/state.json`：
   - 递增 `iteration_count`。
   - 清除 `iteration` 子对象。
   - 将 `current_step` 设回 `"code"`。
   - 更新 `updated_at`。
4. 总结迭代所做的变更及后续事项。

### 阶段到迭代子目录的映射

| 阶段 | 迭代子目录 | 模板 | 文件名 |
|------|------|------|--------|
| `requirements` | `需求文档/` | `requirements_template.md` | `需求文档.md` |
| `design` | `设计稿/` | `design_template.md` | `设计稿.md` |
| `breakdown` | `需求拆解文档/` | `breakdown_template.md` | `需求拆解文档.md` |
| `plans` | `技术方案/` | `plans_template.md` | `技术方案.md` |
| `todos` | `实现清单/` | `todos_template.md` | `实现清单.md` |

### 迭代目录示例

```
07-需求迭代/
├── 2026-06-24-bugfix-修复样式问题/
│   ├── 需求文档/
│   │   └── 需求文档.md
│   └── 实现清单/
│       └── 实现清单.md
└── 2026-06-25-feat-新增下载按钮/
    ├── 需求文档/
    │   └── 需求文档.md
    ├── 需求拆解文档/
    │   └── 需求拆解文档.md
    ├── 技术方案/
    │   └── 技术方案.md
    └── 实现清单/
        └── 实现清单.md
```

## 恢复

当技能被触发且 `.dwf/state.json` 已存在时，首先执行阶段 0 自检，然后读取状态并从相应阶段恢复。不要重新初始化或重启工作流。

- 如果状态为 `requirements`，展示需求文档，使用 `question` 工具请求确认。
- 如果状态为 `design`，展示设计稿信息，使用 `question` 工具请求确认。
- 如果状态为 `breakdown`，展示需求拆解文档，使用 `question` 工具请求确认。
- 如果状态为 `plans`，展示技术方案，使用 `question` 工具请求用户选择方案。
- 如果状态为 `todos`，展示实现清单，使用 `question` 工具请求确认。
- 如果状态为 `code`，检查 `05-实现清单/实现清单.md`：若有未完成任务，从中断处恢复执行；若所有任务已完成（已进入过迭代），则项目处于稳定状态，等待用户提出新需求变更并进入迭代流程。
- 如果状态为 `iteration`，读取 `iteration` 子对象：
  - 确定 `iteration.current_substep` 指向的受影响阶段。
  - 如果该阶段的文档已生成，展示文档并使用 `question` 工具请求确认。
  - 如果该阶段的文档尚未生成，生成文档并使用 `question` 工具请求确认。
  - 用户确认后，推进到下一个受影响阶段或进入实施。
- 如果状态为 `done`，使用 `question` 工具询问用户后续操作（参照工作流完成格式）。

## 重新开始

如果用户想从头开始（一个全新的项目或需求），**必须先进行二次风险告知与确认**：

1. 使用 `question` 工具向用户进行二次风险确认（参照「确认机制 → 新项目风险确认」格式），明确告知将永久删除 `.dwf/` 目录及所有文档目录（`01-需求文档/`、`02-设计稿/`、`03-需求拆解文档/`、`04-技术方案/`、`05-实现清单/`、`06-code/`、`07-需求迭代/`）及其全部文件，且操作不可撤销。
2. **等待用户二次确认。**
   - 如果用户选择"取消，保留现有项目"或输入取消意向：不删除任何内容，回到当前工作流。
   - 只有在用户明确选择"确认删除并重启"后，才删除上述目录，然后从阶段 1 开始。

**在用户二次确认之前，不得删除任何文件或目录。**

## 护栏

### 不可违反的规则

1. **永不跳过阶段。** 如果用户说"直接开始写代码"或"这只是个小 bug"，你必须解释工作流要求先走流程，然后引导进入正确的阶段或迭代流程。

2. **永不自动推进。** 每个阶段转换都必须使用 `question` 工具获取用户确认。用户选择"确认"选项或通过自定义输入明确确认后才能推进。如果没有收到确认，停下等待。

3. **永不直接修改代码。** 当项目已有代码（`current_step` 为 `code` 或 `done`）时，对代码的任何修改必须通过迭代流程。这包括：bug 修复、小幅调整（颜色、文案、间距等）、配置变更、依赖更新、重构、性能优化——**无论变更多小，都必须走迭代。**

4. **永不跳过确认直接行动。** 即使用户请你"确认是否是 bug"，你的回答只能是"是/否及分析"，不得附带代码修改。如需修改代码，必须先进入迭代流程。

5. **永不未经询问就覆盖。** 如果文档目录中已存在文档，向用户展示现有内容，询问是保留、修改还是替换。修改时直接覆盖原文件，不创建新版本。

6. **迭代时只生成受影响阶段的文档。** 不要为未变更的阶段重新生成文档。

7. **迭代时逐步确认，不要批量确认。** 迭代中的每个受影响阶段必须逐一确认后才能进入下一个。

8. **迭代断点恢复时必须从当前阶段继续。** 恢复时从 `iteration.current_substep` 指向的阶段继续，不要跳过未确认的阶段。

9. **技术方案必须提供至少 2 个方案。** 阶段 4（以及迭代中的 `plans` 阶段）必须生成 ≥2 个并列方案，由用户使用 `question` 工具选定其一后才能推进。

10. **启动新项目必须二次确认。** 当用户选择"启动新项目"或请求重新开始时，必须先用 `question` 工具进行风险告知（列出将被永久删除的目录、说明操作不可撤销），由用户二次确认后才能删除任何文件。在二次确认之前，不得删除任何内容。

11. **永不使用英文输出。** 与用户的文字交互、`question` 工具的选项和标题、所有阶段生成的文档内容，一律使用中文。代码、文件路径、技术术语等无法翻译的内容除外。