explain-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explain Codebase

代码库解析

Explain current behavior at the level of detail the user needs. Follow what the system actually does; do not replace the explanation with annotated code, design criticism, or invented history.

按照用户需要的详细程度解释当前行为。遵循系统的实际运行逻辑；请勿用带注释的代码、设计批评或臆造的历史替代解释。

Boundaries

适用边界

This skill is read-only. Do not edit code or documentation.
Explain observed behavior before judging it. If the request also asks for problems or improvements, finish a self-contained explanation first, then use the relevant audit skill and keep its findings separate.
A failing, incorrect, or slow path can still be the subject of a read-only explanation. Use
```
diagnosing-bugs
```
when the user asks to investigate the cause of a reported problem or to fix it, rather than merely to explain the path. Preserve investigation-only and no-edit boundaries; a request to establish a cause does not authorize a fix.
State historical motivation only when an ADR, issue, commit, documentation, or another authoritative record supports it. Otherwise distinguish current purpose from inferred rationale.
Resolve minor ambiguity by stating the working interpretation and proceeding. Ask only when different interpretations would produce materially different explanations.

本技能为只读性质，不得编辑代码或文档。
先解释观察到的行为，再对其进行评判。如果请求同时要求指出问题或改进方案，请先完成完整的行为解释，再使用相关的审计技能，并将其结论分开呈现。
存在故障、错误或运行缓慢的路径同样可以作为只读解释的对象。当用户要求调查已报告问题的原因或修复问题时，请使用
```
diagnosing-bugs
```
技能，而非仅解释路径。严格遵守「仅调查」和「不编辑」的边界；要求查明原因并不等同于授权修复。
仅当有ADR、issue、commit、文档或其他权威记录支持时，才可说明历史动机。否则需将当前用途与推断的理论依据区分开。
对于轻微歧义，可以先说明工作假设并继续推进。只有当不同的解释会导致实质性差异的结论时，才需要向用户询问。

Trace the System

系统追踪流程

Choose the level of detail. Identify whether the user needs a function walkthrough, a feature flow, or a subsystem overview. Read
```
CONTEXT.md
```
and relevant ADRs when they exist, but verify their claims against current code.
Find the real entry point. Start from the trigger: a caller, route, event, job, command, user action, or public function. Use repository search and runtime wiring; do not infer the starting point from filenames.
Follow the execution. Read the calls and event handlers needed to explain how the trigger produces an output, state change, side effect, or external call. Track:
- the module and function responsible for each step
- the data entering, leaving, and changing at that step
- important branches, validation, errors, retries, and asynchronous handoffs
- state ownership, persistence, caches, queues, and external dependencies
- seams where responsibility passes to another module or system
Check runtime selection. Confirm which adapter, implementation, configuration, flag, or registration the running path actually selects. Distinguish a possible path in source from the path used in the scenario being explained.
Close evidence gaps. Use callers, implementations, tests, configuration, and wiring to verify each material connection. If a handoff cannot be established, name the gap and what evidence is missing instead of guessing.

For a genuinely broad subsystem, divide exploration into independent slices such as entry and routing, data and state, and external effects. Explore those slices in parallel when delegation is available, then reconcile overlaps and contradictions against the code before writing the explanation. Keep narrow questions in one pass.

Stop exploring when the requested path can be explained from trigger to effect without hand-waving, the important data changes and seams are accounted for, and remaining uncertainty is explicit. Do not inventory the whole repository.

选择详细程度。确定用户需要的是函数级逐步讲解、功能流程说明还是子系统概览。如果存在
```
CONTEXT.md
```
和相关ADR，请阅读它们，但需对照当前代码验证其描述的准确性。
找到真实入口点。从触发源开始：调用方、路由、事件、任务、命令、用户操作或公共函数。使用代码仓库搜索和运行时装配信息；请勿根据文件名推断起始点。
跟踪执行流程。阅读所有必要的调用和事件处理器，以解释触发源如何产生输出、状态变更、副作用或外部调用。需跟踪以下内容：
- 每个步骤对应的模块和函数
- 该步骤中输入、输出和变更的数据
- 重要的分支、校验、错误处理、重试和异步交接
- 状态所有权、持久化、缓存、队列和外部依赖
- 责任转移到其他模块或系统的接缝
检查运行时选择。确认运行路径实际选用的适配器、实现、配置、flag或注册项。区分源码中可能存在的路径与当前解释场景下实际使用的路径。
填补证据缺口。利用调用方、实现、测试、配置和装配关系验证每个关键连接。如果无法确定某个交接关系，请明确指出缺口及缺失的证据，而非猜测。

对于范围确实较广的子系统，可将探索工作拆分为多个独立部分，例如入口与路由、数据与状态、外部效应等。如果支持任务委派，可并行探索这些部分，然后在编写解释前对照代码协调重叠和矛盾之处。对于范围较窄的问题，一次性完成探索即可。

当无需含糊其辞就能从触发源到效应完整解释目标路径、所有重要的数据变更和接缝都已涵盖、且剩余的不确定性都已明确说明时，即可停止探索。请勿盘点整个代码仓库。

Explain the Result

结果呈现

Lead with the answer at the requested level of detail. Use only the sections that help explain the behavior:

Overview: what the code path or subsystem does and where it begins and ends
Flow: the ordered runtime path, including material data transformations and decisions
Key concepts: only the types, modules, or domain terms needed to follow the flow
Where it lives: the smallest useful map of entry points and implementation files
Gotchas and unknowns: surprising behavior, runtime selection, sharp edges, and unresolved evidence gaps

Reference exact files and symbols so the reader can inspect the evidence. Prefer prose over code dumps. Use a small flow, sequence, or state diagram only when relationships across several modules are materially clearer visually.

Keep observed facts, supported rationale, and inference visibly distinct. The explanation should let an engineer predict what happens for a representative input and know where to begin changing or debugging it, without itself proposing the change or diagnosis.

以用户要求的详细程度直接给出核心答案，仅使用有助于解释行为的章节：

概览： 该代码路径或子系统的功能，以及其起止位置
流程： 按顺序排列的运行时路径，包括关键的数据转换和决策点
核心概念： 仅包含理解流程所需的类型、模块或领域术语
代码位置： 包含入口点和实现文件的最小化实用地图
坑点与未知项： 意外行为、运行时选择、风险点和未解决的证据缺口

引用确切的文件和符号，以便读者查证依据。优先使用文字描述，而非堆砌代码。只有当多个模块之间的关系用可视化方式呈现会清晰得多时，才使用小型流程图、时序图或状态图。

明确区分观察到的事实、有依据的推理和推断内容。解释应当能让工程师预测代表性输入会产生的结果，并知道从哪里开始修改或调试，但解释本身不提出修改或诊断方案。