explain-codebase

解释代码库

根据用户所需的详细程度，解释当前行为。遵循系统的实际运作方式；不要用带注释的代码、设计批评或臆造的历史来替代解释。

范围

• 此技能为只读。不要修改代码或文档。
• 先解释观察到的行为，再做评判。如果请求还涉及问题或改进，先完成一份自成一体的解释，然后使用只读审计技能，例如 audit-code-complexity、blast-radius-audit 或 test-quality-audit，并将审计结果单独列出。
• 失败、错误或缓慢的路径仍可作为只读解释的主题。如果用户要求调查已报告问题的原因或修复问题，而不只是解释这条路径，请使用 diagnosing-bugs。遵守仅调查和不编辑的边界；要求查明原因并不意味着授权修复。
• 只有在 ADR、问题单、提交、文档或其他权威记录提供依据时，才说明历史动机。否则，应区分当前用途与推测的理由。
• 对轻微歧义，说明采用的解释并继续。只有当不同解释会导致实质上不同的说明时，才提出问题。

跟踪系统

1. 选择详细程度。 判断用户需要的是函数调用流程、功能流程还是子系统概述。项目中如有术语表和相关 ADR，无论文件名如何，都应阅读，但要根据当前代码核实其中的说法。
2. 找到真正的入口点。 从触发源开始：调用方、路由、事件、任务、命令、用户操作或公共函数。使用仓库搜索和运行时接线关系；不要根据文件名推断起点。
3. 跟踪执行过程。 阅读解释触发如何产生输出、状态变化、副作用或外部调用所需的调用和事件处理程序。每当路径跨越接口时，先确认运行中的路径实际选择了哪个适配器、实现、配置、标志或注册项，再继续跟踪；区分源码中可能存在的路径与所解释场景实际采用的路径。跟踪：
   • 每个步骤所负责的模块和函数
   • 每个步骤输入、输出和发生变化的数据
   • 重要分支、验证、错误、重试和异步交接
   • 状态的所有权、持久化、缓存、队列和外部依赖
   • 职责移交给其他模块或系统的衔接点
4. 弥补证据缺口。 使用调用方、实现、测试、配置和接线关系核实每个重要关联。如果无法确认某个交接点，指出缺口以及缺少的证据，不要猜测。

对于确实范围广泛的子系统，将探索拆分为相互独立的部分，例如入口与路由、数据与状态、外部影响。如果可以委派，就并行探索这些部分，然后根据代码核对重叠内容和矛盾之处。范围较窄的问题则一次完成。

当请求的路径已能从触发源解释到最终影响，重要的数据变化和衔接点均已交代清楚，剩余的不确定性也已明确说明时，就停止探索。不要盘点整个仓库。

解释结果

按照用户要求的详细程度，先给出答案。只使用有助于解释行为的章节：

• **概述：**代码路径或子系统的作用，以及它的起点和终点
• **流程：**按顺序说明运行时路径，包括重要的数据转换和决策
• **关键概念：**仅介绍理解流程所需的类型、模块或领域术语
• **代码位置：**入口点和实现文件的最简实用索引
• **注意事项和未知项：**意外行为、运行时选择、易出错之处和未解决的证据缺口

引用确切的文件和符号，方便读者检查依据。优先使用文字说明，避免大段粘贴代码。只有在多个模块之间的关系通过图示能明显更清晰地呈现时，才使用简洁的流程图、时序图或状态图。

明确区分观察到的事实、有依据的推理和推断。解释应让工程师能够预测代表性输入会产生什么结果，并知道从何处着手修改或调试，但不要直接提出修改方案或诊断结论。