需求分析与任务分解
核心问题
一个需求来了，Qoder 怎么帮我把关，避免"直接上手就踩坑"？
在传统开发流程中，最常见的错误不是代码写错了，而是需求理解错了。编码之前没有充分分析需求，结果写了一半发现方向偏了，返工成本巨大。
Qoder 的指导思想是：先写文档，再写代码。 需求分析文档是让 AI 第一次"理解"你要做什么，而不是让它从需求描述直接跳到代码实现。
使用篇：/create-proposal 生成需求文档
什么是 create-proposal
/create-proposal 是 Growth 项目中最常用的 Skill 之一。它按照标准的五段式模板，自动生成需求分析文档。
贯穿案例：创建一个"文件压缩"节点
假设我们要创建一个新的工作流节点——"文件压缩节点"。我们输入：
/create-proposal为工作流引擎新增"文件压缩"节点，支持 ZIP 和 7z 格式，用户指定源文件路径和输出路径。
Qoder 自动生成以下文档：
markdown
# 文件压缩节点
> **创建时间**: 2026-06-05 14:30:00
> **需求描述**: 新增文件压缩节点，支持 ZIP/7z 格式
> **涉及模块**: Workflow.Node
> **涉及层级**: Implementations
---
## 一、需求分析
### 1.1 业务背景
用户在自动化工作流中经常需要压缩文件，目前只能通过外部工具实现。
### 1.2 核心问题
工作流引擎缺少内置压缩能力，用户需要手动处理。
### 1.3 预期结果
新增一个压缩节点，拖入即可使用，支持 ZIP 和 7z。
---
## 二、业务流程分析
用户输入文件路径 → 选择压缩格式 → 执行压缩 → 输出压缩文件路径
---
## 三、架构设计
### 3.1 模块依赖
Workflow.Node → CLI（调用 7z 命令行工具）
### 3.2 接口设计
节点输入：SourcePath（string）、OutputPath（string）、Format（enum: zip/7z）
节点输出：OutputPath（string）、FileSize（long）
---
## 四、修改清单
| 层级 | 操作 | 文件路径 | 目的 |
|------|------|----------|------|
| Implementations | 新增 | Workflow.Node/Nodes/FileCompressNode.cs | 节点执行逻辑 |
| Config | 修改 | Workflow.Node/node-registry.json | 注册新节点 |
---
## 五、编码实施
### 实现顺序
1. 创建 FileCompressNode.cs
2. 注册到 node-registry.json
3. 本地测试
为什么时间戳命名
文档的文件名格式为 MMDD-HHMMSS-具体需求名字.md，例如 0605-143000-文件压缩节点.md。
时间戳精确到秒，按文件名排序就是需求时间线。三个月后翻目录，一眼就知道当时改了什么、改的顺序是什么。
实践篇：/plan 模式自动拆解任务
什么是 Plan 模式
文档写完了，方案确认了，接下来是执行。但"文件压缩节点"涉及多个文件、多个步骤，一次性让 AI 搞定容易出错。
Plan 模式的作用就是把大任务拆成小任务，逐个执行。
贯穿案例：用 Plan 拆解"文件压缩节点"
方案的文档确认后，让 AI 进入 Plan 模式：
/plan 按方案文档实现"文件压缩节点"
Qoder 自动生成执行计划：
┌──────────────────────────────────────────┐
│ 实施计划：文件压缩节点 │
├──────────────────────────────────────────┤
│ │
│ [子任务1] 创建节点执行器 │
│ 目标：实现 FileCompressNode.cs │
│ 文件：Workflow.Node/Nodes/ │
│ 验收：能正确调用 CLI 压缩工具 │
│ │
│ [子任务2] 注册节点配置 │
│ 目标：在 node-registry.json 中添加条目 │
│ 文件：Workflow.Node/node-registry.json │
│ 验收：注册后前端能识别该节点 │
│ │
│ [子任务3] 本地测试 │
│ 目标：执行节点验证 ZIP 和 7z 格式 │
│ 命令：.\test.ps1 -Node FileCompress │
│ 验收：两种格式均正确输出 │
│ │
└──────────────────────────────────────────┘Plan 模式 vs 直接写的区别
| 维度 | 直接写 | Plan 模式 |
|---|---|---|
| 执行方式 | 一次性对话 | 工作流式持续运行 |
| 任务范围 | 适合单步操作 | 适合多步骤、跨文件的复杂任务 |
| 会话限制 | 有轮数超时限制 | 可持续直到任务完成 |
| 可审查性 | 改完直接生效 | 每一步可审查、可回滚 |
在贯穿案例中的应用
确认计划后，执行开始。每个步骤依次进行：
- 创建
FileCompressNode.cs→ 完成，审查通过 - 注册
node-registry.json→ 完成，审查通过 - 本地测试 → 发现 7z 格式路径参数错误 → 暂停，修正参数定义 → 继续 → 通过
注意第三步：执行中发现问题，可以随时暂停、纠正、继续。这就是 Plan 模式的优势——每一步都是可审查、可中断的。
实践篇：编码前先输出方案
为什么编码前必须输出方案
这是 Growth 项目中最重要的原则之一：方案对了，后面的编码只是执行。
AI 有一个天然倾向——接到需求就直接开始写代码。如果没有方案审查环节，AI 可能：
- 选择了错误的技术方案
- 遗漏了重要的边界条件
- 设计出了过于复杂的架构
解决方案就是在编码之前强制 AI 先输出一份方案。你审查方案，确认正确了，再让 AI 开始编码。
方案审查清单
在 Growth 项目中，需求文档审查需要确认以下问题：
- [ ] 文件名是否包含精确到秒的时间戳？
- [ ] 是否回答了"不改会有什么后果"？
- [ ] 业务流程是否覆盖了正常流程 + 异常流程？
- [ ] 架构设计是否标注了模块间的依赖关系？
- [ ] 修改清单是否覆盖了所有受影响的层级？
- [ ] 修改清单中的每个文件是否标注了操作类型（新增/修改/删除）？
- [ ] 是否有一个明确的验收标准？
知识篇：文档先行 + AI 执行的协作模式
为什么"文档先行"对 AI 尤其重要
人写代码时，即使需求模糊，也能边走边调整。但 AI 不是——它的每次对话都是独立的。如果需求不明确，AI 要么猜测，要么生成大量无用代码。
文档先行的本质是：在编码之前，把需求的不确定性降到最低。 需求文档就是 AI 的"完整上下文"——它不需要猜测，只需要执行。
文档是 AI 的"上下文压缩包"
一份 100 行的需求文档，可能替代 AI 读取 2000 行现有代码。原因是：
- 文档回答了"为什么要改这个"——AI 不需要从现有代码中逆向推导需求
- 文档标注了"受影响的模块"——AI 不需要搜索整个代码库
- 文档定义了"验收标准"——AI 知道什么时候算完成
我把这个叫做文档的"上下文压缩"效应：一份好的需求文档，把 AI 理解需求所需要的上下文压缩到了最低。
本章小结
| 阶段 | Qoder 工具 | 对贯穿案例的作用 |
|---|---|---|
| 需求分析 | /create-proposal | 生成"文件压缩节点"需求文档 |
| 任务分解 | /plan | 拆为 3 个子任务：创建→注册→测试 |
| 方案审查 | 人工 + Checklist | 确认方案无误再编码 |
| 执行 | Plan 模式逐步执行 | 测试发现问题，暂停修正后继续 |
核心原则：方案对了，后面的编码只是执行。
关联：第二部分 01（文档先行）、第二部分 05（复杂任务分解）。