investigation-workflow

调查工作流技能

用途

此技能提供了一个系统化的 6 阶段工作流，用于调查和理解现有系统、代码库和架构。与针对实现进行优化的开发工作流不同，此工作流专为探索、理解和知识记录而设计。

何时使用此技能

调查任务（使用此工作流）：

• “调查身份验证系统的工作原理”
• “解释 neo4j 记忆集成”
• “了解 CI 为何总是失败”
• “分析反思系统架构”
• “研究会话启动时会触发哪些钩子”

开发任务（改用 DEFAULT_WORKFLOW.md）：

• “实现 OAuth 支持”
• “构建新的 API 端点”
• “添加功能 X”
• “修复 Bug Y”

核心理念

先探索：在深入代码之前定义范围和策略
并行深入调查：同时部署多个 Agent，以高效收集信息
必须验证：通过实际应用检验理解
记录知识：记录调查结果，避免重复调查

6 阶段调查工作流

阶段 1：定义范围

目的：在开始探索前，定义调查边界和成功标准。

任务：

• 首先：确定用户的明确要求——必须回答哪些具体问题？
• 使用 prompt-writer Agent 明确调查范围
• 如果问题不明确，使用 ambiguity Agent
• 定义何为“已充分理解”
• 列出必须回答的具体问题
• 设定边界：哪些内容属于范围，哪些不属于
• 估算所需的调查深度（浅层了解还是深入调查）

成功标准：

• 有待回答问题的清晰列表
• 已定义范围边界
• 可衡量的成功标准（例如，“能够解释系统流程”“能够绘制架构图”）

交付内容：

• 调查范围文档，包含：
  • 需要回答的核心问题
  • 成功标准
  • 范围边界（包含/不包含的内容）
  • 预计深度和时间安排

阶段 2：制定探索策略

目的：规划要部署哪些 Agent 以及需要调查哪些内容，避免低效的随机探索。

任务：

• 使用 architect Agent 设计探索策略
• 使用 patterns Agent 检查是否有类似的既往调查
• 确定要探索的关键领域（代码路径、配置、文档）
• 选择在阶段 3 中并行部署的专业 Agent
• 制定包含优先级的调查路线图
• 确定需要避开的潜在死胡同
• 规划验证方法（如何检验理解）

Agent 选择指南：

• 理解代码：analyzer、patterns Agent
• 系统架构：architect、api-designer Agent
• 性能问题：optimizer、analyzer Agent
• 安全问题：security、patterns Agent
• 集成流程：integration、database Agent

成功标准：

• 清晰的探索路线图
• 阶段 3 中要部署的 Agent 列表
• 已确定优先级的调查领域

交付内容：

• 探索策略文档，包含：
  • 调查路线图
  • 阶段 3 的 Agent 部署计划
  • 探索优先级顺序
  • 每项探索的预期产出

Phase 3：并行深入探索

目的：同时部署多个探索 Agent，高效收集信息。

重要：此阶段默认采用并行执行。

任务：

• 根据 Phase 2 的策略，并行部署选定的 Agent
• 常见并行模式：
  • [analyzer(module1), analyzer(module2), analyzer(module3)] - 多个代码区域
  • [analyzer, patterns, security] - 从多个角度探索同一区域
  • [architect, database, integration] - 探索系统架构
• 每个 Agent 独立探索分配给自己的区域
• 汇总所有并行探索的发现
• 找出各项发现之间的联系和依赖关系
• 记录任何意外发现或异常

并行 Agent 示例：

Investigation: "How does the reflection system work?"
→ [analyzer(~/.amplihack/.claude/tools/amplihack/hooks/), patterns(reflection), integration(logging)]

Investigation: "Why is CI failing?"
→ [analyzer(ci-config), patterns(ci-failures), integration(github-actions)]

Investigation: "Understand authentication flow"
→ [analyzer(auth-module), security(auth), patterns(auth), integration(external-auth)]

成功标准：

• 所有计划的 Agent 均已部署并完成任务
• 已收集每项探索的发现
• 已确定各项发现之间的联系

交付内容：

• 发现报告，包含：
  • 每项并行探索的摘要
  • 代码路径和流程图
  • 架构洞见
  • 意外发现
  • 有待验证的未决问题

