演讲复盘 · AI Engineer 2026 · Geoffrey Litt(Notion)

agent 写的代码,
人还要不要看懂

Notion 的设计工程师 Geoffrey Litt 认为还是要看懂,但理由不是为了检查它对不对。他把这场演讲的三套做法都摊开讲了,包括自己每天在用的一个 skill。

他的答案
为了参与
understand to participate · 一个项目从来不只有一个 loop,想出下一个演进方向的能力,一部分就来自人对系统的理解
常见答案
为了验证
understand to verify · 但他指出 agent 自我验证的能力在持续变强,只把理解的价值押在验证上,人的位置会随之缩小
01 · 起点

跟不上的,是代码量

2026 年 7 月,Notion 设计工程师 Geoffrey Litt 在 AI Engineer 大会上分享了自己每天与 coding agent 协作的做法。他给自己的开场立场贴了一个 hot take 标签,表示他知道这句话会有争议:人依然需要看懂 agent 写的代码。

这个主张听起来接近常识,却需要专门辩护,因为当下流行的设想正相反:把人从循环里拿出来,让 agent 自己循环下去。

这里的 agent,是能连续执行多步任务的 AI 程序,具体指替人写代码的 coding agent。

代码量的变化也在推动这个方向。他展示过一次真实改动:372 个文件、+55,219 行、−3,027 行。面对这种规模,人已经很难逐行跟上。但「看懂」不等于逐行读 diff。diff 是一次代码改动的前后对照,也是 code review 时直接面对的内容。仅靠逐行阅读已经很难跟上,但这不代表人只能彻底放弃理解。

这场演讲提出了三样工具:讲解文档、测验、微世界。讲解文档帮助人建立代码全貌,测验检查理解到了什么程度,微世界则把系统缩小成一个可以动手改变、观察结果的环境。

GitHub 改动统计条:Files changed 372,新增 55,219 行,删除 3,027 行
演讲幻灯片「跟不上」是什么量级:演讲用一次真实改动的体量说明问题,372 个文件、新增 55,219 行、删除 3,027 行。来源 Understanding is the new bottleneck(作者本人博客,2026-07-02)
起点

在他的框定里,代码量涨上来之后,问题不是「还读不读」,而是除了逐行读 diff,还有没有别的读法

02 · 为什么

从验证到参与

一个可能的答案是,看懂是为了验证(understand to verify)。人需要判断 agent 是否完成了任务,结果是否符合规格,架构是否合理。无论中间检查多少细节,最后都要落到一个通过或不通过的判断上。

但 agent 的自我验证能力也在持续变强。Litt 对这种进步乐见其成,但他的推论很直接:如果理解的价值只剩下验证,那么验证工作越多地交给 agent,人必须理解代码的空间就越小。

验证越归 agent,人的位置越缩小。

① 验证在人这边 agent 对不对? 人负责判断通过还是不通过 ② 验证归了 agent agent 对不对? 它越来越会检查自己,人这边淡下去 ③ 人拿回的是参与 agent 新想法 理解撑起的是下一轮该往哪走
按演讲中同一张插画的三帧推进重画。第①帧「对不对」挂在人这边;第②帧同样的问题移到 agent 头上、人这侧淡出;第③帧人这边亮起来的不再是判断,而是下一个想法。

Litt 因此把目标重构为,看懂是为了参与(understand to participate)。一个项目从来不只有一个 loop。loop 是 agent 干活的一个来回:人给出指令,agent 执行,人检查结果,再决定下一步。真实项目由一长串这样的 loop 组成。当前结果即使正确,也只是演进过程中的一个节点。人还要判断系统接下来该往哪里走,哪些能力值得加入,哪些结构需要调整。

“It's never just one loop!”

这种判断依赖人对系统的理解。脑中没有足够丰富的概念,就很难持续、流畅而有创造性地推动下一步。agent 完成了眼前的指令,并不等于人已经形成对这个项目的认识。只盯着每次任务是否通过,会漏掉长期参与所需的那张内部地图。

