researching-codebases

研究代码库

协调多个子 Agent 并行回答复杂的代码库问题。

适用场景

• 涉及多个文件或组件的问题
• 需要追踪代码才能回答的“X 是如何工作的？”类问题
• 在代码库中查找模式或示例
• 理解架构决策或数据流

不适用场景

• 简单的“X 在哪里？”问题——直接使用 code-locator
• 只涉及单个文件的问题——直接阅读该文件
• 仅涉及外部或 Web 研究的问题——直接使用 web-searcher

工作流

0. 检查以往研究（可选）

拆解新的研究问题前，可以先检查是否存在相关的以往研究：

1. 运行 list-research.py 脚本，查看近期的研究文档
2. 运行 search-research.py 脚本，搜索相关关键词
3. 如果存在相关研究，运行 read-research.py 脚本将其加载
4. 基于先前的发现继续研究，而不是从头开始

脚本用法请参阅 research-tools.md。

1. 先阅读提及的文件

如果用户提到了特定文件，请在启动 Agent 前完整阅读这些文件。这能为拆解问题提供背景。

2. 拆解问题

将查询拆分成并行的研究任务。请考虑：

• 代码库的哪些部分与问题相关？
• 我需要查找位置、进行分析，还是寻找示例？
• Agent 的能力请参阅 agent-selection.md

3. 启动并行 Agent

对于彼此独立的任务，同时启动多个 Agent。使用 task 工具并选择合适的 subagent_type。

等待所有 Agent 完成后再综合结果。

4. 综合并作答

将发现整合成连贯的回答：

• 直接回答问题
• 提供关键的 file:line 引用
• 说明各组件之间的关联
• 如果某些方面仍需进一步调查，指出尚未解决的问题

5. 提议保存（可选）

对于内容较多的研究，可以询问：

要我将这些内容保存为研究文档吗？（项目级：.research/；全局：~/.research/）

简单问题无需询问。

保存时：

1. 运行 gather-metadata.py 脚本获取日期、仓库、分支、提交和当前工作目录。
2. 添加查询内容（来自用户的问题）和标签（根据内容确定）
3. 按照 output-format.md 的要求设置 YAML frontmatter 格式
4. 如果目录不存在，则创建该目录
5. 使用文件名：{filename_date}_topic-slug.md

Agent 参考

何时使用各个 Agent，请参阅 agent-selection.md。

常见错误

尚未阅读背景信息就启动 Agent： 先阅读用户提及的文件。

未等待所有 Agent 完成： 只有在所有 Agent 均完成后才能综合结果。

简单回答却过度记录： 并非每个问题都需要保存为研究文档。

可以并行却按顺序执行： 如果任务彼此独立，就同时启动。