Brainstorming 深度解析

作为agent常用的skill，期望理解他真正做了些什么

前置概念：Skill 是什么、怎么生效

Superpowers 里的每个 skill 是一个 SKILL.md 文件，放在 agent 能读到的 skill 目录下。agent 不会主动加载所有 skill------它根据 description 字段（YAML frontmatter）判断"这个 skill 是否适用于当前任务"。所以 description 是 skill 的触发机关，不是简介。

Skill 被加载后，其全部正文注入 agent 的 system prompt。agent 逐字照做------skill 不是"参考资料"，是行为约束代码，只不过它用 markdown 写的，执行环境是 LLM 的注意力机制。

逐层拆解：Brainstorming 在 agent 脑子里塞了什么

以 skills/brainstorming/SKILL.md（160 行）为对象，逐条还原：原文写了什么 → agent 的默认行为是什么 → 这条指令把它扭成了什么。

第 0 层：Description------触发即约束

原文（YAML frontmatter）：

yaml 复制代码

description: "You MUST use this before any creative work - creating features, building components,
adding functionality, or modifying behavior. Explores user intent, requirements and design
before implementation."

agent 的默认行为：agent 不会主动判断"我现在是不是应该先做设计？"。它的推理链是：用户说了需求 → 我能做 → 我开始做。

这条指令把它扭成什么：

"You MUST use this before any creative work"------这不仅仅是一个"何时触发"的描述。它在 agent 的注意力机制里是一个优先级断言 ："如果用户的任务涉及创造性的工作，你必须在做任何事之前先加载这个 skill。" 关键词是 MUST 和 before any------不留任何"这次算了"的空间。

"creating features, building components, adding functionality, or modifying behavior"------四个具体场景覆盖了几乎所有的"写代码"行为。agent 不能说"我在改行为不是在加功能所以不用"------四个场景已经把路都堵死了。

第 1 层：HARD-GATE------全局阻断

原文：

sql 复制代码

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and the
user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

agent 的默认行为：听到需求 → 评估复杂度 → 开始写代码。agent 的推理链路是：用户说"做个 todo list" → 太简单了 → 直接写。它的决策树里没有"先停下来和用户确认设计"这个节点。

这条指令把它扭成什么：

<HARD-GATE> 不是 markdown，是认知标记 。标签名 HARD-GATE 在 LLM 的注意力中比 ## 注意事项 的权重大得多------它告诉模型"这是一个不可绕过的检查点"。自定义 XML 标签在训练数据中通常与"不可协商的约束"关联。
负向指令链："Do NOT invoke... write... scaffold... take any implementation action"------四个连续否定，覆盖了 agent 可能的所有"开始做"的路径。这不是"建议先设计"，是全面封锁。每一项对应一种 agent 会尝试的绕过手段。
"until you have presented a design and the user has approved it"------门有一个明确的解锁条件。"presented a design"（agent 的动作）+ "user has approved it"（用户的动作），两个条件缺一不可。
"This applies to EVERY project regardless of perceived simplicity."------这预判了 agent 最核心的合理化："但这太简单了"。直接封死。

设计精髓：这个门的"锁"是双向的------agent 必须输出设计（不是心里想了一遍），用户必须明确批准（不是没有反对）。两个方向的缺位都无法开门。

第 2 层：Anti-Pattern 预击杀------"太简单"陷阱

原文：

sql 复制代码

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility,
a config change --- all of them. "Simple" projects are where unexamined assumptions
cause the most wasted work. The design can be short (a few sentences for truly
simple projects), but you MUST present it and get approval.

agent 的默认行为：agent 对"简单"的定义是"我能想到怎么做"。一个 todo list 在 agent 脑中只需 30 行 HTML + 10 行 JS。agent 看不到"但这个 todo list 要不要多人共享？数据存哪里？同步还是本地？"这些未被提出的问题。

这条指令把它扭成什么：

