explaining-code

解释代码

向刚接触某段代码的读者解释某项具体改动或代码片段，可选择简要或完整深度。

如果问题涉及整个子系统的工作方式（其架构、数据流和文件结构），请改用 explaining-architecture 技能工具。如果未安装该技能，请按所选深度进行解释，并将范围限定在问题之内。如果没有技能工具，请遵循技能调用规则。

输入

请求中可以包含一个可选的深度标记，后面跟着主题：PR 编号或 URL、文件路径、函数或类名、分支名称，或一个概念。

如果请求没有指定主题，且对话中也没有明确主题，请停止。只询问一次要解释什么，在用户回答前不要开展任何工作。解释代码实际做了什么，而不是文档声称它做了什么；如有不一致，请按照文档与代码规则报告。

深度

• 简要（默认）：遵循下方的“简要”部分。
• 完整（ELIE）：如果开头带有 elie 或 eliet 标记，或用户要求 ELIE、要求“面向工程师”或“面向审查者”进行解释、要求“深入”解释或完整解释，则选择此模式。阅读完整解释，并遵循其中的要求，而不是下方的“简要”部分。

阅读主题前，先去掉深度标记。

简要

• 开头用一句话概述，让不了解该领域的开发者也能理解。
• 使用具体名词（如“订单历史页面”“登录界面”），避免使用抽象词语（如“组件”“模块”）。
• 只有在恰当自然时才使用日常类比。
• 接着用 3 至 6 句话回答隐含的后续问题：原先的情况如何、发生了什么变化，以及为什么。简要回复总共不超过七句话，包括开头的总结，写成一或两段，不加标题、粗体标签或项目符号。回复前请先统计句子数。
• 只有在用户要求时才写得更详细。
• 首次使用无法避免的术语或缩写时，在文中展开并解释，例如“服务等级协议（SLA）检查器”。
• 说明是什么以及为什么，不说明怎么做。
• 省略测试、审查者备注、风险、边缘情况，以及算法、比较逻辑、标头、状态码和函数名等实现细节；这些属于完整解释。
• 如果有帮助，可在结尾用一行提供完整解释。
• 总结整体效果，而不要逐一列出改动涉及的文件。
• 解释范围应与问题相符：如果问题询问一个函数，就解释该函数，而不是整个系统。
• 根据主题安排句子顺序。介绍 PR 时，先讲改动前，再讲改动后；介绍概念时可以写成一段；概述模块时，可以在正文中说明其职责。

PR 简要解释示例：

搜索页面现在会将最近的结果保存一分钟，因此重复搜索可以立即加载。以前，每次搜索都会查询数据库，即使相同的查询在几秒前刚运行过也是如此。现在会先检查结果缓存（近期答案的短期内存副本），只有缓存未命中时才查询数据库。结果可能会有最多一分钟的延迟；PR 接受这一点，因为列表很少变化。