codebase-deep-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase Deep Research

代码库深度研究

Use this skill to build a high-confidence understanding of the repository in the current working directory. Research the codebase from multiple angles in parallel, verify the important claims against primary evidence, and return a structured explanation with exact file references.

使用此 skill 对当前工作目录中的仓库建立高置信度的理解。从多个角度并行研究代码库，使用主要证据验证重要结论，并返回带有精确文件引用的结构化说明。

Scope First

先确定范围

Determine the repository boundary.

Run

git rev-parse --show-toplevel 2>/dev/null || pwd

Run

git rev-parse --abbrev-ref HEAD 2>/dev/null

Treat that repository as the scope unless the user explicitly widens it.

Define the research target.

If the user names a subsystem, feature, bug path, workflow, symbol, or directory, use that as the anchor.
If the request is broad, default to:
- top-level architecture
- build and test entrypoints
- main runtime entrypoints
- major packages or modules
- notable extension points and risky areas

State the working frame before going deep.

Say which question you are answering.
Say which directories, packages, or services are in scope.
Say whether the goal is architecture mapping, behavior tracing, comparison, or handoff preparation.

确定仓库边界。

运行

git rev-parse --show-toplevel 2>/dev/null || pwd

。

运行

git rev-parse --abbrev-ref HEAD 2>/dev/null

。

除非用户明确扩大范围，否则将该仓库视为调查范围。

定义研究目标。

如果用户指定了子系统、功能、bug 路径、工作流、symbol 或目录，则以其为锚点。
如果请求较为宽泛，默认调查：
- 顶层架构
- 构建和测试入口
- 主要运行时入口
- 主要 package 或 module
- 值得关注的扩展点和风险区域

在深入调查前说明工作框架。

说明要回答的问题。
说明涉及哪些目录、package 或 service。
说明目标是架构映射、行为追踪、方案比较还是交接准备。

Start Local, Then Fan Out

先从本地入手，再展开并行调查

Establish a baseline yourself before spawning agents:

Read the highest-value root files first:
```
README*
```
, package manifests, workspace config, build config, lint and test config, and top-level docs.
Use
```
rg --files
```
to map the repository quickly.
Use focused
```
rg
```
searches to find entrypoints, exported APIs, env vars, feature flags, tests, and target symbols.
Prefer primary evidence over assumptions: source files, tests, configs, generated types, and recent git history.

Do not stop after the first scan. Use that baseline to decide what parallel questions need answers.

在启动 Agent 之前，亲自建立基础认知：

优先阅读价值最高的根目录文件：
```
README*
```
、package manifest、workspace 配置、构建配置、lint 和测试配置，以及顶层文档。
使用
```
rg --files
```
快速梳理仓库结构。
使用聚焦的
```
rg
```
搜索查找入口、导出的 API、环境变量、feature flag、测试和目标 symbol。
优先采用主要证据而非假设：source file、测试、配置、生成的类型以及最近的 git history。

不要在首次扫描后停止。根据基础认知决定需要并行回答哪些问题。

Research Angles

调查角度

Cover at least 3 angles for any non-trivial request.

Angle	Questions to answer	Primary evidence
Structure	How is the repo organized? Which packages or modules matter?	manifests, workspace files, directory tree, README
Entrypoints	Where does execution start? What invokes the target flow?	CLI or server boot files, routes, schedulers, framework conventions
Data and control flow	How does state, input, or work move through the system?	imports, function calls, reducers, handlers, adapters
Contracts	What are the external and internal interfaces?	types, schemas, API clients, env vars, config
Validation	What proves expected behavior?	tests, fixtures, snapshots, assertions
History	Why is it this way? What changed recently?	`git log` , docs, ADRs, comments, TODOs

For broad architecture requests, cover

structure

entrypoints

contracts

, and

history

For targeted tracing requests, cover

entrypoints

data and control flow

validation

, and

history

任何非简单请求都至少覆盖 3 个角度。

角度	需要回答的问题	主要证据
Structure（结构）	仓库如何组织？哪些 package 或 module 最为重要？	manifest、workspace file、directory tree、README
Entrypoints（入口点）	执行从哪里开始？是什么触发目标流程？	CLI 或 server boot file、route、scheduler、framework convention
Data and control flow（数据与控制流）	状态、输入或工作如何在系统中流转？	import、function call、reducer、handler、adapter
Contracts（契约）	外部和内部接口是什么？	type、schema、API client、环境变量、配置
Validation（验证）	有什么证据能够证明预期行为？	test、fixture、snapshot、assertion
History（历史）	为什么形成了当前设计？最近发生了哪些变化？	`git log` 、文档、ADR、comment、TODO

