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

如果你用过Claude Code，可能会觉得它是个强大的编程助手，能帮你写代码、调试、解释逻辑。但当你面对一个复杂、开放性的研究任务时——比如“查一下我们上周上线的服务为什么突然变慢了”，或者“研究一下WebAssembly在边缘计算场景下的最新进展”——单次的对话交互就显得有些力不从心了。你需要它像一个真正的调查员一样，能制定计划、分头行动、汇总信息，最后给你一份结构清晰的报告。这正是 investigate-and-report 这个Claude Code技能要解决的问题。

简单来说，它不是一个简单的脚本，而是一套完整的“研究代理”工作流引擎。你只需要在Claude Code会话中输入 /investigate-and-report 并描述你的研究目标，Claude就会自动切换角色，从一个问答助手转变为一个项目负责人。它会为你规划调查路径，同时派出多个“子代理”并行探索不同的线索，并将所有中间发现和最终结论，持久化地记录在Markdown文件中。整个过程完全自主运行，你甚至可以中途离开，回来时它还能从上次中断的地方继续。这背后的核心思想，是将一次性的、受限于上下文长度的对话，升级为一个有状态、可恢复、结构化的研究项目。

我最初接触这个项目，是因为在排查一个棘手的生产环境性能劣化问题。手动在代码库、日志、监控系统之间来回切换，效率低下且容易遗漏线索。使用这个技能后，Claude自动生成了调查计划，一个子代理去分析最近提交的代码差异，另一个去查询特定时间段的监控指标，第三个则尝试复现问题。最终生成的报告不仅指出了根本原因是一个未被注意到的数据库连接池配置变更，还附上了优化建议和相关代码片段。这种“甩手掌柜”式的高效研究体验，让我决定深入拆解并分享它的设计精髓和实战用法。

2. 核心设计思路与架构拆解

2.1 从单次对话到持久化研究项目

传统AI助手的交互模式是“一问一答，答完即忘”。对于复杂研究，这有两个致命缺陷： 上下文遗忘 和 缺乏结构 。Claude的上下文窗口再大，也有被填满的时候，一旦触发“上下文压缩”，早期的关键信息可能丢失。此外，散乱的对话记录很难梳理出清晰的逻辑脉络。

investigate-and-report 的解决方案非常巧妙： 用文件系统作为持久化工作记忆 。它不再依赖易失的对话历史，而是创建并维护一套标准的Markdown文件作为项目的“大脑”。这套文件包括：

1. task_plan.md (任务计划书) ：这是项目的总纲。它定义了调查的目标、阶段划分、提出的初始假设、需要追踪的研究线索（线程），以及每个线索的状态（待处理、进行中、已完成）。它就像一个项目经理的甘特图，确保整个调查不偏离方向。
2. findings.md (研究发现草稿) ：这是所有子代理的共享便签板。任何代理发现了有价值的信息、遇到了矛盾的数据、产生了新的疑问，都会记录在这里。它鼓励“大胆假设，小心求证”，允许信息暂时混乱，留待后续分析阶段进行梳理和交叉验证。
3. progress.md (进度检查点) ：这是实现“可恢复性”的关键。Claude Code会话可能因各种原因中断。这个文件会定期保存当前所有研究线程的快照、已完成的工作摘要以及下一步计划。当重新加载技能或会话恢复时，Claude读取这个文件，就能迅速“接上茬”，几乎无缝地继续调查。

实操心得 ：这种基于文件的工作记忆模式，其优势远超表面。它使得调查过程变得“可审计”。你可以随时打开这些Markdown文件，查看Claude的思考过程和决策依据，这对于信任AI得出的结论至关重要。同时，这些文件本身也是极佳的项目文档，可以直接分享给团队成员。

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

这个技能并非让Claude漫无目的地搜索，而是强制其遵循一个结构化的四阶段工作流，这高度模仿了专业研究员或工程师的思维方式：

第一阶段：界定范围与提出假设 这是最重要的奠基阶段。Claude会与你（用户）进行简短的交互，明确调查的 边界 和 成功标准 。例如，你提出“调查API变慢的原因”，Claude可能会追问：“是哪个具体的端点？变慢的时间范围是什么？比较的基准是什么？” 澄清后，它会将模糊的问题转化为具体的、可验证的 假设 。比如：“假设1：数据库查询性能在特定时间段内下降。假设2：新增的第三方服务调用引入了延迟。假设3：服务器资源（CPU/内存）出现瓶颈。”

