explain-code

解释代码

在指定范围内，解释代码在实际运行中会做什么。范围可以是合并前的变更、函数、子系统、端到端流程、整个系统或其他切片。解释内容就是交付成果。可选后续包括：针对仍不清楚之处进行问答；通过小测验找出误解，而非认证掌握程度；以及构建微型世界——一种用于演示单靠文字和图表无法传达的逻辑的小型交互式模拟。

边界

• 只做解释。绝不评判代码质量，绝不修改项目代码或注释，绝不运行项目代码。微型世界（步骤 8）是单独的一次性模拟，不属于例外。
• 阅读时如果发现疑似错误或可疑之处，用一行说明观察结果并建议进行代码审查；不要将其扩展成审查结论。
• 如果困惑源于代码本身不清晰，而非目标内容，说清楚这一点，并建议进行文档完善或简化；不要在此处修复代码。
• 如果用户想要证明代码能够正常工作，建议进行运行时验证；本技能检查的是用户的理解，而非代码的正确性。

工作流

1. 明确请求的范围。在解释内容顶部用一行说明确定的范围，以便及时发现误读。

   • 变更：一个差异。默认使用当前分支和工作区，与默认分支的合并基点进行比较；也可以指定提交范围、PR、已暂存的变更或文件集。差异是事实依据。如果差异为空，说明没有内容需要解释，然后停止。
   • 部分：一个具名函数、类、模块、功能、子系统、目录或文件集。通过阅读而非猜测，确定哪些文件或代码区域实现了它；如果该名称可能对应多个单元，说明所选的对应项。
   • 系统：整个代码库或整个服务。
   • 其他：端到端流程、横切关注点（错误处理、身份验证）或场景（“登录时会发生什么”）。将其对应到实现代码，并参考最接近范围锚点的指南。
   • 如果请求含糊不清（“解释一下这个”），根据上下文推断：刚完成的变更意味着变更范围；当前打开或点名的文件意味着部分范围；并说明你的判断。

2. 收集补充信息，但绝不依赖这些信息。

   • 对于变更范围，使用实现会话的上下文，以及项目维护的任何实现说明文件作为设计理由的来源。对于部分和系统范围，查看 README、ADR 和设计文档。
   • 在代码库历史中查找记录的设计理由，包括提交消息、blame 和 PR 描述。
   • 会话上下文不可用时，仅依据代码库开展工作。如果未记录设计理由，根据代码推断并标明这是推断。如果代码无法提供依据，就说明设计理由未有记录。当前设计上的连贯性并不能证明原始意图，原始原因也可能已不再适用。

3. 在请求的范围内理解行为。阅读足够多的周边代码，包括调用方、测试、配置和错误处理路径，以描述输出、副作用、时机、失败模式和用户可见结果。当你能够解释从输入到输出，或从触发到效果的每一步时，就停止阅读。

   • 变更：说明差异改变了哪些可观察行为案例、系统之前和现在在每种情况下分别会做什么，以及哪些未改变的案例划定了变更边界。
   • 部分：说明该单元的职责、输入和输出、关键流程及失败模式，以及系统其余部分如何使用它。
   • 系统：说明系统为用户提供什么、主要组件及其职责、关键端到端流程，以及重要状态的存放位置。保持在架构层面；函数级细节属于部分范围。
   • 其他范围：调整到最接近范围的细节层级。例如，解释登录流程时，应跨多个组件追踪这一流程。

