| name | harness-brainstorm |
| description | 头脑风暴技能,在实现前探索用户意图、需求和设计,防止返工 |
| trigger_words | ["harness-brainstorm","头脑风暴","brainstorm","设计讨论","需求澄清"] |
| priority | MEDIUM |
| dependencies | ["harness-init"] |
| version | v3.0.0 |
harness-brainstorm 头脑风暴技能
核心能力
- 检查前置条件(harness-init已完成)
- 探索项目上下文(文件、文档、最近提交)
- 读取
.EnjoyHarness/CONFIG.md,决定头脑风暴是否需要用户参与
- 在自治模式下自动完成需求澄清、方案推断和设计冻结
- 在协作模式下逐一提出澄清问题(一次一个问题)并组织单次最终需求确认
- 编写设计文档(保存到docs/plans/)
- 触发计划编写(harness-plan)
前置条件
- harness-init 已完成
- Git仓库已初始化
执行步骤
Step 1: 检查前置条件
使用 Read 工具读取:.EnjoyHarness/SKILL_REGISTRY.md
检查条件:
如果未完成:
❌ 错误: 系统未初始化
💡 请先运行: harness-init
Step 2: 探索项目上下文
使用 Bash 工具执行:
ls -la
cat README.md CLAUDE.md EnjoyHarness_MANIFEST.md 2>/dev/null | head -100
git log --oneline -10
git status
目的:
- 了解项目当前状态
- 识别现有架构和约束
- 理解技术栈和依赖
Step 2.5: 读取 brainstorm 参与配置
使用 Read 工具读取:.EnjoyHarness/CONFIG.md
读取字段:
brainstorm_user_participation: {true|false}
规则:
- 如果字段不存在,默认视为
false
false:保持现状,走全自动 brainstorm 模式
true:允许用户参与需求头脑风暴;完成一次最终确认后立即切回自治执行
Step 3: 执行需求澄清 / 头脑风暴
模式 A: 全自动 brainstorm(默认)
当 brainstorm_user_participation: false 或未配置时:
- 不向用户发起头脑风暴问题
- 基于用户原始需求、
harness-goal 产物、README、现有代码和约束自动推断需求细节
- 主动列出关键假设、风险和默认取舍
- 直接生成 2-3 种方案并给出推荐
- 生成设计文档后直接冻结
.EnjoyHarness/EXECUTION_CONTRACT.md
confirmation_source 记为 harness-brainstorm-autonomous
模式 B: 用户参与 brainstorm(显式开启)
当 brainstorm_user_participation: true 时:
- 允许用户参与需求表达、澄清和头脑风暴
- 仍然遵循“一次只问一个问题”
- 完成一次最终需求确认后,立即冻结自治执行契约
confirmation_source 记为 harness-brainstorm-user
协作模式强制规则:一次只问一个问题
自治边界规则:
- 只有在
brainstorm_user_participation: true 时,才允许用户参与需求表达、澄清和头脑风暴。
- 一旦达到“需求已充分明确,可进入设计冻结”的状态,必须收敛为一次最终确认。
- 最终确认完成后,不再在后续技能里向用户请求执行方式、恢复方式或任务级确认。
协作模式的问题类型:
- 目的澄清:为什么需要这个功能?解决什么问题?
- 约束澄清:有什么技术或业务约束?
- 成功标准:如何衡量成功?有哪些验收条件?
- 范围澄清:包含什么?不包含什么?
- 优先级澄清:最重要的功能是什么?
协作模式的问题格式示例:
🎯 问题1: 这个功能的主要目的是什么?
A) 解决性能瓶颈
B) 添加新功能
C) 重构现有代码
D) 其他(请说明)
💡 提示:选择最符合你需求的选项,或提供自定义答案
Step 4: 提出2-3种方案
当收集足够信息后,提出方案:
## 方案对比
### 方案A: [方案名称](推荐)
**优点**:
- 优点1
- 优点2
**缺点**:
- 缺点1
**适用场景**:场景描述
### 方案B: [方案名称]
**优点**:
- 优点1
**缺点**:
- 缺点1
- 缺点2
### 方案C: [方案名称]
(如果有第三个方案)
---
**推荐方案A的理由**:
- 理由1
- 理由2
在全自动 brainstorm 模式下,必须额外输出:
- 自动推断的需求假设
- 未显式说明但被默认采用的约束
- 为什么当前推荐方案在缺少用户补充的情况下仍是最稳妥选择
Step 5: 展示设计方案
设计文档结构:
# [功能名称] 设计文档
## 概述
(一句话描述)
## 架构设计
(分层架构图、组件关系)
## 核心组件
(每个组件的职责)
## 数据流
(数据如何流转)
## 错误处理
(如何处理错误)
## 测试策略
(如何测试)
最终确认 / 冻结流程:
- 汇总“概述 / 架构设计 / 核心组件 / 数据流 / 错误处理 / 测试策略”
- 如果
brainstorm_user_participation: true
- 如果
brainstorm_user_participation: false
- 直接将当前设计视为自治模式下的冻结版本,不额外等待用户确认
- 冻结
.EnjoyHarness/EXECUTION_CONTRACT.md
- 后续进入无人值守执行,不再逐节向用户请求批准
Step 6: 编写设计文档
使用 Write 工具创建文件:docs/plans/{YYYY-MM-DD}-{topic}-design.md
文件命名示例:
docs/plans/2026-03-28-user-auth-design.md
docs/plans/2026-03-28-payment-integration-design.md
内容结构:
---
created: {TIMESTAMP}
status: draft
version: v1.0.0
---
# [功能名称] 设计文档
## 背景
(为什么需要这个功能)
## 目标
(SMART目标)
## 方案概述
(选定的方案及其理由)
## 架构设计
(详细架构)
## 组件设计
(每个组件的详细设计)
## 数据模型
(数据结构和关系)
## API设计
(接口定义)
## 错误处理
(错误处理策略)
## 测试策略
(测试计划)
## 风险与缓解
(识别的风险及缓解措施)
## 实施计划
(后续实施步骤,由harness-plan细化)
Step 6.5: 冻结自治执行契约
使用 Edit 工具更新:.EnjoyHarness/EXECUTION_CONTRACT.md
将以下字段写入或更新为:
mode: autonomous_after_confirmation
requirements_confirmed: true
brainstorm_user_participation: {true|false}
confirmation_source: {harness-brainstorm-user|harness-brainstorm-autonomous}
execution_mode: parallel_session
resume_policy: auto_continue
retry_policy: retry_3_then_recover
human_escalation_policy: true_blockers_only
说明:
- 这是“需求澄清结束、系统接管执行”的正式边界。
brainstorm_user_participation: false 时,代表用户选择了全自动 brainstorm,不再需要额外确认。
brainstorm_user_participation: true 时,代表用户参与只发生在 brainstorm 阶段,之后自动切回无人值守。
- 从此刻起,系统默认继续自动执行,直到交付或遇到真实阻塞。
Step 7: 提交设计文档
使用 Bash 工具执行:
git add docs/plans/{YYYY-MM-DD}-{topic}-design.md
git commit -m "docs: add {topic} design document
- Add design document for {feature name}
- Cover architecture, components, data model
- Include error handling and testing strategy
- Generated by harness-brainstorm"
Step 8: 触发下游技能
使用 Edit 工具追加到:.EnjoyHarness/EVENT_LOG.md
事件内容:
{TIMESTAMP} | SKILL_COMPLETE | harness-brainstorm | 设计文档完成 - {topic} | SUCCESS
{TIMESTAMP} | TRIGGER_DOWNSTREAM | harness-plan | 触发计划编写 | PENDING
Step 9: 输出完成信息
使用 Bash 工具输出:
echo ""
echo "✅ harness-brainstorm 完成!"
echo ""
echo "📋 设计文档:"
echo " - 文件: docs/plans/{YYYY-MM-DD}-{topic}-design.md"
echo " - 状态: 已提交"
echo ""
echo "🎯 下一步:"
echo " - 运行 harness-plan 创建实施计划"
echo " - 或使用 harness-auto-full-execution 自动执行全流程"
echo ""
成功标准
失败兜底
- 协作模式下用户不满意方案 → 返回Step 4,重新提出方案
- 协作模式下用户不满意设计细节 → 返回Step 5,修改设计并重新做最终确认
- 技术约束冲突 → 返回Step 3,重新澄清约束
- 自治模式下需求仍存在关键歧义 → 记录假设并继续;仅真实阻塞时触发
harness-escalate-to-human
- 协作模式下无法达成一致 → 触发
harness-escalate-to-human
联动关系
- 触发时机:用户提出新功能需求,需要设计讨论
- 上游技能:harness-init(必须先初始化)
- 下游技能:harness-plan(设计完成后自动触发)
- 并行技能:无(设计阶段需要串行执行)
设计文档质量检查
设计文档必须包含以下部分:
关键原则
- 一次一个问题 - 不要一次性问多个问题
- 多选优于开放 - 尽量提供选项,降低用户回答难度
- YAGNI原则 - 坚决移除不必要的功能
- 探索替代方案 - 总是提出2-3种方案再决定
- 单次冻结 - 在需求充分明确后做一次最终确认并冻结自治契约
- 保持灵活 - 随时准备返回澄清模糊点
- 默认全自动 - 如果未显式开启
brainstorm_user_participation: true,则默认不进入用户参与式 brainstorm
反模式:太简单不需要设计
错误观念:"这个功能很简单,不需要设计"
正确做法:每个项目都经过头脑风暴流程。即使是单个函数、配置修改,也需要设计。设计可以很简短;在自治模式下可直接冻结,在协作模式下再由用户做一次最终确认。
原因:
- "简单"项目往往隐藏最多未审视的假设
- 简单设计只需几句话,但能避免大量返工
- 设计过程本身价值远大于文档
迭代计数
本技能执行预计迭代次数:约 15-20 次
- Bash 探索项目:3-5次
- 逐一提问循环:5-10次
- Write 设计文档:1次
- Edit EVENT_LOG:2次
- Git提交:2次
示例流程
示例:添加用户认证功能
Step 1: 探索项目
ls -la
cat CLAUDE.md
git log --oneline -5
Step 2-3: 逐一提问
🎯 问题1: 用户认证的主要目的是什么?
A) 替换现有的认证系统
B) 添加新的认证方式(如OAuth)
C) 增强现有认证的安全性
D) 其他
用户选择: B
🎯 问题2: 需要支持哪些OAuth提供商?
A) GitHub
B) Google
C) 微信
D) 以上全部
用户选择: D
(继续提问直到信息充分)
Step 4: 提出方案
## 方案对比
### 方案A: 使用现有OAuth库(推荐)
**优点**:
- 成熟稳定,社区支持好
- 开发速度快
- 安全性有保障
**缺点**:
- 定制性较差
- 依赖第三方库
**适用场景**:标准OAuth流程,无特殊定制需求
### 方案B: 自研OAuth实现
**优点**:
- 完全可控
- 可深度定制
**缺点**:
- 开发周期长
- 安全风险高
**推荐方案A的理由**:
- 项目时间紧,需要快速上线
- 标准OAuth流程满足需求
- 安全性比自研更有保障
Step 5: 展示设计
# 用户OAuth认证设计文档
## 概述
为现有用户系统添加GitHub、Google、微信OAuth认证,使用成熟OAuth库实现。
## 架构设计
(架构图)
## 核心组件
1. OAuthController - 处理OAuth回调
2. OAuthService - OAuth业务逻辑
3. UserRepository - 用户数据访问
(最终需求确认:✅)
...
Step 6: 编写文档
Write to: docs/plans/2026-03-28-user-oauth-design.md
Step 7: 提交
git add docs/plans/2026-03-28-user-oauth-design.md
git commit -m "docs: add user OAuth authentication design"
Step 8: 触发下游
2026-03-28T16:00:00 | SKILL_COMPLETE | harness-brainstorm | 设计文档完成 - user-oauth | SUCCESS
2026-03-28T16:00:00 | TRIGGER_DOWNSTREAM | harness-plan | 触发计划编写 | PENDING
参考
- EnjoyHarness设计文档 -
docs/plans/2026-03-28-enjoyharness-design-v3.md