对于宽泛的架构请求，应覆盖

structure

、

entrypoints

、

contracts

和

history

。

对于有明确目标的追踪请求，应覆盖

entrypoints

、

data and control flow

、

validation

和

history

。

Subagent Strategy

Subagent 策略

Prefer

explorer

subagents for read-only codebase research. Use multiple subagents for disjoint questions, not duplicate summaries.

Before spawning, sketch the investigation graph for yourself:

goal
first-wave lanes
ownership for each lane
merge points
what evidence each lane must return

Recommended first wave for a medium or large repository:

Architecture explorer

Own repo structure, packages, entrypoints, and build or runtime map.

Target-flow explorer

Own the specific subsystem, symbol, or workflow the user cares about.

Validation and history explorer

Own tests, docs, recent commits, and known edge cases for that area.

Cross-check explorer

Own contradictions, alternate code paths, feature flags, generated code, or configuration branches.

Prompt each subagent with a crisp contract:

exact question
exact directories or files to prioritize
read-only expectation
required file references
unanswered questions to surface
no generic recap of the whole repository

Example handoffs:

Architecture explorer: Map the monorepo packages, build entrypoints, and runtime entrypoints. Cite exact files and explain how requests or jobs begin.

Target-flow explorer: Trace feature X from inbound trigger to output or storage. Name the main functions, types, and branch conditions with file refs.

Validation and history explorer: Find tests, docs, and recent commits that confirm or complicate the current behavior of feature X.

Cross-check explorer: Identify alternate paths, feature flags, environment-specific code, or generated artifacts that could change the explanation.

Use

worker

fast-coder

only when a bounded helper artifact would materially improve the research, such as:

generating a quick dependency inventory
running a focused repro script
extracting a list of matches for a symbol family

Keep those tasks read-only unless the user also asked for code changes.

只读代码库研究优先使用

explorer

subagent。让多个 subagent 分别负责互不重叠的问题，而不是重复总结相同内容。

启动前，先为自己梳理调查图：

目标
第一轮调查方向
每个方向的负责范围
汇合点
每个方向必须返回的证据

中型或大型仓库推荐的第一轮安排：

Architecture explorer

负责仓库结构、package、入口以及构建或运行时映射。

Target-flow explorer

负责用户关注的具体子系统、symbol 或工作流。

Validation and history explorer

负责相关测试、文档、最近 commit 和已知边界情况。

Cross-check explorer

负责排查矛盾、替代代码路径、feature flag、生成的代码或配置分支。

为每个 subagent 提供清晰的任务约定：

精确问题
需要优先查看的目录或文件
只读要求
必须提供的文件引用
需要 surfaced 的未解答问题
不要对整个仓库进行泛泛总结

任务交接示例：

Architecture explorer: Map the monorepo packages, build entrypoints, and runtime entrypoints. Cite exact files and explain how requests or jobs begin.

Target-flow explorer: Trace feature X from inbound trigger to output or storage. Name the main functions, types, and branch conditions with file refs.

Validation and history explorer: Find tests, docs, and recent commits that confirm or complicate the current behavior of feature X.

Cross-check explorer: Identify alternate paths, feature flags, environment-specific code, or generated artifacts that could change the explanation.

仅当生成范围明确的辅助产物能显著提升研究质量时，才使用

worker

或

fast-coder

，例如：

生成快速 dependency inventory
运行聚焦的 repro script
提取某个 symbol family 的匹配列表

除非用户同时要求修改代码，否则这些任务应保持只读。

Deepen the Investigation

深化调查

After the first wave returns:

Read the key files yourself.

Do not rely solely on subagent summaries.
Open the concrete files they cite and verify the important claims.

Resolve gaps with targeted follow-ups.

Spawn a second wave only for unanswered questions or contradictions.
Narrow the scope each time: one path, one package, one interface, one ambiguity.

Cross-check behavior from multiple sources.

Match implementation claims against tests and config.
Match runtime explanations against framework conventions and actual call sites.
Use
```
git log -- <path>
```
or
```
git blame
```
when history matters.

第一轮结果返回后：

亲自阅读关键文件。

不要仅依赖 subagent 的总结。
打开它们引用的具体文件，验证重要结论。

通过有针对性的后续调查解决信息缺口。

仅针对未解答的问题或矛盾发起第二轮 Agent。
每次都缩小范围：一条路径、一个 package、一个 interface 或一个歧义点。

从多个来源交叉验证行为。

将实现结论与测试和配置进行对照。
将运行时解释与 framework convention 和实际 call site 进行对照。
当历史信息很重要时，使用
```
git log -- <path>
```
或
```
git blame
```
。

Hypothesis Discipline

假设规范

