# 调研团队

> 组建调研团队，通过多 Agent 协作完成调研→撰稿→审核的全流程，最终产出一份基于一手资料反推的策划案或设计文档。当用户提到"调研"、"反推策划案"、"整理系统设计"、"分析模块实现"、"产出设计文档"、"组建调研团队"等意图时，主动使用此 Skill。即使用户只说"帮我看看 XX 模块是怎么实现的，整理成文档"，也应触发。

- Skill: `nuonuo0518/skill-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nuonuo0518/skill-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nuonuo0518/skill-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nuonuo0518 (https://skillmd.com/u/nuonuo0518)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nuonuo0518/skill-2

---


# 调研团队 Skill

通过组建一个多 Agent 调研团队（1~N 个调研员 + 1 个撰稿人 + 1 个审稿人），基于代码仓库或其他一手资料来源，产出一份结构完整、参数有据可查、术语一致的策划案/设计文档。

## 核心理念

这个 Skill 的价值在于：**调研员负责挖掘一手素材并附上引用，撰稿人负责组织成面向非技术读者的策划视角文档，审稿人负责交叉验证事实准确性**。三个角色各司其职，形成信息的"采集→加工→质检"流水线。

撰稿人在写作过程中如果遇到信息缺口，可以随时向调研员发起补充调研请求，而不是凭空猜测——这是保证"有据可查"的关键机制。

---

## 阶段零：环境检查（首次触发时执行）

Agent Teams 功能依赖环境变量 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`。在开始收集信息之前，先检查是否已启用。

### 0. 上下文窗口提示

调研团队全流程会涉及大量素材传递和多轮交互，上下文占用较大。在一切开始之前，先提醒用户：

> 💡 **建议**：调研团队工作流程会产生大量素材和文档内容，建议使用 **1M 上下文窗口** 的模型（如 Opus 1M）来开启本次会话，以减少中途触发上下文压缩的次数，避免丢失重要的调研素材和对话上下文。
>
> 如果当前不是 1M 上下文模型，可以考虑先切换后再继续。

用 AskUserQuestion 确认：

```
问题：当前模型的上下文窗口可能不足以支撑完整调研流程，建议使用 1M 上下文模型（如 Opus 1M）。是否继续？
选项：
- 继续，我已经在用 1M 上下文模型
- 继续，我接受可能触发压缩的风险
- 暂停，我先切换模型再回来
```

如果用户选择暂停，则结束本次 Skill 执行，等用户切换后重新触发。

### 检查步骤

1. **确定全局配置目录**：按优先级依次检查：
   - `~/.claude-internal/settings.json`（优先）
   - `~/.claude/settings.json`（备选）

   使用 Read 工具尝试读取，以第一个存在的为准。

2. **检查 Agent Teams 是否启用**：在找到的 settings.json 中查找 `env` 字段是否包含 `"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"`。

3. **如果未启用**：
   - 告知用户："调研团队功能需要启用 Agent Teams 实验特性，当前尚未启用。"
   - 用 AskUserQuestion 询问：
     ```
     问题：是否立即启用 Agent Teams 功能？
     选项：
     - 是，帮我启用（推荐）
     - 不，稍后手动处理
     ```
   - 如果用户同意，使用 Edit 工具在 settings.json 的 `env` 字段中添加 `"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"`。如果 `env` 字段不存在，创建它。
   - 启用后提示用户：**需要重启 Claude Code 会话才能生效**。Skill 流程在此中断，等用户重启后再次触发。

4. **如果已启用**：静默通过，直接进入阶段一。

---

## 阶段一：信息收集（团队创建前）

在创建团队和分配任务之前，需要先和用户明确所有前置定义。**每次只问一个问题**，问完等用户回答后再问下一个。如果问题的答案可以用少量选项覆盖，使用 AskUserQuestion 工具。

### 必须明确的信息（按顺序逐一收集）

#### 1. 目标与验收标准

**严格分两次提问，问完第一个等用户回答后再问第二个，不可合并。**

**第一问：调研目标**

直接以文本形式询问调研目标，展示样例帮助用户理解格式：

> 请告诉我这次调研的**目标**是什么？
>
> **样例参考：**
> 产出一份基于项目当前实现情况反推的交易行系统策划案（策划视角，设计为主，不引入过多技术实现细节）

等用户回答后，再问第二个问题。

**第二问：验收标准**

直接以文本形式询问验收标准，展示样例帮助用户理解格式：

> 请告诉我**验收标准**是什么？（怎样算完成？）
>
> **样例参考：**
> 结构完整，参数内容都基于实际实现有据可查，术语一致。最终产出物同步到指定目录。

#### 2. 调研员数量与定义

**严格按以下顺序逐一提问，每次只问一个问题，等用户回答后再问下一个。**

##### 第一步：询问调研员数量

用 AskUserQuestion 询问需要几个调研员：

```
问题：需要几个调研员？
选项：
- 1 个
- 2 个
- 3 个
```

##### 第二步：逐个定义每个调研员

确定数量后，从调研员 1 开始，**逐个**完成以下两个问题（完成一个调研员的全部定义后，再开始下一个）：