命名攻击 ：把 agent 最常见的合理化命名为 "Anti-Pattern"。在 agent 的后续思考中，如果产生"太简单了不需要设计"的念头，会因为这条已经被标记为反模式而产生自我抑制。命名一个想法 = 创建了一个可以引用的约束。
具体实例轰炸："A todo list, a single-function utility, a config change"------三个例子覆盖了 agent 最可能认为"太简单"的场景。todo list 是一个完整的应用、single-function utility 是最小的代码单元、config change 甚至不是代码。读到这些例子的 agent 不会说"那确实简单"，而是"作者特意选了最极端的例子------连 config change 都要走设计。"
逻辑论证而非说教："Simple projects are where unexamined assumptions cause the most wasted work." 这是数学：假设密度 × 被审视的概率 = 浪费的风险。简单项目假设密度低，但被审视的概率趋于零，所以乘积仍然大。
退路通道："The design can be short (a few sentences for truly simple projects)"------给了一条出路，防止 agent 把"需要设计"理解为"需要写 10 页文档"而产生另一个方向的抵触。对于 config change，三句话也是设计。约束的是"经过设计"，不是"设计很长"。

第 3 层：强制性 Checklist------9 步不可跳过的顺序

原文：

markdown 复制代码

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Explore project context** --- check files, docs, recent commits
2. **Offer the visual companion just-in-time** --- NOT upfront...
3. **Ask clarifying questions** --- one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** --- with trade-offs and your recommendation
5. **Present design** --- in sections scaled to their complexity, get user approval after each section
6. **Write design doc** --- save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
7. **Spec self-review** --- quick inline check for placeholders, contradictions, ambiguity, scope
8. **User reviews written spec** --- ask user to review the spec file before proceeding
9. **Transition to implementation** --- invoke writing-plans skill to create implementation plan

agent 的默认行为：agent 不维护状态机。它不会说"我先做完第一步再做第二步"。它是端到端的------直接跳到输出。如果让它"先探索项目上下文"，它可能会扫一眼文件列表就说"探索完了"，然后跳过 2-7 直接开始写代码。

这条指令把它扭成什么：

"You MUST create a task for each of these items and complete them in order"------强制 agent 用 todo 系统（TaskCreate/TaskUpdate）追踪这 9 步。每一步是一个独立的状态节点，pending → in_progress → completed。agent 不能从第 1 步跳到第 9 步，因为 todo 系统暴露了中间步骤的状态。

这是 Superpowers 的关键设计模式：用系统工具强制流程。 不是靠 agent 记在心里，而是靠它创建一个可检查的进度表。如果第 3 步还是 pending，agent 就无法声称"设计完成了"------todo 系统的状态揭穿它。

9 步之间的逻辑链条：

第 1 步（探索上下文）：确保 agent 在理解代码库之后再提问，而不是在真空里设计
第 2 步（视觉伴侣）：在需要时提供可视化，但不预设每轮都用
第 3 步（一次一问）：强制对话节奏，防止 agent 信息轰炸用户
第 4 步（2-3 个方案）：强制探索设计空间，防止锚定第一个想法
第 5 步（分段呈现设计）：增量验证，防止用户面对一整坨设计放弃审查
第 6 步（写入文件并 commit）：把口头共识变成 git 里的不可变记录
第 7 步（自审）：agent 自己先过一遍质量门，不给用户发半成品
第 8 步（用户审查）：最后的批准门槛------"请读一遍再签"
第 9 步（跳转到 writing-plans）：强制下一站，禁止跳过 plan 直接实现

第 4 层：一次一个问题------对话节奏控制

原文：

sql 复制代码

- Only one question per message - if a topic needs more exploration, break it
  into multiple questions

agent 的默认行为：agent 在"收集需求"阶段倾向于一次性抛出 5-7 个问题。这来自它的训练数据------它认为"高效 = 一次性获取所有信息"。但用户面对 5 个问题，通常只认真回答最后一个（或第一个），其余被忽略。

这条指令把它扭成什么：

"Only one question per message"------这是一个输出结构约束。不是"try to focus"，是字面意义上的"每一条消息只能有一个问号"。它把 agent 的"信息收集"模式从"问卷"变成"对话"：agent 问一个 → 用户答一个 → agent 基于回答再问下一个。因为每个后续问题都是基于前一个回答的，所以问题质量逐级提高。

