它不是让AI一次就对，是让跑偏能被发现
微信读书《Agentic Coding：从 Vibe Coding 到可托付的工程系统》· 薛志荣
逐页翻阅 279 屏 · 5 章 · 读到 CodeNow 脚手架设计 · 2026-11-03
这本书回答一个问题：为什么你觉得 AI 写代码很猛，但真拿它做项目就一地鸡毛？
作者的答案不绕弯——不是你提示词写得不好，是你在用"一次性的工具"做"长期的事"。他把这个分界叫 Vibe Coding 和 Agentic Coding。
一、Prompt 的极限在哪
书里承认 Vibe Coding 有用："一个清楚的任务表达，列出目标是什么、上下文是什么、限制是什么、完成标准是什么"，这确实能让 AI 一次给出不错的产出。
但接着就点破了：
因为 Prompt 是一次性的。它只能在当前会话里生效。
然后是最扎心的一句：
真正项目里的很多要求不是一次性的。比如"手机号和邮箱不能进日志"、"销售数据不能靠人临时输入"，这类判断说一次就完，迟早会漏掉。
这个例子选得很准。它不是什么复杂的业务逻辑，就是一条安全边界——而安全边界恰恰是最不该依赖"人记得说"的东西。你这次记得提，下次呢？换个新人来提呢？AI 换个会话还记得吗？
所以作者给的分工很清楚：一次性的任务留在 Prompt 和 TODO.md 里；长期事实进 CONTEXT.md；产品目标、非目标、界面流程、状态和验收标准进 ACCEPTANCE.md。
一句话：让该一次性的东西一次性，该长期的东西写进文件。
二、六个文件，各管一段
这是全书最实用的部分，也是一套可以直接抄走的结构：
AGENTS.md —— 项目长期工作协议。每次开工先读，定的是"我们这边一直怎么干"。
CONTEXT.md —— 让 AI 拿到正确的世界。术语、背景、必要事实。
PRD.md —— 定义目标和边界。重点是"不做什么"。
DESIGN.md —— 让设计系统进入工程过程。界面状态、组件策略。
TODO.md —— 记录当前执行状态。
ACCEPTANCE.md —— 把"完成"变成可检查的场景。
书里特意强调了一个反直觉的点：ACCEPTANCE.md 不应该把其他文件的内容重抄一遍。
更好的关系是：PRD.md 给它产品边界，DESIGN.md 在 UI 任务里给它界面状态，CONTEXT.md 给它术语和必要事实，TODO.md 指向它作为当前任务的完成标准。也就是说，验收应该成为"完成标准"的事实源，而不是又一份混合文档。
关键不是文件名，而是验收标准只在一个地方定义。
这句"只在一个地方定义"值得画线。文档体系最容易烂的方式，就是同一个要求散落在四个文件里，改了一处忘了三处。好的结构不是文件多，是每个事实只有一个出处。
三、脚手架：别抄别人的
第三章讲怎么搭自己的脚手架，四件套：Skills、SubAgents、Rules、MCP/Hooks。
里面有两句提醒很清醒：
Skills 要从自己的角色出发。不是把别人的技能包全装上，而是想清楚"我这个角色反复在做哪几类活"，把那几类写成可复用指令。
SubAgents 按任务复杂度设计。简单的活别拆。拆太碎，交接成本比干活还高——这句话在到处鼓吹"多智能体协作"的当下，算是难得的克制。
Rules 管"什么不许做"，Hooks 在动作发生前拦截，MCP 负责接外部能力。四件套的分工不重叠：Skills 管怎么做，Rules 管不许做，Hooks 管做的瞬间能不能过，MCP 管能碰到什么。
四、全书最有价值的一段：三类信号
第四章是实战，用 LeadFlow 这个项目从 MVP 走到迭代。但真正的高光在第 4.3 节——怎么知道 AI 走在正确的路上。
作者说，和普通开发比，动作没变，变的是优先级：
普通开发里，你有 git，主要是任 review 自己或同事写的代码质量；Agentic Coding 里，你先看 diff，是为了确认委托边界有没有被遵守。普通开发里，你跑命令，是为了确认实现是否正确；Agentic Coding 里，你还要看 Codex 是否把一个命令通过误报成"验收完成"。普通开发里，页面看起来对了通常是好消息，Agentic Coding 里，页面看起来对了以后，还要确认它不是靠假数据、硬编码或者越界功能撑出来的。
最后那句"假绿"我读了两遍。这是 AI 编程最隐蔽的坑：界面渲染正确 ≠ 功能实现正确。AI 太擅长把界面做得像那么回事，而人看到界面对了就放松警惕。
接着是这段的落点——为什么文件系统才是关键：
没有 PRD.md、DESIGN.md、TODO.md 和 ACCEPTANCE.md，Codex 收到"完善 AI 建议卡片"时，可能会按常见 SaaS 直觉做一个漂亮的推荐卡片，顺手加发送按钮，甚至把真实 CRM 接入也当成"完善"。
然后是一张对照表，把这句话拆成了四条边界：
PRD.md → 不自动发送、不接真实 CRM、不处理真实客户数据
DESIGN.md → AI 建议是待确认草稿，来源入口靠近正文
TODO.md → 本轮只修可见边界、草稿、来源、无记录不建建议
ACCEPTANCE.md → 用具体场景证明来源、无记录、确认前状态和隐私目录
而全书最好的那一段，是紧接着的：
这不保证 Codex 永远不会跑偏。它改变的是可观察性：当 Codex 准备加发送按钮时，人可以指回 PRD；当它把无记录状态写成通用话术时，可以指回 ACCEPTANCE；当它想重做整张详情页时，可以指回 TODO。Agentic Coding 的价值，不是让 AI 第一次就全对，而是让"跑偏"能被早一点看见、说清楚、拉回来。
这段话把整个方法论的天平调正了。大多数人追求的是"一次就对"，作者追求的是"错了能发现"。前者是运气，后者是工程。
这也是为什么它强调"指得回去"——文档的真正作用不是给 AI 看，是给人一个可以指的地方。当评审变成"你违反了 PRD 第 3 条"，讨论就从"我觉得不好"变成了"这里有约定"。
五、它的短板
说几句实在的。
这套方法是"重型"的。六个文件加脚手架，适合有一定规模、要长期迭代的项目。如果你只是写个脚本或做个周末小工具，全套上马的成本远大于收益——书里其实也承认这一点，Vibe Coding 有它的位置。
它偏重流程，轻技术细节。怎么写出好的 Skills、Hooks 具体怎么写、SubAgent 之间怎么交接状态，这些给的是原则和思路，代码示例不多。想要"照着敲"的人会不够。
它假设你已经有工程判断力。"不自动发送、不接真实 CRM"这种边界，得是你自己先想到，才能写进 PRD。AI 不会替你想到你没想过的事。
但反过来看，这三点也正好划出了它的读者：已经在用 AI 写代码、并且真被坑过的人。没被坑过的人读它，会觉得这些文件是多余的行政负担；被坑过的人读它，会立刻明白那六个文件的价值——它们不是文档，是把口头约定变成可执行检查的装置。
最后一章的标题我很喜欢："如果你要设计自己的 Agentic Coding 脚手架，应该考虑什么"。它没有给标准答案，只给了提问的框架。这也和全书的气质一致——它不卖一套万能模板，它教你给自己造一副合手的工具。
阅读记录：微信读书《Agentic Coding：从 Vibe Coding 到可托付的工程系统》（薛志荣），逐页翻阅 279 屏，5 章 25 个目录节点，读至第 5 章脚手架设计。2026-11-03。
发表评论: