how

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

How

操作步骤

Explore the codebase to answer "how does X work?" questions. Produce clear architectural explanations at the level of a senior engineer onboarding onto a subsystem — enough to build a working mental model, not so much that it reads like annotated source code.

Two modes:

Explain (default) — explore the codebase and produce a clear explanation
Critique — explain first, then spawn multiple models to independently identify architectural issues

探索代码库以解答“X是如何工作的？”这类问题。生成的架构说明需达到资深工程师入职子系统时所需的深度——足以构建有效的心智模型，但又不会像带注释的源代码那样冗长。

两种模式：

说明（默认）——探索代码库并生成清晰的说明
评审——先进行说明，再调用多个模型独立识别架构问题

Explain Mode

说明模式

Step 1 — Understand the Question and Assess Complexity

步骤1 — 理解问题并评估复杂度

Parse what the user is asking about. They might say:

"How does message virtualization work?" — a subsystem
"How do we handle billing for on-demand usage?" — a feature flow
"How is the auth service structured?" — an architectural overview
"Walk me through what happens when a user sends a message" — a runtime trace

Identify the scope. If it's ambiguous, make your best guess and state your interpretation before exploring. Don't ask — explore and let the user redirect if you're off.

Assess complexity to decide the approach:

Simple (a single module, a small utility, a narrow question like "how does function X work"): Skip explorer agents entirely. The explainer agent explores and explains in a single pass. Go directly to Step 2b.
Complex (a subsystem spanning multiple files/services, a cross-cutting feature, a full architectural overview): Spawn parallel explorer agents first, then hand off to the explainer. Go to Step 2a.

When in doubt, lean toward the simple path — you can always spawn explorers if the explainer hits a wall.

解析用户的问题。用户可能会问：

“消息虚拟化是如何工作的？”——针对子系统
“我们如何处理按需使用的计费？”——针对功能流程
“认证服务的结构是怎样的？”——针对架构概述
“带我了解用户发送消息时的整个流程”——针对运行时追踪

确定问题范围。如果范围模糊，先做出最佳猜测并在探索前说明你的理解。不要询问用户，直接探索，若理解有误再由用户纠正。

评估复杂度以确定方法：

简单（单个模块、小型工具类、如“函数X如何工作”这类具体问题）：完全跳过探索Agent。由说明Agent一次性完成探索和说明。直接进入步骤2b。
复杂（跨多个文件/服务的子系统、横向功能、完整架构概述）：先调用并行探索Agent，再交由说明Agent处理。进入步骤2a。

若不确定，优先选择简单路径——如果说明Agent遇到瓶颈，再调用探索Agent即可。

Step 2a — Explore (complex questions only)

步骤2a — 探索（仅针对复杂问题）

Decompose the question into 2-4 parallel exploration angles. Each angle should cover a distinct slice of the subsystem so the explorers aren't duplicating work. For example, if the question is "how does message virtualization work?", you might split into:

Explorer 1: the data model and state management
Explorer 2: the rendering pipeline and DOM interaction
Explorer 3: the scroll/measurement infrastructure

The right decomposition depends on the question — use your judgment. For narrow questions, 2 explorers is fine. For broad subsystems, use up to 4.

Spawn all explorers in a single message:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
gpt-5.4
```
```
readonly
```
:
```
true
```

Each explorer gets the same base prompt from

references/explorer-prompt.md

, plus a specific exploration angle telling it which slice to focus on. Each explorer should:

Start broad: Glob for relevant directories, Grep for key types/interfaces/class names
Follow the thread: once you find an entry point, trace the call chain — callers, callees, data flow, type definitions
Read the actual code, don't guess from file names
Stop when you can describe the full path from input to output (or from trigger to effect) without hand-waving any step
Note things that are surprising, non-obvious, or that a newcomer would get wrong

Each explorer returns structured findings: the components it found, the flow it traced, the files it read, and anything non-obvious. Overlap between explorers is fine — the explainer will reconcile.

Then proceed to Step 3.

将问题拆解为2-4个并行探索方向。每个方向应覆盖子系统的不同部分，避免探索Agent重复工作。例如，若问题是“消息虚拟化是如何工作的？”，可拆分为：

探索Agent 1：数据模型与状态管理
探索Agent 2：渲染流水线与DOM交互
探索Agent 3：滚动/测量基础设施

拆分方式需根据问题而定——请自行判断。对于具体问题，2个探索Agent足够；对于宽泛的子系统，最多使用4个。

在一条消息中调用所有探索Agent：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
gpt-5.4
```
```
readonly
```
:
```
true
```

每个探索Agent将获得

references/explorer-prompt.md

中的基础提示，加上一个特定的探索方向，告知其需聚焦的部分。每个探索Agent应：

从宽泛入手：全局搜索相关目录，查找关键类型/接口/类名
顺藤摸瓜：找到入口点后，追踪调用链——调用方、被调用方、数据流、类型定义
阅读实际代码，不要仅通过文件名猜测
当无需含糊其辞即可描述从输入到输出（或从触发到效果）的完整路径时停止探索
记录令人惊讶、非显而易见或新手容易出错的内容

每个探索Agent返回结构化结果：找到的组件、追踪的流程、读取的文件，以及所有非显而易见的内容。探索Agent之间的结果重叠无关紧要——说明Agent会进行协调。

之后进入步骤3。

Step 2b — Direct Explain (simple questions)

步骤2b — 直接说明（针对简单问题）

Spawn a single Task subagent that explores and explains in one pass:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4.6
```
```
readonly
```
:
```
true
```

This agent does its own exploration (Glob, Grep, Read) and writes the explanation directly. Read

references/explainer-prompt.md

for the communication style and output format — the agent follows the same structure, it just doesn't have explorer findings as input.

Proceed to Step 4.

调用单个任务子Agent，一次性完成探索和说明：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4.6
```
```
readonly
```
:
```
true
```