**问题 2a：调研来源范围**（文本提问，不使用 AskUserQuestion）

直接以文本形式询问，不要在问题中预设或展示具体的仓库路径作为示例：

> 请告诉我**调研员 [N]** 的调研来源范围（如代码仓库路径、文档目录、网站等）。

**问题 2b：使用模型**（用户回答来源范围后，再用 AskUserQuestion 询问）

```
问题：调研员 [N]（[用户刚才回答的来源范围简述]）使用什么模型？
选项：
- Haiku（推荐，速度快成本低，适合代码搜索和文件扫描）
- Sonnet（更强的理解能力，适合复杂分析）
- Opus（最强推理能力，适合需要深度判断的场景）
```

默认推荐 Haiku。

**循环**：完成调研员 [N] 的 2a + 2b 后，如果还有下一个调研员，继续问调研员 [N+1] 的 2a，然后 2b，依此类推，直到所有调研员都定义完毕。

#### 3. 撰稿人定义确认

展示默认撰稿人定义，问用户是否需要调整：

> **默认撰稿人定义：**
> - 基于调研员的素材清单撰写文档初稿
> - 以策划/设计文档视角撰写，不过度涉及技术实现细节
> - 所有参数必须基于素材有据可查，不可编造
> - 遵循统一术语表（如果有的话）
> - 写作过程中遇到信息缺口，可随时向调研员发起补充调研请求

用 AskUserQuestion 询问：

```
问题：撰稿人使用默认定义吗？
选项：
- 使用默认定义（推荐）
- 我要自定义调整
```

#### 4. 审稿人定义确认

展示默认审稿人定义，问用户是否需要调整：

> **默认审稿人定义：**
> - 只读角色，不直接修改文档
> - 检查维度：事实准确性、逻辑连贯性、术语一致性
> - 产出：问题清单（位置 + 原文 + 修改建议 + 严重程度）

用 AskUserQuestion 询问：

```
问题：审稿人使用默认定义吗？
选项：
- 使用默认定义（推荐）
- 我要自定义调整
```

#### 5. 团队规则确认

展示默认流程规则，问用户是否需要调整：

> **默认团队规则：**
> 1. 调研员先并行完成素材清单
> 2. Lead 确认素材完整后启动撰稿人
> 3. 撰稿人写初稿（过程中可向调研员请求补充调研）
> 4. 初稿完成后启动审稿人
> 5. 审稿人产出问题清单（只读不改）
> 6. 撰稿人根据问题清单修订
> 7. 最终文档确认交付

用 AskUserQuestion 询问：

```
问题：团队工作流程使用默认规则吗？
选项：
- 使用默认规则（推荐）
- 我要自定义调整
```

#### 6. 产出位置

问用户最终文档保存到哪里。

---

## 阶段二：创建团队和任务

收集完所有前置信息后，按以下步骤执行：

### 2.1 创建团队

使用 TeamCreate 创建团队，team_name 基于调研主题生成有意义的名称（如 `trading-house-research`）。

### 2.2 创建任务并设置依赖

按以下模板创建任务：

| 任务 | 依赖 | 说明 |
|------|------|------|
| 调研员 1 素材收集 | 无 | 第一个调研员的任务 |
| 调研员 2 素材收集 | 无 | 第二个调研员的任务（如有） |
| ... | ... | 更多调研员（如有） |
| 撰写初稿 | 所有调研任务 | 撰稿人任务，blocked by 所有调研任务 |
| 审核初稿 | 撰写初稿 | 审稿人任务，blocked by 撰写初稿 |

如果后续需要修订，动态追加修订任务。

### 2.3 启动调研员

**并行**启动所有调研员（使用 Agent 工具），每个调研员：
- 使用用户指定的模型（默认 haiku）
- 加入团队（team_name 参数）
- 收到详细的调研指令，包含：
  - 调研来源范围
  - 调研重点（基于目标推导）
  - 产出格式要求：每条素材需包含**文件路径/来源链接** + **模块分类** + **关键内容摘要** + **重要代码片段或配置值**
  - 完成后标记任务完成并发送素材清单给 team lead

---

## 阶段三：调研员工作

### Lead 的职责

- 等待所有调研员完成
- 收到素材清单后做初步审视：
  - 覆盖面是否足够
  - 有没有明显遗漏的模块
- 如果有遗漏，向对应调研员发送补充调研指令
- 全部确认后，标记调研任务完成，解除撰稿任务的阻塞

---

## 阶段四：撰稿

### 启动撰稿人

使用 Agent 工具启动撰稿人，传入：
- 所有素材清单（直接嵌入 prompt 或指向素材文件路径）
- 用户的目标和验收标准
- 术语表路径（如果有）
- 产出文件路径
- 文档结构建议（基于素材内容推导章节结构）

### 关键机制：撰稿人向调研员请求补充调研

在撰稿人的 prompt 中明确告知：

> 写作过程中如果发现素材不够详细或有信息缺口，可以通过 SendMessage 向调研员请求补充调研：
> - [调研员名称]：负责 [来源范围]
>
> 给调研员发消息时说明你需要什么具体信息，他们会帮你查找并回复。

