第36章：学习和理解新项目 —— 用 teach 把陌生代码库读成一门课
"I poured my 10 years of teaching experience into a skill. It's called /teach, and it can teach you anything."
我把十年教学经验灌进了一个 skill。它叫 /teach，能教你任何东西。
—— Matt Pocock（@mattpocockuk），2026 年 6 月 9 日
我一直思考一个问题：AI 已经又快又好地帮我们写好代码了，反而程序员成了瓶颈。程序员需要耗费很长的时间去理解这些代码，以至于经常我们也不 review、不理解这些代码，无脑地接收了。
现阶段，我们还缺少一个让人类能够快速理解 AI 生成代码的方法，所以我也在思考这个问题，尝试使用各种架构图、流程图、UML 图去梳理代码的框架。最近我也看到 Matt 在介绍他的 teach skill。这一章先把研究的成果做一个粗浅的总结，未来几年有更成熟的途径后我再来回顾和更新。
第 2 章认识过 Matt Pocock——TypeScript 教学名家，Skills 系统「真正的工程，不是氛围编程」那套主张的提出者。这次他把自己十年教人写代码的经验，压进了一个叫 /teach 的 skill。本章就从这个 skill 讲起。
一个真实的场景：你接手一个陌生项目。github.com/Gitlawb/zero，一个现代终端 coding agent，68 个 internal 包，2700 行的主循环文件。这是一个新的开源项目，你要在这上面加功能、修 bug，甚至照着它复刻一个自己的 agent。
传统办法你我都熟：clone 下来，从 main 函数一路点进去，开十几个标签页，画一张越来越乱的手绘图，两周后勉强摸清一半，再过两周忘了前一半。这套流程在 AI 时代显得格外浪费。理解一个代码库恰恰是大模型最擅长的事之一：它读得比你快，记得比你全，还能随时回答追问。
问题在于，光让 agent「给我讲讲这个项目」得到的是一坨即用即弃的概述。听的时候懂了，关掉窗口就忘。这不叫学会，这叫 agent 学会了、你没有。
本章讲怎么把「让 agent 讲」变成「让 agent 教」——用三个 skill：/teach 把陌生代码库变成一门为你量身定制、能长期回看的课；/insight-diagram 把代码结构画成图；/architecture-diagram 负责把图渲染得专业好看。全程以一个真实的学习工作区 zero-learn 为例——它就是用这三个 skill 搭出来的。
36.1 读代码不等于学会
第 21 章的 Understand-Anything 把代码库变成知识图谱，第 22 章的 UML 新用途让 AI 反向生成图来帮它自己理解代码。这两章解决的是「让机器理解代码」。本章解决的是另一头——让人理解代码，而且是长期理解、能带走的理解。
这两件事不一样。机器理解代码是为了在这个 context window 里把活干对；人理解代码是为了在下个月、下个项目里还记得。前者要的是覆盖率和精确度，后者要的是留存率。
留存率是认知科学里一个被反复验证的现象。你读一遍讲解，当场能复述，这叫流畅度（fluency），一种「我懂了」的错觉。但一周后再问，全忘了，因为流畅度不等于存储强度（storage strength）。让知识留下来的是费劲地回忆：合上书自己推一遍、隔几天再考一次、把相关的几个概念混在一起练。听得顺没用。这套「合意困难（desirable difficulty）」正是 /teach 这个 skill 的设计地基。
换句话说：一个只会「讲」的 agent 在优化流畅度，一个会「教」的 agent 在优化存储强度。差别就在这里。
36.2 /teach：把代码库变成一门课
/teach 出自 Matt Pocock 的公开 skills 合集（github.com/mattpocock/skills，在 productivity/teach/ 目录下）。它的 SKILL.md 开头第一句就点明了它和普通问答的区别：
This is a stateful request - they intend to learn the topic over multiple sessions.
有状态、跨会话。这是整个 skill 的立身之本。普通对话是一次性的，关掉就没了；/teach 把当前目录当成一个教学工作区（teaching workspace），把你的学习状态沉淀成磁盘上的一组文件。下次再进来，agent 读这些文件就知道你学到哪了、偏好什么、下一步该教什么。
它还特意关掉了模型自动调用（disable-model-invocation: true）。只有你亲手敲 /teach 才进得去教学模式。学习是个需要主动发起的严肃动作，不该被 agent 顺手触发。
36.2.1 工作区的六种文件
一个 /teach 工作区由六类文件构成，各管一件事：
| 文件 | 作用 | 类比 |
|---|---|---|
MISSION.md | 你为什么学、学成什么样、边界在哪 | 项目的北极星 |
RESOURCES.md | 可信资源清单，教学的知识来源 | 参考书目 |
NOTES.md | 教学偏好、学习者画像 | 老师的备课笔记 |
learning-records/ | 已被验证的关键理解，驱动下一课 | 架构决策记录（ADR） |
lessons/ | 一课一个 HTML，教学的主产物 | 讲义 |
reference/ | 跨课复用的速查文档 | 速查表 / 术语表 |
这套结构不是随便定的。它对应 skill 的教学哲学——深度学习需要三样东西：知识（Knowledge）从高可信资源里来，进 RESOURCES.md；技能（Skills）通过高相关的互动课练出来，进 lessons/；智慧（Wisdom）只能靠真实世界的实践和社区交流获得，这也是为什么 skill 会在合适的时候建议你去某个论坛或社区验证。
其中 MISSION.md 是重中之重。skill 反复强调：每一课都要挂到 mission 上。如果不理解你为什么学，教学就会飘：课程太抽象，agent 也没法判断下一步该教什么。所以第一次 /teach 时，如果 mission 不清楚，agent 不会开讲，第一件事是反问你为什么要学。
36.2.2 最近发展区与合意困难
/teach 决定「下一课教什么」靠的是最近发展区（Zone of Proximal Development）：每一课都要让你觉得「有点难，但够得着」。太简单浪费时间，太难吃光工作记忆。agent 怎么算这个区？读你的 learning-records，看你已经验证掌握了什么，再结合 mission，挑一个正好在边界上的东西教。
课程本身的设计处处是「合意困难」的落地：
- 每课短小、单一主题：工作记忆容量极小，一次塞一个架构决定就够。
- 每课配回忆测验（retrieval practice），逼你合上讲义从记忆里捞答案。skill 甚至规定：每个选项的字数（乃至字符数）要尽量一致，不给你任何靠格式猜答案的线索。
- 课程之间交错、回指（interleaving + spacing），后面的课常引用前面的，把相关概念混着练。
还有个反直觉的分工：课程（lessons）几乎不会被回看，参考文档（reference）才会。所以课程负责「第一次学会」，可以长、可以有互动；参考文档是课程的压缩精华，为「日后速查」而生，要短、要能打印。术语表尤其重要：一旦建立，之后每一课都要遵守同一套术语。
36.3 zero-learn 实录：一门 20 课的 Zero 架构课
抽象讲完了，看真东西。zero-learn 就是一个跑了多轮 /teach 攒出来的工作区，学习对象是 Zero 这个 coding agent。
36.3.1 先立 mission，再开课
工作区根目录的 MISSION.md 定义得极其克制。它说清了三件事——为什么学、学成什么样、边界在哪：
## Why
深入理解一个现代终端 coding agent 是怎么设计的——turn loop、
工具分发、权限/沙箱模型、上下文管理、TUI——通过读 Zero 的真实源码。
目标是从内部建立「一个 coding agent 到底怎么工作」的心智模型，
不是浮光掠影的走马观花。
## Success looks like
- 能把一个 prompt 端到端追踪:prompt → provider 流 → 工具调用 →
工具结果 → 下一轮 → 最终答案,每一步都叫得出具体的 Zero 函数名。
- 能解释 Zero 怎么判断一个回合「结束了」还是「还要再来一轮」。
- 能解释一次危险工具调用的权限/沙箱判定路径。
- 我自己能画出一个可比的 agent 的最小架构。
## Out of scope (for now)
- 贡献 PR / 修 bug(这是学习,不是贡献)。
- provider 特定的 API wire 格式。
- 构建/发布工具链。注意「Success looks like」里的每一条都是可验证的能力，不是「大致了解」。这直接决定了后面每一课的深度：既然目标是「叫得出每一步的函数名」，那课程就必须精确到 file:line，而不能停在「大概有个循环」。
配套的 NOTES.md 记的是学习者画像和教学偏好。它让这门课不像一份通用教程，而像为这一个人定制的私教：
## Learner profile
- 资深 Go 开发。不要解释 Go 语法、goroutine、channel、interface、
module。要解释*架构决策*和*代码为什么长这样*。
## Preferences observed
- 课程必须用中文写。代码、标识符、file:line 引用保持原样,
正文/测验/批注用中文。(第一课初稿用英文写完后,学习者要求改的。)这两条偏好都是在教学过程中逐步观察到并记下来的：学习者纠正过一次，agent 就记进 NOTES.md，之后每一课都遵守。这正是 NOTES.md 的用途：把一次性的纠正沉淀成长期的教学契约。
36.3.2 一课一个零件
跑了多轮之后，zero-learn/lessons/ 里攒了 20 课，从 0001 编号递增，分成六组，覆盖一个 coding agent 的全部要害：
- 核心循环与上下文（01–05）：主循环、工具执行闸门、上下文压缩、护栏、系统提示拼装
- 交互与持久化（06–08）：TUI 桥接、会话落盘与时间旅行、会话回放
- Provider 与流（09–12）：适配层、共享地基、流的抽干、重试路径
- 沙箱安全（13–14）：判定链引擎、命令进笼子
- 会话拓扑（15–16）：分叉 vs 子会话、专家子会话进度回流
- 工具系统与扩展（17–20）：注册分发、MCP 接入、Skill 系统、Skill vs 用户命令
每一课只讲一个架构决定。拿第一课「Agent 主循环」举例，它的解剖结构完全踩在 skill 的设计原则上：
- 一句话模型开场，先给心智锚点：「问模型 → 要调工具就执行、把结果喂回去 → 重复；不调工具，那段文本就是答案。」
- 紧贴源码：贴出
Run函数骨架，每一行后面挂loop.go:130、:149、:178这样的精确引用。SKILL.md 要求「每个架构论断都引用 file:line」，因为这位学习者「看重源码级的准确，胜过含糊其辞」，这条又是从NOTES.md来的。 - 对齐 mission：课程里专门有一段 blockquote 写「这一课交付你目标的前半部分」，把这一课挂回
MISSION.md的成功标准。 - 配套架构图：课程顶部一个 callout 直接链到
diagrams/里的流程图和时序图，这就是/insight-diagram的产物，下一节讲。 - 回忆测验 + 下一步清单：结尾三道测验逼你回忆，再给一份「接下来该读的源码」。
- 老师随叫随到：每课都提醒你，不懂就在
/teach里追问，agent 就是你的老师。
36.3.3 课程的样子：一个能开 GitHub Pages 的站点
所有课程都是自包含的 HTML，共享 assets/course.css（统一排版）和 assets/quiz.js（测验控件）。这是 skill 的「组件复用」原则：第一课就该挣到一张共享样式表，之后每课都链它，于是 20 课看起来像一门课，而不是一堆各写各的一次性文件。
网站：https://colobu.com/zero-learn/
根目录的 index.html 是课程目录首页，按六组列出全部 20 课，每课配一句「钩子」概括。它刻意放在根目录，是为了能直接开 GitHub Pages 当站点首页。整个工作区还刻意放在 Zero 仓库之外（相邻的 zero-learn/ 目录），课程用相对路径 ../zero/... 引用源码，学习笔记不污染那份干净的 checkout。
这就是 /teach 的产出形态：一门可回看、可分享、可继续的课，关掉窗口也还在，不像普通对话那样即用即弃。想学下一块，回到 Zero 仓库敲 /teach <主题> 即可；不指定主题，agent 会读 learning-records 和 MISSION.md，自己挑下一课。
36.4 /insight-diagram：把代码结构画出来
课程讲清了「一个回合怎么跑」，但纯文字讲控制流是费劲的。第 22 章说过，图是压缩过的理解。zero-learn/diagrams/ 里那些流程图和时序图，就是用 /insight-diagram 生成的。（/insight-diagram 出自 github.com/smallnest/goal-workflow，基于 /architecture-diagram 做渲染。）
/insight-diagram 干的事，一句话：分析任意代码库，自动生成 UML/架构图/流程图，再交给 /architecture-diagram 渲染成 HTML+SVG。它认识 17 种图，分结构性（静态）和行为性（动态）两大类：
| 类别 | 图表 |
|---|---|
| 结构性（静态） | 系统架构图、类图、对象图、组件图、部署图、包图、复合结构图、剖面图 |
| 行为性（动态） | 流程图、用例图、活动图、状态机图、序列图、通信图、定时图、交互概览图、泳道图 |
其中系统架构图和流程图不算严格 UML，但最常用；默认推荐组合是 architecture + sequence + flowchart，三张图就能覆盖一个项目「长什么样、怎么调、怎么流」的骨架。
36.4.1 四步执行流程
/insight-diagram 的工作流很规整：
- 分析代码库：读
CLAUDE.md（如有）、扫源码结构、读入口文件、grep 接口定义和依赖注入，提炼出组件清单、调用关系、核心类型、主流程、部署拓扑。 - 选图：用
AskUserQuestion分四组让你多选要生成哪些图。理解一个项目，你不需要 17 张图全画，挑要害的三五张。 - 逐个生成：对每张图，先读对应的示例文件（
examples/architecture.html等），提取布局、节点样式、标注风格，再调/architecture-diagram渲染，存到docs/<标识>.html。 - 报告：列出生成的文件和每张图的简述。
36.4.2 「先读示例」这条铁律
第 3 步里「先读示例」是这个 skill 最关键的一条纪律，也是它对抗 AI slop 的核心手段。skill 的 examples/ 里放了 13 张已完成的图作为模板，SKILL.md 用加粗强调：「生成任何图表前，必须先阅读对应的示例文件」。
为什么？因为如果不给参照，模型画图会往它的统计均值收敛：节点乱摆、箭头打架、信息密度失控，画出来一眼假。给它一张高质量示例，让它照着提取「布局策略、节点样式层级、标注风格、信息密度」，输出质量立刻稳定。这和第 40 章讲前端设计 skill 的发现是同一个道理：约束比自由更能提升 AI 的审美下限。
但示例只借样式，不借内容。SKILL.md 特意提醒：示例里的业务数据（一个虚构的风控系统）只是参照，生成时必须换成目标项目的真实架构信息：参考布局，不复制业务。
skill 里还有一整段「防遮盖」规则：算每个元素的边界框确保不重叠、箭头画在节点下方、节点间留足间距、超长文字截断换行、图太挤就拆子图。这些都是从无数张画烂了的图里总结出来的经验，写进 skill 后就成了每次生成的默认纪律。
36.5 /architecture-diagram：图的渲染引擎
/insight-diagram 决定画什么，/architecture-diagram 决定长什么样。它是最底层的渲染引擎，一个专门产出专业技术架构图的 skill（Cocoon AI 的开源项目 architecture-diagram-generator，github.com/Cocoon-AI/architecture-diagram-generator，MIT 许可），输出永远是单个自包含的 HTML 文件：内嵌 CSS、内联 SVG、除了 Google Fonts 不依赖任何外部资源、不需要 JavaScript，直接双击就能在浏览器里正确渲染。
它带一整套设计系统，而不是随手配色：
- 背景：
#020617（slate-950）深色底，叠一层细网格。 - 字体：JetBrains Mono，等宽，技术味。组件名 12px、子标签 9px、标注 8px，字号分层严格。
- 语义配色：按组件类型分色，前端青、后端翠、数据库紫、云/AWS 琥珀、安全玫红、消息总线橙、外部灰。看一眼颜色就知道这个节点是干什么的。
- 布局结构：标题（带脉冲圆点）→ 圆角边框卡片里的主 SVG → 底部三张摘要卡 → 页脚元信息。
它还把画图的坑写成了硬规则：箭头 z 序（先画箭头后画节点，让线走到节点背后）、遮罩（半透明节点下先垫一层不透明底矩形，别让箭头透出来）、间距（垂直至少 40px，消息总线放在间隙里别压节点）、图例位置（必须放在所有边界框外，不够就撑高 viewBox）。
回头看 zero-learn/diagrams/ 里那九张图，用的正是这套深色设计系统：slate-950 底、JetBrains Mono、脉冲绿点、青翠紫琥珀的语义配色、底部三张摘要卡。agent.Run 循环流程图、单轮时序图、TUI 处理序列图……每一张都是一个自包含 HTML，配合对应课程一起看。第一课顶部那个「配套架构图」callout，链的就是它们。
有意思的是 /insight-diagram 和 /architecture-diagram 在配色上的一个张力：/architecture-diagram 原生是深色主题，而 /insight-diagram 在调用它时会强制切成 light Claude 风格（暖白底、terracotta/sage 配色、Inter 字体）。同一个渲染引擎，套不同的皮。zero-learn 的图走的是深色原生风，说明这里更贴近 /architecture-diagram 的默认审美。两条路都通，看你要哪种视觉。
36.6 三个 skill 的分层
把三个 skill 摆到一起，大致是三层，各有各的活：
| Skill | 管什么 | 一句话 |
|---|---|---|
/teach | 教学法 | 学什么、按什么顺序学、怎么让它留下来 |
/insight-diagram | 画什么 | 分析代码库，决定该出哪几张图 |
/architecture-diagram | 怎么画 | 把一张图渲染成专业的 HTML+SVG |
这是典型的关注点分离。/teach 站在最上层，它知道你的 mission、你的进度、你的最近发展区，于是它决定「这一课需要一张主循环的时序图」；它把「画什么」的活派给 /insight-diagram；/insight-diagram 分析完代码、定下图的内容和类型，再把「怎么渲染」的活派给 /architecture-diagram。
不过下面两层的边界没那么干净，/insight-diagram 和 /architecture-diagram 是既重叠又分工的关系，值得说清楚。分工那半边好理解：前者是分析器加编排器，读代码、让你选画哪几张、覆盖 17 种 UML 和流程图，自己不动手渲染；后者是纯渲染引擎，给它图的内容就吐一个自包含 HTML，自带那套深色设计系统，不分析代码也不问你画什么。重叠那半边容易被忽略：两者都产出 HTML+SVG，画图的底层纪律（防遮盖、箭头 z 序、半透明节点垫底、间距、图例位置）几乎是重复的，/insight-diagram 把这几条又抄了一遍。更明显的重叠点是「系统架构图」这一种图两边都能出，你直接调 /architecture-diagram 就得到一张架构图，走 /insight-diagram 时 architecture 也只是它 17 种图里的一种，最后照样甩给 /architecture-diagram 渲染。
所以准确的说法是：/architecture-diagram 是被 /insight-diagram 内含的那一层，两者在「渲染架构图」这件事上重叠，区别在一个管选题加分析、一个管渲染。上一节那个配色张力正是这层重叠的副产品：同样是架构图，/architecture-diagram 原生深色，/insight-diagram 调它时却强制切成 light 风，同一个引擎、同一种图，两个入口给你两种皮。
好处是每一层都能单独用。你不学习、只想给现有项目补几张架构图，直接 /insight-diagram 就行（第 8 章的 goal-workflow 里它就是这么当 bonus skill 用的）。你手头已经有图的内容、只想要漂亮渲染，直接 /architecture-diagram。三者组合起来，才是「把一个陌生项目学透并留档」的完整链路。
这也呼应了本书反复出现的一条主线：好的 AI 能力是一组各司其职、可组合的 skill，拼起来用。一个大而全的 prompt 想一口气全包，反而做不到。第 2 章 Mattpocock 讲 skill 是真正的工程、第 16 章 agent-skills 把工程纪律结构化、第 25 章 autoreview 把审查做成绕不过的关口——都是同一个思路。/teach + /insight-diagram + /architecture-diagram 是这个思路在「学习理解」这件事上的落地。
36.7 什么时候用，用哪个
「理解一个项目」在本书里出现过好几次，工具也不止一个。别用混了：
- 第 21 章 Understand-Anything：把代码库变成知识图谱，供 agent 查询和导航。面向机器，重覆盖。
- 第 22 章 UML 新用途：让 AI 反向生成 UML 来帮它自己理解你的代码。面向 agent 的当次任务。
/code-to-spec（第 8 章）：从现有代码逆向出一份 SPEC 文档。面向交付物、面向规格。/teach（本章）：把代码库变成一门给人上的课，追求长期留存。面向人，重存储强度。
判据很简单：产物是给谁看的、要不要留得住。要 agent 干活用前三个；要你自己在下个月还记得，用 /teach。而 /insight-diagram + /architecture-diagram 是横切的可视化底座，谁都能调。
一个实用组合：接手陌生项目时，先 /insight-diagram 出三张骨架图（architecture + sequence + flowchart）建立全局观，再 /teach 立 mission、逐课深入要害模块。图给你广度，课给你深度。
36.8 本章小结
- 读代码不等于学会。光让 agent「讲一遍」优化的是流畅度：听着懂、关窗就忘。
/teach优化的是存储强度，用回忆测验、间隔、交错这些「合意困难」，让理解真的留得住。 /teach把目录当有状态的教学工作区。MISSION 定为什么学、NOTES 记学习者画像、learning-records 当 ADR、lessons 是主产物、reference 供速查。每一课挂回 mission，精确到file:line，落在你的最近发展区里。zero-learn是活样本：一门 20 课的 Zero 架构课，自包含 HTML、共享样式、能开 GitHub Pages，学习笔记还刻意放在被学仓库之外。/insight-diagram决定画什么（17 种图，默认 architecture+sequence+flowchart），铁律是「先读示例再画」：用高质量模板对抗 AI slop，借样式不借内容。/architecture-diagram决定怎么画：一套深色语义化设计系统，输出自包含、无 JS 的 HTML+SVG，把箭头 z 序、遮罩、间距、图例都写成了硬规则。- 三层分工、可单独用、可组合。教学法 → 画什么 → 怎么画，各司其职。这正是本书的主线：好的 AI 能力是一组可组合的 skill，不是一个大 prompt。
留言板
欢迎在此分享你的想法！评论通过 GitHub Issues 存储，需要 GitHub 账号登录。