[SuperPower] Brainingstorm - 流程控制架构分析

Brainstorming - 流程控制架构分析

核心发现

brainstorming技能通过三个相互关联的章节构建了完整的流程控制架构：

Checklist：9步强制流程的骨架
Process Flow：可视化决策逻辑的脉络
The Process：详细执行指南的血肉

这三个章节构成了一个三层架构的质量保证体系。

1. Checklist：强制性的9步流程

核心特点

"MUST create a task for each"：每个步骤都必须创建任务
"complete them in order"：必须按顺序完成
强制性的质量检查点：9个步骤包含3个关键审查点

9步流程的深度分析

markdown 复制代码

# 流程的演进逻辑

阶段1：探索与理解 (步骤1-3)
1. **Explore project context** - 查看项目现状
2. **Offer visual companion** - 准备视觉工具（可选）
3. **Ask clarifying questions** - 一问一式理解需求

阶段2：设计与验证 (步骤4-5)  
4. **Propose 2-3 approaches** - 提出多种方案
5. **Present design** - 分块呈现设计，获得批准

阶段3：文档化与审查 (步骤6-8)
6. **Write design doc** - 写入设计文档并提交
7. **Spec self-review** - 自动自我审查
8. **User reviews written spec** - 用户审查

阶段4：过渡实现 (步骤9)
9. **Transition to implementation** - 调用writing-plans技能

关键设计原则

渐进式细化：

从宏观（项目上下文）到微观（具体设计）
从发散（多种方案）到收敛（最终设计）
从思考到文档化

强制性质量门控：

每个主要阶段结束都有审查点
3个关键批准点：设计批准、文档完成、用户确认
任何一步不通过都可以回到前一阶段

2. Process Flow：可视化的决策逻辑

流程图的精妙设计

yes
no
no revise
yes
changes requested
approved
Explore project context
Visual questions ahead
Offer Visual Companion

own message no other content
Ask clarifying questions
Propose 2-3 approaches
Present design sections
User approves design
Write design doc
Spec self-review

fix inline
User reviews spec
Invoke writing-plans skill

流程图的关键特性

1. 条件分支的精确控制：

"Visual questions ahead?" - 可选的视觉伴侣路径
两个关键的质量判断节点

2. 迭代循环的设计：

设计阶段可以返回修改（no, revise）
文档阶段可以再次修改（changes requested）
允许必要的返工，但控制在合理范围内

3. 终点状态的强制：

明确说明终点必须是invoking writing-plans
禁止调用其他实现技能
确保流程的一致性

3. The Process：细节执行的完整指南

Understanding the idea：理解阶段

Explore project context：项目上下文探索

探索什么？：

markdown 复制代码

# 三大探索维度

**文件结构 (files)**
- 项目根目录的组织方式
- 主要源码目录（src/、lib/、components/等）
- 配置文件（package.json、tsconfig.json等）
- 测试目录结构

**文档资源 (docs)**
- README.md 和项目说明
- API文档或设计文档
- CONTRIBUTING.md 等贡献指南
- 现有的设计规范或风格指南

**最近变更 (recent commits)**
- 最近10-20次提交的摘要
- 主要的开发分支和活跃状态
- 最近的架构或重大变更
- 代码质量和提交模式

探索结果承载到哪里？：

1. 内部上下文窗口 ：

探索结果主要存储在LLM的上下文窗口中，作为后续生成回答的参考。但由于Token限制，这种存储有以下特点：

早期探索结果可能被压缩或遗忘
需要通过关键信息优先保存策略来应对
无法在会话外保持状态

2. 结构化暂存（理论机制）：

python 复制代码

# 内部上下文构建
project_context = {
    "structure": {
        "type": "monorepo/microservice/single-app",
        "framework": "React/Vue/Angular/Node.js",
        "architecture": "MVC/Feature-based/Layered"
    },
    "patterns": {
        "naming_convention": "kebab-case/PascalCase",
        "file_organization": "feature-based/layer-based",
        "state_management": "Redux/Vuex/Context"
    },
    "constraints": {
        "tech_stack": "已知使用的技术栈",
        "dependencies": "现有依赖和版本限制",
        "architecture_decisions": "已做的技术决策"
    },
    "recent_activity": {
        "commits": "最近的主要变更",
        "issues": "活跃的问题和修复",
        "trends": "开发趋势和重点"
    }
}

