researching-codebases

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Researching Codebases

代码库研究

Coordinate parallel sub-agents to answer complex codebase questions.

协调并行子代理（sub-agents）以回答关于代码库的复杂问题。

When to Use

使用场景

Questions spanning multiple files or components
"How does X work?" requiring tracing through code
Finding patterns or examples across the codebase
Understanding architectural decisions or data flow

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

When NOT to Use

不适用场景

Simple "where is X?" - use
```
code-locator
```
directly
Single file questions - just read the file
External/web research only - use
```
web-searcher
```
directly

简单的“X在哪里？”问题——直接使用
```
code-locator
```
仅涉及单个文件的问题——直接读取该文件即可
仅需外部/网络研究的问题——直接使用
```
web-searcher
```

Workflow

工作流程

0. Check past research (optional)

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

Before decomposing a new research question, consider checking for related past research:

Run
```
list-research.py
```
script to see recent research docs
Run
```
search-research.py
```
script with relevant keywords
If related research exists, run
```
read-research.py
```
script to load it
Build on previous findings instead of starting fresh

See

research-tools.md

for script usage.

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

运行
```
list-research.py
```
脚本查看近期研究文档
使用相关关键词运行
```
search-research.py
```
脚本
若存在相关研究，运行
```
read-research.py
```
脚本加载该研究
基于已有研究结果继续，无需从头开始

脚本使用方法详见

research-tools.md

。

1. Read mentioned files first

1. 先阅读提及的文件

If the user references specific files, read them FULLY before spawning agents. This gives you context for decomposition.

如果用户提到了特定文件，在启动代理前先完整读取这些文件。这能为你提供拆解问题的上下文信息。

2. Decompose the question

2. 拆解问题

Break the query into parallel research tasks. Consider:

Which areas of the codebase are relevant?
Do I need locations, analysis, or examples?
See
```
agent-selection.md
```
for agent capabilities

将查询拆解为多个并行的研究任务。思考以下几点：

代码库的哪些领域与此相关？
是否需要定位、分析或示例？
代理能力详见
```
agent-selection.md
```

3. Spawn parallel agents

3. 启动并行代理

Launch multiple agents concurrently for independent tasks. Use the

task

tool with appropriate

subagent_type

Wait for ALL agents to complete before synthesizing.

为独立任务同时启动多个代理。使用

task

工具并指定合适的

subagent_type

。

需等待所有代理完成后再进行结果整合。

4. Synthesize and respond

4. 整合结果并回复

Combine findings into a coherent answer:

Direct answer to the question
Key
```
file:line
```
references
Connections between components
Open questions if any areas need more investigation

将所有研究结果整合成连贯的回答：

直接回应用户的问题
标注关键的
```
文件:行号
```
引用
说明组件间的关联
若有需要进一步研究的领域，列出未解决的问题

5. Offer to save (optional)

5. 询问是否保存结果（可选）

For substantial research, ask:

Want me to save this to a research doc? (project:
.research/
or global:
~/.research/
)

Skip this for quick answers.

When saving:

Run
```
gather-metadata.py
```
script to get date, repo, branch, commit, cwd.
Add query (from user's question) and tags (from content)
Format YAML frontmatter per
```
output-format.md
```
Create directory if it doesn't exist
Use filename:
```
{filename_date}_topic-slug.md
```

对于较为深入的研究，可询问用户：

是否需要将本次研究保存为研究文档？（项目级：
.research/
或全局级：
~/.research/
）

简单问题可跳过此步骤。

保存时需执行以下操作：

运行
```
gather-metadata.py
```
脚本获取日期、仓库、分支、提交记录、当前工作目录信息。
添加用户的问题（作为查询内容）和标签（从研究内容中提取）
按照
```
output-format.md
```
的要求格式化YAML前置内容
若目录不存在则创建
文件命名格式：
```
{filename_date}_topic-slug.md
```

Agent Reference

代理参考

See

agent-selection.md

for when to use each agent.

各代理的适用场景详见

agent-selection.md

。

Common Mistakes

常见错误

Spawning agents before reading context: Read any files the user mentions first.

Not waiting for all agents: Synthesize only after ALL agents complete.

Over-documenting simple answers: Not every question needs a saved research doc.

Sequential when parallel works: If tasks are independent, spawn them together.

未读取上下文就启动代理： 先完整读取用户提及的所有文件。

未等待所有代理完成： 必须等所有代理都完成后再整合结果。

简单问题过度文档化： 并非所有问题都需要保存为研究文档。

可并行却串行处理： 若任务相互独立，应同时启动代理。