wk-brainstorm

name: wk-brainstorm description: 实现前的设计探索 — 通过需求澄清、方案对比、设计文档输出，把模糊想法转化为可执行计划。在写代码前触发，防止基于未验证假设开工。

WK-Brainstorm — 设计探索 Skill

核心铁律

在呈现设计并获得用户批准之前，不得写任何代码、脚手架或实施性内容。

这适用于所有规模的任务。"这个太简单了不需要设计"是最常见的误判——越简单的任务越容易在未检查的假设上浪费工作。

触发时机

• 用户提出新功能、新模块、架构改动或较复杂的 Bug 修复
• 需求模糊、方案不明时
• 多个实现路径需要对比取舍时

工作流程

Step 1：探索项目上下文

提问之前，先了解当前状态：

# 相关目录结构
find . -name "*.swift" -o -name "*.m" -o -name "*.h" | head -30

# 近期提交方向
git log --oneline -10

# 现有相关模块接口
# 用 Read / Grep 查阅关键文件

目标：提问时不问显而易见的事，不提出与现有架构冲突的方案。

Step 2：需求澄清（逐个提问）

每次只问一个问题，提问规则：

• 优先多选题（比开放题容易回答）
• 聚焦：目的、约束、成功标准
• 如果发现请求覆盖多个独立子系统，先拆解范围，再逐一深入

❌ 不允许一次抛出多个问题

Step 3：提出 2-3 个方案

以自然语言呈现，包含：

• 每个方案的核心思路和关键技术决策
• 各方案的优劣对比（复杂度、可测试性、扩展性、与现有架构的契合度）
• 推荐方案及理由（先说推荐，再说原因）

Step 4：分段呈现设计

理解需求后，分段展示设计（每段结束问用户是否认可后再继续）：

覆盖维度：

• 架构与模块划分
• 关键接口/协议定义
• 数据流与状态管理
• 错误处理策略
• 测试策略

设计原则：

• 每个模块单一职责，接口清晰，能独立理解和测试
• 改内部不影响调用方
• 文件/函数尽量小而聚焦，大文件往往意味着职责混乱
• 在现有代码库中：先探索现有结构，遵循既有模式；发现影响本次改动的问题可在设计中包含针对性改进；不提无关的重构建议

Step 5：写设计文档

用户批准设计后，将设计写入文件并提交：

保存路径： .claude/plans/YYYY-MM-DD_<主题>_设计.md

文档必须包含：

## 背景与目标
[问题背景 + 可验证的验收标准]

## 方案决策
[选了哪个方案，为什么，放弃了什么]

## 架构与模块设计
[模块划分、职责边界、依赖关系]

## 关键接口定义
[核心 API / Protocol 签名]

## 数据流与错误处理
[主流程 + 异常路径]

## 测试策略
[单元测试、集成测试覆盖范围]

写完后执行自检（Step 6），然后请用户确认。

Step 6：自检

以新视角快速过一遍：

1. 占位符扫描 — 有无 "TBD"、"TODO"、未完成章节、模糊描述？补全或明确化。
2. 内部一致性 — 各章节是否矛盾？架构描述与功能描述是否匹配？
3. 范围合理性 — 这个设计对应的实施计划是否可独立完成、独立测试？如果横跨太多子系统，建议拆分。
4. 歧义消除 — 某个需求有两种合理理解时，明确选一种并写明。

发现问题直接修正，无需重走流程。

Step 7：用户确认 → 制定实施计划

设计文档写完后提示：

"设计文档已保存至 .claude/plans/<filename>.md，请确认后我们开始制定实施计划。"

用户确认后，按 plan-writing-guide.md 制定实施计划，保存到 .claude/plans/YYYY-MM-DD_<主题>_计划.md。

输出清单

关键原则速查

• 每次只问一个问题
• 优先多选题
• 探索先于提问
• 提出 2-3 方案，先说推荐
• 分段呈现，增量确认
• YAGNI：移除设计中不必要的功能
• 设计批准前不写代码