这正是 cognitive debt,也就是认知债所描述的问题。这个概念由两个人带火:维多利亚大学计算机系教授 Margaret-Anne Storey(Litt 的幻灯片把她署名为 Margaret Storey),以及 Django 框架的共同作者、长期写 LLM 工程实践的开发者 Simon Willison。代码交付时,人可能并未真正跟上。即使 agent 生成的代码本身清晰易读,参与者仍可能不知道程序应该做什么,设计意图如何落进代码,以后需要修改时又该从哪里开始。

Even if AI agents produce code that could be easy to understand, the humans involved may have simply lost the plot and may not understand what the program is supposed to do, how their intentions were implemented, or how to possibly change it.
—— Margaret-Anne Storey,Cognitive debt(加粗为 Litt 幻灯片上的加粗)

认知债与技术债相似。技术债是为赶进度留下的代码层面欠账,日后需要付出更多成本才能修改或扩展。认知债欠在人脑中。短期内,不理解并不妨碍代码运行;项目继续演进时,这笔债就会限制人的参与能力。

建立理解并不是一个全新的问题。怎么把理解传给别人,教育领域早就积累了大量方法。接下来要做的,是把那里最好的点子借过来,用在人与 AI 的协作中。

03 · 技术一

讲解,和一道他自己设的测验

agent 每完成一段工作,摆在面前的原材料通常是一份 diff。Litt 换了个问法:假设有一个团队,不论成员是人还是 AI,真的下功夫把这次改动讲明白,他们会交出怎样一份讲解?他每天使用的 Claude Code skill /explain-diff,就是照着这个问题设计的。

skill 是给 coding agent 预置的一套可复用指令,可以用斜杠命令调起,让 agent 按固定方式生成内容。/explain-diff 做的事,是把一次代码改动讲成一份文档,让他先读讲解,再读 diff。

这是他个人编写并以 gist 公开的 skill,不是 Notion 或 Anthropic 的官方产品。不少同事也觉得它有用。文档可以输出三种形态:HTML、markdown、Notion 文档。Notion 文档适合团队围绕讲解协作讨论。利益关系也很直接,他就在 Notion 工作,「所以我有偏向」。

一份讲解包含四个做法:先补背景、先建直觉、交互式图示、literate diff。

skill 文件里写死了四个段落,顺序也是固定的,两个变体一致。以下取自公开的 skill 原文,不是演讲讲稿:

Background
先补背景
讲清与本次改动相关的现有系统,并为此广泛查看周边代码。同时给一份面向新手的完整背景(注明熟悉者可跳过)和一份只讲直接相关部分的背景
Intuition
先建直觉
讲清核心直觉,重点是讲清本质而不是罗列全部细节。要用带简化数据的具体例子,大量使用图示
Code
再走代码
对代码改动做一遍高层走查,并把改动按可理解的方式分组和排序
Quiz
最后做测验
出五道题考察读者是否掌握这个 PR。难度中等,必须真正理解实质才能答对,但不出偏题怪题

以一次游戏视角改动为例,文档不会立刻列出修改了哪些文件。它先介绍原来的游戏引擎如何工作,让读者知道改动发生在什么环境中。没有这层背景,后面的代码即使逐行读懂,也很难判断它为什么要这样改。

接下来,文档在任何代码出现之前先说明目标。文档原话大意是:「用二维绘图技巧让这个花园显得有立体感」。目标清楚之后,才轮到 isometric projection,也就是等轴测投影。文档会解释这个概念,还配了一个可以操作的小图:读者拖动花园中的石头,看它在二维画面中的位置和坐标如何变化,观察平面上的移动怎样呈现出三维空间感。拖动几次,等轴测视角带来的感觉就具体了。

讲解文档的 Background 段截图:讲解游戏引擎 Phaser 3 与平面画布,含坐标系说明框
演讲幻灯片Background 段:先讲清原有的引擎与坐标系,含一处概念说明框。来源 同上
讲解文档的 Intuition 段截图:先说明改动目标,再解释什么是等轴测投影
演讲幻灯片Intuition 段:先说目标,再解释等轴测投影是怎么回事,之后才进代码。来源 同上