3. 对话中的逐步构建：

通过探索-澄清循环逐步积累信息
每轮探索后通过问题确认理解
将关键信息融入后续对话中

探索结果的内部处理

信息提取和结构化

python 复制代码

# 内部信息处理流程
def process_exploration_results(file_contents, directory_structure, git_history):
    # 1. 提取项目类型
    project_type = detect_project_type(file_contents)

    # 2. 识别技术栈
    tech_stack = identify_tech_stack(file_contents)

    # 3. 分析架构模式
    architecture_pattern = analyze_patterns(directory_structure, file_contents)

    # 4. 构建上下文模型
    context = {
        "type": project_type,
        "tech_stack": tech_stack,
        "architecture": architecture_pattern,
        "constraints": extract_constraints(file_contents),
        "recent_changes": summarize_git_history(git_history)
    }

    return context

Token限制下的管理策略

markdown 复制代码

# 探索结果的管理
1. **关键信息优先**
   - 项目类型和主要技术
   - 目录结构概览
   - 最近重要变更

2. **细节按需提供**
   - 具体文件内容只在被询问时提供
   - 配置细节保留引用
   - 代码片段选择性展示

3. **渐进式深化**
   - 初始探索只获取高层信息
   - 通过问题逐步深入了解
   - 保持上下文窗口效率

如何确保探索全面？：

1. 结构化检查清单：

markdown 复制代码

- 项目类型识别（前端/后端/全栈）
- 技术栈完整性（框架、库、工具）
- 目录结构分析（标准目录是否存在）
- 配置文件覆盖（构建、测试、代码规范）

2. 智能体内部验证机制：

markdown 复制代码

# 检查是否遗漏关键目录（如src/、tests/、docs/）
# 验证项目类型识别是否准确
# 确认技术栈信息是否完整
# 评估最近变更的相关性

3. 上下文完整性检查：

markdown 复制代码

> "Have I seen enough to understand:
> - What kind of project this is?
> - What technologies it uses?
> - How it's organized?
> - Recent development patterns?"

4. 探索-澄清循环的完整性保障：

markdown 复制代码

# 循环机制
探索 → 建立模型 → 提出问题 → 获得答案 → 更新模型 → 重复

# 具体示例
初始请求：
用户："我需要个登录功能"

第1轮探索：
智能体探索项目结构，发现：
- Next.js + TypeScript
- Prisma ORM
- PostgreSQL数据库
- Tailwind CSS

第1轮澄清：
智能体："基于你的技术栈，认证方案选择：
A. NextAuth.js（专为Next.js设计）
B. 自建JWT系统
C. 传统表单提交 + Session"

# 循环的价值
1. **精准性**：基于实际情况提问，不是泛泛而谈
2. **效率**：避免提出无关或不可能的问题
3. **教育性**：用户了解技术选项和权衡

项目范围评估

识别大型子系统的信号：

markdown 复制代码

- "build a platform with chat, file storage, billing, and analytics"
- 多个独立的业务领域
- 不同的数据模型或存储需求
- 独立的用户群体或使用场景

处理策略：

立即标记：This needs to be decomposed
引导用户：What's the most important piece to start with?
分解项目：建立依赖关系图，确定实施顺序

Exploring approaches：方案探索

方案探索的深度解析

markdown 复制代码

# 超越简单的方案列举
不是问"你想要什么方案"，而是：
1. 基于项目上下文，提出2-3个可行的技术方案
2. 每个方案都考虑项目的约束和模式
3. 明确对比每个方案的优缺点
4. 推荐最适合的方案并解释理由

方案设计的精妙之处

1. 数量控制：为什么是2-3个？

markdown 复制代码

