【3】第一条工作流：Spec 先行 + Superpowers 分步交付

 

## 为什么需要「第一条工作流」

工具链齐了，若仍用「一句话做一个后台管理系统」，你会得到：

- 一次改十几个文件，diff 难审  

- 上下文压缩后 AI 忘记最初目标  

- 能跑但缺 empty/error/权限  

**第一条工作流** 的目标：把 AI 的产出 **锁在 Spec 和步骤里**，让人每一步都能审、能停、能回滚。

---

## 总流程（平台 / 中后台）

```text

brainstorming（设计对齐）

    → writing-plans（实现计划）

    → subagent-driven-development / executing-plans（分步实现）

    → test-driven-development（关键逻辑）

    → verification-before-completion（声称完成前跑验证）

    → code-review（审查）

    → finishing-a-development-branch（合并/PR）

```

以上步骤对应 `ai-native` 仓库中的 **superpowers** Skill 子模块。在 Cursor 里用自然语言触发即可。

### 对话示例

| 阶段 | 你对 Agent 说 |

|------|-------------|

| 设计 | 「用 superpowers 的 brainstorming，先别写代码，帮我把需求问清楚。」 |

| 计划 | 「用 writing-plans 把刚才的设计拆成带文件路径的任务。」 |

| 实现 | 「实现 Task 1，遵守 fullstack-dev-standards。」 |

| 完成前 | 「用 verification-before-completion，跑测试后再说是否完成。」 |

| 合并前 | 「用 code-review 审查本次 diff。」 |

---

## 阶段一：brainstorming（动手前对齐）

**铁律：未呈现设计并获认可前，不写代码。**

brainstorming Skill 要求：

1. 探索项目上下文  

2. 一次只问一个澄清问题  

3. 给出 2–3 种方案与权衡  

4. 分节呈现设计，逐节确认  

5. 写入 `docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md`  

6. 用户审阅通过后 → **只** 进入 writing-plans  

即使「只是个简单列表页」，也要走短版设计——简单项目更需要明确边界，否则 AI 假设会跑偏。

---

## 阶段二：writing-plans（可执行任务）

设计通过后，产出 **实现计划**，建议路径：

`docs/superpowers/plans/YYYY-MM-DD-<feature>.md`

每个任务须包含：

- **精确文件路径**（Create / Modify）  

- **完整代码片段**（不是「加个表单」）  

- **可运行验证命令** + 期望输出  

- **TDD 步骤**：失败测试 → 实现 → 通过 → commit  

计划头模板：

```markdown

# [功能名] Implementation Plan

> **For agentic workers:** 使用 superpowers:subagent-driven-development 或 executing-plans 按任务执行。

**Goal:** [一句话]

**Architecture:** [2–3 句]

**Tech Stack:** [关键技术]

## Global Constraints

[从 Spec 复制的项目级约束]

```

**禁止** 计划里出现 TBD、implement later、类似 Task N 等占位。

---

## 规划落盘：planning-with-files

除实现计划外，**长任务**（预计 5 次以上工具调用）建议在项目根维护三文件：

| 文件 | 用途 |

|------|------|

| `task_plan.md` | 阶段、进度、决策、错误记录 |

| `findings.md` | 调研与发现（每 2 次搜索/浏览后更新） |

| `progress.md` | 会话日志、测试结果 |

**类比**：上下文窗口 = RAM（易失）；文件 = 磁盘（持久）。对话被压缩后，计划仍在磁盘上。

模板：`ai-native` → `.cursor/skills/planning-with-files/templates/`

触发语：

> 「用 planning-with-files，先建 task_plan.md，再开始改代码。」

---

## 阶段三：分步实现

两种执行模式（superpowers 提供）：

| 模式 | 适用 | 说明 |

|------|------|------|

| **subagent-driven-development** | 有 Subagent / Task | 每任务派生子代理，任务间 Review |

| **executing-plans** | 单会话 | 按 checkbox 逐步执行，卡点停下来问人 |

**共同原则：**

- 一次只做计划里的一项  

- 不越界改「禁止修改」路径  

- 每步跑验证命令  

- 卡住就停，不要猜  

---

## 阶段四：质量闸门

### test-driven-development

关键逻辑：**先写失败测试，再写实现**。  

若已经先写了实现再补测试，严格 TDD 要求删掉重来——否则无法证明测试有效。

### verification-before-completion

**铁律：没有 fresh 验证证据，不得声称完成。**

```

1. 识别：什么命令能证明 claim？

2. 运行：完整跑一遍

3. 阅读：exit code、失败数

4. 再声称：通过 / 未通过

```

禁止「应该没问题了」「看起来对了」。

### code-review

合并前用 code-review Skill 或人工按维度审查：安全、性能、正确性、可维护性、测试。

---

## 给 AI 的第一条消息模板（复制即用）

```markdown

## 目标

[一句话要做什么]

## 非目标

[明确不做什么]

## 技术栈

Vue 3 + TypeScript + Pinia + 团队 request 封装（code/data/message）

## 允许修改

- src/views/xxx/

- src/services/xxxService.ts

## 禁止修改

- src/utils/request.ts

- 路由配置

## 验收标准

- [ ] loading / error / empty

- [ ] 筛选变更重置 pageNo=1

- [ ] 无权限按钮置灰

## 参考 Skill

请先读 fullstack-dev-standards，再动手。

```

**非目标** 和 **禁止修改** 往往比目标更能省返工。

---

## 分场景：官网 vs 平台

| 类型 | 时间重心 | 流程是否省略 Spec |

|------|---------|------------------|

| **官网 / 品牌站** | 设计工具（Figma、动效） | 否，仅设计占比更高 |

| **中后台 / 平台** | Cursor + 组件规约 + 需求迭代 | 否，Spec 与计划更重要 |

两类都要 **人审、测试、Review**；差别只在设计 vs 工程的时间分配。

---

## OpenSpec 与 SDD（延伸阅读）

大需求可借助 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 等工具，把需求写成 **结构化规格**（边界、输入输出、与模板接点），再逐条喂给 Agent。

核心思想不变：**别让 AI 在对话里临时发明一套互相矛盾的约束。**

---

## 本篇小结

1. 先 brainstorming，再 writing-plans，再分步写代码。  

2. 长任务用 planning-with-files 落盘。  

3. 首条消息写清目标、非目标、允许/禁止路径、验收标准。  

4. 完成前 verification，合并前 code-review。

---

## 系列导航

| 篇目 | 标题 |

|:---:|------|

| 1 | [AI-Native 是什么？](01-AI-Native是什么.md) |

| 2 | [工具链入门](02-工具链入门.md) |

| **3** | **第一条工作流：Spec 先行 + Superpowers 分步交付**（本文） |

| 4 | [前后端交付标准](04-前后端交付标准.md) |

| 5 | [7 天上手计划与 FAQ](05-七天上手与FAQ.md) |

---

*本文是「AI-Native 开发入门」系列文章，配套仓库 `ai-native`。*