Phase 4：验证与测试

目的：通过实际操作测试并验证理解。

任务：

• 根据 Phase 3 的发现提出假设
• 设计实际测试以验证理解：
  • 手动追踪特定代码路径
  • 检查日志和输出
  • 测试边缘情况和假设
  • 验证配置的影响
• 运行验证测试
• 记录测试内容和结果
• 找出理解上的空白
• 根据测试结果完善假设
• 对任何不明确的部分重复验证

验证示例：

Understanding: "Authentication uses JWT tokens"
Verification: Trace actual token creation and validation in code

Understanding: "CI fails because of dependency conflict"
Verification: Check CI logs, reproduce locally, verify fix works

Understanding: "Reflection analyzes all user messages"
Verification: Examine reflection logs, trace message processing

成功标准：

• 所有假设均已测试
• 已通过实际测试验证理解
• 已找出并弥补理解上的空白

交付内容：

• 验证报告，包含：
  • 已执行的测试
  • 结果和观察
  • 已确认的理解
  • 尚存的空白或不确定之处

Phase 5：综合整理

目的：将发现整理成连贯的说明，回答最初的问题。

任务：

• 使用 reviewer Agent 检查发现是否完整
• 使用 patterns Agent 识别发现的可复用模式
• 将 Phase 3-4 的发现综合整理成连贯的说明
• 如有帮助，创建可视化材料（图表、流程图）
• 回答 Phase 1 范围定义中的每个问题
• 指出哪些做得好，哪些出乎意料
• 记录仍然存在的任何假设或不确定之处
• 准备适合用户阅读的清晰说明

综合整理输出：

1. 执行摘要：用 2-3 句话回答主要问题
2. 详细说明：提供完整说明和支持证据
3. 可视化辅助材料：展示系统流程、架构等的图表
4. 关键洞见：不明显的发现或模式
5. 未决问题：仍不清楚或不确定的内容

成功标准：

• 已回答所有 Phase 1 问题
• 说明清晰完整
• 发现有验证证据支持
• 可视化辅助材料有助于阐明复杂内容

交付内容：

• 包含全部 5 项综合整理输出的调查报告
• 可在 Phase 6 中用于知识记录

阶段 6：知识沉淀

目的：创建持久文档，避免今后重复进行此调查。

任务：

• 使用 amplihack.memory.discoveries 中的 store_discovery() 将发现存入记忆
• 如果发现可复用的模式，则更新 .claude/context/PATTERNS.md
• 创建或更新相关文档文件
• 为关键理解添加行内代码注释
• 可选：创建 GitHub issue 以跟进改进事项
• 可选：根据需要更新架构图
• 确保未来的调查人员能够轻松找到这些知识

文档编写指南：

## Discovery: [Brief Title]

**Context**: What was investigated and why
**Key Findings**:

- Main insight 1
- Main insight 2
  - **Supporting Evidence**: Links to code, logs, or verification tests
  - **Implications**: How this affects the project
  - **Related Patterns**: Links to similar patterns in PATTERNS.md

成功标准：

• 将发现存入记忆，供未来参考
• 更新相关文档文件
• 未来的调查人员能够找到这些知识
• 不丢失任何信息

交付物：

• 已存入记忆的发现
• 已更新的 PATTERNS.md（如适用）
• 已更新的项目文档
• 可选：关于改进事项的 GitHub issue
• 位于 ~/.amplihack/.claude/runtime/logs/ 的调查会话日志

过渡到开发工作流

调查完成后，如果任务需要实施（而不仅是理解），则过渡到 DEFAULT_WORKFLOW.md：

1. 从第 4 步继续（研究与设计），并运用调查获得的知识
2. 如果调查已提供明确的设计指导，则从第 5 步继续（实施解决方案）
3. 使用记忆中的调查结果（通过 get_recent_discoveries() 获取）和会话日志，为设计决策提供依据

混合工作流示例：

User: "/ultrathink investigate how authentication works, then add OAuth support"

Phase 1: Investigation
→ Run INVESTIGATION_WORKFLOW.md (6 phases)
→ Complete understanding of existing auth system
→ Store findings in memory via discoveries adapter