第二阶段：并行研究 这是最体现其“代理”能力的阶段。Claude会根据第一阶段产生的假设和研究线索，动态创建3到5个甚至更多的“子代理”，让它们 并行 工作。每个子代理被赋予一个明确的子任务，例如：

• 代理A：分析最近一周与认证端点相关的代码变更 ( git log 和 git diff )。
• 代理B：查询应用监控系统（如Prometheus/Grafana），获取该端点的P99延迟和错误率图表。
• 代理C：检查服务器和数据库的负载指标（CPU, Memory, IO）。
• 代理D：在项目文档和工单系统中搜索相关已知问题。

这些子代理会像真正的团队成员一样，独立开展工作，并将初步发现写入 findings.md 。

第三阶段：分析与综合 当并行研究收集到足够信息（或达到预设的检查点）后，主控Claude（或称“协调代理”）会介入。它的任务是扮演“侦探组长”的角色：

• 交叉验证 ：对比不同子代理的发现，寻找佐证或矛盾。例如，代理B发现延迟峰值，代理C同时发现CPU飙升，这就形成了强关联。
• 解决矛盾 ：如果发现冲突信息（比如日志显示成功但监控显示错误），它会尝试启动新的调查线程去澄清。
• 评估置信度 ：对每个发现和结论，标注其置信水平（例如，“高：有监控数据和日志双重印证”；“中：基于代码模式推断，需测试验证”）。 这个阶段是将原始数据转化为真知灼见的关键。

第四阶段：报告生成 最后，Claude会综合所有分析结果，撰写一份完整的 investigation-report.md 。一份优秀的报告不仅罗列“发现了什么”，还包括：

• 执行摘要 ：让忙碌的读者30秒内了解核心结论。
• 详细发现 ：按重要性或逻辑顺序组织，附上证据来源。
• 未能确认的事项 ：诚实记录调查的局限性和尚存的疑问。
• ** actionable 的行动项**：具体的、可执行的建议，如“回滚提交abc123”、“将数据库连接池参数 max_connections 从50调整为100”。

2.3 智能子代理调度：用对的模型做对的事

这个技能另一个精妙之处在于其对Claude不同模型的“知人善任”。它并非盲目地使用最强大的模型，而是根据任务类型分配合适的模型，在效果和成本/速度间取得平衡。

子代理类型	默认模型	擅长场景与选用理由
Explore (探索型)	Claude 3.5 Haiku	快速检索与发现 。Haiku模型速度极快、成本低，非常适合执行模式固定的任务，如在代码库中进行关键词全局搜索 ( grep -r )、列出目录结构、快速浏览文件内容以判断相关性。它像是一个高效的侦察兵。
general-purpose (通用分析型)	Claude 3.5 Sonnet	复杂分析与综合研究 。当任务需要理解复杂逻辑、进行多步推理、总结长篇文档或执行需要深度思考的网页搜索时，Sonnet模型的能力更为合适。它像是团队中的高级分析师。
Bash (操作执行型)	Claude 3.5 Sonnet	执行命令行操作 。运行测试脚本、执行Git操作（如 git bisect 定位问题提交）、调用构建工具或处理系统命令。使用Sonnet是出于安全性和准确性考虑，确保生成的命令是合理且无害的。

注意事项 ：模型的选择策略写在技能的配置中，高级用户可以根据自身需求调整。例如，如果你更追求速度且任务简单，可以将更多任务分配给Haiku；如果研究任务极其复杂，可以全部指定使用Sonnet（但需注意成本）。默认的混合策略是经过实践验证的性价比最优解。

3. 从安装到实战：手把手运行你的第一次AI调查

3.1 环境准备与技能安装

首先，你需要一个可用的 Claude Code 环境。Claude Code是Anthropic为深度开发者集成提供的IDE插件环境，通常作为桌面应用或深度集成插件提供。确保你已安装并配置好。

这个技能的安装过程极其简单，因为它遵循了Claude Code的技能标准。打开你的终端，执行以下命令：

# 克隆技能仓库到Claude Code的技能目录
git clone https://github.com/faustow/investigate-and-report.git ~/.claude/skills/investigate-and-report

