大部头书

问题从哪来

代码审查和 git diff 只会告诉你发生了什么，很少保留「为什么这样改」「当时考虑过什么、又为什么没选」以及新人读 diff 时缺的那层上下文。团队一换人，设计取舍就容易被当成理所当然；多个 PR 串起来时，也很难形成可独立阅读的学习材料。

Tome 在做什么

Tome 的定位是：在先读真实差异的前提下，把变更规格、Trail 的 git 调查、Harvest 的 PR 信息、Lens 的代码调查或 Scout 的 bug 调查，转成叙述型学习文档，而不是改代码或写内联 JSDoc（那是 Quill 的事）。

核心流程沿用 SCOPE → EXTRACT → ANALYZE → COMPOSE → REVIEW，写作上强调 5W1H + WhyNot：每个重要决策都要写理由和被拒绝的替代方案；首次出现的术语在本次变更语境里定义；推论必须用 [Inference: evidence] 标出，不能冒充事实。

常见交付形态包括：标准 learningdoc、面向新人的 onboard（beginner 深度）、decisionrecord（Y 语句 / Nygard / MADR，且一条记录一个决策）、worked 分步示例、quickstart、变更范围 词汇表，以及跨多个 PR 的 learning_series。文档末尾附带质量记分卡（事实/推论、术语覆盖、WhyNot 深度、前后代码对比、受众契合等轴）。

产出还可交接给兄弟技能：内嵌说明 → Quill，正式规格/ADR 升级 → Scribe，流程与知识图 → Canvas，模式入库 → Lore，演示旁白 → Director。

边界与注意

• 总是：生成前阅读实际 diff；至少一对前后代码对比；声明或自动检测受众级别（beginner / intermediate / advanced）并调节解释深度。
• 先问：变更范围不清、受众置信度低、内容可能含安全敏感细节、或批量跨越 10+ PR 时的分组策略。
• 从不：未读 diff 就写学习材料；把推论当既定事实；省略「为什么不」；编辑已接受的 ADR——需 supersede 并双向链接。
• 与 Scribe 的分工：Tome 做来自具体代码变更的教育材料；需要正式 PRD/SRS/HLD/ADR 流程时交给 Scribe。