---
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. **再问**：查不到 → `AskUserQuestion` 问用户，记录答案到 spec
3. **绝不**留 `【人工填写：】` 占位符；若 1 + 2 都解决不了，spec 必须写出具体阻塞点（不是泛化的人工填写标记），Q&A 继续直到解决

## 执行步骤

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

2. **交互式 Q&A**（参考下方"Q&A 原则"）：
   - **先评估 scope**：单 spec 容纳得下吗？跨多个独立子系统（如"含登录 + 文件存储 + 计费 + 分析"）→ 先提示分解，每个子项目独立 brainstorm
   - **一次一问** `AskUserQuestion`，仅对真模糊点；多选题优先
   - 决策完成后挑一种 approach；trade-off 直接内嵌 spec，**不设确认 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
   - 文件已存在 → 征求用户确认后覆盖

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 原则

- **一次一问** — 不堆问题
- **多选题优先** — 答更快
- **仅对真模糊点问** — 不造确认问题
- **YAGNI** — 删 spec 中不必要的功能
- **渐进理解** — 不明白就问
- **无审批 gate** — 写 spec 即 commit；分歧落地为具体 Q&A 项，不靠"等用户确认"

## 参考

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