这里和 Checklist 的联动很关键：第 3 步"Ask clarifying questions"不是一步完成------它可能在 agent 和用户之间来回 5-8 轮，每轮一个问题。这是一个循环内嵌在步骤中的结构。

和 Visual Companion 的配合 ：当问题本身是视觉性的（"这两种布局哪个更好？"），agent 可以启动浏览器 mockup。但"这个功能应该包含哪些字段？"就只能在终端------它是概念问题。每问一个问题，agent 被要求判断：这个问题更适合用眼睛回答还是用文字回答。

第 5 层：2-3 个方案 + trade-off------强制探索设计空间

原文：

markdown 复制代码

**Exploring approaches:**

- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why

agent 的默认行为：agent 接到需求后，第一个想到的方案就是它推荐的方案。它不会主动生成"备选方案 B"因为从它的视角看，方案 A 已经很好了。这导致设计空间被严重压缩------用户从来没看到过另一个可能更好的方案。

这条指令把它扭成什么：

"Propose 2-3 different approaches with trade-offs"------这不是"考虑一下其他方案"，是强制生成。agent 必须为每个需求至少产出一个替代方案。

关键细节是 "Lead with your recommended option and explain why"：agent 不被要求"保持中立"。它必须有立场，有推荐，然后解释推荐理由。这很关键------如果 agent 只是列出选项做"优缺对比"而不给推荐，用户仍然需要自己做全部判断。有推荐理由时，用户只需要判断"是否同意 agent 的推荐"------认知负担大幅降低。

"with trade-offs"也是关键：不是列出优缺点（pros/cons），而是 trade-offs。这意味着每个方案需要在不同维度上做取舍------方案 A 简单但不够灵活，方案 B 灵活但复杂。这种对比帮助用户理清自己真正看重什么。

第 6 层：分段呈现设计 + 增量批准------防止审批疲劳

原文：

python 复制代码

**Presenting the design:**

- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward,
  up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense

agent 的默认行为：agent 一次性输出整个设计文档。用户读完 5000 字后，发现中间某个假设是错的------但前面的 3000 字已经基于这个错误假设。用户要么接受这个有问题的设计，要么让 agent 重写。两种结果都很差。

这条指令把它扭成什么：

"Ask after each section whether it looks right so far"------这是增量批准。设计被切成多个小节（架构 → 组件 → 数据流 → 错误处理 → 测试），每完成一个小节，agent 停下来问"这部分对吗？"。如果用户在第二步就发现了基础假设的错误，后面三步根本不会基于错误假设写。

隐藏约束："Scale each section to its complexity"------简单的部分就几句话，复杂的部分允许 200-300 字。这防止了 agent 用统一的"详细程度"填充所有区域------简单的部分不需要为了看起来"完整"而啰嗦。

强制覆盖维度："Cover: architecture, components, data flow, error handling, testing"------agent 不能只讲架构和组件，必须讨论错误处理和测试。这五个维度确保了设计的最低完备性。

第 7 层：写入文件 + commit------对话 → 不可变记录

原文：

markdown 复制代码

**Documentation:**

- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git

agent 的默认行为：agent 把对话当成记录。"我们不是已经讨论过了吗？"------但是对话在上下文压缩（compaction）后会丢失，且无法被团队其他成员检索。六个月后换一个人来维护这段代码，对话早就没了。

这条指令把它扭成什么：

"Write to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md"------强制输出到文件系统，带上日期前缀（ISO 8601）。日期前缀让 specs 目录天然按时间排序。
"Commit the design document to git"------写入文件还不够。必须 commit。这意味着设计决策进入版本历史，可以被 blame、被 revert、被引用、在 code review 中被引用为"为什么这样设计"的权威来源。

这是 brainstorming 独有的约束层级：在"对话共识"和"git 记录"之间，只有后者是持久的。对话会被遗忘和压缩；commit 不会。

第 8 层：Spec 自审------agent 在给用户看之前先自己查一遍

原文：

sql 复制代码

