how

怎么工作：把子系统讲清楚

Explore the codebase to answer “how does X work?” questions. Produce 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.

扫代码库，回答「X 怎么工作」。目标是资深工程师上手子系统时的架构讲解：够搭起可用的心智模型，别写成带注释的源码朗读。

Step 1. Assess Complexity

Step 1. 评估复杂度

If the scope is ambiguous, state your interpretation and explore. The user can redirect.

范围含糊就先说出你的理解再探索。用户可以纠正方向。

• Simple (a single module, a small utility, a narrow question such as “how does function X work”): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.

• Complex (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): spawn parallel explorers first, then hand off to the explainer. Go to Step 2a.

• Simple（单个模块、小工具、窄问题如「函数 X 怎么工作」）：不用 explorer。一个 explainer 一次扫完并讲完。去 Step 2b。

• Complex（跨多文件/服务的子系统、横切特性、完整架构总览）：先并行 spawn explorer，再交给 explainer。去 Step 2a。

When in doubt, take the simple path.

拿不准就走简单路径。

Step 2a. Explore (complex questions only)

Step 2a. 探索（仅复杂问题）

Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message:

把问题拆成 2 到 4 个探索角度，每个是子系统的一块切片。在同一条消息里 spawn 全部 explorer：

• subagent_type: generalPurpose

• model: your configured how-explorer model (default grok-4.7-xhigh-fast)

• readonly: true

• subagent_type: generalPurpose

• model: 你配置的 how-explorer 模型（默认 grok-4.7-xhigh-fast）

• readonly: true

Each explorer gets the prompt in references/explorer-prompt.md with its angle filled in. Then go to Step 3.

每个 explorer 用 references/explorer-prompt.md 的 prompt，填入各自角度。然后去 Step 3。

Step 2b. Direct Explain (simple questions)

Step 2b. 直接讲解（简单问题）

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

Spawn 一个 Task subagent，一次完成探索和讲解：

• subagent_type: generalPurpose

• model: your configured how-explainer model (default claude-opus-5-5-max)

• readonly: true

• subagent_type: generalPurpose

• model: 你配置的 how-explainer 模型（默认 claude-opus-5-5-max）

• readonly: true

Build its prompt from references/explainer-prompt.md without the explorer-findings section. Go to Step 4.

用 references/explainer-prompt.md 组 prompt，不要 explorer-findings 那一段。去 Step 4。

Step 3. Synthesize (complex questions only)

Step 3. 综合（仅复杂问题）

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

等全部 explorer 回来后，spawn 一个 Task subagent，把发现合成一份讲解：

• subagent_type: generalPurpose

• model: your configured how-explainer model (default claude-opus-5-5-max)

• readonly: true

• subagent_type: generalPurpose

• model: 你配置的 how-explainer 模型（默认 claude-opus-5-5-max）

• readonly: true

Build its prompt from references/explainer-prompt.md with every explorer’s findings filled in.

用 references/explainer-prompt.md 组 prompt，填入每个 explorer 的发现。

Step 4. Present

Step 4. 呈现

Present the explainer’s output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.

把 explainer 的输出交给用户。为清晰或对话上下文做轻度编辑可以；不要大改重写。

Output Format

输出格式

The explanation uses the sections defined in references/explainer-prompt.md, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.

讲解按 references/explainer-prompt.md 里的小节来，不适用的直接丢掉：Overview、Key Concepts、How It Works、Where Things Live、Gotchas。