交互式图示在这里不是装饰。代码要实现的视觉结果,先被变成一个可以亲手试验的对象。读者不必只凭术语和公式想象,而是能直接改变输入,看到画面随之变化。Notion 刚上线页面内嵌可交互 HTML 的功能,这类小图也可以直接放进讲解文档。

这套安排的目的不是让文档替他做 review,而是先让他这个人跟上进度,使他能够在理解上成为平等的参与者。

到了代码部分,典型 diff 的问题开始显现。它通常按文件名排列,一个个文件依次展开,没有解释,也没有为理解设计阅读顺序。一个概念可能分散在几个文件里,读者只能沿着文件结构自行拼接前因后果。

Litt 把自己的组织方式称为 literate diff。这是他自创的说法,做法是把一次改动按讲解顺序重组成散文,而不是照着文件名复述原始 diff。代码片段嵌在讲解中,前后补上背景和作用,读者沿着一条说得通的路径看完整个改动。他的判断是,这样比阅读原始 diff 更快完成 review。

原始 diff · 按文件名排列 a/GardenScene.js b/border.js c/sand.js 没有解释,也没有为理解设计的阅读顺序 literate diff · 按讲解顺序重排 1 · 先定形状常量 const GARDEN_RY = … 2 · 再讲透视渐变 fillSand() { … } 走一条说得通的顺序,解释包着代码片段
同一次改动的两种读法示意。演讲里这两页给的是同一个 commit:左边是按文件名铺开的原始 diff,右边是重排成讲解顺序、代码片段嵌在解释里的 literate diff。
黑白照片:桌上一份长尾夹装订的代码讲解打印稿
演讲幻灯片他有时把讲解包打印出来带到咖啡馆读,因为干扰少。打印稿的正文部分由作者本人打码。来源 同上

最后得到的是一份完整的讲解包。他仍然会读 diff,只是总把讲解放在前面。有时,他还会把文档打印出来,带到咖啡馆阅读,减少干扰。这件事带着一种令他颇为得意的反讽:AI 把一项本来交互式的活动变成了静态纸质报告,反而让他能够沉下心仔细阅读。

“It's beautifully ironic: AI turns an interactive activity into a static paper report I can focus on deeply :)”

但讲解做得再好,阅读本身仍是费劲的工作,人也太容易骗自己说已经读懂了。

这种错觉有人专门研究过。Andy Matuschak 是一位独立研究者,做的正是「帮人思考的工具」这一类东西,早年在 Apple 参与 iOS、在 Khan Academy 领导研发。他用一句 books don’t work 概括这个问题。人以为读过就懂了,实际既没有记住,也没有形成清楚的理解。文字可以把解释摆在眼前,却不能保证理解已经发生。

Matuschak 和 Michael Nielsen 尝试把检查理解的动作直接放进阅读过程。Nielsen 是量子计算标准教材的合著者,后来把精力转向如何让人真正读懂并记住复杂内容。两人采用 spaced repetition,也就是按逐渐拉长的时间间隔反复考问自己,并把测验题嵌进在线文章。他们合作的 Quantum Country 就是这样的读物:内容是量子计算入门,读者一边阅读,一边被文章中的题目检验,不能只凭熟悉感判断自己是否掌握了内容。

Litt 把这个做法接进了自己的 agentic coding 流程。现在讲解文档底部有一个交互测验,五道题,全部围绕这次代码改动,他自己去答。

他给自己定的规矩是:过不了测验,代码不发给别人。

轮到他 review 别人的代码,执行的仍是同一条规矩。

“My rule: I won't send code to others until I can pass the quiz, and I do the same when reviewing others' code.”

agent 的循环速度 人的理解速度 测验 测验 测验 过不去就不放行,两条速度被重新对齐
按演讲里的速度阀示意重画:上面一条是 agent 的循环速度,下面一条是人的理解速度,测验在几个点上把两条线重新对齐。

“A quiz is a speed regulator.”

与 AI 一起工作时,生成、修改和提交代码的 loop 很容易跑得比人的理解更快。前一个改动还没有完全弄清,agent 已经可以继续处理下一个 prompt。速度本身不会提醒人停下来,顺畅的输出反而容易制造已经掌握的感觉。