4. 在聊天中呈现解释。不要将其写入文件。按便于理解的顺序组织：

   • 根据对话推断用户的目的，不要通过提问来确认，并围绕用户的问题着重说明。编辑、审查、调试和学习陌生代码，需要不同的解释方式。如果看不出明确目的，就面向将维护这段代码的工程师来写。如果问题中包含对代码的某种判断，先确认或纠正该判断。
   • 先提供理解解释所需的周边系统背景，并根据用户已有的了解调整详略。刚提交新改动的作者可能只需要一句话；新人则需要更多背景。
   • 在介绍代码层面的细节之前，用几句话说明本质，并通过一个具体输入及其可观察结果来说明。如果真实系统太庞大，不适合用清晰的示例，就构造一个最小化的假想示例，例如两个节点或一个有三个槽位的队列。只保留能体现机制的内容。如果逻辑结构本身是重点，就用真实名称写几行伪代码，并用 ... 标记省略部分。这是文字层面的思维实验；交互式微型世界在第 8 步。
   • 只有当区分行为的边界是难点时，才补充对照示例，例如边缘情况或另一个分支。如果代码容易引发某种看似合理的误读，就指出并纠正。如果代码实现了某种已知模式，例如环形缓冲区、去抖动或两阶段提交，就自然地说出模式名称，并结合当前情况说明。
   • 然后说明细节：沿着行为流程展开，每一部分前用一句话引入，不要按文件逐一罗列。沿用直觉部分中的同一个输入，贯穿各个部分，并展示数据在每一步的形态，让读者跟踪同一条线索，而不是每一部分都切换到新的抽象。每一步都要点出真实的函数、表或标志，方便读者查找。
   • 改动范围的解释应先说明实际可观察到的变化及其重要性，且只在此之前补充理解改动所需的背景；之后再说明机制。应涵盖每种发生变化的情况在改动前后的表现、用来界定边界的不变情况、改动原因，以及合并后需要注意的事项。当改动涉及三种或更多不同情况，且每种情况的结果都能用简短表格单元格表达时，应使用表格，每种情况占一行，列出改动前后的表现；也要包括边界情况，并在表格上方用文字说明改动原因。如果情况存在嵌套关系或结果较长，则使用分组项目符号。说明后续编辑必须保持的不变量，并举例说明某种编辑会如何破坏它。有会话背景或备注时，应以其为依据说明理由；否则应明确标注为推断。
   • 部件范围的解释应涵盖该单元的职责、关键行为和流程、边缘情况和故障模式，以及它与系统其他部分的交互。还要说明该单元对系统的假设。
   • 系统范围的解释应涵盖：系统的用途、主要组件及其协作方式、关键端到端流程，以及新人必须了解的关键设计决策。
   • 其他范围：根据用户需要，调整最接近的范围所涵盖的内容。
   • 如果用户接下来要编辑、审查或调试源代码，只在结尾列出开始工作所需的文件，并说明打开每个文件的原因。例如，将处理器与消费其行数据的工作进程配对。对于其他目的，不要列出文件。
   • 直接陈述解释。省略诸如“关键见解”“本质上”或“简而言之”等引导标签，以及“下面来看看难点”“接下来就精彩了”等预告语。
   • 解释和问答答案应使用轻松易懂的 ASD-STE100 风格，同时保留真实代码名称和用户的用词。
   • 如果序列图、状态图、流程图或组件图比文字更清楚，例如用于说明跨组件控制流、状态转换、执行顺序或分支故障路径，就使用图示。用纯文本绘制，因为解释是在聊天中阅读的。对于包含三个或更多环节的内容，按顺序绘制一组简短图示，每张图在上一张的基础上增加一个环节。
   • 面向用户写作，并确保解释足够自足，可直接复用为改动范围说明中的 PR 描述，或其他情况下的入门说明或架构文档。
   • 将所有后续选项一并提供：第 5 步的问答、第 6 步的长期存放位置、第 7 步的测验，以及仅在第 8 步适用时提供的微型世界。用一个连续编号的列表列出选项。请用户只回复编号，例如“1”“2 3”或“all”。
   • 在呈现前，检查解释能否帮助读者预测一个未在讲解中使用的输入会产生什么结果，并说明某个具体部分发生变化时会破坏什么。补上检查发现的缺口。
   • 然后停下来，让用户阅读。只执行用户接受的内容；同时选择多项时，按步骤顺序执行。对话即将结束时，重新列出用户尚未回应的选项。

5. 如果用户选择参加，则开展问答环节：持续回答用户关于已讲解代码的后续问题，直到用户满意。用户接受后，阅读 references/qa.md 并遵循其中的说明。

6. 如果用户选择参加，则为讲解内容提供一个持久的存放位置：将其写入未来读者通常会查阅的地方。用户接受后，阅读 references/durable-home.md 并遵循其中的说明。

7. 如果用户选择参加，则对用户进行测验：围绕容易忽略的行为进行一轮选择题，然后评分并重新讲解。用户接受后，阅读 references/quiz.md 并遵循其中的说明。

8. 在适用且用户选择参加时，构建一个微型世界：创建一个小型交互式模拟，让用户亲身体验逻辑如何运作。用户接受后，阅读 references/micro-world.md 并遵循其中的说明。

   • 仅当逻辑难以通过阅读理解时才适用，例如状态机、坐标或几何运算、多步转换、调度或并发、算法边界情况。如果逻辑读起来很容易理解，就完全跳过，也不要提供此选项；应优先使用文字说明、示例和图表。