**2个方案太少**
- 无法展示权衡的复杂性
- 可能遗漏最佳选择
- 容易陷入非此即彼的思维

**3个方案是理想选择**
- 展示设计思维的广度
- 提供清晰的最佳/中等/保守选择
- 便于对比trade-offs

**4个方案太多**
- 增加认知负担
- 决策变得复杂
- 可能引入不切实际的选项

2. 方案类型的设计模式

markdown 复制代码

**保守型方案（Safe Choice）**
- 使用现有技术栈
- 最小风险，易于实现
- 扩展性可能有限

**平衡型方案（Recommended）**
- 结合新成熟技术
- 适当的创新和风险
- 良好的扩展性

**创新型方案（Aggressive）**
- 采用前沿技术
- 最大创新和性能
- 较高学习曲线和风险

Presenting the design：设计呈现

分块呈现策略

markdown 复制代码

# 根据复杂度调整呈现规模
**简单设计**（几句话）：
- 用户认证使用JWT
- 状态管理使用Context API
- 路由由React Router处理

**复杂设计**（200-300字）：
**架构概述**：
采用分层架构，分为API层、业务逻辑层、数据访问层。API层使用RESTful设计，业务逻辑层采用领域驱动设计（DDD），数据访问层使用Repository模式。

**组件设计**：
主要组件包括AuthContainer（认证容器）、LoginForm（登录表单）、Dashboard（仪表盘）。使用React Hooks管理状态，通过Context API实现状态共享。

**数据流**：
用户登录 → 表单验证 → 调用API → 更新状态 → 重定向到仪表盘。错误处理通过全局错误捕获机制实现。

具体提案示例

认证方案提案：

markdown 复制代码

# 认证方案选择

基于您的项目（Next.js + TypeScript），我建议以下三种方案：

**方案1：保守型（Safe Choice）- 传统表单提交**
- 使用：HTML表单 + Session管理
- 优点：简单易实现，风险低
- 缺点：功能有限，安全性一般

**方案2：平衡型（Recommended）- NextAuth.js**
- 使用：NextAuth.js库
- 优点：与Next.js深度集成，功能丰富
- 缺点：需要学习新库

**方案3：创新型（Aggressive）- 自建JWT系统**
- 使用：自建JWT认证系统
- 优点：完全定制，高性能
- 缺点：开发复杂，风险高

您倾向于哪种方案？

状态管理提案：

markdown 复制代码

# 状态管理方案选择

基于您的项目，状态管理方案：

**方案1：保守型 - Context API**
- 使用：React Context API
- 优点：简单，内置功能
- 缺点：复杂应用管理困难

**方案2：平衡型 - Redux Toolkit**
- 使用：Redux Toolkit
- 优点：标准化，工具丰富
- 缺点：需要额外学习

**方案3：创新型 - Zustand**
- 使用：Zustand库
- 优点：轻量，API简单
- 缺点：相对较新

增量验证机制

markdown 复制代码

# 每个部分都需要确认
> "这个架构设计看起来合理吗？"

# 基于反馈调整
用户确认 → 进入下一部分
用户质疑 → 解释或修改

# 价值
1. **及时纠错**：避免设计方向的重大偏差
2. **用户参与**：增强用户对设计的认同感
3. **降低风险**：每个小模块都经过验证

Design for isolation and clarity

隔离性原则：

每个模块应该独立工作
最小化模块间的依赖
清晰的接口定义

清晰性原则：

设计应该易于理解
接口应该明确
命名应该有意义

实际应用：

markdown 复制代码

# 设计隔离性检查

**组件隔离**：
- AuthContainer是否独立于其他组件？
- LoginForm是否可以被独立测试？
- Dashboard是否依赖于具体的认证实现？

**接口清晰**：
- 认证接口是否清晰定义？
- 数据流是否容易理解？
- 错误处理是否明确？

4. Superpower的智能探索机制

核心探索策略

智能探索策略：

分层探索：先进行高层探索，再根据需要深入
按需探索：根据用户需求动态调整探索深度
针对性探索：专注于与当前任务相关的部分