测验提供了一股反向的力:在流程里机械地逼他检查一句,「我真的懂了吗?」

这套做法就是 /explain-diff。这个 skill 已经公开,Litt 在演讲现场用二维码提供了入口。它有两个变体,一个输出 HTML,一个输出 Notion 页面。两个变体在测验的实现上并不相同:HTML 变体要求做成可交互多选题,点击后告知对错并给出反馈;Notion 变体要求每题的选项都配一段解释为什么对或错,用 toggle block 承载,每段解释前用 ❌ 和 ✅ 标出对错。

两个变体共用

  • 文风被点名指定:以 Martin Kleppmann 的清晰度和行文节奏来写,行文好读,用平实直陈的经典文体,段落之间过渡平顺
  • 图示要成体系:先挑少数几类可以在全篇复用的图示,再用它们去解释各种情况
  • 关键概念、定义、重要边界情况用 callout 呈现

只写在 HTML 变体里

  • 单文件自包含:CSS 与 JavaScript 都在里面,整体一个长页面,配段落标题和目录;顶层结构不许用 tab 分页;最好有基础响应式样式
  • 产物刻意放在代码仓库之外:存到电脑上一个全局位置,文件名必须以 YYYY-MM-DD- 开头,理由是便于按时间排序、且不会进版本控制
  • 点名两类有用的图:一类是把界面极度简化的示意图;一类是展示组件间数据流或通信的系统图,并要求这类图必须带示例数据
  • 禁止 ASCII 图,图示一律用简单 HTML 实现,列表用 HTML 列表
  • 代码块一律用 <pre>;若改用自定义样式的 div,CSS 里必须有 white-space: pre-wrap,否则浏览器会把换行折成一行;存盘前逐个扫一遍确认

只写在 Notion 变体里

  • 用 Notion 的 MCP 工具新建页面,并把新页面的链接返回

Notion 变体也要求带示例数据,但写成了对所有图示的通则,而非只针对系统图。

相关

站内 《找出你的 Unknowns》 里也出现过一条「生成 HTML 报告 + 底部测验,全对才 merge」的 prompt。那篇讲的是动手前怎么把 unknowns 说清楚,测验只是收尾的一条 prompt;本篇给的是完整的 skill 原文,以及「为什么还要看懂」这一层的重构。

04 · 技术二

微世界:让 agent 写一个能玩的东西

第二套技术不从读代码入手:让 agent 另写一个可以上手操作的小程序,人靠使用它来理解原来的代码在做什么。这里有两个案例,都是 Litt 自己做过的项目。

幻灯片:左侧黑白照片是两个孩子和一台 Logo 海龟机器人,右侧是 Living in Mathland 标题与 Papert 在《Mindstorms》里的原话
演讲幻灯片Papert 的 living in Mathland:想学数学就住进数学国,跟想学法语去法国生活一个道理。幻灯片同时给出了他在《Mindstorms》里的原话。来源 同上

这个想法来自教育学者 Seymour Papert。他有一个设想叫 living in Mathland:想学数学,就住进「数学国」,如同想学法语便去法国生活。Papert 琢磨的是,能否造出一种环境,让孩子在好奇心的推动下自然学会数学。

放到代码上,这类环境就是 micro-worlds,一个人可以置身其中、亲手操作的「微世界」。人不必先读懂整个系统,而是在观察系统如何运行、如何变化的过程中逐渐形成理解。

去年,Litt 在写一个 Prolog 解释器。Prolog 程序由一组规则构成,运行时不断拿规则进行匹配,再一步步推导答案。只看代码,很难凭空想清楚这一连串推导究竟发生了什么。

<> Program father(orville, abe). father(abe, homer). parent(X, Y) :- father(X, Y). grandfather(X, Y) :- father(X, Z), parent(Z, Y). grandfather(X, Y)? Stack R0 Goals: grandfather(X, Y) θ: ø Timeline: Step 1 of 85 < Prev Next > Reset Add notes about this step…
案例一:他去年在写一个 Prolog 解释器,很难凭空想清楚里面在发生什么,于是和 agent 一起做了这个调试器。可以在时间轴上来回移动,看每一步的栈和正在求值的规则,还能给自己留注释。按演讲录屏的界面重画。