命令中的 ~/.claude/skills/ 是Claude Code默认查找技能的标准路径。完成克隆后，重启你的Claude Code应用，技能就会被自动加载。

验证安装 ：在Claude Code的任何会话窗口中，尝试输入 /inv 然后按Tab键，如果看到 investigate-and-report 的自动补全选项出现，就说明安装成功了。

3.2 发起一次完整的调查：以“网站性能下降”为例

假设你负责的网站在最近一次更新后，首页加载速度明显变慢。我们来发起一次调查。

1. 启动技能 ： 在Claude Code的聊天输入框里，直接输入：

   /investigate-and-report
   

   按下回车，Claude的回复风格会立刻改变，进入“调查代理”模式。

2. 定义调查目标 ： Claude会提示你描述调查内容。你输入：

   “我们的网站在昨天下午部署了v1.2.0版本后，首页的加载时间从平均1.5秒增加到了4秒以上。请调查性能下降的根本原因。”

3. 交互澄清（第一阶段） ： Claude不会立即开始盲搜，而是可能会问你几个澄清问题，例如：

   • “首页加载时间的数据来源是哪个监控工具？（例如：Google Analytics, New Relic, 自建监控）”
   • “v1.2.0版本具体包含了哪些主要的变更？有变更日志或Pull Request链接吗？”
   • “性能下降是影响所有用户，还是特定地区或设备类型？” 你回答后，Claude会将这些信息纳入背景，并开始生成 task_plan.md 。你可以立即在项目文件树中看到这个新文件。

4. 观察自主运行（第二、三阶段） ： 接下来，你可以泡杯茶，观察Claude的“表演”。它会：

   • 在 task_plan.md 中创建研究线程，如：“线程1：分析v1.2.0的代码变更”、“线程2：查询昨日至今的服务器性能指标”、“线程3：检查前端资源（JS/CSS）的加载大小和耗时”。
   • 同时启动多个子代理。你会在聊天窗口看到类似这样的动态：

     [启动子代理：Explore-代码分析] 正在扫描 `git diff v1.1.0..v1.2.0` 的输出...
     [启动子代理：Bash-服务器检查] 正在运行 `docker stats` 和 `kubectl top pod`...
     [启动子代理：general-purpose-前端分析] 正在使用Chrome DevTools Protocol模式分析首页网络瀑布图...
     

   • 各个代理的发现会实时汇总到 findings.md 。你可能会看到：“发现：v1.2.0中引入了一个新的未压缩的第三方JavaScript库，体积为2.1MB。”、“发现：下午2点后，容器内存使用率持续高于85%。”、“矛盾：后端API响应时间正常，但前端测得的TTFB（首字节时间）很高。”
   • Claude会定期保存 progress.md 。

5. 获取最终报告（第四阶段） ： 当所有线程状态变为“已完成”或达到某个逻辑终点时，Claude会通知你调查结束，并生成 investigation-report.md 。报告结构清晰，可能包含：

   • 根本原因 ：1) 新引入的巨型JS库阻塞了主线程渲染；2) 内存压力导致垃圾回收频繁，间接影响响应。
   • 证据 ：附上了具体的代码片段、监控图表链接、性能测评截图。
   • 建议 ：1) 异步加载或替换该第三方库；2) 调整容器内存限制与请求；3) 对首页进行懒加载优化。

3.3 文件系统结构详解

安装后，你的技能目录结构如下，理解每个文件的作用有助于高级调试和定制：

~/.claude/skills/investigate-and-report/
├── SKILL.md              # 【核心】技能定义文件。Claude Code通过读取此文件来理解如何触发和运行该技能。
├── reference.md          # 【理论】上下文工程原理参考。解释了为何采用工作记忆文件、子代理模式等设计，是理解技能哲学的基础。
├── examples.md           # 【实用】详细示例库。提供了多个不同场景（性能调试、安全审计、技术调研）的完整运行样例和报告输出，是学习的最佳材料。
└── templates/            # 【模板】工作记忆文件模板目录
    ├── task_plan.md      # `task_plan.md` 的初始模板，定义了结构。
    ├── findings.md       # `findings.md` 的初始模板。
    └── progress.md       # `progress.md` 的初始模板。

