第32章：PLAN、Task List 和 Walkthrough：执行阶段的三件套

上一章我们把 PRD、设计文档、SPEC 摆开讲了一遍。那三份文档管的是动手之前的事——要做什么、为什么选这条路、按什么契约建。可它们都停在"还没写代码"的那一刻。

真到 Agent 开始改文件，另一批问题冒出来了：动手之前，能不能先看一眼它打算怎么改，觉得不对还来得及拦？改的过程里，一个大目标被拆成了几步、做到哪一步了，我怎么盯？做完之后，它到底动了哪些地方、这些改动靠不靠谱，我怎么快速搞清楚，而不用一行行去读 diff？

这三个问题，对应执行阶段的三样：PLAN（动手前先把改法过一遍）、Task List（把大目标拆成能勾掉的小步）、Walkthrough（做完之后把改动讲清楚）。Claude Code、Codex、Google 的 Antigravity 三家工具各自都做了这三样，做法有出入，冲着的是同一个问题。这一章把它们拆开讲，最后再补一个 goal-workflow 的 /note-it——它接在三件套后头，记的是这三样都漏掉的那一半：为什么这么改。

一、PLAN：动手前先把改法过一遍

plan mode 现在是三家工具的标配，动作也差不多：你把任务丢进去，Agent 先只读不写——翻代码、搜文件、必要时反问你几句，然后给出一份"我打算这么改"的方案，等你点头才动手。

Claude Code 里按 Shift+Tab 切进 plan mode，Agent 进入只读状态，探完仓库给你一份计划，你批准了它才退出 plan mode 开始写。Codex 在 2026 年初的 v0.93 版本正式带上了 plan mode，和 Pair、Execute 并列成三种协作模式：Pair 是你说一步它做一步、每个动作都要你确认，Execute 是全自主放手跑，Plan 夹在中间——只读、探仓库、产出一份带步骤、涉及文件和验收标准的结构化计划，在一个专门的终端视图里流式画出来，你可以改、可以驳回，批了才进执行。有个坑值得记一句：Codex 的只读是靠 prompt 约束模型别写文件，不是硬沙箱；要真拦住写操作，得再叠一层只读权限。

Antigravity 把这份计划做成了一份能存下来的产物，叫 Implementation Plan artifact。它读起来就像一份 spec：要改哪些组件、加哪些 API 路由、打算怎么验证，一条条列清楚。最顺手的是它支持像批 Google Doc 那样直接在计划上划评论——"这里用 SQLite 存""这段复用逻辑放到那个文件里"——留完评论点 Proceed，Agent 拿着你的意见，要么改计划再找你看一遍，要么就照着开工。

三家做法不同，图的是同一个关口：在 Agent 碰你的代码之前，插一道你能拦下来的门。这道门在 Agent 时代比过去值钱。一个跑得快的 Agent，能在你反应过来之前写完两百行、顺手定了五个你没审过的架构决定；plan mode 把"想"和"做"分成两段，让你在便宜的阶段（几段文字）拦下方向错误，而不是等它写完两千行、你才发现从一开始就歪了。

二、Task List：把大目标拆成能勾掉的小步

计划批下来，Agent 开工，接着你要盯的是进度。三家工具都会把一个大目标摊成一张清单，一步一个勾选框，做完一步勾一个。

Claude Code 边做边维护一张 todo list，哪条在做、哪条做完，实时更新在你眼前。Codex 维护一张步骤清单，靠一个叫 update_plan 的工具随进展刷新状态。Antigravity 的 Task List 是个 artifact，点开能看到"建 requirements.txt、写 main.py、写 index.html、验证应用"这样一条条离散的步骤，Agent 边生成文件、装依赖、写代码，你边看着勾选框一个个被打上。

这张清单的用处，是把 Agent 的黑箱开一道缝。你不用盯着它每一次工具调用，扫一眼清单就知道它拆成了几步、走到哪儿、还剩什么。步骤要是拆得离谱，你当场就能看出来它理解偏了，赶在这份理解落进代码之前拦下来。

这类内建清单有个短板：它是会话级的，关掉窗口就没了，也带不到下一个会话、交不到别人手里。goal-workflow 的 /to-issues 补的正是这一段。它把 PRD 或 SPEC 拆成一张张 Issue 卡片——每张一个能独立实现的小任务，带验收标准、标好依赖（#2 依赖 #1）、分好类型和优先级，落到 GitHub、本地文件或者 iCafe 上存着。内建 todo list 是给"这一趟"用的草稿，Issue 卡片是给"这个项目"用的、能跨会话跨人流转的正式任务单。两者层次不同：一个记着 Agent 这半小时的思路，一个记着这个功能要干的全部活。

三、Walkthrough Document：做完之后，把改动讲清楚

代码写完，Agent 报一句"done"，你信不信？

Antigravity 的答案是给你一个 Walkthrough artifact。Agent 完成实现后自己生成一份，里头是这轮对话改了什么的一段扼要总结；碰上带界面的活，还会附上它在浏览器里的截图和录屏——它自己起本地服务、开一个带蓝色边框的受控浏览器，点按钮、填数据、把功能跑一遍，把这些过程录下来放进 walkthrough。官方文档给它的定位是：Agent 改完之后，你用它快速追上代码现在长什么样，尤其是你刚才没盯着每一步的时候。