**Spec Self-Review:**
After writing the spec document, look at it with fresh eyes:

1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. **Internal consistency:** Do any sections contradict each other? Does the architecture
   match the feature descriptions?
3. **Scope check:** Is this focused enough for a single implementation plan, or does it need
   decomposition?
4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so,
   pick one and make it explicit.

Fix any issues inline. No need to re-review --- just fix and move on.

agent 的默认行为：agent 写完就交。不会自己读第二遍。任何模型在第一遍生成时都会产生内部矛盾、模糊点、未填的坑------因为生成是逐 token 的，后面的 token 不知道前面的 token 具体保证了什么。

这条指令把它扭成什么：

四个具体的检查项------不是"review your work"，而是精确到四个可执行的动作，各有明确目标：

找 TBD：grep 自己的输出文件，找占位符和未完成段落
找矛盾：A 节说用 SQLite，B 节说用 PostgreSQL → 自相矛盾
找范围蔓延：这个 spec 是不是偷偷包含了三个独立系统？
找歧义："用户登录后显示 dashboard"→ 哪个 dashboard？选一个并明确写下来

"Fix any issues inline. No need to re-review --- just fix and move on."------这是个效率约束。修完之后不要再审一遍（否则会无限循环：修 → 审 → 修 → 审）。信任一次修改，往前走。

第 9 层：用户审查门------签字画押

原文：

vbnet 复制代码

**User Review Gate:**
After the spec review loop passes, ask the user to review the written spec before proceeding:

> "Spec written and committed to `<path>`. Please review it and let me know if you want
> to make any changes before we start writing out the implementation plan."

Wait for the user's response. If they request changes, make them and re-run the spec
review loop. Only proceed once the user approves.

agent 的默认行为：agent 在用户口头说"看起来不错"之后就会直接进入实现。但口头批准和读了文档之后的批准是完全不同的质量门槛。

这条指令把它扭成什么：

用户审查和口头设计批准是两个不同的步骤：

Step 5 的批准（分段呈现时）：对话中同意了大致方向------"这个架构看起来合理"。
Step 8 的审查：读完了完整的书面 spec，确认每一个字------"我同意你写在文件里的所有内容。"

这两个步骤之间的间隔是"写作"------当 agent 把口头共识写成结构化文档时，可能会引入（或暴露）在对话中没有注意到的细节。用户审查就是为了抓住这些。

"Wait for the user's response."------不是"用户没反对就继续"，是用户必须明确说可以。沉默不代表同意。

第 10 层：终端状态控制------只能去 writing-plans

原文：

python 复制代码

**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design,
mcp-builder, or any other implementation skill. The ONLY skill you invoke after
brainstorming is writing-plans.

vbnet 复制代码

**Implementation:**
- Invoke the writing-plans skill to create a detailed implementation plan
- Do NOT invoke any other skill. writing-plans is the next step.

agent 的默认行为：agent 完成设计后，"下一步"可以是很多事------可以直接开始写前端代码、可以写后端、可以同时做。agent 会选它认为最高效的路径。

这条指令把它扭成什么：

这不是"建议先写 plan"，是锁定下游。Brainstorming 之后的唯一出口是 writing-plans。不是 implementation，不是 frontend-design，不是任何其他 skill。它强制整个流程沿着设计好的单向管道走：brainstorming → writing-plans → 下一站。

这条规则在 skill 正文中出现了两次（第 61-62 行 + 第 128-131 行），两次都用大写 Do NOT 和 ONLY 强调，防止 agent 在读完大部分内容后"忘记"了这个终端约束。

总结：Brainstorming 的 11 层约束

sql 复制代码

