Add dense teaching-style walkthrough comments above existing source code without changing runtime behavior. Use when Codex needs to annotate obscure modules for beginners, produce 教学式逐段讲解注释, explain a file section by section, or upgrade sparse comments to a self-contained canonical quality bar bundled inside this skill.
给现有源码补上“教学式逐段讲解注释”。目标读者是第一次接触该仓库的新手，所以注释必须解释“为什么这样设计、它和谁协作、隐藏约束在哪里、最容易误读什么”，而不只是把代码翻译成人话。
references/quality-bar.md 和 references/canonical-example.md 为最终验收标准。mcp__codebase_retrieval__codebase_retrieval）理解文件定位、上游调用者、下游消费者、关键依赖和跨模块数据流。rg/grep。references/quality-bar.md 和 references/canonical-example.md，统一注释密度、颗粒度和讲解方式。在写任何一段注释之前，先尽量回答这些问题：
如果这些问题回答不出来，就继续分析，不要急着写注释。
优先按下面这些边界切段：
不要为了“显得详细”而把每一行都拆成独立注释块；要让每个代码段都对应一个完整的小知识点。
每段注释优先覆盖下面这些维度里的 3 个以上；代码越难，覆盖维度越多：
优先写“解释性注释”，不要写“翻译性注释”。例如：
metadata 字段为什么故意保持宽松，以及下游谁会消费它。const x = foo() 改写成“定义一个变量 x 并赋值为 foo()”。交付前逐项确认：
references/quality-bar.md 的质量门槛？try/catch、提前返回、哨兵值、约定字段、魔法字符串、隐式默认值时，要解释这些设计如何影响控制流。references/quality-bar.md：skill 内置的质量标尺、分析清单和反例。references/canonical-example.md：skill 内置的 TypeScript canonical example，包含原始代码片段和教学式逐段注释版。