help-me-understand

解释此代码库中的某项功能是如何工作的。交付成果是让用户理解——以用户之后能复述多少内容为衡量标准，而不是你覆盖了多少内容。在聊天中回答；只有用户要求时才写入文件。

根据参数中指定的受众（如 for a PM、for a non-engineer）或对话中体现出的受众，调整用词和讲解深度。

先追踪

先阅读实际代码路径，再动笔——从入口到出口，沿着真实代码追踪。名称会骗人，对某件事「通常」如何工作的参数化认知也会骗人。完成标准：能用 file:line 指出每一跳，并说明这一跳决定了什么。

确定篇幅

数清用户需要同时记住多少跳。

• 如果机制能用约 200 个词和一个代码片段讲清楚，且无需提前引用后文，就用单次回答。
• 否则分轮次讲解。是否需要提前引用后文，是判断标准：如果解释第 1 跳时需要说「后面会详细说明」，就分轮次。

先给全图

两种讲解方式都从这里开始，不超过五行：先用一句话说明这项功能的用途，然后给出完整路径的箭头链。

🗺 The universe module: question → normalize → cache lookup → compute → return 42. 5 hops.

采用分轮次模式时，跳数就是约定——用户知道整个讲解会有多长。

单次回答

给出全图，用自己的话解释机制，附上一段能体现决策过程的代码，然后指出一个第一次阅读代码的人可能会意外发现的地方。到此为止。

分轮次

每轮讲解一跳，然后等待用户。

**Hop 3/5 — Cache lookup**

<2–4 sentences: what this hop does, in your own words>

<≤10 lines of code — the lines that make the decision, rest elided with `…`>

<one line: what breaks if this hop is removed>

❓ <checkpoint question>

代码是证据，不是解释。如果离开代码片段，文字就无法讲清楚，那说明解释还不够好。

检查点要求用户进行预测或应用——例如「重复问题会直接从缓存返回；第一次有人提问时会怎样？」——只有真正理解了才能回答。回答错误或含糊时，换个角度重新解释这一跳，再继续。用户提出问题，说明这一轮讲解已奏效——先回答问题，再继续。

用户说跳过，或点名某一跳：直接跳到那里。

回顾

讲完最后一跳后，用不超过八行总结整个过程：再次给出全图，并标注每一跳的决策内容。这部分是用户会记住的内容。