他和 agent 一起做了一个 debugger,也就是能逐步观察程序内部状态的调试器。界面上有一条可以来回拖动的时间轴。每走一步,都能看到当前正在求值的规则,以及此时的 stack。stack 记录程序正处于哪一层调用,沿着它往回看,就能知道程序如何走到眼前这一步。他还可以给某个节点留下自己的注释,比如「不错,这条规则应用对了」,把当时的判断直接留在推导过程旁边。

Litt 特别强调,做一个工具供自己调试,和让 agent 直接完成调试,是两件不同的事。亲手拖动时间轴,亲眼看着规则匹配、调用层级变化,理解才会在这个过程中长出来。

“There's a big difference between making a tool for me to debug and letting the agent debug”

第二个案例来自一次框架迁移,也就是把网站从一套开发框架换到另一套。Litt 要把个人网站从旧站 Middleman 迁到新站 Astro。Claude 写了一个脚本,把迁移做完了。结果已经摆在面前,他却无法判断做得是否正确,因为自己并不熟悉新框架。当时能给出的全部评价只有一句:「大概看着是对的。」

“I guess that looks about right.”

ASTRO PORT · INTERACTIVE LIVE EXEC STAGE 2 · PENDING ADD CORE STYLING EXECUTE TERM $ npm install packages installed ✅ Copying essential images… ✅ Creating basic homepage… ✅ Basic site initialized SRC · Middleman :4567 Geoffrey Litt Projects · Writing · Inspirations Files Path not found: /source · Retry DST · Astro :4321 Geoffrey Litt Projects Writing Inspirations Files · 9 items (5 changed) astro.config.mjs package.json public/ src/ README.md
案例二:他让 Claude 做了一个电子游戏式的指挥台,由他自己点按钮逐步执行迁移,旧站与新站并排跑着,每一步的可见效果和文件树变化都看得到。演讲录屏里旧站跑在 Middleman、新站跑在 Astro。按录屏界面重画。

这点窘迫成了重新设计过程的起点。他让 Claude 做了一个电子游戏式的迁移指挥台,由他自己逐步推进这次迁移。每按一次按钮,迁移就向前走一步,页面上的可见效果和文件树的变化也随之出现。

他不再只是接收一个已经完成的结果,而是看着新站一点点运行起来。哪一步移动了文件,哪一步改变了页面,哪一步让新框架接管原来的功能,都能在操作中看到。得到的理解接近亲手完成一次迁移,只是整个过程快得多,因为每一步都已经由 agent 提前铺排好。

这一节的结论

在他看来,这件事的分量很重:agent 可以写一些代码,帮助人类理解另一些代码

05 · 技术三

共享空间:从一个人懂到一起懂

前面的两个案例都在处理一个人如何理解代码。团队协作还需要进一步解决多个人如何共同理解。

当两个人脑中装着相近的模型,一套共享词汇就能唤起相近的画面。一个人提出的思路,另一个人才能接住,并继续往下推。缺少这些共享结构,双方即使使用同样的词,也可能在谈不同的东西。

Litt 关注的是如何造出让团队共同建立理解的环境。他说,这也差不多是 Notion 正在做的事。由于 Notion 是他的雇主,他此前已经声明自己的立场会有所偏向。

现在,Claude 和 AI 代码编辑器 Cursor 的 agent 都可以在 Notion 里运行,他自己的许多编码工作也通过这种方式完成。agent 生成的技术方案默认落在协作页面上,他可以立刻评论,并和团队继续讨论。理解不再只停留在一个人的头脑里,而是在共享空间中逐步形成。

Notion 页面截图:一份技术方案,右侧栏有两位同事关于实现取舍的评论往来
演讲幻灯片agent 在 Notion 里生成的技术方案默认落在协作页面上,右侧是就实现取舍展开的评论往来(一人问这个做法行不行,一人答不必存完整快照、记指针即可)。来源 同上