当你运行技能时，它会在你的 当前工作目录 （或你指定的目录）中动态创建上述三个工作记忆文件（ task_plan.md , findings.md , progress.md ）以及一个 research/ 文件夹（用于存放各子代理的原始输出）。因此，每次调查都是一个独立的、自包含的项目文件夹。

4. 高级技巧与实战避坑指南

4.1 如何提出一个“好”的调查提示

技能的效能很大程度上取决于你输入的初始指令。模糊的指令会导致低效甚至跑偏的调查。

差的提示 ：“看看系统有什么问题。”（过于宽泛，目标不明） 一般的提示 ：“调查数据库慢的问题。”（范围仍大，缺乏上下文） 优秀的提示 ：“过去24小时内，订单服务API（ /api/v1/orders ）的P99延迟从120ms上升至450ms，同时数据库（PostgreSQL RDS）的CPU使用率从30%升至70%。请调查两者是否存在关联，并定位根本原因。相关资源：监控面板链接 [此处填入链接] ，代码仓库为 order-service 。”

优秀提示的要素 ：

1. 具体指标 ：明确要调查的实体（哪个API、哪张数据库表）和异常指标（P99延迟、CPU使用率）。
2. 变化时间 ：指明问题发生的时间窗口。
3. 相关上下文 ：提供可直接访问的资源链接（监控、代码库、日志系统），这能极大减少子代理“寻找入口”的时间。
4. 初始假设 ：暗示可能的关联方向（“调查两者是否存在关联”），引导Claude建立更精准的研究线程。

4.2 管理长期运行与中断恢复

复杂的调查可能耗时很长，超过一次会话的时间。 progress.md 文件就是为此设计的。

• 主动中断 ：如果你需要暂停调查，可以直接告诉Claude“请暂停并保存进度”，或者直接关闭会话窗。最后的状态已保存在 progress.md 。
• 恢复调查 ：在新的Claude Code会话中， 首先确保你的当前工作目录是上次调查所在的目录 ，然后再次输入 /investigate-and-report 。Claude会读取目录下的工作记忆文件，并通常能识别出这是一个未完成的项目，提示你是否继续。确认后，它将从上次的检查点恢复。
• 注意事项 ：如果中间你手动修改了 task_plan.md 或 findings.md ，Claude在恢复时也能识别并纳入考虑。这种“人机协同”模式非常灵活。

4.3 子代理的协作与冲突处理

有时，不同子代理的发现会相互矛盾。例如，一个代理从日志看到大量错误，另一个代理从状态端点看到服务健康。此时，协调代理（主Claude）的处理逻辑至关重要。

技能内置的冲突解决策略 ：

1. 优先级评估 ：给不同来源的数据赋予置信权重。例如，直接来自生产环境日志的错误信息，可能比一个自我报告的健康检查端点更可靠。
2. 发起验证线程 ：当冲突出现时，协调代理会自动创建一个新的研究线程，专门设计一个“验证实验”来裁决矛盾。例如，它可能编写并运行一个简单的curl脚本，直接调用有争议的API，对比其返回结果与日志记录。
3. 记录并存 ：如果短期内无法解决，它会将矛盾点清晰记录在报告的“未解疑问”部分，并说明每种证据的来源和可能解释。

你可以这样干预 ：在调查过程中，如果你浏览 findings.md 时发现了明显的跑偏或误解，可以直接在该文件中以注释的形式（ <!-- 用户注：这里可能理解错了，实际原因是... --> ）加入你的指导。协调代理在后续分析阶段会读取这些注释并调整方向。

4.4 自定义与扩展技能

对于高级用户，这个技能提供了良好的扩展性。

1. 修改模板 ： templates/ 目录下的文件是你可以直接编辑的。例如，如果你希望每次的调查报告都符合你公司的文档规范，你可以修改 templates/task_plan.md ，加入你们特有的章节（如“影响等级评估”、“相关责任人”）。
2. 调整代理策略 ：技能的核心逻辑定义在 SKILL.md 中（虽然大部分是自然语言指令）。你可以通过修改其中的提示词，来改变子代理的创建逻辑、模型分配策略或阶段转换条件。例如，你可以要求“在分析阶段，必须至少引用三个独立的数据源”。
3. 集成外部工具 ：技能的子代理可以执行Bash命令。这意味着，如果你有封装好的诊断脚本、内部CLI工具，都可以通过让Bash子代理调用的方式集成进来。例如，你可以预设一个命令，让代理在调查性能问题时自动运行你的 perf-script.sh 。

