eli12

eli12

用通俗易懂的方式解释代码，让好奇的新手能够建立正确的心智模型，而不被术语淹没。

灵感来自 poteto/how，但更注重易懂性：语言更简单，结构更紧凑，并使用贴近实际代码的真实类比。

决策树

1. 如果用户想了解某个子系统、功能流程、运行时路径或一组文件的工作方式，请使用此技能。
2. 根据对话和仓库上下文推断一个范围明确且有用的主题。只有在尚未解决的歧义会实质性改变解释时，才提出一个简短问题。
3. 如果问题范围较窄，仅涉及一个函数、类、钩子或文件，就直接依据相关代码解释；如果不清楚代码位置或相关联系，则进行有针对性的搜索。
4. 对于跨模块或端到端的问题，如果委托独立的只读探索能带来有用的信息，且运行环境支持，就进行委托。否则直接追踪流程；仅仅因为范围广，并不意味着必须分头探索。
5. 如果用户主要关注 Bug、风险或架构评析，只解释足以说明问题的内容，然后切换到常规评审模式，不要继续采用教学框架。
6. 如果现实类比会让解释变得更模糊，就少用类比，多贴近代码本身。

快速参考

情况	打开 / 执行	原因
用户提出“解释这个仓库”之类的宽泛问题，但没有指定目标	根据上下文提供范围明确的概览；仅在有实质性歧义时澄清	避免无关的架构漫游，同时不妨碍给出有用的回答
需要帮助调整语气或解释结构	查阅 references/explainer-prompt.md	让回答直截了当、易于理解
需要帮助追踪宽泛的子系统或运行时流程	查阅 references/explorer-prompt.md	支持收集证据，但不强制要求单独进行一轮探索
需要更好的类比，又不想失之粗略	查阅 references/analogy-patterns.md	将抽象的代码概念对应到有依据的日常系统
不确定简化解释时容易出什么问题	查阅 references/gotchas.md	避免居高临下的语气和误导性的简化
需要现成的输出结构	复制 templates/explanation-outline.md	为最终解释提供稳定的结构
需要在本地检查提示词路由	运行 python3 scripts/probe_eli12.py --prompt "How does auth work?"	测试建议性启发规则，不会测试必答问题、委托或参考资料查阅

此技能的优化目标

• 首先建立最精简且正确的心智模型
• 不进行耗时的仓库漫游，也能选出有用的范围
• 在术语出现时立即定义
• 使用简短具体的段落，而不是长篇大论
• 当流程或边界用图比文字更容易理解时，使用友好的 ASCII 示意图
• 将每个类比与真实文件、函数和数据流联系起来
• 帮助读者知道接下来该去代码库的哪里查看

默认工作模式

1. 利用现有上下文选择范围明确的解释主题；只有在仍存在会造成实质差异的多种理解时才提问。
2. 目标明确后，说明你对问题的理解。
3. 搜索入口点、关键类型，以及实际传递数据或作出决策的文件。
4. 追踪从触发到结果的真实路径。不要只根据文件名进行解释。
5. 将发现整理成通俗易懂的语言。
6. 如果有帮助，就使用有依据的类比，并将类比对应到具体的代码名称。直接解释可能更清楚。
7. 如果拓扑结构、控制流或数据流用图比文字更容易理解，就添加简短的 ASCII 示意图。
8. 如果有助于读者核实或继续探索，就提供简短的导航或后续阅读建议；行内文件锚点可能已经足够。

输出结构

使用有帮助的章节，跳过会徒增噪声的部分。

• 整体概览 - 说明这个东西的作用，以及它存在的原因。
• 主要组成 - 列出读者理解后续内容所需的少数概念或文件。
• 运作过程 - 逐步说明从输入到输出、从触发到效果，或从请求到响应的流程。
• ASCII 示意图 - 如果能比文字更快地讲清系统流程、边界或所有权，就用简洁的文本图示。
• 现实类比 - 给出一个贴合系统实际用途的具体类比，而非卡通式的说法。
• 从哪里着手 - 如果读者想验证或扩展说明，指出最重要的文件和目录。
• 需要注意之处 - 说明不明显的行为、隐藏状态、历史遗留问题或容易产生的误解。

风格约定

1. 像对聪明的新同事讲解，而非对孩子讲解

语言要简单易懂，但不要卖萌、居高临下或假装热情。

2. 讲清系统，而非语法

不要逐行转述代码。应聚焦职责、边界、数据流动和决策点。

3. 把类比当作脚手架，而非替代品

类比应帮助读者建立初步认识。随后要立即联系实际代码，避免解释偏离实际。

4. 术语出现时就加以说明

如果必须使用“中间件”“幂等”或“水合”等术语，请在首次出现时用通俗语言解释。

5. 保留证据线索

指出相关的实际文件、符号或目录，让读者能轻松验证说明。

6. 区分推断与观察

如果部分说明是推断而非直接观察，请明确说明。

7. 谨慎使用 ASCII 示意图

只有在小图表比段落更能减少困惑时，才优先使用。图表要窄小、标明实际代码概念，并避免装饰性边框。

示例：

request
  -> auth middleware
  -> controller
  -> service
  -> database

8. 把篇幅用在合适的范围

对于“这个应用如何运作？”，请结合上下文选择有用的概览或代表性流程，并说明范围。只有在多个合理目标之间的选择会实质性影响答案时才提问；不要用全仓库巡览来替代聚焦的说明。

何时展开探索

只有在有助于提升覆盖面且支持委派时，才展开探索。以下是可能的契机，并非自动触发条件：

• 广泛的架构概览
• 跨越多个层的运行时流程
• 涉及多个包或服务的问题
• 数据、编排和 UI 各自分离的系统

范围较窄的问题应一次完成。额外委派只会拖慢简单说明。

指引不再适用时

仓库的实际行为优先于打包附带的类比或工作流。框架行为不明确时，请查阅已安装的版本及相关官方文档或可信的一手资料；如果无法查阅，请说明不确定之处。如果示例已过时，或某条规则会降低说明的实用性，请结合代码或来源证据以及反例，建议对规范技能进行修正或删除。不要默默修改已安装的副本。

阅读指南

以下是可选的定向参考资料。只有在能解决说明或探索需求时才打开；普通回答无需预先加载参考资料。

需求	阅读
核心探索工作流和证据收集	references/explorer-prompt.md
面向读者的说明语气和章节结构	references/explainer-prompt.md
贴合技术实际的日常系统类比	references/analogy-patterns.md
失败模式、过度简化的陷阱和补救方法	references/gotchas.md
参考资料集的高层概览	references/README.md

注意事项

1. 使用更简单的语言，不代表可以含糊带过重要行为。如果重试、缓存或后台任务很重要，就用浅显的语言解释清楚，不要省略。
2. 如果可爱的类比与实际控制流对不上，那还不如不用类比。
3. 介绍子系统时，只列出文件还不够。要梳理实际发生的过程。
4. 如果用户只问了一个范围很窄的问题，就不要把回答扩展成整个架构的介绍。
5. 如果代码很混乱，就直说。提升可访问性不该掩盖真实的复杂性。