explain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explain — guided walk-through of code

解释——代码引导式梳理

Produce a focused, file-anchored explanation. The output is conversational — NOT a permanent doc. If the user wants a persistent artifact, point them at

write-doc

document-feature

, or

arc42

生成聚焦于文件的针对性解释。输出风格为对话式——而非永久文档。如果用户需要持久化成果，请引导他们使用

write-doc

、

document-feature

或

arc42

。

Before You Start

开始之前

Root
```
CLAUDE.md
```
— the ambient context. Read it before explaining anything to match the project's vocabulary.
Any scope-level
```
CLAUDE.md
```
relevant to the code in question.
If the project has an arc42 tree under
```
docs/arc42/
```
or similar, chapters 3 (context), 4 (solution strategy), and 5 (building blocks) are the best orientation for higher-level explanations.

根目录下的
```
CLAUDE.md
```
——全局上下文。在解释任何内容前先阅读它，确保与项目术语保持一致。
所有与待解释代码相关的作用域级
```
CLAUDE.md
```
文件。
如果项目在
```
docs/arc42/
```
或类似路径下有arc42目录结构，第3章（上下文）、第4章（解决方案策略）和第5章（构建模块）是进行更高层级解释的最佳参考资料。

Step 1: scope the ask

步骤1：明确需求范围

Clarify what level the user wants:

Level	Example ask	What you do
Line/function	"What does `calculateDiscount` do?"	Read the function and adjacent helpers, explain mechanics.
File/module	"What does `src/billing/` do?"	Read the module, map exports to responsibilities.
Subsystem	"How does the billing pipeline work?"	Trace data flow across multiple files, draw the path.
Concept	"How does our auth model work?"	Read CLAUDE.md + the canonical implementation, explain the pattern.

If the level is ambiguous, ask before diving. A code-level walk-through and a concept-level explanation require different reading and different output shapes.

确认用户需要的解释层级：

层级	示例需求	操作方式
行/函数	“ `calculateDiscount` 是做什么的？”	阅读该函数及相关辅助函数，解释其工作机制。
文件/模块	“ `src/billing/` 模块有什么作用？”	阅读该模块，梳理导出内容对应的职责。
子系统	“计费流水线是如何工作的？”	跟踪跨多个文件的数据流，梳理路径。
概念	“我们的认证模型是如何运作的？”	阅读 `CLAUDE.md` 及标准实现代码，解释其模式。

如果层级不明确，在深入前先询问用户。代码级梳理和概念级解释需要不同的阅读方式和输出形式。

Step 2: orient yourself

步骤2：定位上下文

For a subsystem or concept explanation, start with the macro view:

bash

ls <relevant-dir>
find <relevant-dir> -type f | head -30

对于子系统或概念解释，先从宏观视角入手：

bash

ls <relevant-dir>
find <relevant-dir> -type f | head -30

Which files are central? (entry points often show up as most-imported)

哪些是核心文件？（入口文件通常是被引用最多的）


For a line or function, just open the file.


对于行或函数级解释，直接打开对应文件即可。

Step 3: read, don't assume

步骤3：阅读代码，避免假设

Open the actual files. Every claim you make should trace to a file you have just read, not to pattern-matching on the name.

Common traps:

The file name suggests one thing; the contents do another.
A class looks standard but has a project-specific override.
The "obvious" caller of a function isn't the only caller — grep for all usages.

打开实际文件。你所做的每一个结论都必须基于你刚刚阅读的文件，而非仅通过文件名进行模式匹配。

常见误区：

文件名暗示的功能与实际内容不符。
某个类看似标准，但存在项目特定的重写逻辑。
某个函数的“明显”调用方并非唯一调用方——需搜索所有调用场景。

Step 4: structure the explanation

步骤4：组织解释结构

—

行/函数级：

For a line/function:

markdown

undefined

markdown

undefined

<function-name>

<file>:<line>

<function-name>

<file>:<line>

What it does: one sentence.

Inputs: ... Returns: ... Side effects: (DB writes, network calls, mutations). None if pure.

Called from: {list of callers with file:line}.

How it works: paragraph walking through the body, naming the helper it delegates to.

Gotcha (if any): {a non-obvious thing the reader should know}.


For a module:

```markdown

功能： 一句话描述。

输入： ... 返回值： ... 副作用： （数据库写入、网络请求、状态变更）。纯函数则标注“无”。

调用方： {列出调用方的文件:行号}。

工作机制： 一段文字梳理函数主体逻辑，说明其调用的辅助函数。

注意事项（如有）： {读者需要了解的非直观细节}。

undefined

<path/to/module>

模块级：

Responsibility: one-sentence scope — what this module owns.

Key files:

```
<file1>
```
— {what it does}
```
<file2>
```
— {what it does}

Public API: the exports, briefly.

Depends on: {other modules this one imports from}. Depended on by: {modules that import this one}.

How it fits in: how a typical flow enters this module and what it hands off.


For a subsystem/concept:

```markdown

markdown

undefined

How

<concept>

works

<path/to/module>

What it is: paragraph at the right level — higher than code, lower than marketing.

The flow: step-by-step, naming files and functions at each step.

Entry: request arrives at
```
src/api/routes/<...>.ts:<line>
```
.
Middleware:
```
<middleware>
```
runs, validating
```
<x>
```
.
Handler dispatches to
```
<service.method>
```
.

Service calls

<repository.method>

and

<external-client.method>

Response is shaped by
```
<mapper.method>
```
and returned.

The contract: a minimal code reference (file + line) for the shape.

