1. 项目概述：一个让Claude化身深度研究代理的智能技能

如果你经常使用Claude Code进行代码审查、问题排查或技术调研，可能会遇到一个痛点：当研究任务变得复杂，涉及多个并行线索时，单次的对话交互就显得捉襟见肘了。你需要自己规划研究步骤，手动切换不同的搜索和验证方向，还得费心记住中间的各种发现和矛盾点，整个过程既低效又容易遗漏关键信息。 investigate-and-report 这个Claude Code技能，就是为了彻底解决这个问题而生的。

简单来说，它把Claude从一个“一问一答”的助手，变成了一个能自主规划、并行执行、并产出结构化报告的“研究主管”。你只需要给它一个模糊的指令，比如“查查为什么我们的应用最近登录变慢了”，它就能自己拆解问题、制定计划、派出多个“子代理”同时去查代码、看日志、测接口，最后把所有线索汇总，给你一份详实的调查报告。这背后的核心，是一套借鉴了现代AI代理工程最佳实践的“上下文工程”方法，通过持久化的Markdown文件作为工作记忆，让Claude能够突破单次对话的上下文限制，完成长时间、多线程的复杂调查任务。

2. 核心设计思路：如何构建一个“有记忆”的研究代理

2.1 从单次对话到持久化工作流

传统的AI对话模型有一个根本性限制：上下文窗口。一旦对话内容超出这个窗口，最早的记忆就会被“遗忘”。对于需要回溯大量历史信息的长周期任务（比如一个持续数小时的代码库调查），这是致命的。 investigate-and-report 的核心理念，就是 将工作状态外化到文件系统中 ，用Markdown文件充当Claude的“外部大脑”。

这个设计非常巧妙。它没有试图去修改模型本身，而是利用Claude Code能够读写本地文件的特性，建立了一套标准化的“记忆文件”体系。每次Claude执行一个步骤，它都会把关键信息——比如当前的假设、已发现的线索、待验证的问题——写入到指定的Markdown文件里。当后续需要参考这些信息时，它不再是依赖模型内部的“记忆”，而是去“读取”这些文件。这样一来，无论调查过程多长、中间经历了多少次上下文切换或模型调用，核心的工作状态始终被完整地保存在磁盘上，随时可以加载和继续。

2.2 四阶段工作流：模仿人类研究员的思考过程

这个技能并非让Claude漫无目的地搜索，而是强制它遵循一个结构化的、四阶段的研究方法论。这模仿了专业研究员或工程师解决问题的思路，确保了调查的深度和系统性。

第一阶段：界定范围与提出假设 这是最关键的一步，决定了整个调查的方向和效率。当你输入一个模糊的指令后，Claude不会立刻开始行动，而是会先与你进行一轮“需求澄清”。例如，你输入“调查API变慢的原因”，它可能会追问：“请明确是哪个API端点？变慢是相对于哪个时间点或版本？是否有相关的错误日志或监控指标可供参考？” 这个过程旨在将模糊的问题转化为一个或多个可验证的 具体假设 。比如，最终形成的假设可能是：“假设1：用户认证端点在版本v1.2.0部署后，第95百分位响应时间增加了300ms，可能与新增的JWT签名验证逻辑有关。” 同时，它会识别出几个并行的 研究线索 ，如“线索A：分析版本v1.2.0的代码变更”，“线索B：查询该时间段内的应用性能监控(APM)数据”，“线索C：检查数据库在该时间段的查询性能”。

第二阶段：并行研究 这是体现其“代理”能力的地方。在第一阶段规划好的多个研究线索，会被分配给不同的“子代理”同时进行。技能内部预设了不同类型的子代理，针对不同任务进行优化：

• 探索型代理 ：通常使用响应速度更快的模型（如Claude Haiku），负责快速的文件搜索、代码库遍历和基础信息查找。比如，快速定位所有与“认证”相关的代码文件。
• 通用分析代理 ：使用能力更强的模型（如Claude Sonnet），负责复杂的逻辑分析、多步骤推理和整合信息。比如，对比两个版本的代码差异，并推断其性能影响。
• Bash操作代理 ：同样使用强模型，专门执行终端命令。比如，运行特定的性能测试脚本、执行Git历史查询或分析日志文件。

所有这些子代理的发现，都会被规整地写入一个统一的 research/ 目录下，按线索分类，为下一阶段的整合做好准备。