一个实战技巧 ：对于需要登录或认证的内部系统（如公司内网的监控平台），直接让Claude去“浏览”是不现实的。更好的做法是， 你先手动执行查询，将结果（图表截图、数据表格）保存为文件（如 metrics.png 或 data.json ）放在项目目录下 。然后在初始提示中告诉Claude：“相关数据我已放在 ./data/ 目录下，请分析这些文件。” 子代理中的 Explore 和 general-purpose 模型能够很好地读取和分析这些本地文件内容。

5. 常见问题与排查实录

在实际使用中，你可能会遇到一些典型情况。以下是我和社区成员遇到过的常见问题及解决方法。

问题现象	可能原因	排查与解决步骤
输入 /investigate-and-report 无反应或报错	1. 技能未正确安装到 ~/.claude/skills/ 目录。 2. Claude Code版本过旧，不支持技能功能。 3. 技能目录权限问题。	1. 检查路径： ls -la ~/.claude/skills/ ，确认 investigate-and-report 文件夹存在。 2. 升级Claude Code到最新版本。 3. 确保技能目录有读取权限。
Claude启动了调查，但子代理似乎“卡住”，长时间无输出	1. 子代理在执行一个非常耗时的操作（如全代码库搜索）。 2. 遇到了需要交互的命令（如需要输入密码的sudo）。 3. 网络问题导致外部搜索失败。	1. 耐心等待（5-10分钟）。可查看 research/ 文件夹下是否有新文件生成。 2. 避免 让技能执行需要人工交互的命令。在提示中应提供无需权限的数据。 3. 检查Claude Code的网络连接。对于外部网页调研，依赖其内置浏览能力，可能受限制。
生成的报告流于表面，缺乏深度洞察	1. 初始提示过于模糊。 2. 缺乏足够的上下文数据供Claude分析。 3. 研究线程设计得过于宽泛。	1. 遵循“优秀提示”的要素，提供具体、可测量的目标。 2. 提前将相关的日志片段、错误信息、配置代码等以文本文件形式放入项目目录。 3. 在调查开始后，查看 task_plan.md ，如果觉得线程不够聚焦，可以直接编辑该文件，添加更具体的子问题。
技能在分析阶段陷入循环，不断重复研究同一问题	协调代理在试图解决一个证据矛盾，但未能找到决定性证据。	1. 查看 findings.md ，找到矛盾点。 2. 人工介入，在 findings.md 中提供决定性信息或做出裁决。 3. 或者，直接修改 task_plan.md ，将该研究线程的状态标记为“已完成-需人工判断”，推动流程进入下一阶段。
恢复调查后，Claude似乎“忘记”了之前的部分内容	progress.md 文件可能未在关键时刻保存，或文件损坏。	1. 检查 progress.md 文件内容是否完整、可读。 2. 更可靠的方式是，结合 task_plan.md 和 findings.md 来手动引导：告诉Claude“请基于 task_plan.md 中‘线程2：分析内存泄漏’的当前状态，以及 findings.md 第X-Y行的发现，继续进行调查。”
技能尝试执行危险或不受欢迎的命令	提示词中可能隐含了危险操作，或技能对Bash代理的约束不足。	1. 重要 ：永远不要在具有高权限或存有关键数据的环境中以root或管理员身份运行Claude Code。 2. 在技能配置中，可以强化对Bash代理的约束指令，例如明确“禁止使用 rm -rf / 、 dd 、 chmod 777 等危险命令”。 3. 对于生产环境，建议先在隔离的沙箱或开发环境中运行调查。

最后一点个人体会 ： investigate-and-report 技能最强大的地方，不在于它比人类专家更聪明，而在于它不知疲倦、并行处理、且严格遵循流程的“超能力”。它将我从繁琐的信息搜集和初步筛选中解放出来，让我能更专注于需要人类直觉和创造力的高层决策和深度分析。它就像一个永远在线、任劳任怨的初级研究员，为你打好坚实的前站。要让它发挥最大效用，关键就在于像对待一位新同事一样，给它清晰、明确的指令和足够、规范的“资料”（上下文）。当你掌握了这一点，你会发现，许多曾经令人头疼的排查和调研工作，变得前所未有的高效和轻松。