# Harness Brainstorm

> 头脑风暴技能，在实现前探索用户意图、需求和设计，防止返工

- Skill: `konglong87/harness-brainstorm` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-brainstorm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-brainstorm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-brainstorm

---


# harness-brainstorm 头脑风暴技能

## 核心能力
1. 检查前置条件（harness-init已完成）
2. 探索项目上下文（文件、文档、最近提交）
3. 读取 `.EnjoyHarness/CONFIG.md`，决定头脑风暴是否需要用户参与
4. 在自治模式下自动完成需求澄清、方案推断和设计冻结
5. 在协作模式下逐一提出澄清问题（一次一个问题）并组织单次最终需求确认
6. 编写设计文档（保存到docs/plans/）
7. 触发计划编写（harness-plan）

## 前置条件
- harness-init 已完成
- Git仓库已初始化

## 执行步骤

### Step 1: 检查前置条件

使用 Read 工具读取：`.EnjoyHarness/SKILL_REGISTRY.md`

检查条件：
- harness-init 已标记为完成

如果未完成：
```
❌ 错误: 系统未初始化
💡 请先运行: harness-init
```

### Step 2: 探索项目上下文

使用 Bash 工具执行：

```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`

读取字段：
```yaml
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. **目的澄清**：为什么需要这个功能？解决什么问题？
2. **约束澄清**：有什么技术或业务约束？
3. **成功标准**：如何衡量成功？有哪些验收条件？
4. **范围澄清**：包含什么？不包含什么？
5. **优先级澄清**：最重要的功能是什么？

协作模式的问题格式示例：
```
🎯 问题1: 这个功能的主要目的是什么？

A) 解决性能瓶颈
B) 添加新功能
C) 重构现有代码
D) 其他（请说明）

💡 提示：选择最符合你需求的选项，或提供自定义答案
```

### Step 4: 提出2-3种方案

当收集足够信息后，提出方案：

```markdown
## 方案对比

### 方案A: [方案名称]（推荐）
**优点**：
- 优点1
- 优点2

**缺点**：
- 缺点1

**适用场景**：场景描述

### 方案B: [方案名称]
**优点**：
- 优点1

**缺点**：
- 缺点1
- 缺点2

### 方案C: [方案名称]
（如果有第三个方案）

---

**推荐方案A的理由**：
- 理由1
- 理由2
```

在全自动 brainstorm 模式下，必须额外输出：
- 自动推断的需求假设
- 未显式说明但被默认采用的约束
- 为什么当前推荐方案在缺少用户补充的情况下仍是最稳妥选择

### Step 5: 展示设计方案

设计文档结构：

```markdown
# [功能名称] 设计文档

## 概述
（一句话描述）

## 架构设计
（分层架构图、组件关系）

## 核心组件
（每个组件的职责）

## 数据流
（数据如何流转）

## 错误处理
（如何处理错误）

## 测试策略
（如何测试）
```

**最终确认 / 冻结流程**：
1. 汇总“概述 / 架构设计 / 核心组件 / 数据流 / 错误处理 / 测试策略”
2. 如果 `brainstorm_user_participation: true`
   - 由用户进行一次最终需求与方案确认
3. 如果 `brainstorm_user_participation: false`
   - 直接将当前设计视为自治模式下的冻结版本，不额外等待用户确认
4. 冻结 `.EnjoyHarness/EXECUTION_CONTRACT.md`
5. 后续进入无人值守执行，不再逐节向用户请求批准

### 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`

内容结构：
```markdown
---
created: {TIMESTAMP}
status: draft
version: v1.0.0
---

# [功能名称] 设计文档

## 背景
（为什么需要这个功能）

## 目标
（SMART目标）

## 方案概述
（选定的方案及其理由）

## 架构设计
（详细架构）

## 组件设计
（每个组件的详细设计）

## 数据模型
（数据结构和关系）

## API设计
（接口定义）

## 错误处理
（错误处理策略）

## 测试策略
（测试计划）

## 风险与缓解
（识别的风险及缓解措施）

## 实施计划
（后续实施步骤，由harness-plan细化）
```

### Step 6.5: 冻结自治执行契约

使用 Edit 工具更新：`.EnjoyHarness/EXECUTION_CONTRACT.md`

将以下字段写入或更新为：