第三阶段：分析与综合 当所有并行研究线程完成后，主导调查的“主代理”会登场。它的任务是扮演“侦探组长”的角色，阅读 research/ 文件夹中所有子代理的产出，进行交叉比对和矛盾验证。例如，探索型代理可能发现代码中新增了一个循环，而Bash代理提供的性能剖析数据却显示瓶颈在数据库调用。主代理就需要分析这两种证据，判断是循环导致了额外的数据库查询，还是两个独立的问题。它还会评估每个发现的 置信度 ，区分“确凿证据”、“强相关性”和“待验证猜想”。

第四阶段：撰写报告 最后，所有经过综合分析的发现，会被组织成一份完整的 investigation-report.md 。一份优秀的报告不仅罗列“发现了什么”，还会包含“哪些方法没奏效”（避免他人重复踩坑）以及具体的“后续行动项”（如“需要为X服务添加监控”、“建议重构Y模块的代码”）。这使得调查结果具有直接的操作指导价值。

2.3 三个记忆文件：项目管理的实体化

为了让上述工作流稳定运行，技能定义了三个核心的Markdown文件作为持久化工作区。你可以把它们理解为一个研究项目的“看板”或“项目管理文档”。

• task_plan.md ： 路线图 。它记录了最初的调查目标、形成的所有假设、规划的研究线索，以及每个线索的当前状态（待开始、进行中、已完成）。这是整个调查的顶层设计图。
• findings.md ： 草稿纸 。这是一个动态更新的文件，所有子代理的初步发现、数据片段、相互矛盾的观测结果、以及新产生的开放性问题，都会随时被记录在这里。它是分析阶段的主要原料。
• progress.md ： 检查点 。这是应对Claude Code上下文限制的“安全阀”。Claude会定期在这里写下“当前进行到哪一步了”、“接下来要做什么”、“遇到了什么障碍”。万一对话中断或上下文被压缩，重新加载技能后，Claude可以通过读取这个文件快速恢复到中断前的状态，继续执行任务。

实操心得：文件命名的艺术 这三个文件的命名非常考究。 task_plan 强调规划和结构， findings 强调收集和积累， progress 强调状态和连续性。在实际使用中，我建议你不要修改这些文件名。它们已经成为Claude内部工作流程的“约定”，改变名称可能会破坏技能对自身状态的识别和恢复逻辑。

3. 安装、配置与核心使用详解

3.1 环境准备与技能安装

使用这个技能的前提，是你已经在本地安装并配置好了 Claude Code 。Claude Code是Anthropic为开发者提供的桌面应用，它允许Claude深度集成到你的IDE和文件系统中。安装好Claude Code后，它会自动在用户目录下创建一个 .claude/skills/ 文件夹，所有自定义技能都存放在这里。

安装 investigate-and-report 非常简单，只需要一行终端命令：

git clone https://github.com/faustow/investigate-and-report.git ~/.claude/skills/investigate-and-report

这条命令的作用是将远端的技能仓库克隆到本地Claude Code技能目录下的一个同名文件夹中。完成后，你不需要重启Claude Code应用，它会自动扫描并加载新的技能。

注意事项：权限与路径 确保你有权限向 ~/.claude/skills/ 目录写入文件。在极少数情况下，如果该目录不存在，你可以手动创建它。安装后，你可以通过 ls -la ~/.claude/skills/ 来确认 investigate-and-report 文件夹是否存在及其内容。

3.2 技能调用与初始化交互

安装成功后，在任何Claude Code的会话窗口中，你只需要键入特定的命令即可激活技能：

/investigate-and-report

按下回车后，Claude的回复风格会立刻转变。它不会再以普通的对话助手身份回应，而是会进入“调查代理”模式，通常会这样开场：“我已切换到调查模式。请详细描述您希望我调查的问题或主题。” 这时，你就可以提出你的调查需求了。

如何给出一个好的初始指令？ 初始指令的质量直接影响后续调查的效率和准确性。一个模糊的指令会导致大量的澄清回合，消耗不必要的交互。一个优秀的指令应包含以下要素：

1. 核心问题 ：清晰陈述你想要调查的现象或问题。
2. 上下文边界 ：指明相关的系统、服务、时间范围或代码版本。
3. 可用资源 ：提及可能相关的日志文件、代码路径、文档或数据源的位置。
4. 期望产出 ：简要说明你希望报告侧重哪个方面（如根因分析、性能优化建议、安全评估）。

• 较差示例 ：“看看系统有什么问题。”（过于模糊，毫无边界）
• 良好示例 ：“调查昨晚（3月15日）20:00至22:00期间，‘订单服务’（代码位于 ./services/order ）API响应时间飙升的原因。相关的应用日志在 /var/log/app/order.log ，监控数据可以从Grafana上的‘Order-Service’面板查看。我希望报告能定位到具体的代码变更或外部依赖问题。”