项目分解机制

对于大型项目，Superpower会：

识别关键子系统：自动识别项目的主要组成部分
确定优先级：询问用户最重要的部分优先处理
分阶段处理：将大型项目分解为可管理的部分

探索-澄清循环

Superpower采用探索-澄清循环：

markdown 复制代码

探索 → 建立模型 → 提出问题 → 获得答案 → 更新模型 → 重复

这个循环确保：

不会遗漏关键信息
探索深度适应项目复杂度
用户参与确保准确性

用户反馈整合

在探索过程中，Superpower会：

主动询问确认：确保理解正确
根据反馈调整：如果用户指出遗漏，可以补充探索
迭代改进：通过对话逐步完善理解

Token优化策略

Superpower会：

优先保存关键信息：确保重要信息不丢失
按需加载细节：避免信息过载
智能摘要：将复杂信息简化为关键要点

探索工具的局限性

Superpower在探索时主要依赖以下内置工具：

Read：读取文件内容
Glob：文件模式匹配
Grep：内容搜索
Bash：执行基本shell命令

探索范围：

✅ 文件结构和组织方式
✅ 配置文件内容
✅ 代码模式和组织架构
✅ Git历史和最近变更
❌ 不能运行项目或执行测试
❌ 不能创建或修改文件

4+1视图的适用性评估

为什么不采用完整4+1视图：

Token成本过高
- 完整视图需要约14,000 tokens
- 占用上下文窗口7%，挤压设计空间
边际效益递减
- 基础探索（1,300 tokens）：60%价值
- 部分视图（3,000 tokens）：80%价值
- 完整视图（14,000 tokens）：95%价值
- 最后11,000 tokens仅带来15%价值提升
信息过载
- 过多文档反而降低效率
- 挤占方案对比和用户反馈空间
- 增加认知负担

智能探索策略：

分层探索
- 核心文档（~1,000 tokens）：项目类型、技术栈、结构概览
- 扩展文档（~2,000 tokens）：主要组件关系、核心业务流程
- 完整文档（仅在必要时）：完整的4+1视图
按需探索

根据用户需求动态决定探索深度和范围
可视化精简

使用图表、表格代替大量文字描述

5. 信息持久化与复用

持久化必要性

Superpower的上下文窗口有限，需要持久化重要信息：

避免重复探索：大型项目中重复探索效率低
保持信息一致性：确保后续工作基于准确信息
支持长期项目：跨会话保持项目状态

持久化策略

核心限制：不调用其他技能写代码/脚手架

从/brainstorming skill中可以看到明确的限制：

复制代码

**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.**

探索依靠的内置工具：

1. 基础文件操作工具