“Thinking together, not alone!”

06 · 收尾

本来就是为了增强,不只是自动化

三套技术都是理解代码的具体做法,但代码只是入口。Litt 的收尾把视野拉回一个更大的问题:人仍然需要理解事物怎样运转。理解不只是为了验证,而是为了参与。

这个问题也不新,计算机这门学科起步时,就有人思考过它。五十年前,计算机科学家 Alan Kay 已经提出,计算机可以成为一种比书更进一步的新媒介。作为个人电脑与图形界面的早期设计者之一,他长期主张,计算机不应只负责计算,还应帮助人思考,尤其是帮助孩子理解世界。

Litt 展示了 Kay 论文《A Personal Computer for Children of All Ages》中的一张图。那是手绘线条插画,不是照片。画面乍看很像今天的孩子拿着平板看视频,实际发生的事却不同:孩子们在玩一个可以交互的游戏,还会一边玩一边改代码,从而理解物理规律。程序把系统的运行规律跑起来,人可以观察、尝试和改变条件,这就是模拟。

Alan Kay 论文《A Personal Computer for Children of All Ages》中的线条插画:两个孩子各拿一块平板状设备坐在草地上
演讲幻灯片出自 Kay 的论文《A Personal Computer for Children of All Ages》。画面里的孩子看着像在拿平板看视频,其实是在玩一个可交互的游戏、并一边玩一边改代码来理解物理。这是手绘插画,不是照片。来源 同上
太空人梗图:一人问计算机的意义原来是造动态模拟帮人理解复杂概念吗,另一人持枪答一直都是
演讲幻灯片他用这张梗图收束整条谱系。持枪一侧配的是 Alan Kay 本人的照片。来源 同上

Litt 用一张太空人梗图收束这条线索。图上的人问:「等一下,计算机的意义原来是造出动态模拟,帮人理解复杂概念?」持枪一侧配着 Alan Kay 本人的照片,回答只有一句:「一直都是。」他的立场也落在这里:计算机本来的目的,一直是增强人的能力,不只是替人自动化。

“The point was always to augment, not just automate.”

Litt 说,AI 让做模拟这件事变得容易得多,这很美妙。让 AI 来教人,在他看来,是计算机这门技术出现以来最了不起的可能之一,也是他对未来乐观的原因。

工具搭对了,人可以比过去任何时候都更好地理解世界。

If we build the right tools, we can now understand the world better than we ever could before. We don't have to merely take ourselves out of the loop, we can get deeper in the loop too. It's up to us.
—— Geoffrey Litt,演讲收尾
来源说明

单一一手来源,忠实还原

一手Understanding is the new bottleneck

geoffreylitt.com · 2026-07-02 · Geoffrey Litt(Notion 设计工程师)。作者在 2026 年 7 月 AI Engineer 大会的演讲文字版,逐页幻灯片配讲稿共 35 页。本文只整理他的论点与做法,不附加评价、启示或建议;他本人的判断均已挂归因。

一手/explain-diff skill 两个变体

gist.github.com · 作者本人公开。第三节里「skill 规定了什么」一段取自这两个文件本身,不是演讲讲稿;四个段名与格式规则均按原文分组,共用规则与各变体专有规则已分开列出。这是他个人编写的 skill,不是 Notion 或 Anthropic 的官方产品。

引用源How Generative and Agentic AI Shift Concern from Technical Debt to Cognitive Debt

margaretstorey.com · 2026-02-09 · Margaret-Anne Storey(维多利亚大学计算机系教授)。演讲第 9 页引用了这篇,本文据原文核对引文并解释 cognitive debt 的含义。Litt 幻灯片上的署名为 Margaret Storey。

图片本页嵌入的原始幻灯片

本页 .source-figure 内的图片均为作者演讲幻灯片的引用,逐张注明出处并链回原文。站点内容安全策略不允许外站图片,故存为站内副本引用,未作任何裁剪或修改。概念图(三帧推进、diff 对照、速度阀、两个自制工具界面)为本站按原图重画,图注已标明。