给出良好示例后，Claude通常会直接进入第一阶段，开始制定详细的 task_plan.md ，并可能就计划中的个别细节向你做最终确认，然后便会自主地展开调查。

3.3 工作目录与文件结构解析

技能启动后，它会在你 当前Claude Code会话所在的工作目录 中创建一系列文件和文件夹。理解这个结构对于你监控进度和干预调查至关重要。

你的工作目录/
├── task_plan.md          # 调查主计划
├── findings.md           # 研究发现汇总
├── progress.md           # 进度检查点
├── investigation-report.md # 最终报告（调查完成后生成）
└── research/             # 研究过程资料库
    ├── thread_a/         # 线索A的研究产出
    │   ├── exploration_notes.md
    │   └── analysis_summary.md
    ├── thread_b/         # 线索B的研究产出
    │   ├── bash_output.log
    │   └── code_comparison.diff
    └── ...               # 其他线索

• 工作目录的选择 ：这是一个关键技巧。建议在启动技能前，通过Claude Code的文件面板或终端， cd 到与你调查内容最相关的项目根目录。例如，调查某个微服务的问题，就进入到该服务的代码仓库目录。这样，Claude在执行文件搜索、Git操作或运行脚本时，就有了正确的上下文路径。
• 文件的实时监控 ：调查过程中，你可以随时打开并阅读 task_plan.md 和 findings.md 来了解实时进展。你甚至可以在 findings.md 中手动添加备注或提示，Claude在后续分析时会读取这些内容。这实现了 人机协同调查 。
• research/ 目录的价值 ：这里存放的是原始证据。最终报告中的结论是否可信，你可以到这里来溯源。例如，报告说“数据库查询慢”，你就可以到对应线索的文件夹里查看具体的慢查询日志或EXPLAIN命令的输出结果。

4. 实战案例拆解：一次完整的性能问题调查

为了让你更直观地理解这个技能如何运作，我们模拟一个真实的场景： “调查用户上传图片功能变慢的原因” 。

4.1 阶段一：问题界定与计划制定

我在项目根目录启动Claude Code，输入 /investigate-and-report ，然后给出指令：“调查我们Web应用的用户头像上传功能，在最近一周变得异常缓慢的原因。功能代码主要在 app/controllers/upload_controller.rb 和 app/models/image_processor.rb 。服务器是AWS EC2。”

Claude的回复首先确认了问题，然后开始构建计划。它生成的 task_plan.md 可能包含以下内容：

# 调查计划：用户头像上传性能下降

**目标**：定位并理解最近一周用户头像上传功能响应时间显著增加的根本原因。
**时间范围**：最近7天。
**相关系统**：Web应用（Ruby on Rails），AWS EC2实例，可能涉及S3存储。

## 假设
1.  **代码变更假设**：最近一周的部署引入了新的处理逻辑或外部库，增加了处理耗时。
2.  **资源瓶颈假设**：服务器（CPU、内存、磁盘I/O）或网络（到S3的延迟）成为瓶颈。
3.  **依赖服务假设**：所依赖的第三方服务（如图像处理API、数据库）性能下降。
4.  **负载增长假设**：用户上传并发量增加，但系统水平扩展不足。

## 研究线索
- **线索A（代码与配置）**：分析最近一周的Git提交历史，重点审查上传控制器和图像处理器模型；检查相关Gemfile变更和环境配置。
- **线索B（系统资源）**：检查服务器监控数据（CloudWatch），查看CPU、内存、磁盘I/O、网络流量在过去一周的趋势。
- **线索C（外部依赖）**：测量到AWS S3存储桶的网络延迟；检查图像处理外部服务（如Imagga）的状态和响应时间。
- **线索D（数据库与队列）**：调查上传过程中涉及的数据库操作（如记录存储）和异步任务队列（如Sidekiq）的积压情况。

同时，它会更新 progress.md ：“已制定初始调查计划，包含4个假设和4条研究线索。准备启动并行研究。”

4.2 阶段二：多线程并行研究展开

接着，Claude开始同时推进多个线索。它会创建 research/thread_a/ , research/thread_b/ 等文件夹。