Read：读取文件内容
- 读取配置文件（package.json, tsconfig.json）
- 查看代码文件内容
- 阅读文档（README.md, API文档）
Glob：文件模式匹配
- **/*.js：查找所有JavaScript文件
- src/components/*：查找组件目录
- config/*：查找配置文件
Grep：内容搜索
- 查找特定关键词或代码模式
- 分析项目架构和设计模式
- 识别使用的库和框架

2. 系统命令工具

Bash ：执行基本shell命令
- ls -la：查看目录结构
- git log --oneline -10：查看最近提交
- find . -name "*.json"：查找特定类型文件
- cat package.json | head -20：查看依赖信息

可以探索的内容：

markdown 复制代码

✅ 文件结构和组织方式
✅ 配置文件内容
✅ 代码模式和组织架构
✅ Git历史和最近变更
✅ 项目文档和说明
✅ 依赖关系和技术栈

不能探索的内容：

markdown 复制代码

❌ 运行时行为（不能运行项目）
❌ 性能特征（不能执行测试）
❌ 复杂的业务逻辑（只能静态分析）
❌ 不能创建或修改文件
❌ 不能生成代码实现
❌ 不能执行构建命令

手动保存与复用：

markdown 复制代码

# 项目信息保存策略

## 目录结构
docs/
├── project-info/
│   ├── project-exploration-report.md  # 项目探索报告
│   ├── key-decisions.md             # 关键决策记录
│   └── design-rationale.md          # 设计理由

具体实施方案：

方案1：手动保存与复用

第一次对话 - 探索并保存：

复制代码

用户：请帮我探索这个项目，然后把探索结果完整保存到一个文件中

系统：[使用Superpower的工具执行探索]
1. 用 Bash 查看目录结构
2. 用 Read 读取 package.json
3. 用 Glob 查找主要文件
4. 用 Grep 了解技术栈
5. 用 Bash 查看Git历史

[探索完成后]

系统：探索完成！我现在将结果保存到文件中。
[使用Write工具创建文件]

文件名：project-exploration-report.md
位置：当前目录下的 docs/project-info/

文件内容示例：

markdown 复制代码

# 项目探索报告
生成时间：2026-04-16 10:30

## 目录结构

H:/

└── code/

└── superpowers/

├── 5.0.7/

│ ├── skills/

│ ├── tests/

│ └── docs/

├── CLAUDE.md

└── README.md

复制代码

## 技术栈
- 项目类型：技能开发框架
- 主要语言：TypeScript
- 构建工具：未知（需要检查package.json）
- 版本控制：Git

## 重要文件
- CLAUDE.md：项目配置
- 5.0.7/skills/：技能目录
- docs/：文档目录

## 最近变更
- 最新提交：feat: add new skill
- 开发状态：活跃

第二次对话 - 复用：

复制代码

用户：在之前探索的项目基础上，添加一个新的技能功能

系统：在开始之前，我先加载之前保存的项目信息。
[使用Read工具读取文件]

Read "./docs/project-info/project-exploration-report.md"
✅ 已加载项目探索报告

基于已保存的信息，这是一个技能开发框架，主要包含：
- 技能目录：5.0.7/skills/
- 配置文件：CLAUDE.md
- 已有技能数量：[统计数量]

现在开始设计新技能...

方案2：项目状态文件

创建特殊的配置文件告诉SuperPower直接使用已有信息：

markdown 复制代码

# 创建 .project-state.md

# 项目探索状态
status: "explored"
last_exploration: "2026-04-16"
skip_future_exploration: true

# 项目概览
project_type: "Skill Development Framework"
main_technologies: ["TypeScript", "Node.js"]
architecture: "Modular skills system"
key_constraints:
  - Zero-dependency design
  - Follow existing skill patterns
  - Store specs in docs/superpowers/specs/

# 告诉SuperPower直接使用这些信息
instruction: "Use this information instead of re-exploring the project"

方案3：在CLAUDE.md中添加配置

markdown 复制代码

## SuperPower Configuration
Project exploration status: Already completed
Skip re-exploration: true
Cached context:
  - Type: Skill Development Framework
  - Tech: TypeScript, Node.js
  - Architecture: Modular skills
  - Last updated: 2026-04-16
Instruction: Use this context directly, no re-exploration needed

自动保存机制：

探索完成后自动保存关键信息
创建标准化的报告格式
添加时间戳和版本信息

复用机制

信息加载：

设计阶段自动加载已保存的信息
验证信息有效性
提供信息摘要

信息更新：

检测信息过期
提醒更新
保持信息最新

Token消耗分析

不同探索策略的Token消耗：

markdown 复制代码

**当前策略（基础探索）**
- 目录结构：~500 tokens
- 技术栈：~300 tokens
- 最近变更：~500 tokens
总计：~1,300 tokens

**完整4+1视图**
- 所有视图详细描述：~14,000 tokens
- 占用：大量token，减少设计空间

**保存+复用策略**
- 首次探索：~1,300 tokens + 写入文件
- 后续复用：~200 tokens（读取文件摘要）
- 节省：每次节省1,100 tokens (85%)

6. 设计原则与质量保证

核心设计原则

单一责任原则

每个系统单元都应该明确回答：

做什么：What does it do?
如何使用：How do you use it?
依赖什么：What does it depend on

边界清晰性的标准：

能否在不读取内部代码的情况下理解功能
能否修改内部实现而不影响使用者
接口是否清晰定义

接口设计特征

明确性：参数和返回值清晰定义
稳定性：向后兼容，不轻易改变
完整性：覆盖所有使用场景
简洁性：避免过度设计

现有代码工作原则

探索优先原则：

先Explore project context
Follow existing patterns
Identify problematic areas
Include targeted improvements
Stay focused on current goal

改进策略识别：

文件过大（>1000行）
边界不清（职责混乱）
依赖复杂（耦合度高）

改进原则：

最小化干预：只修改必要的部分
保持一致性：遵循现有模式
渐进式重构：不破坏现有功能
文档化变更：记录所有改动

质量保证机制

三层架构协同

Checklist（骨架）
- 9个强制性步骤
- 质量检查点
- 进度追踪
Process Flow（脉络）
- 步骤间的逻辑关系
- 决策分支
- 循环迭代
The Process（血肉）
- 每步的详细执行指南
- 心理学技巧
- 最佳实践

三重质量门控

设计质量：User approves design
- 确保设计满足需求
- 获得用户明确认可
文档质量：Spec self-review
- 确保设计可执行
- 检查完整性和一致性
实现准备：User reviews spec
- 确保用户和实现者理解一致
- 最后的质量确认

7. Working in existing codebases：在现有代码库中工作

核心工作原则

遵循现有代码模式

识别架构模式：了解项目的组织方式和设计模式
遵循代码约定：遵循项目的命名规范、目录结构等
重用现有组件：重用现有代码和组件

最小化干扰原则

避免破坏现有功能：确保新设计不会影响现有代码
渐进式改进：只修改必要的部分
保持一致性：遵循现有代码的风格和模式

工作流程

探索现有代码

识别代码结构：了解代码库的组织方式
理解架构约束：识别项目的架构限制
发现代码模式：识别项目的编码规范和设计模式

识别改进机会

问题区域识别：找出需要改进的代码部分
改进策略制定：设计改进方案
兼容性评估：确保改进与现有代码兼容

实施改进

最小化干预：只修改必要的部分
保持一致性：遵循现有代码的风格
文档化变更：记录所有改动

约束和限制

在现有代码库中工作意味着：

技术栈限制：必须使用项目已有的技术栈
架构限制：必须符合项目的架构模式
依赖关系：必须考虑现有代码的依赖关系

实际应用

当用户要求在现有代码库中添加新功能时，/brainstorming skill会：

探索现有代码库的结构和模式
识别新功能应该放在哪里
设计与现有代码兼容的方案
确保新功能不会破坏现有功能
遵循项目的代码规范和约定

这样，skill能够在现有代码库中有效地工作，而不是从零开始创建新项目。

8. 核心价值总结

流程控制架构的核心价值

brainstorming技能通过三层架构构建了完整的质量保证体系：

强制性流程设计
- Checklist确保每个步骤都执行
- Process Flow提供清晰的决策路径
- The Process提供详细的执行指南
- 三重质量门控确保输出质量
智能探索机制
- 在工具限制下最大化探索效果
- 通过探索-澄清循环确保理解准确性
- 渐进式信息积累避免Token浪费
实用主义设计哲学
- 避免过度工程化的4+1视图
- 按需探索策略平衡深度与效率
- 持久化方案实现探索结果复用

实际应用中的优势

质量保证
- 每个阶段都有明确的审查点
- 设计获得用户批准后才进入实现
- 文档化过程确保设计可执行
效率优化
- 探索结果可持久化和复用
- Token使用效率最大化
- 避免重复和不必要的探索
用户体验
- 渐进式设计过程降低认知负担
- 多选项设计提供清晰的选择路径
- 分块呈现确保设计理解准确

这种架构设计确保了即使在复杂项目中，也能通过系统化的流程获得高质量的设计方案，同时保持良好的性能和用户体验。通过合理的探索策略和持久化机制，Superpower能够在有限的Token资源下实现最大的开发价值。