Extension points: where to add a variant. Often a factory, a registry, or a subclass.

Pitfalls: 1–3 things that trip up newcomers.

undefined

职责： 一句话描述该模块的核心范围——它负责什么。

关键文件：

```
<file1>
```
— {功能描述}
```
<file2>
```
— {功能描述}

公开API： 简要说明导出内容。

依赖： {该模块导入的其他模块}。 被依赖： {导入该模块的其他模块}。

定位： 典型流程如何进入该模块，以及它会将结果传递给哪里。

undefined

Step 5: link and stop

子系统/概念级：

End the explanation with pointers:

To go deeper: 1–2 files worth reading next.
To extend: the right skill (scaffolding, documentation) or ADR.
To verify: a test file that exercises the flow.

Do not write a wall of text. The goal is orientation, not exhaustive coverage.

markdown

undefined

Verify

<concept>

的工作机制

This skill's output is conversational, so there's no mechanical verification. Self-checks:

Every file path mentioned actually exists (grep the output against the filesystem).
No claims that aren't anchored in a file you just read.
The explanation is not a permanent artifact — it's in the chat, not in
```
docs/
```
.

定义： 一段文字，介于代码细节和营销话术之间的合适层级描述。

流程： 分步说明，每一步标注涉及的文件和函数。

入口：请求到达
```
src/api/routes/<...>.ts:<line>
```
。
中间件：
```
<middleware>
```
执行，验证
```
<x>
```
。
处理器分发至
```
<service.method>
```
。

服务调用

<repository.method>

和

<external-client.method>

。

响应由
```
<mapper.method>
```
处理后返回。

契约： 最小化的代码引用（文件+行号）说明数据结构。

扩展点： 可添加变体的位置。通常是工厂类、注册器或子类。

常见陷阱： 1-3个容易让新手出错的点。

undefined

Common Mistakes

步骤5：给出指引并结束

Mistake	Correction
Explaining based on file names without reading contents	Read every file you cite. Pattern-matching on names produces confident wrong answers.
Dumping 50 lines of code in the response	Reference the file (principle 04). The user can open it. Explain WHY, not WHAT the code already shows.
Turning an explanation into a tutorial	If the user wants a reusable walk-through, it's `write-doc` . `explain` is for one-shot context-building in the current conversation.
Answering "how does X work" by quoting `CLAUDE.md` alone	`CLAUDE.md` orients; the code answers. Read the code; cite the exact files.

解释结尾需提供相关指引：

深入学习： 推荐1-2个值得后续阅读的文件。
扩展开发： 推荐合适的技能（如scaffolding、documentation）或ADR（架构决策记录）。
验证测试： 推荐可验证该流程的测试文件。

请勿输出大段文字。目标是帮助用户快速定位，而非全面覆盖所有细节。

—

验证

—

本技能的输出为对话式，因此无需机械验证。请自行检查：

提及的所有文件路径均真实存在（可通过文件系统搜索验证）。
所有结论均基于你刚刚阅读的文件。
解释内容并非永久文档——仅用于当前对话，不会存入
```
docs/
```
目录。

—

常见错误

—

错误	修正方式
仅通过文件名而非阅读内容进行解释	阅读所有你引用的文件。仅通过文件名模式匹配会导致自信的错误答案。
在响应中粘贴50行代码	引用文件即可（原则04）。用户可自行打开文件。解释代码的原因，而非代码本身展示的内容。
将解释变成教程	如果用户需要可复用的梳理文档，请使用 `write-doc` 。 `explain` 仅用于当前对话中的一次性上下文构建。
仅引用 `CLAUDE.md` 来回答“X如何工作”	`CLAUDE.md` 仅用于定位上下文；代码才是答案。阅读代码并引用具体文件。

explain

Original

Translation

Explain — guided walk-through of code

解释——代码引导式梳理

Before You Start

开始之前

Step 1: scope the ask

步骤1：明确需求范围

Step 2: orient yourself

步骤2：定位上下文

Which files are central? (entry points often show up as most-imported)

哪些是核心文件？（入口文件通常是被引用最多的）

Step 3: read, don't assume

步骤3：阅读代码，避免假设

Step 4: structure the explanation

步骤4：组织解释结构

行/函数级：

`<function-name>`
in
`<file>:<line>`

`<function-name>`
in
`<file>:<line>`

`<path/to/module>`

模块级：

How
`<concept>`
works

`<path/to/module>`

Step 5: link and stop

子系统/概念级：

Verify

`<concept>`
的工作机制

Common Mistakes

步骤5：给出指引并结束

验证

常见错误

explain

Original

Translation

Explain — guided walk-through of code

解释——代码引导式梳理

Before You Start

开始之前

Step 1: scope the ask

步骤1：明确需求范围

Step 2: orient yourself

步骤2：定位上下文

Which files are central? (entry points often show up as most-imported)

哪些是核心文件？（入口文件通常是被引用最多的）

Step 3: read, don't assume

步骤3：阅读代码，避免假设

Step 4: structure the explanation

步骤4：组织解释结构

行/函数级：

<function-name> in <file>:<line>

<function-name> in <file>:<line>

<path/to/module>

模块级：

How <concept> works

<path/to/module>

Step 5: link and stop

子系统/概念级：

Verify

<concept>的工作机制

Common Mistakes

步骤5：给出指引并结束

验证

常见错误

`<function-name>`
in
`<file>:<line>`

`<function-name>`
in
`<file>:<line>`

`<path/to/module>`

How
`<concept>`
works

`<path/to/module>`

`<concept>`
的工作机制