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

4.1 为什么先设计再编码

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

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

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

4.2 brainstorming 的触发场景

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

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

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

4.3 brainstorming 的核心流程

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

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

编写失败测试。
运行测试确认失败。
编写最少实现代码。
运行测试确认通过。
Commit。

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

4.8 计划文档头部

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

# 功能名称 实现计划

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

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

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

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

---

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

4.9 计划中的禁止项

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

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

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

4.10 从设计到计划的衔接

推荐顺序：

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

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

4.11 计划审查清单

计划写完后，应自查：

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

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

4.12 实战提示

小功能也写短设计

例如按钮文案调整：

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

这就是足够的设计。

大功能先拆子项目

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

设计应服务当前目标

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

4.13 本章小结

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