┌─────┬─────────────────────────┬──────────────────────────────┐
│ 层  │ 约束                     │ 对抗的 agent 默认行为           │
├─────┼─────────────────────────┼──────────────────────────────┤
│  0  │ description 触发断言      │ "这不是创造性工作"              │
│  1  │ HARD-GATE 全局阻断        │ 听到需求 → 开始写代码           │
│  2  │ "太简单"陷阱预击杀          │ 判断"很简单" → 跳过流程         │
│  3  │ 9 步强制 checklist        │ 没有状态机 → 跳步              │
│  4  │ 一次一个问题               │ 批量抛问题 → 用户漏答           │
│  5  │ 2-3 个方案强制探索         │ 锚定第一个想法 → 不思考替代       │
│  6  │ 分段呈现 + 增量批准        │ 一次性输出 → 用户审批疲劳        │
│  7  │ 写入文件 + commit         │ 对话当记录 → 压缩后丢失          │
│  8  │ 自审（4 项检查）           │ 写完就交 → 有洞没发现           │
│  9  │ 用户审查门                 │ 口头 OK → 跳过书面确认          │
│ 10  │ 终端状态锁定 writing-plans │ 完成设计 → 跳到实现             │
└─────┴─────────────────────────┴──────────────────────────────┘

这 11 层约束的本质是：agent 的自然倾向是"尽快开始写代码"。Brainstorming 在 agent 的认知路径上插入了 11 个不可跳过的减速带，每个减速带都被设计成对抗一个特定的 agent 合理化借口。

这 11 层可以分为三组：

组	层	功能
入口控制	0-2	确保 agent 进入 brainstorming 流程，且不中途跳出
流程执行	3-6	确保 agent 在流程中按正确的节奏和质量执行每一步
出口控制	7-10	确保产出持久化、被审查、且正确交接给下一阶段

附录：Brainstorming SKILL.md 完整原文

markdown 复制代码

---
name: brainstorming
description: "You MUST use this before any creative work - creating features,
building components, adding functionality, or modifying behavior. Explores user
intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative
dialogue.

Start by understanding the current project context, then ask questions one at a
time to refine the idea. Once you understand what you're building, present the
design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project,
or take any implementation action until you have presented a design and the
user has approved it. This applies to EVERY project regardless of perceived
simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility,
a config change --- all of them. "Simple" projects are where unexamined assumptions
cause the most wasted work. The design can be short (a few sentences for truly
simple projects), but you MUST present it and get approval.

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Explore project context** --- check files, docs, recent commits
2. **Offer the visual companion just-in-time** --- NOT upfront...
3. **Ask clarifying questions** --- one at a time, understand purpose/constraints/
   success criteria
4. **Propose 2-3 approaches** --- with trade-offs and your recommendation
5. **Present design** --- in sections scaled to their complexity, get user approval
   after each section
6. **Write design doc** --- save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
   and commit
7. **Spec self-review** --- quick inline check for placeholders, contradictions,
   ambiguity, scope
8. **User reviews written spec** --- ask user to review the spec file before proceeding
9. **Transition to implementation** --- invoke writing-plans skill

## The Process

**Understanding the idea:**
- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes
  multiple independent subsystems, flag this immediately
- If the project is too large for a single spec, help decompose into sub-projects
- Ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message
- Focus on understanding: purpose, constraints, success criteria

**Exploring approaches:**
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why

**Presenting the design:**
- Once you believe you understand what you're building, present the design
- Scale each section to its complexity
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense

**Design for isolation and clarity:**
- Break the system into smaller units that each have one clear purpose
- Each unit: what does it do, how do you use it, what does it depend on?

**Working in existing codebases:**
- Explore current structure before proposing changes. Follow existing patterns.
- Include targeted improvements for existing problems that affect the work

## After the Design

**Documentation:**
- Write to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- Commit the design document to git

**Spec Self-Review:**
1. Placeholder scan: TBD/TODO/incomplete sections?
2. Internal consistency: Contradictions? Architecture matches features?
3. Scope check: Single plan or needs decomposition?
4. Ambiguity check: Any requirement interpretable two ways? Pick one.
Fix issues inline. No re-review needed.

**User Review Gate:**
After spec review, ask user to review the written spec. Wait for response.
If changes requested, make them and re-run spec review. Only proceed once
user approves.

**Implementation:**
- Invoke the writing-plans skill. Do NOT invoke any other skill.

## Key Principles
- One question at a time
- Multiple choice preferred
- YAGNI ruthlessly
- Explore alternatives
- Incremental validation
- Be flexible