该Agent自行完成探索（全局搜索、查找、读取）并直接撰写说明。请阅读

references/explainer-prompt.md

了解沟通风格和输出格式——该Agent遵循相同的结构，只是无需以探索结果作为输入。

进入步骤4。

Step 3 — Synthesize (complex questions only)

步骤3 — 综合（仅针对复杂问题）

Once all explorers have returned, spawn a single Task subagent to synthesize their findings into one coherent explanation:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4.6
```
```
readonly
```
:
```
true
```

The explainer gets all explorers' findings and writes the human-facing explanation (see output format below). Read

references/explainer-prompt.md

for the full prompt template. The explainer reconciles overlapping findings, resolves contradictions, and weaves the separate slices into a unified picture.

所有探索Agent返回结果后，调用单个任务子Agent将结果整合成连贯的说明：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4.6
```
```
readonly
```
:
```
true
```

说明Agent将获取所有探索Agent的结果，并撰写面向用户的说明（见下文输出格式）。请阅读

references/explainer-prompt.md

获取完整提示模板。说明Agent会协调重叠的结果、解决矛盾，并将各个部分整合成统一的内容。

Step 4 — Present

步骤4 — 呈现

Take the explainer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite — the explainer agent's communication is the product.

将说明Agent的输出呈现给用户。你可稍作编辑以提升清晰度，或添加对话上下文，但不要大幅重写——说明Agent的输出即为最终成果。

Output Format

输出格式

The explanation should follow this structure, but adapt it to what makes sense for the question. Not every section is needed for every question.

Overview — 1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read this and decide whether they need to keep reading.

Key Concepts — The important types, services, or abstractions. Brief definition of each, not exhaustive — just the ones needed to understand the rest.

How It Works — The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where does data go, what are the decision points. Use prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a specific snippet is genuinely necessary to understand the point.

Where Things Live — A brief map of the relevant files/directories. Not every file — just the ones someone would need to find to start working in this area.

Gotchas — Things that are non-obvious, surprising, or that would trip someone up. Historical context that explains why something looks weird. Known sharp edges.

说明应遵循以下结构，但可根据问题适当调整。并非每个部分都适用于所有问题。

概述——1-2段。介绍该功能是什么、作用是什么、存在的意义。读者阅读后应能判断是否需要继续阅读。

核心概念——重要的类型、服务或抽象概念。每个概念给出简要定义，无需详尽——仅保留理解后续内容所需的部分。

工作原理——说明的核心部分。逐步讲解流程：触发条件、每一步的操作、数据流向、决策点。使用散文式语言，而非伪代码。引用具体文件和函数，方便读者查阅，但除非某段代码对理解至关重要，否则不要直接粘贴代码块。

文件位置——相关文件/目录的简要说明。无需列出所有文件——仅保留读者开始在此领域工作时需要查找的文件。

注意事项——非显而易见、令人惊讶或容易让新手出错的内容。解释某些设计看起来怪异的历史背景。已知的潜在问题。

Critique Mode

评审模式

Triggered when the user asks for architectural issues, problems, or improvements — not just understanding.

当用户询问架构问题、缺陷或改进建议时触发——而非仅需理解系统。

Step 1 — Explain First

步骤1 — 先进行说明

Run the full explain flow above (Steps 1-4). You need to understand the architecture before you can critique it.

运行上述完整的说明流程（步骤1-4）。在评审架构前，你需要先理解它。

Step 2 — Spawn Critics

步骤2 — 调用评审Agent

After the explanation is complete, spawn architectural critics. Launch all in a single message:

Subagent	Model
Critic A	`claude-opus-4.6`
Critic B	`composer-2`
Critic C	`gpt-5.4`

For each critic:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
: the model from the table. These are starting suggestions — escalate to a higher reasoning tier of the same model family when the architecture warrants deeper analysis.
```
readonly
```
:
```
true
```

Read

references/critic-prompt.md

for the prompt template. Each critic gets:

The explanation from Step 1 (so they don't waste time re-exploring)
The relevant file paths (so they can read the actual code)
The architectural critique rubric from
```
references/critique-rubric.md
```

说明完成后，调用架构评审Agent。在一条消息中启动所有评审Agent：

子Agent	模型
Critic A	`claude-opus-4.6`
Critic B	`composer-2`
Critic C	`gpt-5.4`

每个评审Agent的配置：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
: 表格中的模型。这些是初始建议——若架构需要更深入的分析，可升级为同模型家族的更高推理层级。
```
readonly
```
:
```
true
```

请阅读

references/critic-prompt.md

获取提示模板。每个评审Agent将获得：

步骤1生成的说明（避免重复探索）
相关文件路径（以便读取实际代码）
```
references/critique-rubric.md
```
中的架构评审准则

Step 3 — Lead Judgment

步骤3 — 主导判断

You're a pragmatic lead, not an aggregator.

Categorize findings:

Act on — Architectural problems worth fixing now
Consider — Real concerns, but the cost/benefit is unclear
Noted — Valid observations, low priority
Dismissed — Wrong, missing context, or style preference

Present the explanation first (from Step 1), then the critique verdict below it. The explanation should stand on its own — someone who just wants to understand the system shouldn't have to wade through critique.

你是务实的负责人，而非结果汇总者。

对结果进行分类：

立即处理——当前值得修复的架构问题
考虑处理——确实存在问题，但成本/收益尚不明确
记录在案——有效观察，但优先级较低
不予采纳——错误结论、缺乏上下文或仅为风格偏好

先呈现说明内容（来自步骤1），再在下方呈现评审结论。说明内容应独立存在——仅需理解系统的用户无需浏览评审内容。