• 线索A ：一个“Bash代理”被启动。它执行 git log --oneline --since="7 days ago" -- app/controllers/upload_controller.rb app/models/image_processor.rb 来获取代码变更列表。然后，一个“探索代理”会快速查看这些变更的文件内容。最后，一个“通用分析代理”会仔细阅读关键的diff，评估其性能影响，并将分析摘要写入 research/thread_a/code_analysis.md 。
• 线索B ：一个“通用分析代理”被启动。由于直接访问AWS CloudWatch需要复杂权限，它可能会采取间接方式：首先尝试读取本地可能存在的监控日志，或者分析系统命令 top , iostat , dstat 的历史记录（如果有）。它也可能建议我（用户）提供相关的监控截图或数据。它的发现会被记录在 research/thread_b/system_metrics.md 。
• 线索C ：一个“Bash代理”可能尝试执行 curl -o /dev/null -s -w 'Total: %{time_total}s\n' https://your-bucket.s3.amazonaws.com/test 来测试S3延迟。同时，另一个代理会模拟调用图像处理服务的代码路径，并记录耗时。
• 线索D ：代理会检查数据库慢查询日志，或尝试运行 ps aux | grep sidekiq 和 sidekiq-monitor 之类的命令来查看队列状态。

所有这些分散的发现，会不断被汇总到 findings.md 中：

## 线索A发现
- 发现：7天前提交 #a1b2c3d 在 `image_processor.rb` 中引入了 `mini_magick` 库，替换了之前的 `fastimage`。新库增加了自动旋转和EXIF信息剥离功能。
- 数据：暂无性能对比数据。

## 线索B发现
- 发现：通过分析 `sar` 历史数据，发现过去一周磁盘 `await`（I/O等待时间）指标在高峰时段有明显上升。
- 矛盾点：CPU和内存利用率保持平稳。

## 线索C发现
- 发现：到S3的延迟测试结果稳定在~50ms，属正常范围。第三方图像服务API响应时间也无异常。
...

4.3 阶段三：综合分析形成洞见

当各线索研究初步完成后，主代理开始阅读 findings.md 。它发现了潜在的关联： 线索A的代码变更（引入了更重的图像处理库） 和 线索B的系统指标（磁盘I/O等待增加） 。

它不会轻易下结论，而是会启动更深度的验证。例如，它可能会：

1. 编写一个简单的基准测试脚本，分别用旧的 fastimage 和新引入的 mini_magick 处理一批样本图片，并记录处理时间和磁盘活动。
2. 分析 image_processor.rb 中新的处理逻辑，看是否在处理过程中产生了大量的临时文件，导致磁盘频繁读写。
3. 检查服务器的磁盘类型（是通用型SSD还是吞吐优化型HDD）以及EC2实例的EBS带宽限制。

经过这一轮分析，它会在 findings.md 中更新一个“综合分析”部分，将置信度低的猜测排除，将关联性强的证据链接起来，并可能提出新的、更具体的假设，比如：“ 高置信度假设 ： mini_magick 库在处理图片时，默认设置或我们的调用方式导致其生成了超出预期的临时中间文件，这些文件写入操作与用户上传并发叠加，超过了当前EBS卷的IOPS/吞吐量限制，引起磁盘排队，进而拖慢了整个处理流水线。”

4.4 阶段四：产出结构化报告

最后，主代理会撰写 investigation-report.md 。一份优秀的报告可能结构如下：

# 用户头像上传性能下降调查报告

**执行摘要**：调查确认，性能下降的主要原因是近期引入的 `mini_magick` 图像处理库在默认配置下产生了高磁盘I/O负载，与服务器EBS卷的吞吐限制形成瓶颈。

## 主要发现
1.  **根本原因**：提交 #a1b2c3d 引入的 `mini_magick`，在 `ImageProcessor#optimize` 方法中，未配置 `temp_path` 且使用了多步转换，导致大量临时文件写入系统默认临时目录（通常是 `/tmp`），该目录位于根卷。
2.  **证据链**：
    - 代码Diff显示新增了旋转和EXIF处理。
    - 系统监控显示磁盘 `await` 与上传高峰完全吻合。
    - 编写的基准测试显示，使用新库后，单个图片处理的磁盘写入量增加了10倍。
    - 服务器根卷为通用型SSD (gp2)，其基准IOPS在持续高负载下成为瓶颈。
3.  **其他已排除的原因**：S3延迟正常，第三方服务无异常，数据库查询无慢日志，内存/CPU无瓶颈。

## 未能验证的方面
- 未能精确量化在最高并发下，需要多少IOPS才能满足需求，因为缺乏生产环境完全一致的负载测试。

## 建议的行动项
1.  **立即缓解**：修改 `mini_magick` 调用，显式设置 `temp_path` 指向一个更大、更高性能的临时存储卷（如实例存储或预配置IOPS的EBS卷）。
2.  **短期优化**：评估是否所有图片都需要自动旋转和EXIF剥离，或许可以改为按需处理。
3.  **长期规划**：考虑将图像处理卸载到异步任务队列，避免阻塞前端请求；或者评估使用更高效、内存处理为主的库（如 `libvips` 的Ruby绑定）。
4.  **监控增强**：为应用服务器添加磁盘I/O的详细监控和告警。