When behavior is ambiguous, state 1 to 3 concrete hypotheses and work them down with evidence.

Label each one as
```
CONFIRMED
```
,
```
REJECTED
```
, or
```
UNRESOLVED
```
.
Tie each verdict to files, tests, config, or history.
Prefer a smaller set of sharp hypotheses over a vague list of possibilities.
Leave a hypothesis
```
UNRESOLVED
```
if the codebase does not support a stronger claim.

当行为存在歧义时，提出 1 到 3 个具体假设，并用证据逐一验证。

将每个假设标记为
```
CONFIRMED
```
、
```
REJECTED
```
或
```
UNRESOLVED
```
。
为每个结论关联 file、test、config 或 history。
相比模糊罗列各种可能性，更推荐少量且明确的假设。
如果代码库无法支持更确定的结论，则将假设保留为
```
UNRESOLVED
```
。

Output

输出

Return a compact research report with:

Scope: repo root, branch, target question, and assumptions
Executive summary: the answer in 3 to 6 sentences
System map: key modules or packages and how they relate
Trace: the relevant flow from entrypoint to effect
Evidence: exact file references for the main claims
Impact surface: likely callers, dependencies, configs, and tests affected by edits in this area
Variants and edge cases: feature flags, alternate paths, env-specific behavior, generated code, or version boundaries
Hypotheses: any
```
CONFIRMED
```
,
```
REJECTED
```
, or
```
UNRESOLVED
```
behavior questions that mattered
Confidence and open questions: what is verified, inferred, or still uncertain
Next steps: only if useful, such as where to edit, what to test, or what to verify next

Prefer file references over long code quotes. Distinguish direct evidence from inference.

返回一份紧凑的研究报告，包括：

Scope（范围）：仓库根目录、branch、目标问题和假设
Executive summary（执行摘要）：用 3 到 6 句话给出答案
System map（系统映射）：关键 module 或 package 及其关系
Trace（追踪）：从入口到最终影响的完整相关流程
Evidence（证据）：主要结论对应的精确文件引用
Impact surface（影响范围）：编辑该区域时可能受影响的调用方、dependency、配置和测试
Variants and edge cases（变体与边界情况）：feature flag、替代路径、环境相关行为、生成的代码或版本边界
Hypotheses（假设）：重要的行为问题及其
```
CONFIRMED
```
、
```
REJECTED
```
或
```
UNRESOLVED
```
状态
Confidence and open questions（置信度与开放问题）：哪些内容已经验证、属于推断或仍不确定
Next steps（后续步骤）：仅在有实际价值时提供，例如应在哪里编辑、测试什么或接下来验证什么

优先引用文件，而不是粘贴大段代码。区分直接证据与推断。

Guardrails

约束条件

Stay inside the current local codebase unless the user explicitly asks for external research.
Do not answer from a quick skim when the request needs a trace across multiple files.
Do not delegate the final synthesis; keep dedupe, contradiction handling, and confidence scoring local.
Do not spawn multiple subagents onto the same vague question.
Do not turn this into implementation work unless the user asks for changes.
If the repo is huge, narrow the question instead of pretending to understand everything.
If evidence conflicts, say so plainly and cite both sides.
Use
```
$recent-work-context
```
separately when the user wants prior Codex session state rather than code behavior.
Use
```
$debugger-mode
```
separately when the answer depends on runtime repro, instrumentation, or live evidence.

除非用户明确要求外部研究，否则将调查范围限制在当前本地代码库内。
当请求需要跨多个文件追踪行为时，不要仅凭快速浏览便给出答案。
不要将最终综合分析完全委托给 Agent；应在本地完成去重、矛盾处理和置信度评估。
不要让多个 subagent 重复处理同一个模糊问题。
除非用户要求修改代码，否则不要将研究转化为实现工作。
如果仓库规模很大，应缩小问题范围，而不是假装已经理解整个仓库。
如果证据存在冲突，应明确说明并同时引用双方。
当用户需要先前的 Codex session state 而非代码行为时，单独使用
```
$recent-work-context
```
。
当答案依赖运行时复现、instrumentation 或 live evidence 时，单独使用
```
$debugger-mode
```
。

Default Depth

默认深度

If the user says only "research this codebase," produce:

Repository shape and major packages or modules.
Build, test, and local development entrypoints.
Main runtime entrypoints.
One representative end-to-end flow.
Important contracts and configuration.
Highest-risk or least-obvious areas worth knowing before editing.

如果用户只说"research this codebase"，应输出：

仓库形态以及主要 package 或 module。
构建、测试和本地开发入口。
主要运行时入口。
一条具有代表性的端到端流程。
重要契约和配置。
编辑前最值得了解的高风险或最不明显区域。