---
description: 生成草案文件 — 将任务列表（或方案文档）输出为 ./drafts/ 目录下的独立草案文件
---

# 生成草案文件

将确认的任务输出为 `./drafts/<名称>/` 下的独立 `.md` 草案文件，衔接 `/dev-new`。

## 演进场景的处理规则

当目标 `./drafts/<名称>/` 已存在时，视为「演进场景」，处理规则：

| 操作 | 说明 |
|---|---|
| **新增任务** | 在最大编号之后顺延创建新草案文件（如已有 1~10，新增从 11 开始） |
| **取消任务** | 原草案文件**不删除**，在文件顶部加引用块 `> [变更 YYYY-MM-DD] **已取消**：原因`；summary.md 表格状态改为「已取消」 |
| **调整任务** | 直接编辑原草案文件，重大调整在文件顶部加引用块 `> [调整 YYYY-MM-DD] 说明` |
| **依赖更新** | 反映到 summary.md 表格的依赖列（新增任务可能依赖原任务，原任务也可能新增对新任务的依赖） |
| **重排优先级** | 调整 summary.md 表格中行的顺序（编号不变，仅换行），优先级高的排在前面 |
| **已完成任务** | **不动**——已完成任务的草案和代码都是历史记录，任何调整都不应破坏其一致性 |

> 已完成任务的草案文件可加锁标记（在 summary.md 状态列显示 `✅ 已完成`），避免后续误编辑。

## 执行流程

**第一步：确定任务来源**

- 运行过 `/epic-list` 且已确认 → 按已确认列表输出
- 未运行过 `/epic-list` → 自行分析 `epics/<名称>.md`，拆分原则同 `/epic-list`（扁平化、每个任务=构建/验收单元、仅标注硬依赖、控制粒度）

自行分析时需先用 `question` 确认粒度和范围。

**第二步：创建草案文件**

目录结构：
```
./drafts/<名称>/
├── summary.md           # 概述 + 任务清单
├── 1-<任务标题>.md      # 草案（按执行顺序编号）
└── ...
```

子目录用中文名（如 `./drafts/Agent平台/`），文件名 `N-<中文标题>.md`。

#### summary.md 格式

```markdown
# <名称>

> 详细方案: [../epics/方案名称.md](../epics/方案名称.md)

## 概述
<背景、目标、整体描述>

## 关键文件与模块
<探索代码库发现的关键路径和模块结构，方便 dev-new 快速了解代码布局>

## 子任务

| # | 标题 | 简介 | 依赖 | 状态 |
|---|------|------|------|------|
| 1 | <标题> | <一句话简介> | | 已完成 |
| 2 | <标题> | <一句话简介> | 1 | 开发中 |
| 11 | <新增标题> | <一句话简介> | 2, 5 | 未开始 |
| 4 | <标题> | <一句话简介> | | 已取消 |

```

**字段说明**：

- **#**：子任务编号。首次创建从 1 递增；演进场景下老编号**永不重排**，新增任务顺延最大编号
- **依赖**：本任务的前置子任务编号清单，多个用英文逗号分隔（如 `2, 5`）；无依赖则留空
- **状态**：`未开始` / `开发中` / `已完成` / `已取消`
- **行顺序**：表格中行的物理顺序表示**当前优先级**（高优先级在前），与编号解耦

> 演进场景下，已取消任务的行保留在表格中（不删除），其简介列可补充取消原因。

#### 子任务草案格式

```markdown
# <子任务标题>

## 背景
— 所属整体方案上下文，与其他子任务关系（前置/后续依赖）

## 目标
— 功能/行为层面达成什么

## 范围
— IN SCOPE：明确包含
— OUT SCOPE：明确排除
— TODO：尚未决定是否纳入的事项（待 /dev-new 确认）

## 关键文件
— 本子任务直接相关的具体文件路径

## 关键决策
— 已定：用户明确做出的技术决策，/dev-new 直接采纳
— 待定：方向已定但具体值/参数未定（需数据或用户确认）

## 约束与注意事项
— 技术约束、风险点
— QUESTION：需 /dev-research 调研或用户确认后才能决策的问题

## 验收标准（粗略）
— 功能层面验收，不写具体命令（留给 /dev-new 细化）
```

> 若存在方案文档：草案"关键决策"优先引用 `epics/` 文档"七、关键设计决策"；"约束"引用"二、平台约束"和"六、关键执行链路"，保持一致。

**待定项标记约定**

草案中所有未决事项一律**行内标记**，不单开「待讨论/待细化」章节：

| 标记 | 含义 | 解决阶段 |
|------|------|----------|
| `TODO` | 范围/取舍未定 | `/dev-new` 拍板 |
| `待定` | 方向已定但具体值/参数未定（阈值、命名、配置等） | `/dev-new` 或 `/dev-research` |
| `QUESTION` | 需外部信息（调研、用户确认）才能决策 | `/dev-research` 或用户 |

**规则**：
- 标记必须**留在它语义所属的章节里**（范围里的 TODO 写在「范围」、决策里的待定写在「关键决策」），便于 `/dev-new` 扫到时保留上下文
- 每个标记后用一句话说明**未定的是什么**和**该由谁解决**
- `grep -E 'TODO|待定|QUESTION'` 可一键汇总所有未决事项

**第三步：汇报**

首次创建：

```
./drafts/<名称>/ 已创建 N 个草案文件。你可以：
- 查看并调整某个草案
- 调整任务顺序或粒度（拆分/合并）
- 确认无误后开始: /dev-new ./drafts/<名称>/1-<标题>.md
```

演进更新：

```
./drafts/<名称>/ 已同步演进:
- 新增草案 X 个（编号顺延至 N）
- 取消草案 Y 个（文件保留并加标注）
- 调整草案 Z 个（依赖/优先级更新）
你可以：
- 查看新增或调整的草案
- 继续开始下一个任务: /dev-new ./drafts/<名称>/<编号>-<标题>.md
```

用户可能的行为：修改草案 → 调整对应文件；调整拆分 → 修改 summary 及受影响文件；确认 → 引导下一个。

**第四步：引导第一步任务（必须主动向用户输出以下内容）**

首次创建：

```
草案已确认，开始第一个任务:
  /dev-new ./drafts/<名称>/1-<标题>.md

每个任务可在同一或新会话中继续。
```

演进场景（按优先级指向下一个未开始且无未完成依赖的任务）：

```
草案已更新，继续下一个任务:
  /dev-new ./drafts/<名称>/<编号>-<标题>.md

每个任务可在同一或新会话中继续。
```

## 约束

- ⛔ 草案**只含需求描述和边界，不含代码实现思路**（留给 `/dev-new` 分析）
- ⛔ 待定项用行内标记（`TODO`/`待定`/`QUESTION`）写在所属章节，**不单开「待讨论/待细化」章节**——避免决策债堆积
- 每个任务可独立完成、独立验证
- 验收标准可观测（能看到/能测试）
- 探索过代码库时将关键文件路径写入草案
- 状态由 `/dev-fire` / `/dev-commit` 自动更新
- **演进场景下老任务编号永不重排**——已取消任务的草案文件不删除，仅在文件顶部加引用块标注
- **已完成任务的草案默认不动**（历史记录），如需调整必须经用户显式确认