**调查置信度**：高。证据间能相互印证，且通过可控测试复现了问题现象。

至此，一次完整的、深度的问题调查就结束了。你得到的不再是零散的聊天记录，而是一份可以直接转给团队、用于指导下一步行动的工程报告。

5. 高级技巧与常见问题排查

5.1 如何引导技能进行更有效的调查？

虽然技能是自主的，但你的引导能极大提升其效率。

• 预设边界 ：在启动技能前，可以提前准备好相关的文档、日志文件或数据图表，并告诉Claude：“关于系统架构的文档在 docs/architecture.md ，最近三天的错误日志在 logs/error_*.log 。” 这样它能更快地定位资源。
• 中途干预 ：如果发现 task_plan.md 中的某个线索方向不对，你可以直接在该文件中以注释的形式写下：“这个线索优先级降低，请先聚焦于线索A和B。” Claude在后续读取计划文件时会注意到你的指令。
• 提供上下文 ：对于非常专业的领域，你可以先让Claude阅读一些背景资料。例如，先让它读一遍 README.md 和主要的架构图，然后再启动调查技能。

5.2 常见问题与解决方案

在实际使用中，你可能会遇到一些典型问题，以下是排查思路：

问题现象	可能原因	解决方案
输入 /investigate-and-report 无反应或报错	1. 技能未正确安装到 ~/.claude/skills/ 目录。 2. Claude Code版本过旧，不支持技能功能。	1. 检查 ~/.claude/skills/investigate-and-report/ 目录是否存在且包含 SKILL.md 文件。 2. 升级Claude Code到最新版本。
调查卡在某个阶段，长时间无进展	1. 子代理在执行某个耗时极长的命令（如全量代码扫描）。 2. 遇到权限错误或命令不存在，子代理陷入重试循环。 3. 上下文窗口耗尽，主代理“失忆”。	1. 查看 progress.md 和各个 research/ 子目录下的最新文件，了解卡在哪一步。 2. 检查是否有命令报错。你可以手动执行该命令，或修改 task_plan.md 跳过该步骤。 3. 这是设计上要避免的。如果发生，尝试输入“请读取progress.md文件并继续调查”来唤醒它。
最终报告内容肤浅，没有深入根本原因	1. 初始指令过于宽泛。 2. 研究线索设计得不好，停留在表面现象。 3. 缺乏关键数据源（如日志、监控）的访问权限。	1. 重新开始，给出更具体、包含边界和资源的指令。 2. 在调查中期，通过修改 findings.md 主动提出更深层的问题引导它，例如：“当前发现只说明了‘是什么’，请深入分析‘为什么’磁盘I/O会增加，是哪些具体操作引起的？” 3. 尽可能将相关数据文件提前放置在工作目录，或在指令中明确告知如何获取模拟数据。
技能创建了大量临时文件，造成混乱	这是正常现象。 research/ 目录就是用于存放中间产出的。	调查结束后，如果不需要保留过程文件，可以手动删除整个 research/ 目录以及 task_plan.md , findings.md , progress.md 文件。只保留最终的 investigation-report.md 。建议在版本控制中忽略这些临时文件。

5.3 与其他工具链的集成思路

investigate-and-report 技能可以成为你开发运维工作流中的一个强大节点。

• 与CI/CD集成 ：设想在CI流水线中，如果自动化测试失败，可以自动触发一个精简版的调查技能，让它分析测试日志、对比本次提交与上次成功提交的差异，生成初步的失败分析报告，节省工程师的初步排查时间。
• 作为知识库生成器 ：对于复杂的遗留系统，你可以指令Claude“调查XX模块的架构和数据流”，它生成的最终报告，连同 research/ 目录下的代码摘要和依赖分析，就能构成一份不错的初步技术文档。
• 事后复盘辅助 ：线上发生故障后，将相关的日志、指标导出文件、部署记录放在一个目录中，然后让调查技能去分析，它能帮助你快速梳理时间线，关联不同系统的日志，形成结构化的复盘材料初稿。

这个技能的真正威力在于，它将研究过程 标准化、自动化、持久化 了。它可能不会每次都直接给你魔术般的答案，但它能确保你的调查是系统性的，不遗漏重要线索，并且所有推理和证据都留有可追溯的记录。对于任何需要深度挖掘、复杂排查的技术工作来说，这无疑是一个范式级别的效率提升工具。