---
name: feature-brainstorm
description: 功能循环第 1 步。针对单个 REQ-XXX-NNN 做交互式 Q&A + 写规格，产出到 docs/superpowers/specs/，链入 feature-plan。
user-invocable: false
allowed-tools: Read Write Skill AskUserQuestion Bash(mysql *)
---

**所有输出必须使用中文。**

# feature-brainstorm

## 阶段范围（后端）

本 skill 服务于**后端阶段**。产出范围限定为 controller / service / repository / DTO / 校验 / SQL migration / REST 契约。读 docs/01 REQ 卡片时**忽略 UI 描述**（输入控件类型、按钮位置、列表布局等），但**校验规则、业务规则**仍要落到后端 DTO + service。UI 实现统一推迟到前端阶段（fe-feature-*）。

## 占位符规则

本 skill 写的 spec 是 CC 内部推理产物，不是用户审阅文档。**不允许** `【人工填写：...】` 占位符——A 阶段 `docs/01~10` / `CLAUDE.md` / `.env.local` 才用那个标记。需要具体值时：

1. **先查** `.env.local` / `docs/07-环境配置.md` / `CLAUDE.md` / 现有代码。值已落地某处 → 在 spec 中引用源（例 "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入"）
2. **再自决**：查不到 → 按"自主决策优先级"自行选定值，在 spec 中以 `自动选用 X（来源: <规范/惯例/现有代码>）` 注明
3. **最后才问**：上述两步均无合理推荐项时（如跨子系统的重大 trade-off、规范明确要求人工拍板的字段），才 `AskUserQuestion`，并记录答案到 spec
4. **绝不**留 `【人工填写：】` 占位符；若 1~3 都解决不了，spec 写出具体阻塞点，Q&A 继续直到解决

**自主决策优先级**（由高到低）：
1. `docs/04-技术规范.md` / `docs/06-UI交互规范.md` / `CLAUDE.md` 明文规定
2. 现有代码已落地的同类模式（保持一致）
3. 主流框架/库的官方推荐默认值
4. 最简、最少依赖、最易回滚的实现

## 执行步骤

1. **收集上下文**：确定本次 REQ-XXX-NNN（由 module-start 派发时指定），读取：
   - REQ 卡片 `docs/01-需求清单/<module>/<req_id>.md`
   - 涉及的数据表定义（取自 docs/03 或实时 mysql 查询）

2. **自主决策为主，Q&A 为辅**（参考下方"Q&A 原则"）：
   - **先评估 scope**：单 spec 容纳得下吗？跨多个独立子系统（如"含登录 + 文件存储 + 计费 + 分析"）→ 先提示分解，每个子项目独立 brainstorm
   - **默认自动决策**：按"自主决策优先级"自行选定 approach，trade-off 直接内嵌 spec 并注明来源，**不弹问**
   - **仅在真硬阻塞时** `AskUserQuestion`：四级优先级都给不出合理推荐 + 决策影响重大（如核心契约、跨模块兼容、安全/合规） → 才一次一问、多选题优先
   - **不设确认 gate**

3. **写 spec 到 `docs/superpowers/specs/<YYYY-MM-DD>-<REQ-id>.md`**：
   - 按 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` 渲染
   - 覆盖：goal / 输入输出 / 业务规则 / 约束 / schema / API 引用 / acceptance criteria
   - 文件已存在 → 直接覆盖（spec 是 CC 内部产物，无需确认）

4. **Spec 自审**（inline 修，无须用户等待）：
   - **占位符扫描**：`TBD` / `TODO` / `【人工填写：】` / 含糊段 → 修（按"占位符规则"流程解决）
   - **内部一致性**：节与节是否矛盾？架构是否匹配功能描述？
   - **范围检查**：单 plan 能消化吗？还是需要分解
   - **歧义检查**：任何 requirement 两种解读？挑一个写明
   
   fix inline，无须 re-review。

5. **输出 + 链 feature-plan**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
   - 输出一行 `feature-brainstorm: <REQ> → <path>`
   - **同一 turn 内立即** `Skill(feature-plan)`

## Q&A 原则

- **自主决策优先** — 默认按规范/惯例自行选推荐项写入 spec，不弹问；只有"真硬阻塞"才问
- **真硬阻塞 = 四级优先级都给不出合理推荐 + 决策影响重大**（核心契约 / 跨模块兼容 / 安全合规 / 不可逆架构选型）
- **一次一问** — 真要问就不堆问题
- **多选题优先 + 标记推荐项** — 选项里把推荐项放第一并标注 `(Recommended)`，便于用户秒选
- **YAGNI** — 删 spec 中不必要的功能
- **无审批 gate** — 写 spec 即 commit；分歧落地为具体决策记录，不靠"等用户确认"

## 参考

- `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md`
- 上游：`module-start`
- 下游：`feature-plan`