---
name: brainstorming
description: "Use before design-level creative work. MANDATORY when the change touches public API, port (Protocol) signatures, or architecture boundaries — these require an approved design and a human gate. For smaller changes (internal implementation, test fixes, tasks inside an approved plan), use your judgment: skip if requirements are already unambiguous."
---

# Brainstorming Ideas Into Designs

把想法变成经过对比与确认的设计。产出是一份设计文档,不是代码。

## 触发边界(何时必须用)

| 情形 | 是否强制 |
|---|---|
| 变更公共 API、端口(Protocol)签名、架构边界(`ports.py`/`types.py`/`errors.py`、middleware 洋葱层次、依赖铁律) | **强制**,且设计必须经人类确认后才能实施 |
| 新增子系统/新组件、里程碑级功能 | **强制** |
| 内部实现、测试修复、已批准 plan 内的任务、文档修订 | 自判;需求无歧义即可直接做 |

不确定属于哪一类时,按"是否会改变库对下游三个项目的承诺"判断:会,就走设计。

## 核心要求(设计的验收标准)

一份合格的设计必须包含,缺一即不完整:

1. **备选方案对比**:至少 2-3 个可行方案、各自权衡、你的推荐及理由。只有一个方案 = 没有做设计。
2. **旧版行为审计(仅重写/迁移类任务)**:本库大量工作是从 `reference/` 三项目迁移治理代码。凡替换/重写既有模块,必须列出旧版全部行为(含持久化、崩溃恢复、幂等、断点续跑),逐条标注"保留 / 替换 / 有意放弃"。未声明的隐式丢弃 = bug。
3. **非功能维度(逐条回答,允许"不适用"但必须写明)**:
   - 并发与取消:并发调用下的行为?`CancelledError` 穿透路径?
   - 降级方向:依赖的后端不可用时,静默降级还是报错?(对照 CLAUDE.md 库铁律)
   - 幂等与重复:同一操作重复执行是否安全?
   - 持久化与原子性:什么时候落盘?部分写入会不会损坏数据?
4. **错误处理与测试策略**:失败落入哪个错误分类?怎么测?

## 过程建议(非脚本)

先查 `research-wiki/ARCHITECTURE.md` 与相关 `reference/` 代码,再提问;问题一次一个、能选择题就选择题;范围过大(多个独立子系统)先拆分再逐个设计。不做任务外的重构与抽象——设计只服务当前目标。

如需向人类展示视觉对比(布局/图示),可参考 `visual-companion.md`(可选工具,非流程)。

## 留痕与审批门(不可省略)

1. **写设计文档**: `research-wiki/designs/YYYY-MM-DD-<topic>-design.md`(≤400 行),并提交 git。
2. **自审后送 Codex 独立审**: 用 `/codex:rescue --fresh --wait` 只读审查(需求覆盖、内部一致性、与 ARCHITECTURE.md/CLAUDE.md 的冲突)。逐条核验其意见后就地修订——不盲从。模板见 `spec-document-reviewer-prompt.md`。
3. **人类审批门**: 凡触发"强制"档的设计,必须请人类审阅设计文档并明确同意后才进入 `writing-plans`。这是硬门,不因任何理由跳过。
4. **Wiki 注册**(`research-wiki/` 存在时):
   ```bash
   .claude/tools/research_wiki.py add_entity research-wiki/ --type design --id <slug> --title "<title>"
   .claude/tools/research_wiki.py rebuild_index research-wiki/
   ```
   在生成页中记录:选定方案、关键理由、**被否决的备选及否决原因**。

设计获批后的下一步是 `writing-plans`(若达到其触发规模),不要跳到实现类 skill。