第四章：需求澄清、方案设计与计划编写

4.1 为什么先设计再编码

AI 编程最大的浪费往往发生在需求未澄清阶段。用户说「加一个导出功能」，AI 可能立即写 CSV 导出，但真实需求可能是：

• 需要 Excel 而不是 CSV。
• 数据量可能上百万行，需要异步任务。
• 只有管理员能导出。
• 需要脱敏手机号和身份证。
• 需要记录审计日志。
• 前端要显示进度和下载历史。

如果跳过澄清，后续返工成本远高于前期多问几个问题。brainstorming 的目标就是把模糊想法变成可审查的设计规格。

4.2 brainstorming 的触发场景

只要任务涉及创造性工作或行为变更，就应该先使用：

• 创建新功能。
• 构建新组件。
• 修改现有行为。
• 新增 API。
• 重构影响边界。
• 设计 UI 或交互。
• 新增自动化流程。

即使任务看起来很小，也不应直接跳过。对于真正简单的任务，设计可以非常短，但仍需要确认意图和成功标准。

4.3 brainstorming 的核心流程

brainstorming 要求按顺序完成以下阶段：

1. 探索项目上下文。 先阅读现有文件、文档和相关结构，不在不了解项目的情况下提方案。
2. 提出澄清问题。 每次一个问题，优先选择题，聚焦目的、约束、成功标准。
3. 提出 2-3 种方案。 每个方案说明权衡，并给出推荐。
4. 展示设计。 按复杂度分节展示架构、组件、数据流、错误处理、测试策略等。
5. 获得用户批准。 在批准前不写实现代码。
6. 写设计文档。 默认位置为 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md，除非用户另有要求。
7. 规格自检。 检查占位符、矛盾、范围过大和模糊性。
8. 过渡到 writing-plans。 设计通过后再写实现计划。

其中最重要的硬门禁是：在展示设计并获得批准前，不要调用实现 Skill、不要写代码、不要搭建项目。

4.4 如何提出好问题

好的澄清问题应该降低用户回答成本。优先使用选择题：

导出功能更倾向哪种模式？
A. 同步导出：适合小数据量，立即返回文件
B. 异步导出：适合大数据量，后台生成后下载
C. 两者都支持：按数据量自动选择

不要一次抛出十几个问题。每次一个问题可以让对话逐步收敛，避免用户被长清单压垮。

问题应围绕：

• 目标： 为什么要做？解决谁的问题？
• 范围： 包含什么？明确不包含什么？
• 约束： 技术栈、兼容性、权限、性能、时间。
• 成功标准： 如何判断完成？有什么可验证结果？
• 风险： 安全、数据一致性、迁移、回滚。

4.5 方案设计的结构

设计不需要长篇大论，但要覆盖决策点。推荐结构：

## 背景与目标

说明要解决的问题和成功标准。

## 范围

本次包含什么，不包含什么。

## 推荐方案

描述总体思路和为什么推荐。

## 备选方案

列出 1-2 个替代方案和取舍。

## 组件与边界

说明要新增或修改哪些模块，职责分别是什么。

## 数据流

从用户操作到系统响应，数据如何流动。

## 错误处理

失败、重试、回滚、用户提示、日志。

## 测试策略

单元测试、集成测试、端到端或手动验证。

复杂系统可以加安全、性能、部署、迁移和可观测性章节。简单任务可以压缩为几段，但不能省略关键约束。

4.6 writing-plans 的作用

设计规格回答「要做什么、为什么这么做」。实现计划回答「按什么顺序改哪些文件，如何验证每一步」。

writing-plans 假设执行计划的人是有经验的工程师，但对当前代码库没有上下文。因此计划必须写清：

• 要创建和修改哪些文件。
• 每个文件的职责。
• 每个任务的步骤。
• 每步对应的代码、测试和命令。
• 预期失败和预期通过的输出。
• 何时 commit。

它强调小步骤、TDD、DRY、YAGNI 和频繁 commit。

4.7 实现计划的粒度

writing-plans 规定每步应是 2-5 分钟的小操作。例如：

1. 编写失败测试。
2. 运行测试确认失败。
3. 编写最少实现代码。
4. 运行测试确认通过。
5. Commit。

这看起来繁琐，但对 AI 很重要。AI 容易在一个大步骤中同时改测试、改实现、重构和修其他问题，导致失败时无法判断原因。小步骤能让每个变化可验证。

4.8 计划文档头部

计划应包含目标、架构和技术栈摘要。典型结构：

# 功能名称 实现计划

> 面向 AI 代理的工作者：必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。

**目标：** 一句话描述要构建什么。

**架构：** 2-3 句话描述方案。

**技术栈：** 关键技术/库。

---

这段头部的价值是让后续执行者快速理解整体意图，不必回看完整对话。

4.9 计划中的禁止项

writing-plans 明确禁止含糊占位符：

• 「TODO」
• 「后续实现」
• 「添加适当的错误处理」
• 「处理边界情况」但不列具体边界
• 「为上述代码编写测试」但不给测试内容
• 「类似任务 N」
• 引用尚未定义的类型和函数

这些写法对人类也许还能理解，对 AI 执行者会造成猜测。计划越具体，执行越稳定。

4.10 从设计到计划的衔接

推荐顺序：

1. 用户提出需求。
2. AI 使用 brainstorming 澄清并给设计。
3. 用户批准设计。
4. AI 写设计规格并自检。
5. 用户审查规格。
6. AI 使用 writing-plans 写实现计划。
7. 用户选择执行方式：子 Agent 驱动或内联执行。

不要把设计和计划混在一起。设计阶段讨论方案和边界；计划阶段才拆具体文件和步骤。

4.11 计划审查清单

计划写完后，应自查：

• 规格中的每项需求是否都有任务覆盖？
• 是否有 TODO、待定、类似任务、适当处理等占位符？
• 类型名、函数名、文件路径是否前后一致？
• 每个任务是否有明确验证命令？
• 是否按依赖顺序排列？
• 是否避免无关重构？
• 是否每步都能独立判断成功或失败？

如果发现问题，应直接修正计划，而不是带着模糊计划进入实现。

4.12 实战提示

小功能也写短设计

例如按钮文案调整：

目标：把导出按钮文案从「下载」改为「导出 CSV」，只影响用户列表页。
成功标准：页面按钮显示新文案，现有点击行为不变。
测试：更新对应快照或组件测试。

这就是足够的设计。

大功能先拆子项目

如果需求包含多个独立子系统，例如「聊天、文件存储、计费、分析平台」，应先拆分，而不是写一个巨型规格。每个子项目独立经历规格、计划、实现周期。

设计应服务当前目标

在现有代码库中发现坏味道时，可以在设计中包含与当前目标直接相关的改进。但不要借机做大范围无关重构。

4.13 本章小结

brainstorming 和 writing-plans 是 superpowers-zh 的前置双门。前者防止需求没想清楚就编码，后者防止设计没拆清楚就执行。真正稳定的 AI 编程不是「提示词更强」，而是让 AI 在每个阶段都有明确产物和门禁。