Walkthrough 对付的是异步协作里的一个麻烦：Agent 越自主、跑得越久，你越不可能全程盯着；等你回来，面对的是一堆已经改完的文件。Walkthrough 让你不用从 diff 一行行倒推它干了啥，读一份带图带录屏的总结就能追上。它还把自己的验证过程摆出来：起服务、点按钮、看结果，都录在里头，你能亲眼核对，不用光凭一句 done 就当它做对了。

四、/note-it：Walkthrough 说做了什么，note-it 补上为什么

Walkthrough 和 diff 能告诉你改了哪些代码——这些 git 里都看得到。看不到的是另一半：spec 在某处没写清，Agent 自己拿了个主意；它有一处故意没照 spec 来，因为照着来会出问题；它在两三种做法里挑了一种，别的都试过又放掉了；还有几处它没底，想让你确认。这些判断全在 Agent 脑子里，代码本身讲不出来，不写下来，就随着这轮对话一起蒸发了。

goal-workflow 的 /note-it 专门捞这一半。它跑在 /goal 实现完、/review-it 审完之后、/ship-it 交付之前，对着 spec 复盘一遍实现，把四类判断记进一个 docs/issue#XXXX.html 文件：

• 设计决策：spec 含糊或没提的地方，做了什么选择，为什么。
• 偏离：哪里故意没按 spec 写，spec 说的是啥、实际做成了啥、为什么这么改更稳。
• 取舍：考虑过哪些别的方案，各自利弊，为什么选中的这个赢了。
• 待确认：哪条假设自己还没把握，你该验证什么，哪里可能要跟进。

哪一类没有，就写一句 None 并说明，比如"None，实现完全照 spec"。

note-it 和上一章设计文档里的 Rationale 是一个路子：把"为什么这么选、放弃过什么"主动写下来，省得几个月后有人（包括你自己）对着代码干猜。区别在时机——设计文档在动手前写，是计划；note-it 在做完后写，是实录。计划里想的和真做出来的，中间总有些没对上的地方，note-it 记的正是这些出入。

五、四样拼到一起看

把这四样按时间摆开：动手前用 PLAN 预演，动手中用 Task List 盯梢，做完后用 Walkthrough 交代改了什么、用 note-it 交代为什么这么改。

内建和 skill 之间还隔着一条线。工具内建的 plan mode、todo list、walkthrough 大多是会话级的，方便、即时，可一旦关掉窗口或者换个人接手，就没了。skill 这一层——/to-issues、/note-it，还有上一章的 /prd、/to-design——做的是把这些临时产物落成能提交、能复审、能被后人翻出来的文件。built-in 管"这一趟顺不顺"，skill 管"这个项目留不留得下账"。两层叠着用，才既跑得快、又不把账丢了。

这条执行三件套接在上一章那条规划流水线的后头。/prd → /to-design → /prd-to-spec 把"要什么"定下来；到了 /goal 这一步开始动手：先过一遍 PLAN，拆出 Task List，逐个 Issue 实现，/review-it 审完，/note-it 记下决策，/ship-it 交付。规划的三份文档管进场之前，执行的三件套管进场之后，中间的接缝就是动手写代码的那一下。

我的经验

这三件套我不是每次都齐用，看这趟活的分量。

• plan mode 我只在改动有分量、或者需求还含糊的时候开。 一个单文件的小修，进 plan mode 纯属浪费——它探半天仓库、给你一版计划、等你批，就为改三行。Codex 官方也是这么讲的：plan mode 是把精密的手术刀，问题真含糊时值回票价，改个单文件的小 bug 时反而碍事。反过来，凡是要动公共 API、要跨好几个文件、或者我自己都还没想清怎么改的活，我一定先 plan，把它的改法逼出来看一眼。
• Task List 我基本让工具自己维护，扫一眼确认它没拆歪就行。 只有当一个功能要跨好几天、或者要交给别人接着做，我才走 /to-issues 落成 Issue——会话级的 todo list 扛不住跨天跨人。
• note-it 是我一开始最想省、后来最舍不得省的一步。 做的时候，为什么绕开某个方案、为什么在这儿偏离 spec，心里门儿清，懒得记。等三个月后 bug 找上门，或者同事问"这儿当初为啥这么写"，那份 issue#XXXX.html 就是唯一还记得答案的地方。花五分钟记下来，换的是以后不用对着自己写的代码考古。

规划的文档让你想清楚要什么，执行的文档让你盯得住进度、也交代得清怎么把它做出来的。前者省的是返工，后者省的是过几个月连自己都看不懂的那笔账。

参考资料

• Introducing Google Antigravity —— Antigravity 的 Artifacts 理念与总览
• Antigravity Docs：Artifacts、Implementation Plan、Walkthrough —— 三类 artifact 的官方说明
• openai/codex —— Codex CLI 的 plan mode 与 Pair / Plan / Execute 三种协作模式
• Claude Code 文档 —— plan mode、skills、plugins
• goal-workflow —— /to-issues、/note-it 等 skill 的来源
• 本书第 8 章《Goal Workflow：目标驱动的研发闭环》、第 31 章《PRD、设计文档和 SPEC：一次功能规划里的三种文档》