Lead 在撰稿人启动后也发一条通知，确认撰稿人知道调研员可用。

---

## 阶段五：审核

### 启动审稿人

撰稿人完成初稿后，启动审稿人。审稿人使用 Explore subagent_type（只读权限）：

- 阅读初稿文档
- 阅读素材清单
- 阅读术语表（如有）
- **回到源码/源数据进行交叉验证**（这是审稿人的核心价值）
- 产出问题清单，每个问题包含：
  - 位置（章节 + 行号范围）
  - 类型（事实错误 / 逻辑问题 / 术语不一致 / 内容缺失）
  - 原文引用
  - 问题描述
  - 修改建议
  - 严重程度（🔴 严重 / 🟡 中等 / 🟢 轻微）

---

## 阶段六：修订

### 将问题清单转化为修订指令

Lead 收到审稿人的问题清单后：
1. 汇总展示给用户
2. 创建修订任务
3. 向撰稿人发送修订指令，逐条列出需要修改的内容
4. 撰稿人修订后，Lead 验证最终文档

---

## 阶段七：交付与收尾

1. 阅读最终文档确认质量
2. 向用户汇报最终成果：
   - 文档位置
   - 章节概览
   - 关键参数一览
   - 质量保障说明（审核通过的问题数、修订情况）
3. **团队清理**：向所有队友发送 shutdown_request，然后尝试 TeamDelete 清理团队。
   - 由于队友进程的关闭是异步的，TeamDelete 可能因"仍有活跃成员"而失败——这是正常现象。
   - **不要反复重试 TeamDelete**。如果第一次失败，直接告知用户：

   > 📋 调研任务已全部完成，文档已交付。团队队友正在异步关闭中，如果需要立即清理团队资源，可以告诉我"清理团队"，我会帮您手动删除团队配置和任务目录。

   - 当用户显式要求清理时，使用 PowerShell/Bash 手动删除团队目录：
     - `~/.claude-internal/teams/<team-name>/`
     - `~/.claude-internal/tasks/<team-name>/`

---

## 调研员 Prompt 模板

```
你是 [角色名]。你的任务是调研 [来源范围] 中与 [主题] 相关的实现/内容。

**调研范围：** [具体路径或来源]

**调研重点：**
[基于目标推导的 5-7 个调研维度]

**调研方法：**
- 使用 Grep 搜索关键词如：[相关关键词列表]
- 使用 Glob 查找相关文件
- 使用 Read 阅读关键文件内容

**产出格式：**
每条素材需要包含：
- 文件路径（完整路径）或来源链接
- 模块/功能分类
- 关键内容摘要
- 重要的代码片段或配置值

完成后通过 TaskUpdate 标记任务完成，并通过 SendMessage 将素材清单发送给 team lead。
```

## 撰稿人 Prompt 模板

```
你是撰稿人。基于调研员提供的素材清单撰写 [文档类型]。

## 写作定位
- 以策划/设计文档视角撰写，不过度涉及技术实现细节
- 读者是 [目标读者]
- 所有参数必须基于素材有据可查，不可编造

## 目标
[用户定义的目标]

## 验收标准
[用户定义的验收标准]

## 文档结构
[基于素材推导的章节结构]

## 素材来源
[素材清单内容或文件路径]

## 术语表
[术语表路径，如有]

## 重要：补充调研机制
写作过程中如果发现素材不够详细或有信息缺口，可以通过 SendMessage 向调研员请求补充调研：
[列出各调研员名称和负责范围]

## 产出
保存到 [产出路径]
完成后通过 TaskUpdate 标记任务完成，并通过 SendMessage 通知 team lead。
```

## 审稿人 Prompt 模板

```
你是审稿人（只读角色），负责审核 [文档名] 的质量。

**审核文件**: [文档路径]
**素材来源**: [素材清单路径列表]
**术语表**: [术语表路径，如有]

**审核维度**（按优先级）:

### 1. 事实准确性（最重要）
逐一核实文档中的关键参数和数值是否与源码实现一致。
[列出需要核实的关键数据点和对应的源文件路径]

### 2. 逻辑连贯性
- 文档结构是否清晰合理
- 章节之间是否有逻辑断层
- 流程描述是否完整

### 3. 术语一致性
- 是否使用了统一术语
- 同一概念是否在不同位置使用了不同名称

### 4. 完整性
- 是否有素材中提到但文档未覆盖的重要内容

**产出格式：**
每个问题包含：位置、类型、原文、问题描述、修改建议、严重程度（🔴/🟡/🟢）

注意：你是只读角色，不要修改任何文件。
通过 SendMessage 将问题清单发送给 team lead。
```

---

## 注意事项

- 调研员可以使用较便宜的模型（haiku），因为主要是搜索和摘录工作
- 撰稿人和审稿人建议使用更强的模型（默认继承 Lead 的模型）
- 审稿人使用 `subagent_type: Explore`（只读权限），确保不会误改文件
- 多个调研员必须并行启动，不要串行等待
- Lead 在流程中扮演"信息中转站"和"质量把关"的角色