Phase 2: Development
→ Transition to DEFAULT_WORKFLOW.md
→ Resume at Step 4 (Research and Design)
→ Use investigation insights to design OAuth integration
→ Continue through Step 15 (implementation → testing → PR)

何时过渡：

• 调查发现需要进行实施
• 用户明确要求同时进行调查和开发
• 知识沉淀期间发现了后续工作

效率目标

目标效率：与临时调查相比，此工作流旨在将消息数量减少 30-40%。

临时方式	调查工作流
70-90 条消息	40-60 条消息
频繁回溯	有计划的探索
重复调查	并行深入调查
范围不明确	明确界定范围
知识丢失	见解已记录

效率提升源自：

1. 范围界定可防止范围蔓延和漫无目的的探索
2. 探索策略可避免随机且低效的探索
3. 并行深入调查可最大限度地提高信息收集速度
4. 验证阶段可及早发现理解偏差
5. 综合整理可确保回答所有问题
6. 知识沉淀可避免重复调查

与 DEFAULT_WORKFLOW.md 的比较

相似之处（结构一致性）

两种工作流都遵循以下核心原则：

• 各阶段明确，并设有清晰的交付物
• 每个阶段都由 Agent 驱动执行
• 通过质量关卡防止过早进入下一阶段
• 沉淀知识并编写文档
• 使用 TodoWrite 跟踪进度

差异（调查与开发）

方面	调查工作流	DEFAULT_WORKFLOW.md
目标	理解	实施
阶段	6 个阶段	多步骤工作流
执行方式	先探索	先实施
并行重点	阶段 3（深入调查）	各个步骤
测试	理解验证	代码验证
交付物	文档	可运行的代码
Git 使用	可选	必需（分支、PR）

阶段映射（便于用户理解）

调查阶段	DEFAULT_WORKFLOW 对应步骤	目的
阶段 1：范围定义	步骤 1：需求澄清	明确成功的标准
阶段 2：探索策略	步骤 4：研究与设计	规划方法
阶段 3：并行深入探索	步骤 5：实施	执行计划（探索还是构建）
阶段 4：验证	步骤 7-8：测试	验证结果
阶段 5：综合	步骤 11：审查	确保质量和完整性
阶段 6：知识留存	步骤 15：清理	让成果持久留存

与 UltraThink 集成

UltraThink 工作流检测：调用 /ultrathink 时，它会通过关键词自动检测调查任务，并建议使用此工作流。

自动工作流建议：

User: "/ultrathink investigate how authentication works"

UltraThink: Detected investigation task. Using INVESTIGATION_WORKFLOW.md
→ Reading workflow from .claude/workflow/INVESTIGATION_WORKFLOW.md
→ Following 6-phase investigation workflow
→ Starting Phase 1: Scope Definition

自定义

若要自定义此工作流：

1. 编辑 ~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md，以修改、添加或移除阶段
2. 根据需求调整 Agent 部署策略
3. 添加项目专属的调查模式
4. 根据指标更新效率目标

更改会立即对后续调查生效。

成功指标

跟踪以下指标以验证工作流的有效性：

• 消息数量：目标是比临时处理减少 30-40%（待验证）
• 调查时间：跟踪完成所需时间
• 知识复用：记忆检索避免重复工作的频率
• 完整性：文档齐全的调查所占百分比
• 用户满意度：是否达成清晰的理解

核心原则

• 先确定范围，再进行探索——深入调查前先界定边界
• 并行探索是关键——在阶段 3 同时部署多个 Agent
• 验证理解——在阶段 4 测试你的假设
• 留存知识——始终在阶段 6 将发现存入记忆
• 此工作流优化的是理解，而非实施

难以区分调查与开发时：

• 调查：“我需要理解 X”
• 开发：“我需要构建／修复／实现 X”

相关资源

• 源工作流：~/.amplihack/.claude/workflow/INVESTIGATION_WORKFLOW.md（完整的 436 行规范）
• 知识提取：调查后使用 knowledge-extractor 技能来留存经验
• Agent 目录：~/.amplihack/.claude/agents/CATALOG.md，包含所有可用 Agent
• 模式库：~/.amplihack/.claude/context/PATTERNS.md，包含可复用的调查模式