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 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:

"How does the rate limiter 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 submits a form", a runtime trace

Identify the scope. If ambiguous, state your best-guess interpretation before exploring. Don't ask. 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; the explainer explores and explains in a single pass. Go 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 simple. 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 a distinct slice of the subsystem so explorers don't duplicate work. Example split for "how does the rate limiter work?":

Explorer 1: data model and state management
Explorer 2: request path and enforcement
Explorer 3: configuration and metrics infrastructure

The right decomposition depends on the question. Use your judgment. Narrow questions: 2 explorers is fine. Broad subsystems: up to 4.

Spawn all explorers in a single message:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
composer-2.5-fast
```
```
readonly
```
:
```
true
```

Each explorer gets the same base prompt from

references/explorer-prompt.md

plus a specific exploration angle naming its slice. Each explorer should:

Start broad: Glob for relevant directories, Grep for key types/interfaces/class names
Follow the thread: from 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 it can describe the full path from input to output (or 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: components found, flow traced, files read, anything non-obvious. Overlap between explorers is fine; the explainer reconciles.

Then proceed to Step 3.

将问题拆解为2-4个并行探索方向，每个方向对应子系统的不同部分，避免探索Agent重复工作。例如，针对“限流组件是如何工作的？”的拆分方式：

探索Agent 1：数据模型与状态管理
探索Agent 2：请求路径与执行逻辑
探索Agent 3：配置与指标基础设施

合理的拆分方式取决于具体问题，请自行判断。窄范围问题：2个探索Agent即可；宽泛的子系统：最多4个。

在单条消息中启动所有探索Agent：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
composer-2.5-fast
```
```
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-8-thinking-xhigh
```
```
readonly
```
:
```
true
```

The 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. Same structure, just no explorer findings as input.

Proceed to Step 4.

启动单个任务子Agent，一次性完成探索与解释：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4-8-thinking-xhigh
```
```
readonly
```
:
```
true
```

该Agent将自行完成探索（搜索、查找、读取）并直接撰写解释内容。请参考

references/explainer-prompt.md

中的沟通风格与输出格式。结构一致，只是无需输入探索Agent的结果。

进入步骤4。

Step 3. Synthesize (complex questions only)

步骤3. 整合（仅适用于复杂问题）

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

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4-8-thinking-xhigh
```
```
readonly
```
:
```
true
```

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

references/explainer-prompt.md

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

所有探索Agent返回结果后，启动单个任务子Agent将结果整合成连贯的解释内容：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
:
```
claude-opus-4-8-thinking-xhigh
```
```
readonly
```
:
```
true
```

解释Agent将获取所有探索Agent的结果，并撰写面向人类的解释内容（输出格式如下）。请参考

references/explainer-prompt.md

中的完整提示模板。解释Agent会整合重叠结果、解决矛盾，并将各部分内容编织成统一的整体。

Step 4. Present

步骤4. 呈现

Present the explainer's output to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite. The explainer's communication is the product.

将解释Agent的输出内容呈现给用户。你可稍作编辑以提升清晰度，或添加对话中的上下文信息，但请勿大幅改写。解释Agent的输出即为最终成果。

Output Format

输出格式

Follow this structure, adapted to the question. Not every section is needed for every question.

Overview. 1-2 paragraphs. What it is, what it does, why it exists. Enough to decide whether 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 data goes, the decision points. Prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a snippet is genuinely necessary.

Where Things Live. A brief map of the relevant files/directories. Not every file, just the ones needed to start working in this area.

Gotchas. Non-obvious or surprising things 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 must understand the architecture before critiquing 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-8-thinking-xhigh`
Critic B	`gpt-5.3-codex-high-fast`
Critic C	`gpt-5.5-high-fast`

For each critic:

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
: the model from the table. These are minimum reasoning levels. The lead should escalate any model 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 re-explore)
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-8-thinking-xhigh`
Critic B	`gpt-5.3-codex-high-fast`
Critic C	`gpt-5.5-high-fast`

每个评审Agent的配置：

```
subagent_type
```
:
```
generalPurpose
```
```
model
```
: 表格中对应的模型。这些是最低推理级别。若架构需要更深入的分析，负责人可升级模型。
```
readonly
```
:
```
true
```

请参考

references/critic-prompt.md

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

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

Step 3. Lead Judgment

步骤3. 负责人判断

Same framework as the interrogate skill. 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 wade through critique.

与interrogate技能的框架一致。你是务实的负责人，而非结果汇总者。

对评审结果进行分类：

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

先呈现步骤1中的解释内容，再展示评审结论。解释内容需独立成篇；仅需理解系统的用户无需浏览评审内容。