```yaml
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 工具执行：

```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`

事件内容：
```markdown
{TIMESTAMP} | SKILL_COMPLETE | harness-brainstorm | 设计文档完成 - {topic} | SUCCESS
{TIMESTAMP} | TRIGGER_DOWNSTREAM | harness-plan | 触发计划编写 | PENDING
```

### Step 9: 输出完成信息

使用 Bash 工具输出：

```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 ""
```

## 成功标准
- [ ] 设计文档已创建
- [ ] 设计文档已提交到Git
- [ ] 协作模式下用户已完成单次最终需求确认，或自治模式下已完成自动冻结
- [ ] `.EnjoyHarness/EXECUTION_CONTRACT.md` 已冻结为自治模式
- [ ] 事件已记录到EVENT_LOG.md
- [ ] 下游技能已触发

## 失败兜底
- 协作模式下用户不满意方案 → 返回Step 4，重新提出方案
- 协作模式下用户不满意设计细节 → 返回Step 5，修改设计并重新做最终确认
- 技术约束冲突 → 返回Step 3，重新澄清约束
- 自治模式下需求仍存在关键歧义 → 记录假设并继续；仅真实阻塞时触发 `harness-escalate-to-human`
- 协作模式下无法达成一致 → 触发 `harness-escalate-to-human`

## 联动关系
- 触发时机：用户提出新功能需求，需要设计讨论
- 上游技能：harness-init（必须先初始化）
- 下游技能：harness-plan（设计完成后自动触发）
- 并行技能：无（设计阶段需要串行执行）

## 设计文档质量检查

设计文档必须包含以下部分：
- [ ] 背景和目标
- [ ] 方案概述（包含对比）
- [ ] 架构设计
- [ ] 组件设计
- [ ] 数据模型（如适用）
- [ ] API设计（如适用）
- [ ] 错误处理策略
- [ ] 测试策略
- [ ] 风险识别
- [ ] 实施计划概述

## 关键原则

1. **一次一个问题** - 不要一次性问多个问题
2. **多选优于开放** - 尽量提供选项，降低用户回答难度
3. **YAGNI原则** - 坚决移除不必要的功能
4. **探索替代方案** - 总是提出2-3种方案再决定
5. **单次冻结** - 在需求充分明确后做一次最终确认并冻结自治契约
6. **保持灵活** - 随时准备返回澄清模糊点
7. **默认全自动** - 如果未显式开启 `brainstorm_user_participation: true`，则默认不进入用户参与式 brainstorm

## 反模式：太简单不需要设计

**错误观念**："这个功能很简单，不需要设计"

**正确做法**：每个项目都经过头脑风暴流程。即使是单个函数、配置修改，也需要设计。设计可以很简短；在自治模式下可直接冻结，在协作模式下再由用户做一次最终确认。

**原因**：
- "简单"项目往往隐藏最多未审视的假设
- 简单设计只需几句话，但能避免大量返工
- 设计过程本身价值远大于文档

## 迭代计数

本技能执行预计迭代次数：约 15-20 次
- Bash 探索项目：3-5次
- 逐一提问循环：5-10次
- Write 设计文档：1次
- Edit EVENT_LOG：2次
- Git提交：2次

## 示例流程

### 示例：添加用户认证功能

**Step 1: 探索项目**
```bash
ls -la
# 发现是Go项目，已有用户模型
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: 提出方案**
```markdown
## 方案对比

### 方案A: 使用现有OAuth库（推荐）
**优点**：
- 成熟稳定，社区支持好
- 开发速度快
- 安全性有保障

**缺点**：
- 定制性较差
- 依赖第三方库

**适用场景**：标准OAuth流程，无特殊定制需求

### 方案B: 自研OAuth实现
**优点**：
- 完全可控
- 可深度定制

**缺点**：
- 开发周期长
- 安全风险高

**推荐方案A的理由**：
- 项目时间紧，需要快速上线
- 标准OAuth流程满足需求
- 安全性比自研更有保障
```

**Step 5: 展示设计**
```markdown
# 用户OAuth认证设计文档

## 概述
为现有用户系统添加GitHub、Google、微信OAuth认证，使用成熟OAuth库实现。

## 架构设计
（架构图）

## 核心组件
1. OAuthController - 处理OAuth回调
2. OAuthService - OAuth业务逻辑
3. UserRepository - 用户数据访问

（最终需求确认：✅）

...
```

**Step 6: 编写文档**
```bash
Write to: docs/plans/2026-03-28-user-oauth-design.md
```

**Step 7: 提交**
```bash
git add docs/plans/2026-03-28-user-oauth-design.md
git commit -m "docs: add user OAuth authentication design"
```

**Step 8: 触发下游**
```markdown
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`