阅读提示：点击任意配图可放大（Esc 关闭）；右上角可调字号、收起目录、加宽版心、切换夜读，或进入沉浸阅读（再按一次按钮或 Esc 退出）；目录中篇 / 章 / 节标题右侧的 ˅ 箭头可折叠下级内容，也可用筛选框下方的「全部展开 / 全部收起」一键操作；拖动目录与正文之间的细线可调宽度（双击恢复默认）；用 Ctrl/⌘ + P 可直接打印为 PDF（打印时自动隐藏侧栏、按章分页）。

修订状态：正文按技术审稿意见修订；配图仍为上一版，部分数字、措辞与坐标尚待更新，请以修订后的正文为准。本稿不是发布成品，配图回填并完成图文与排版复核后再定稿。

术语与约定：为什么有些词不翻译

判据只有一条：会不会让人误解

这本书要讲给很多人听，其中相当一部分不写代码。

所以术语的处理需要一条能公开检验的规则，而不是随手决定。这条规则是：

这个英文词，在中文技术语境里有没有一个稳定、无歧义的译法？
有——就用中文。没有，或者译了反而让人想到别的东西——就保留英文原词，并且在第一次出现时用一句白话解释清楚。

按这条规则，本书有三个词的处理需要单独说明。

同一条规则还带出两个派生词：agentic（形容词）与 agentic engineering（一种工作方式的名称），都保留英文。

保留英文但不单独说明的词

除了上面三个，还有若干词天然就是英文形态，不再逐条解释：

• 协议、组织与基准名：MCP、A2A、OWASP、SWE-bench
• 代码与配置里的实体：AGENTS.md、pyproject.toml、reasoning_effort
• 行业既有说法：vibe coding、context engineering

有稳定中文译法、就直接用中文的词

不是越英文越好。下面这些词的中文译法已经稳定，硬改成英文反而让人别扭：

sandbox→沙箱 · routing→路由 · benchmark→基准 · spec→规格 · diff→变更 · prompt→提示词 · context→上下文 · checkpoint→检查点 · trace→追踪 · guardrail→护栏

一个记号

正文里凡是出现 ⚠️ 的地方，提醒的都是同一类事：这一条与数据、口径或者引用方式有关，值得你自己核对一遍。

它标的是"这一条能不能被核实"，不是"这里危险"——所以它出现在数据与引用的旁边，不出现在操作步骤上。

一个提醒

术语策略是为读者服务的，不是为一致性服务的。

如果你读到某个词卡了一下——那一处就是该改的地方。欢迎标出来。

前言：155 天，一行代码没手写

0.1 先说一件我自己的事

2026 年 4 月 18 日早上 6 点 43 分，我开始想一个产品的样子。8 点 07 分，第一笔代码提交进了仓库。到 9 月 19 日，一共 155 天。

这 155 天里，我一行代码都没有自己敲。

我不是在说一件值得炫耀的事。我是做架构的，从 1999 年开始写代码，到今天也没离开过一线。手写代码对我来说不是负担——我在这 155 天里不写，是因为我想认真试一次：如果实现这件事完全交给模型，我会变成什么？我的工作还剩下什么？这件事到底能不能成？

我做了四个仓库：一个桌面智能体工作台、一个云端企业平台、一个官网，后来又加了一个简化版的桌面智能体。到 2026 年 9 月 19 日，四个仓库加起来的提交数超过四千次，业务代码三十多万行，测试代码十二万行，文档十三万行。

数据卡 · 前言

作者自测口径（核对路径与复核材料的缺口见附录 A）。
统计范围：ClawBible Desktop / ClawBible Cloud / ClawBible Website / BetterWork 四个仓库。
提交数 4,194 次；业务代码 338,280 行；测试代码 121,630 行；Markdown 131,607 行。
时间范围：2026-04-18 至 2026-09-19。
局限：行数为物理行（含空行与注释）；四个仓库的任务类型、语言与成熟度不同，行数不可直接相加比较。

到项目第 100 天（2026-07-26）冻结为止，我攒下了 100 篇按天写的开发日志（有一天同时在两个仓库各写了一篇，按天去重后是 100 篇）、七十多份架构决策记录、二十多份规则文件，以及一份正式的冻结案例研究。第 100 天之后我仍在写日志，但没有严格按天补齐——所以"100 篇"是前 100 天的口径，不是整个 155 天的口径；155 天全程的规模数字见上面的数据卡，两个节点的对照在第 6 章。这本书里凡是我说"我试过"，指的都是这些可以拿出来核对的东西。

0.2 这本书要解决一个很具体的困惑

我周围大概有两种人。

第一种，觉得 AI 写代码是万能的。 他们说："都什么年代了还自己写？把需求说清楚，剩下的交给它。"这话听完之后，最让人不安的不是它对不对，而是它听起来太顺了。

第二种，觉得 AI 写代码根本不行。 他们说："它写的东西你敢上线？迟早出事。"这话也有道理——但同样地，它只是把问题推走，没有回答任何东西。

这两种说法有一个共同的毛病：它们都试图用一个"行"或者"不行"来结束讨论。

而我在这 155 天里得到的最实在的一条体会是：

核心判断 0
AI 编码不是一个"能不能"的问题，是一个"怎么分工"的问题。它能不能用，不取决于模型有多强，取决于你有没有把活儿分开——哪些交给它、哪些必须自己来、哪些交给机器去拦。

这就是全书要展开的唯一一件事。

0.3 我为什么敢写这本书

不是因为我做得最好。是因为我的账记得比较全。

这本书使用三类材料。它们回答的问题不同，不按离作者远近排强弱：

亲历记录能把过程讲清楚，不等于它比随机试验更能证明普遍效果。 随机试验有自己的适用边界，大样本调查也不会因为人数多就自动变成因果证据。读一个结论，要同时问四件事：谁提供的材料、怎么得到的、核查到了哪一步、能够支持什么判断。附录 A 的 A / B / C 只标来源类别，不是质量或因果证据的统一排行榜。

0.4 这一层证据有多硬，我先把话说尽

我不想用"我的经验"这四个字来加冕任何结论。所以下面这些边界，我摆在最前面：

1. 我是一个有 27 年经验的架构师，这是全书最强的干扰变量。 同样一套协作方法，换到刚入行的人手里未必成立。我在这本书里报告的结果，不能被读成"AI 能自己把楼盖起来"。
2. "一行代码没手写"是我亲眼确认的事实，但它不是可被第三方鉴定的事实。 代码仓库只能记录"谁提交了"，不能记录"每个字符是谁敲的"。能被人独立复核的，是产出、提交、测试和规则结构，不是我的键盘。
3. "快了几倍"是一个有真实参照的判断，不是一个精确测量值。 我在同期带着团队做高度相似的项目，所以我有可比对象；但我们没有事先约定统一的计时口径。我报告方向与量级，不给小数点。
4. "155 天"是日历，不是工时——而且是全勤投入。 这 155 天里没有哪一天空过：每一天都写过代码、文档或书稿。工时按平均每天 4 小时上下估算（工作日晚上少，周末和假期多），全程约 620 小时，大约相当于 78 个八小时工作日。第 6 章账本用的是另一个更早的口径——第 100 天冻结的案例研究（2026-04-18 至 07-26 的 100 个日历日）：约 400 小时，约合 50 个八小时工作日。两个数同法估算、截止点不同，不可混用。

0.5 这本书怎么读

五篇，十五章。每一篇回答上一篇留下的那个问题。

• 第一篇 认清它（1–3 章）——这台机器到底学会了什么？ 从"vibe coding"这个词的三次变形讲起，然后从逐 token 生成讲起，区分生成机制、能力与可靠性，最后讲清楚它的边界在哪。
• 第二篇 算清账（4–6 章）——它到底让你更快了吗？ 两堆互相矛盾的证据都摆出来，然后讲成本结构搬到了哪里，最后把我自己这 155 天的账本摊开。
• 第三篇 用对它（7–10 章）——那我具体该怎么做？ 想清楚再动手、一个有终点的循环、让它自己发现错误、别让它把代码库越写越烂。
• 第四篇 建起来（11–13 章）——我照做了，为什么还是不如别人？ 因为决定成败的东西很大一部分在模型之外：运行时、安全、接口。
• 第五篇 看清楚（14–15 章）——那人和组织还剩什么？ 为什么个体提效传不到组织，以及最后一件谁也不能替你做掉的事。

如果你时间很少，只读三章：第 3 章（它能做什么不能做什么）、第 5 章（什么变贵了）、第 15 章（人还剩什么）。

每一章都有：本章承诺、读完后你能回答、本章小结、对不写代码的人意味着什么、行动清单、延伸阅读；定义框、核心判断、数据卡、"一句话讲明白"按内容需要出现——有话要说才写，硬凑一个出来只会多一处经不起追问的空话。延伸阅读里的多数条目给了网址，你可以自己点开去看我说的对不对；其余是经典论文与书内互指，只给了出处，需要你自己去找。

0.6 一句话的立场

写这本书的是两个人：一个做了二十七年软件的人，和一个每天都在被要求写几万字的模型。我们在这本书里的分工，恰好就是这本书要讲的那种分工——我决定什么值得说、什么经不起追问；它负责检索、组织、铺陈，出了错由我抓住：附录 A 里的撤回记录就是现场。

这个分工不是写在纸上的姿态。写这本书，用的就是书里讲的那个分工。

这本书想说的，不是"AI 能做什么"——那个问题从来不缺人回答；而是当"写"这件事变得便宜之后，你到底还剩下什么。

全书地图

一条完整的论证线：

前言 · 155 天，一行代码没手写
交代这本书的材料来源、不同研究设计能支持什么判断，以及作者案例的四条边界。

第一篇 · 认清它：这台机器到底学会了什么

• 第 1 章 一个词的三次变形——vibe coding 是怎么来的、怎么被用歪的；工具那条路的四步（补全 → 对话 → 智能体 → 集群）背后真正的变化是什么。
• 第 2 章 从猜下一个词说起——从逐 token 生成认识模型：为什么流畅不等于正确、同一个问题的答案为何不同，以及为什么上下文很长也不保证可靠使用全部信息。
• 第 3 章 能写代码，不等于能做软件——它的能力边界是锯齿状的；榜单第一为什么救不了你；做软件的五件事，不能用生成代码代替完整交付。

第二篇 · 算清账：它到底让你更快了吗

• 第 4 章 两堆互相矛盾的证据——说它快的、说它慢的，都是真的。中间那 36 个百分点的落差，是这个时代最贵的一堂度量课。
• 第 5 章 什么变便宜了，什么变贵了——成本结构被迫显形；0.99 的 500 次方；瓶颈搬到了"读代码"那一侧；三种税。
• 第 6 章 一笔真实的账——我自己这 155 天：四个仓库、一组注明口径与复核缺口的数字、三个层次的变革，以及这笔账不能推广到哪里。

第三篇 · 用对它：一个人的功夫

• 第 7 章 先想清楚，再动手——提示词和规格是两种东西；一页规格里的六件事；需求与实现的区分、可独立验证的粒度；以及什么时候不该写规格。
• 第 8 章 一个会停下来的循环——四拍：意图、生成、验证、判断；验证要分层，越便宜的越靠前；到底该修还是该重来。
• 第 9 章 让它自己发现错误——测试从"质量工序"升格为"生产设施"；版本控制不只是时光机；"完成"的新定义。
• 第 10 章 别让它把代码库越写越烂——AI 让复制比复用便宜，这不是小事；认知债；深模块；以及怎么把"人要遵守的规则"变成"机器拦得住的约束"。

第四篇 · 建起来：模型之外决定成败

• 第 11 章 模型只是发动机，不是整台车——同一个模型为什么在别人手里是生产力；运行时的受控实验与成本观察；上下文是一张工作台不是仓库；模型升级后重新评估组件。
• 第 12 章 当它开始动手——代码漏洞与权限、执行风险都要管；三件不能讲错的事；提示注入为什么不能只靠"叮嘱它一句"；红线清单。
• 第 13 章 让它接进真实世界——两个协议、两层分工；把工作方法变成资产；谁在管这些事；以及中国语境下的标准与政策。

第五篇 · 看清楚：人还剩什么

• 第 14 章 "人人都在用"不等于"组织提效"——个体提效为什么传不到组织；瓶颈搬到了评审；一条可以照着走的工艺；别拿生成量邀功。
• 第 15 章 签名的是人——入门任务变化后，判断力怎样积累；三种岗位值得重视的能力；专业、组织与法律责任的边界；这一章留给你的三件事。

尾声 · 三个问题

后记 · 这本书是怎么写出来的
兑现前言那句"写这本书，用的就是书里讲的那个分工"：哪些环节一点没快、AI 做了什么、我做了什么，以及你如果想自己写一本，可以照着走的六条。

附录 A 数据与来源清单（每条给：数值、口径、时点、局限、网址）
附录 B 可以直接拿去用的清单（规格模板、智能体协作说明骨架、门禁清单、安全配置、指标定义表）
附录 C 术语表

一条暗线贯穿全书：

凡是能被说清楚的，终将被自动化；剩下的人的价值，恰恰藏在那句话之上——判断什么该被说清楚、验证它有没有被做到、以及为那些后果没法事先说清楚的决定签字。

目录

• 术语与约定：为什么有些词不翻译
• 前言：155 天，一行代码没手写
• 第一篇 认清它：这台机器到底学会了什么
• 第 1 章 一个词的三次变形
• 第 2 章 从猜下一个词说起
• 第 3 章 能写代码，不等于能做软件
• 第二篇 算清账：它到底让你更快了吗
• 第 4 章 两堆互相矛盾的证据
• 第 5 章 什么变便宜了，什么变贵了
• 第 6 章 一笔真实的账：我自己这 155 天
• 第三篇 用对它：一个人的功夫
• 第 7 章 先想清楚，再动手
• 第 8 章 一个会停下来的循环
• 第 9 章 让它自己发现错误
• 第 10 章 别让它把代码库越写越烂
• 第四篇 建起来：模型之外决定成败
• 第 11 章 模型只是发动机，不是整台车
• 第 12 章 当它开始动手：安全到底怎么回事
• 第 13 章 让它接进真实世界
• 第五篇 看清楚：人还剩什么
• 第 14 章 "人人都在用"不等于"组织提效"
• 第 15 章 签名的是人
• 尾声：三个问题
• 后记：这本书是怎么写出来的
• 附录 A 数据与来源清单
• 附录 B 可以直接拿去用的清单
• 附录 C 术语表

第一篇　认清它：这台机器到底学会了什么

第 1 章　一个词的三次变形

"有一种新的编程方式，我称之为 vibe coding：你完全臣服于氛围，拥抱指数增长，甚至忘记代码的存在。"
—— Andrej Karpathy，2025 年 2 月 2 日

"如今（一年之后），通过 LLM 智能体编程，正日益成为专业人士的默认工作流——只不过带着更多的监督与审视。"
—— Andrej Karpathy，2026 年 2 月 4 日

本章承诺：读完这一章，你能说清楚"vibe coding"这个词最早指什么、被用歪到哪里去了，以及从它的兴衰里能看出的那件更重要的事——变的不是模型有多强，而是人站在哪个位置。

读完后你能回答

• "vibe coding"最早是什么意思？为什么提出这个词的人一年后自己不用了？
• 为什么"用 AI 写代码"和"vibe coding"不是一回事？
• 从 2021 年到现在，"AI 写代码"这条路到底变了哪几步？

1.1 一条推文

先从一个很日常的场景说起。

你在做一个周末的小网页。你不想查文档，也不想改样式表里那行 padding。你干脆对着编辑器说了一句"把侧边栏的内边距减一半"，它就改了。你没看它改了什么。跑起来报错了，你把报错原样贴回去，它又改了一次。再跑，好了。

整个过程里，你从来没有真正读过那些代码。你甚至不太确定它到底写了什么。它管用，就行了。

2025 年 2 月 2 日，Andrej Karpathy 把这件事写成了一条推文，并且给它起了个名字：

"有一种新的编程方式，我称之为 vibe coding：你完全臣服于氛围，拥抱指数增长，甚至忘记代码的存在。这是可能的，因为现在的 LLM（比如 Cursor Composer 加 Sonnet）已经太好了。我甚至用语音跟它说话，几乎不碰键盘。

我会提一些蠢到家的要求，比如'把侧边栏的内边距减一半'，因为我懒得去找那行代码。我永远点'全部接受'，我再也不读它给我的改动了。遇到报错我就原样贴回去，也不加注释，通常这样就修好了。代码长得超出了我的理解范围，我得认真读上一会儿才能跟上。有时候模型修不好一个 bug，我就绕过去，或者随便让它改点别的，直到那个问题自己消失。

拿来做用完就扔的周末项目还行，但还挺好笑的。我在做一个小项目或者网页应用，但这不太算编程——我只是看看、说说、跑跑、复制粘贴，然后它大体上能跑。"

这条推文后来被他自己称为"一条随手发出的、洗澡时想到的推文"。

但这个词活得比他想象的长。九个月后，2025 年 11 月 6 日，柯林斯词典把 vibe coding 选为 2025 年度词汇，给出的定义是："用自然语言提示人工智能来写计算机代码"。柯林斯在同一篇文章里写了一句很克制、也很到位的话——"技术专家们仍在争论它是革命性的还是鲁莽的"。

定义 · vibe coding
本书沿用它的原始含义：让 AI 写代码，而你不审查它写出来的东西。
注意这里的关键词是"不审查"，不是"用 AI"。这个区分是下一节的全部内容。

1.2 一个词被用歪了

推文发出几周后，麻烦来了。

人们开始把这个词用在所有"用 AI 写代码"的场合。你在编辑器里让 AI 补全一个函数——有人叫它 vibe coding；你让 AI 写单元测试、你自己逐行读了一遍——也有人叫它 vibe coding。

Django 的联合创始人 Simon Willison 在 2025 年 3 月 19 日写了一篇文章，标题就是他的态度：《不是所有 AI 辅助编程都是 vibe coding（但 vibe coding 很酷）》。他写：

"我担心这个词的定义已经偏离了它最初的意思。我看到人们把这个词用在所有借助 AI 写代码的形式上。我认为这既稀释了这个词，也给出了一个关于'负责任的 AI 辅助编程能做到什么'的错误印象。"

然后他给出了自己一直在用的判据，一句话：

"当我说 vibe coding，我指的是：用 LLM 构建软件，而不审查它写出来的代码。"

接着是这本书里我最想让你记住的一段话：

"如果代码是 LLM 给你写的，然后你审查了它、认真测试了它、并且确保你能向别人解释它是怎么工作的——那不是 vibe coding，那就是软件开发。在这个过程中用没用 LLM，无关紧要。"

他还给了自己的一条硬规矩：

"我不往仓库里提交任何我无法向别人解释清楚的代码。"

这条规矩值得抄下来贴在显示器上。它跟用不用 AI 完全无关——它是"我是个专业工程师"这件事的定义。

核心判断 1
"AI 写的代码"和"我负责的代码"是两件事。判断一个人是不是在 vibe coding，不看他用没用 AI，看他能不能解释自己提交的那一行。

1.3 三次变形

现在我们把这个词的一年捋一遍。它经历了三次变形：

第三次变形值得看原文。2026 年 2 月 4 日——正好是那条推文一周年——Karpathy 写道：

"如今（一年之后），通过 LLM 智能体编程，正日益成为专业人士的默认工作流——只不过带着更多的监督与审视。目标是通过使用智能体拿到杠杆效应，同时不在软件质量上做任何妥协。"

"我个人目前最喜欢的叫法是'agentic engineering'：用'agentic'，是因为新的默认状态是你 99% 的时间不直接写代码，而是在编排智能体去写，并扮演监督者；用'engineering'，是为了强调这里面有它的艺术、科学和专门技能。"

请注意这两个说法的差别，它精确地划出了这本书要讲的界线：

• vibe coding 降低的是门槛——它让从来没学过编程的人也能做出一个小工具。这是好事，Karpathy 自己说它"为所有人抬高了下限"。
• agentic engineering 守的是质量线——它要的是"不牺牲质量地拿到杠杆"。这是另一件事。

同一个人的同一个观察，一年之后长出了两个完全不同的用途。这就是为什么"AI 编码到底行不行"这个问题没有意义——你得先问：你说的是一件事，还是两件事？

工具那条路的四步

词在变形的同时，工具也在变。这一路走了四步：

第一步·自动补全（2021–2023）——GitHub Copilot 把模型塞进编辑器：你写注释，它续写函数。这个阶段 AI 干的是打字员的活。人写代码，AI 补行；你审的是每一行。

效率的提升有实验证据。GitHub 2022 年做过一次随机对照实验（95 名开发者、一个从零写的 HTTP 服务任务），在完成任务的参与者中，Copilot 组的平均完成时间比对照组缩短 55.8%（Peng et al., 2023, https://arxiv.org/abs/2302.06590 ）。但请记住这个实验的场景——从零开始、单一目标、技术栈极其常见。第 4 章会看到，另一项针对资深开发者和成熟仓库的实验测得"慢了 19%"。两项研究的人、任务和工具都不同，不能把反差只归因于换了场景。

第二步·对话生成（2023–2025）——你描述需求，AI 生成整段代码，你复制粘贴。产出单位从"行"变成"块"，你审的是每一段。

vibe coding 就诞生在这一步。它在一件事上确实快得惊人：一次性脚本、原型验证、技术探索。但同期专业开发者群体里出现了一个奇怪的组合：使用率一路上涨，而对 AI 输出准确性的信任度在下跌。据 Stack Overflow 2025 年的开发者调查，84% 的受访者已在使用或计划使用 AI 工具，而认为 AI 输出准确性可信的只有 33%、明确表示不信任的有 46%（见附录 A 第 12 条）。

第三步·智能体执行（2025–2026）——AI 从对话框里走出来：它能读你的整个仓库、拆开任务、跨文件修改、自己跑测试、根据报错自我修复。人不再"写每一行"，而是"委托任务、验收结果"。你审的是每个任务的产出。

第四步·智能体集群（2026–）——单个智能体有注意力上限，于是并行成为主流：多个智能体各占一个工作区，会话之间可以互相发现、同步变更。人开始定架构与规格，只审合并策略。

这条路上有一个极易被忽略的规律：

AI 承担的比重每上一个台阶，"人"的角色就从"生产者"向"验证者"与"编排者"移动一格。

补全时代你审每一行，对话时代你审每一段，智能体时代你审每个任务的产出，多智能体时代你审架构与合并策略。

审查的对象越来越抽象，审查的责任却越来越重。

数据卡 · 工具演进的四步

阶段	AI 承担的比例（示意）	人的审查单位
自动补全 2021–2023	约 25%	每一行
对话生成 2023–2025	约 45%	每一段
智能体执行 2025–2026	约 70%	每个任务的产出
智能体集群 2026–	约 90%	架构与合并策略

口径：比例为示意值，用于表达相对趋势，不是实测数据。本书全部四步的划分依据工具公开能力的时间线，不依据某一家的产品路线图。

核心判断 2
工具演进的实质，不是"AI 越来越会写代码"，而是人对代码的直接责任在系统性上移：从写作者，到审查者，再到编排者与验收者。
你的价值不取决于你能产出多少代码，而取决于你能对多少代码负责。

1.4 为什么"用什么词"很重要

你可能会想：这只是个叫法，值得花一整章吗？

值得。因为一个词会决定你检查什么。

如果你把"用 AI 写代码"统称为 vibe coding，那么当你听到别人说"我用 vibe coding 做了个系统"时，你无法判断：他到底读了那些代码没有？测试写了没有？出了问题他能不能解释？

反过来，如果你按 Willison 的判据把两件事分开，你会立刻知道该问什么：

这两种情况的风险等级、适用场景、验收标准完全不同。用一个词盖住两件事，就等于放弃了所有判断。

顺便说一个真实的教训。2026 年，Karpathy 自己讲过他项目里的一件事：他让智能体给他的菜单生成应用做支付集成，代码跑通了，看起来没问题。但里面藏着一个 bug——Stripe 和 Google 登录之间的邮箱字段不匹配。它不一定涉及编造内容，而是一个隐蔽的集成语义错误，在开发过程中没有被发现（来源：Sequoia Ascent 2026 对谈，2026-04-30；转引自 The Agent Times, https://theagenttimes.com/agents/article/karpathy-declares-agentic-engineering-the-successor-to-vibe--4d7126be ）。

提出 vibe coding 的那个人，自己在真金白银的支付链路上，被一个"跑得通但有错"的改动咬了一口。

这就是"能跑"和"能做对"之间的距离。而这条距离，就是这本书后面十四章要讲的东西。

本章小结

• "vibe coding"指的是用 AI 写代码而你不审查它——关键词是"不审查"，不是"用 AI"。
• 这个词经历了三次变形：一个玩笑描述 → 被当成方法论 → 提出者本人换成了"agentic engineering"（vibe coding 降低门槛，agentic engineering 守住质量线，两者不是一回事）。
• 工具那条路走了四步：补全 → 对话 → 智能体 → 智能体集群。每一步，人的角色都从生产者向验证者与编排者移动一格。
• 审查的对象越来越抽象，审查的责任越来越重。你的价值取决于你能对多少代码负责。
• 一个真实教训：连提出这个词的人，都在一个"跑得通但有错"的支付集成上栽过。

对不写代码的人意味着什么

你不需要知道 padding 是什么，也能从这里拿到一条判断标准：当一个团队说"我们用 AI 把系统做出来了"，你要问的不是"用了什么模型"，而是"谁读过那些代码、谁签的字"。这两个问题的答案，决定了这个东西能不能用在你的业务上。

行动清单

1. 把两件事分开说：下次讨论时，明确区分"我们用 AI 写代码并且审查"和"我们用 AI 写代码不审查"。如果团队里说不清，就先定一条："提交代码的人必须能解释它。"
2. 列一张"允许不审查"的清单：写清哪些场景可以不审查（用完就扔的脚本、一次性分析、个人小工具），以及为什么（没有数据风险、没有用户、没有资金链路）。清单之外的，一律要审查。
3. 别用"AI 写的"当挡箭牌：如果一段代码进入了主干、跑在生产上，写它的是谁无关紧要——负责的是签字的人。

延伸阅读

• Andrej Karpathy 提出 vibe coding 的原始推文（2025-02-02）：https://x.com/karpathy/status/1886192184808149383
• Simon Willison, Not all AI-assisted programming is vibe coding (but vibe coding rocks)（2025-03-19）：https://simonwillison.net/2025/Mar/19/vibe-coding/
• Collins Dictionary, Word of the Year 2025: vibe coding（2025-11-06）：https://blog.collinsdictionary.com/language-lovers/collins-word-of-the-year-2025-ai-meets-authenticity-as-society-shifts/
• Darryl K. Taft, Vibe coding is passé. Karpathy has a new name for the future of software（The New Stack, 2026-02-10）：https://thenewstack.io/vibe-coding-is-passe
• Peng et al., The Impact of AI on Developer Productivity: Evidence from GitHub Copilot（arXiv:2302.06590, 2023）：https://arxiv.org/abs/2302.06590
• Anthropic, Building effective agents（2024-12-19）——工作流与智能体的官方定义：https://www.anthropic.com/engineering/building-effective-agents
• Stack Overflow Developer Survey 2025（AI 章节）：https://survey.stackoverflow.co/2025/ai

第 2 章　从猜下一个词说起

本章承诺：读完这一章，你能从生成机制入手，理解模型的一些本领与局限——包括它为什么可能一本正经地编造、为什么同一个问题问两遍答案不一样、以及为什么"一次能读下整个仓库"却不等于可靠地用上每一段。

读完后你能回答

• 为什么它能把一个函数写得漂亮，却在两个函数的衔接处编出一个不存在的参数？
• 为什么同一个问题问两遍，答案会不一样？
• "上下文窗口大到能装下整个仓库"，为什么还不等于"它记住了整个仓库"？

2.1 一台"下一个词"的机器

理解大语言模型的文字生成，可以先记住一句话：

常见的自回归模型，会根据已有上下文预测下一个 token，再接着生成。

先把 token 粗略当成"词"。你写"今天天气"，它算出后续各个 token 的概率，再按生成设置挑一个，接上去。再猜下一个。如此往复，直到输出结束标记或达到长度限制。

你看到的一气呵成的回答，就是这样一步步接出来的。但输出流畅，不保证事实正确。

这解释了文字怎样生成，却不能单凭它推出模型的全部能力与限制。训练数据与方法、后训练、推理时投入的计算、可用上下文和工具，都会影响它能做好什么。

• 它为什么懂那么多？ 训练让它从大量代码、文档、论坛问答、教科书、issue 讨论里学到知识与模式，后训练等环节也会影响它怎样运用这些能力。
• 它为什么可能不了解你的项目？ 因为项目事实未必在训练数据或当前上下文里。把相关代码、文档交给它，或让它用工具查，能补上信息，但仍要核验。
• 它为什么能写漂亮的函数、却在两个函数的衔接处编参数？ 因为符合常见写法，不等于符合你们系统的真实接口。缺少信息或推断出错时，它仍可能给出看起来顺畅的答案。

定义 · token
模型处理文字的基本单位。它先把文字切成一个个小块（可以是一个词块、半个词，也可以就是一个标点），每一块叫一个 token。具体怎么切，取决于模型使用的分词器。
为什么要知道这个？因为上下文与输出长度的上限通常用 token 计，许多服务也按 token 收费，但它不是全部成本和限制的唯一单位。

还有一类推理模型，会在给出最终回答前投入额外的推理计算。中间过程不一定完整展示给用户，所以不能只凭最终回答，就判断它到底检查过什么。工程上仍要靠可见的工具调用、测试结果与留痕来核验，而不是把一段推理说明当成审计证据。

2.2 它为什么会一本正经地编

定义 · 幻觉（hallucination）
模型生成与事实不符或缺乏依据的内容，往往还说得流利、自信。自回归生成本身不保证事实正确；幻觉也受训练、上下文、推理与工具等因素影响，不能只归因于"猜下一个词"。

有个经典例子到今天仍值得警惕。你让模型读一个 YAML 配置文件，它可能会写出 pd.read_yaml(path) 这样一行代码——看起来很自然，很有信心。问题是：pandas 这个库根本没有这个函数。

一种可能的解释是：read_csv、read_json、read_excel 都是常见写法，模型顺着相似模式生成了 read_yaml。名字像真的，不等于接口真的存在。

从编造事实到业务逻辑出错，常见问题有三副面孔，发现难度与后果各不相同：

第三类尤其麻烦。它未必"编了一个东西"，也可能只是把真实需求理解错了。这种错误可能通过编译、现有测试与评审，一直活到生产环境里某个边界条件被触发的那一天。这是错误类型，不等于"校准失效"。

对付这些问题没有一招制胜，可以先用三层组合：

1. 接地——把真实的上下文喂给它（项目文档、现有代码、报错日志）。让它"看着资料说话"。
2. 验证——假设每一个 API 调用都可能是编的，用编译器和测试去机械化地验证，业务语义还要对照需求检查。这是第 9 章的内容。
3. 校准——检查模型表达的置信程度与实际正确率是否匹配；不匹配才叫校准失效。不能凭语气谦虚就选型，要在有代表性的任务上验证它说得多有把握、实际答得多准。

一句话讲明白：不妨把模型当成一个读过很多资料、却未必掌握你项目细节的实习生。给他资料，也要验收；他可能说得很自信，也可能表示不确定，两种语气都不能替代检查。

2.3 同一个问题问两遍，为什么答案不一样

这不是模型"不稳定"，而是有几个旋钮在被拧动。

旋钮一：随机性。 上一节说了，模型是"按概率挑一个词"。挑的时候带多少随机性，由一个参数控制。这个值调低，它几乎总挑概率最高的那个，输出稳定但死板；调高，低概率的词也有机会被选中，输出多样但更容易跑偏。

写代码时，低随机性通常是一个可测试的起点；但工具是否开放这个参数、默认值是什么，要看具体配置。

旋钮二：思考多少。 一些推理模型允许设置思考预算，影响回答前投入的计算。并不是所有模型都开放这个参数，也不能假定系统总会按任务难度分配得恰到好处。

这里有个很实际的坑：默认档不一定适合你的任务。要核对它用了多少推理计算、怎样计费，而不是只数你看得见的输出。

旋钮三：采样与并发。 即使参数完全一样，不同平台、不同并发条件下也可能出现差异。所以"我昨天用同样的提示词能得到正确结果"不是一个可以依赖的假设。想要可复现，得显式设计，而不是默认它成立。

核心判断 1
给智能体配模型时，先核对默认值，不要照单全收。
在参数可调时，可以从"高难度重构：低随机 + 较多思考；批量模板：低随机 + 较少思考"开始试，再用任务结果决定。
随机性影响输出稳定性，思考预算影响质量与成本；两者都不保证正确或完全可复现。

2.4 它能"看见"多少

定义 · 上下文窗口（context window）
模型一次能"看见"的上下文长度上限，以 token 计。可以把它比作工作台：窗口里的内容会互相影响；窗口外的项目资料不会自动成为这次回答的依据，需要重新提供或通过工具取回。

2026 年，已有前沿模型提供百万 token 级窗口。一个中等规模的代码仓库塞进一次对话，在一些配置下已经可行。

但有三条常识必须说清楚，否则"大窗口"会变成一种幻觉。

第一，窗口大不等于记性好。 2023 年有一篇很有名的论文叫《Lost in the Middle》（Liu et al., TACL 2023, https://arxiv.org/abs/2307.03172 ）。它发现：把关键信息放在长文本的开头或结尾，模型找得最准；放在中间，准确率明显下降——即使是对那些专门为长上下文设计的模型。这个问题在 2026 年被大幅缓解，但没有消失。把关键约束放在上下文的开头或结尾，仍然是个值得养成的习惯。

第二，注意力是稀缺的。 你往窗口里塞五万行无关代码，模型对你真正关心的那两千行的专注就会被稀释。第 11 章会把这件事讲透——一句话先记住：要给模型一张干净的工作台，而不是一间堆满杂物的仓库。

第三，窗口会满，满了要处理——而"怎么处理"是今天的核心工程决策。 平台普遍的做法是自动压缩：把旧历史摘要化。但压缩是有损的，被摘要掉的细节，可能恰好是后面需要的那一条。

还有一种被命名的失败模式值得单独说：上下文焦虑。模型接近上下文上限时，可能提前收尾——把没干完的活包装成"已完成"交给你。这是长任务里值得检查的一种失败模式，不是每个模型必然出现的行为。

一句话讲明白：上下文窗口像一张桌子。桌面再大，你也不该把整个仓库的书都摊上去——该摊的是这一件事需要的那几本。

本章小结

• 常见的自回归模型逐个预测 token 来生成文字，流畅不等于事实正确。训练、后训练、推理计算、上下文与工具共同影响能力，不能从生成机制推出全部本领与局限。
• 编造 API、编造依赖、隐蔽的业务／语义错误，发现难度与后果各不相同；最后一类不等于校准失效。
• 可以用接地、验证、校准组合应对。校准看的是置信程度与实际正确率是否匹配，不是语气是否谦虚，要用代表性任务检验。
• 随机性、思考预算、采样与并发条件都可能影响输出。先核对默认值，不要照单全收。
• 上下文窗口再大也不等于记性好：中间可能漏、无关信息可能干扰、压缩可能丢细节。还要留意"上下文焦虑"这类提前收尾的失败模式。

对不写代码的人意味着什么

你不需要懂 token，也能拿到两条：
第一，"AI 说得很有信心"和"AI 说得对"是两回事——自信或谦虚都不能替代实际验证。
第二，"我给它看了所有资料"不等于"它读懂了所有资料"——给得太多，反而可能让它漏掉关键的那一页。所以重要的约束，要放在最前面或最后面，并且反复确认。

行动清单

1. 检查你的模型参数：核对随机性、思考预算等参数是否可调、默认是什么；对能调的参数显式记录配置，再比较不同设置的质量与成本。
2. 给每个重要输出配一个验证动作：哪怕只是"这个函数真的存在吗"——查一次文档，或者直接跑一遍。选模型时，再用一组代表性任务检查答案正确率与它表达的置信程度是否匹配，别只看语气。
3. 控制你的上下文：给智能体的每个任务，只放这件事需要的资料，别把整个仓库倒进去。关键约束写在最前或最后。
4. 留意"提前收尾"：如果它说"已完成"，随机挑两条它声称做完的事实际验一遍。这个动作能帮你发现遗漏。

延伸阅读

• Liu et al., Lost in the Middle: How Language Models Use Long Contexts（TACL 2023, arXiv:2307.03172）：https://arxiv.org/abs/2307.03172
• Anthropic, Effective context engineering for AI agents（2025-09-29）：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Anthropic, Building effective agents（2024-12-19）——第 2 节"什么时候该用智能体"：https://www.anthropic.com/engineering/building-effective-agents
• 各厂商官方模型卡：上下文长度、思考预算参数、缓存定价与限流规则的一手来源（必读，别读二手转述）

第 3 章　能写代码，不等于能做软件

本章承诺：读完这一章，你能分清"能写代码"和"能做软件"之间差了什么，能理解为什么一个模型可以在考试里考满分、却在你的项目里帮不上忙，也能自己判断一件事该不该交给它。

读完后你能回答

• 为什么同一个模型，能在难题上让你惊讶，却在"很简单"的问题上让你无语？
• 榜单第一名，为什么保证不了它在你的仓库里好用？
• 做软件这件事拆开看有五件事，AI 现在能帮上哪些忙？

3.1 一条锯齿状的边界

先看两个真实场景。

一个资深工程师发现，模型能一眼指出他分布式系统里的竞态条件——这在他看来是个很难的问题。但同一个模型，会坚持给一个脚本装上根本不存在的一个第三方库。

另一个更常见：模型能写出五百行的 Kubernetes 控制器，却在"这个仓库用的是 npm 还是 yarn"上猜错。

这里一个重要区别是：通用知识可能已经学过，项目事实却需要从上下文或工具中取得。但仅靠这个区别，也不能解释所有成败。

所以模型的能力边界不是一条平滑的线——不是"越难越不会"、或者"越简单越会"。它是锯齿状的：有些很难的事它做得很漂亮，有些看起来很简单的事它做不对，而且不能只凭难度预测哪一件是哪一件。

"锯齿状边界"这个说法来自哈佛商学院的一项研究（Dell'Acqua et al., Navigating the Jagged Technological Frontier, Harvard Business School Working Paper 24-013, 2023）。他们的实验设计很聪明：让顾问做两类任务，一类落在 AI 能力范围之内，一类落在之外，然后对比。结果出现了两个方向的差距——在边界之内，AI 明显帮了大忙；在边界之外，它反而让人做错了。

这个实验最值得记住的不是它给了什么数字，而是它给了什么结论：

"AI 能帮上忙"和"AI 帮不上忙"这两种判断，不能靠感觉，只能靠用你自己的任务去测。

锯齿边界的实践含义只有一句话：不要用平均能力评估模型，要用你的任务评估。

3.2 它最擅长什么、最不擅长什么

那么这排锯齿大致长什么样？先按"通用知识"和"需要补充的项目事实"分一分。这只是选任务的起点，不是固定的能力边界。

一句话概括：通用知识常常更容易借力；只有你们知道的项目事实，要先补给它，再验证它用得对不对。

一个必须知道的数字反差

2025 年 9 月 19 日，评测机构 Scale AI 发布了一个新的编码基准 SWE-bench Pro（https://scale.com/blog/swe-bench-pro ）。它的设计目标是解决旧基准的一个致命问题：题目可能被"背过"。

做法是这样的：它从采用带有较强开源义务的许可（如 GPL）的代码库和私有商业代码库里出题。Scale AI 认为，GPL 等许可带来的法律约束，使这些代码很可能未被纳入训练；私有代码也有助于降低污染风险，但都不能据此保证模型从未见过。它还把真实提交里含糊、不完整的需求，由人工补成清晰的问题陈述（但不给解法）。最终共 1,865 道题、41 个代码库，平均每道题要改 107.4 行代码、涉及 4.1 个文件，任务也比旧基准更复杂。

报告列出了这组反差：

在旧的 SWE-bench Verified 上，多数顶尖模型得分超过 70%。
在 SWE-bench Pro 公开集上，最好的两个模型——OpenAI GPT-5 和 Claude Opus 4.1——分别拿到 23.3% 和 23.1%。
在私有商业代码库那个子集上，GPT-5 得分为 14.9%。

旧基准超过 70%，Pro 公开集约 23%，商业集里的 GPT-5 约 15%。这些基准与子集不能直接相减：换的不只是题目来源，还有难度与任务构成。它们说明，在降低污染风险、同时更复杂的基准上，模型表现明显下降；不能单独分离出陌生度、难度或训练污染各自的影响。

另有一项关于污染的诊断研究值得注意。2025 年 6 月的一篇论文（Liang, Garg & Moghaddam, The SWE-Bench Illusion, arXiv:2506.12286, https://arxiv.org/abs/2506.12286 ）做了两个诊断实验，其中一个特别能说明问题：只给模型一段 issue 描述，不给任何仓库结构，让它猜"哪个文件有 bug"。在 SWE-bench 的题目上，它猜中的比例最高到 76%；换到不在 SWE-bench 里的代码库，掉到 53%。

只凭问题描述就能指出文件路径，值得警惕训练记忆的影响；但仅凭这个现象，不能断定每次命中都是"背过"。

数据卡 · 不同基准与子集的得分反差

基准	题目来源	顶尖模型得分
SWE-bench Verified	公开、可能进过训练数据	多数顶尖模型 > 70%
SWE-bench Pro（公开集）	GPL 代码库，旨在降低污染风险	GPT-5 23.3% / Claude Opus 4.1 23.1%
SWE-bench Pro（商业集）	私有商业代码，旨在降低污染风险	GPT-5 14.9% / Claude Opus 4.1 17.8%

口径与时点：Scale AI 研究博客，2025-09-19；Pro 成绩采用 SWE-Agent 脚手架，公开集与商业集分别列示。
局限：不同基准的题量、难度与任务构成不同，分数不能直接相减，也不能保证模型从未见过相关代码。更复杂、旨在降低污染风险的基准上表现下降，不能据此分离陌生度、难度和污染各自的影响。

3.3 榜单第一名，为什么救不了你

到这里，你可能已经接受"能力是锯齿状的"。但还有一个更隐蔽的陷阱：就算榜单是对的，它测的也不是你要的东西。

这张图想提醒的是：解题能力强，不等于在多轮工具调用中就可靠。但匿名指数缺少可追溯的定义，也没有已确认的共同量尺，不能把两种得分相减，解释成能力损失（见附录 A.3 第 24 条）。这里仅保留这个概念判断，不量化落差，也不据此推荐具体模型。

两类评测可能关注不同的事情：

单轮解题评测关注"能否答对这道题"。
多轮智能体评测还要看"能否选工具、读结果、处理失败，并且不跑偏"。

一个模型可以推理得很漂亮，却在第 14 轮调用工具时传了一个格式错误的参数，把空结果当成成功，然后自信地报告"任务完成"。

所以选型的第一条纪律是：

核心判断 1
要建智能体，就按"智能体能力"筛，不要按"智力分数"筛。
而且——榜单分数不只属于模型，它属于"模型 + 外围运行时 + 工具 + 任务设计 + 执行环境 + 允许花的算力"这个整体。同一个模型在不同配置下的成绩可能明显不同。这也是第 11 章要讲的问题。

顺便给读者一条实用的读榜纪律：

1. 看基准的版本和日期，别只看排名。版本改变了题目或口径，分数就未必可比。
2. 看它测的是什么：单轮答题？还是几十轮的工具调用？后者才更接近智能体的实际场景。
3. 看它有没有防污染设计：设计能降低风险，但不能证明题目绝未进过训练。
4. 先看量尺、样本与结果波动，再看分差，别为缺乏证据支持的小幅领先多付钱。

最后一条，也是最有用的一条：拿你自己仓库里的 50–150 个真实任务做试金石。如果任务有代表性、验收可靠，这个自有评测集会比只看公开榜单更贴近你的需求；它仍是抽样，不是对所有任务的保证。

3.4 做软件的五件事，它做了几件

现在把"做软件"这件事拆开。任何一件软件交付，无论大小，都要做完五件事：

五件事里，它在第 ③ 件上最容易显出本领，也能协助第 ② 和第 ④ 件；但每件能做到什么程度，都要看任务，不能说哪一件已经普遍"做完了"。

（第 ④ 件尤其容易被高估。第 9 章会讲：测试是必要条件，不是充分条件。测试全绿的系统照样可以出事。）

所以"AI 能做软件了吗"这个问题，问错了。正确的问法是：

核心判断 2
做软件有五件事：决定做什么、说清楚要什么、把它做出来、证明它对、为后果负责。
AI 能帮你把代码做出来，不等于这五件事都完成了。
把五件事连成可靠的交付，才是"软件工程"这门手艺。

本章小结

• 模型的能力边界是锯齿状的：通用知识常常更容易借力，项目事实要补给它，再验证。不能只凭难度或感觉判断，要用你自己的任务去测。
• 更复杂、旨在降低污染风险的基准上，模型表现明显下降。旧基准上多数顶尖模型超过 70%，Pro 公开集领先模型约 23%，商业集里的 GPT-5 约 15%；题源、难度与任务构成都变了，不能单独归因于陌生度或污染。
• 要建智能体，就按智能体能力筛，不要按智力分数筛。榜单分数属于"模型 + 外围配置"这个整体；不同量尺的指数不能相减为能力损失。
• 做软件有五件事，AI 能协助其中多件，但能生成代码，不等于完成了软件交付，更不等于有人为后果负责。

对不写代码的人意味着什么

这一章给了你一个可以立刻用的判断框架。下次有人跟你说"我们用 AI 做了一个系统"，你就问这五件事：

1. 谁决定要做这个？（有没有人真的想过它值不值得做）
2. 需求是谁确认的？（有没有人对"做成什么样算完成"负责）
3. 代码是谁写的？（这时可以坦然说"AI 写的"，没问题）
4. 怎么证明它能用？（有没有测试、有没有真实链路验证）
5. 出事了谁负责？（这个问题如果没人能回答，那这个系统不该上生产）

第 3 和第 5 个问题的答案，基本上决定了这个东西能不能托付。

行动清单

1. 建一个自有评测集：从你的仓库里挑 50–150 个有代表性的真实任务，覆盖常见任务、难题与边界情况，固定验收标准。这是选型的起点，不是一个通用样本量要求。
2. 给你的团队做一次"五件事"体检：拿最近交付的三个功能，逐条对照上表，标出每一件事是谁做的。别只盯着第 ③ 件的产出，其他环节也可能藏着风险。
3. 做一次"锯齿测试"：挑三件事交给它——一件你认为它肯定会的、一件你认为它可能不会的、一件你认为它绝对不会的。看结果和你的预期差在哪。把反差收进自有评测集，而不是用三道题概括全部能力。
4. 控制依赖准入：只使用经过审批的包与版本，内部仓库不得自动透传未知公共包；锁文件固定版本与完整性，不能鉴定包是否恶意。

延伸阅读

• Scale AI, SWE-Bench Pro: Raising the Bar for Agentic Coding（2025-09-19）：https://scale.com/blog/swe-bench-pro
• Liang, Garg & Moghaddam, The SWE-Bench Illusion: When State-of-the-Art LLMs Remember Instead of Reason（arXiv:2506.12286）：https://arxiv.org/abs/2506.12286
• SWE-bench 官方排行榜与方法论：https://www.swebench.com
• Dell'Acqua et al., Navigating the Jagged Technological Frontier（Harvard Business School Working Paper 24-013, 2023）。注：该文有多个访问入口，若链接失效可按标题检索
• Anthropic, Building effective agents（2024-12-19）——注意它的核心建议是"用最简单的方案，只在确有必要时才增加复杂度"：https://www.anthropic.com/engineering/building-effective-agents

第二篇　算清账：它到底让你更快了吗

第 4 章　两堆互相矛盾的证据

本章承诺：读完这一章，你能看懂为什么"AI 让我快了 5 倍"和"AI 让资深开发者慢了 19%"这两句话可以是同时为真的，也能学会在听到任何一个"提效百分比"时，该追问哪三句话。

读完后你能回答

• 说 AI 快的那些研究，实验条件是什么？为什么换成另一个条件结论就反了？
• 说 AI 慢的那个随机对照实验，到底做了什么？它的结论不能用在哪里？
• 为什么"感觉自己更快了"和"实际更快了"能差出 36 个百分点？

4.1 说它快的那些研究

先看最常被引用的一组数字。

第一个：55.8%。 2022 年，GitHub 团队做了一次随机对照实验：95 名开发者，任务是从零写一个 HTTP 服务，随机分成"可以用 Copilot"和"不能用"两组。结果：在完成任务的参与者中，Copilot 组的平均完成时间比对照组缩短 55.8%（95% 置信区间：21%–89%；Peng et al., 2023, https://arxiv.org/abs/2302.06590 ）。

数字很漂亮。但请你先看一眼它的实验条件：

这是一个边界清晰的实验场景。论文作者提醒，效果可能随任务和编程语言变化，还需要更多研究来判断能否推广；这不等于作者断言真实现场的收益一定更小。

所以 55.8% 不是一个错的数字，它是一个有条件的数字。把它的条件去掉，只留百分比，就变成了误导。

第二个：3.6%。 一项覆盖 3,000 万次 GitHub 提交、17 万名开发者的研究（Daniotti et al., Who is using AI to code?, arXiv:2506.08945, https://arxiv.org/abs/2506.08945 ）用分类器识别代码里有多少是 AI 写的，然后看它对产出的影响。结论是三句话：

1. 在美国，约 29% 的 Python 函数由 AI 生成；
2. 开发者季度产出（按线上代码贡献计）因此提升了 3.6%；
3. 经验丰富的程序员拿走了几乎全部收益，技能差距被拉大而不是缩小。

第 3 句比第 2 句重要得多。它说明"AI 提效"这件事在一开始就不是均匀分配的——工具越强，会用的人和不那么会用的人之间的差距越大。

这句话的实践含义很直接："我们团队都买了工具"和"我们团队都从工具里拿到了收益"，是两件不同的事。如果组织只做前者，结果大概率是"少数人真的快了，多数人没变化，而整体的交付周期也没变"（第 14 章会展开讲这件事）。

数据卡 · 说它快的两个来源

研究	样本	结果	条件与局限
GitHub Copilot 随机对照实验（2023）	95 名开发者	完成者的平均完成时间 −55.8%（95% 置信区间：21%–89% 的缩短）	单一合成任务（从零写 JS HTTP 服务）；未测代码质量；参与者是自由职业者而非企业开发者；效果可能随任务与语言变化，推广仍需研究
Who is using AI to code?（2025）	3,000 万次提交 / 17 万开发者	季度产出 +3.6%	观察性研究（非因果）；用分类器推断哪些代码是 AI 写的；仅覆盖 Python 与 GitHub

口径警示：这两个数字不可相加、不可互换——一个测的是"某个任务快了多少"，一个测的是"整体产出多了多少"。

4.2 说它慢的那一份

现在看另一堆。

2025 年 7 月，非营利研究机构 METR 发布了一项随机对照实验（https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/ ）。它的实验条件，恰好是上面那一份的反面：

• 16 名资深开发者，平均参与过 2.2 万星以上、超百万行的开源项目多年；
• 在他们自己最熟悉的那个仓库里；
• 处理 246 个真实 issue（修 bug、加功能、重构——都是他们本来就要做的事）；
• 随机分配成"允许用 AI"和"不许用 AI"两组；
• 每个任务平均两小时，开发者全程录屏，自报实现时间；
• 工具主要是 Cursor Pro 配 Claude 3.5/3.7（当时的前沿模型）；
• 按 150 美元/小时付酬。

结果：

允许使用 AI 的那一组，完成时间反而长了 19%。

而且：开发者在实验前预测 AI 能让自己快 24%；在亲身经历了变慢之后，他们仍然相信自己快了 20%。

METR 在原文里做了一件关键的事——它专门列了一张表，写清"我们没有证明什么"：

• 没有证明 AI 不能让大多数开发者变快；
• 没有证明这 16 名开发者或这些仓库能代表大多数软件开发工作；
• 没有证明 AI 在其他领域也不能提效；
• 没有证明未来的 AI 不会在同样的条件下提速。

一份研究主动划清自己的边界，比它的结论更有价值。这一点第 6 章还会讲到：摊开我自己这笔账时，先划口径，再用一整节说清楚它"不能推广到哪里"（6.4）。

2026 年 2 月，METR 发布了后续数据，并对研究方法做了修正说明（https://metr.org/blog/2026-02-24-uplift-update/ ）。但他们对新数据给出的评价是"非常弱的证据"——原因是越依赖 AI 的开发者越倾向于拒绝"不许用 AI"这个实验条件，样本产生了明显的选择偏差。他们因此决定重新设计实验。

所以到 2026 年 9 月为止，这一组的正确表述是：

在"资深开发者 + 自己最熟悉的成熟仓库 + 真实任务"这个条件下，早期 2025 年的工具让人变慢；但这个结论不能推广到新手、不能推广到全新项目、也不能代表后面几代模型。

4.3 那几十个百分点的错觉

把上面两堆数据放在一起，会发现它们并不矛盾——参与者、任务、工具和测量口径都不同，不能只用某一项差异解释结果。真正值得琢磨的，是夹在中间的那件事。

落差一：感知与事实。

同一个随机对照实验里出现了三个数字，但它们不是一把尺：预测与自评问的是"快了多少"（提速口径），实测记的是"完成时间变了多少"（耗时口径）。要对比，得先折算：

折算法：把"提速 N%"看作单位时间产出变为 1＋N，耗时即 1/(1＋N)−1。这里只用于把三者放到同一把尺上比较量级，不是 METR 报告的原始数值。

折到耗时这把尺上，自评与实测差约 36 个百分点，预测与实测差约 38 个百分点。原来的 24%、20% 与 19% 分属提速与耗时两种口径，不能直接相减。这不是把任何团队的自评统一减去一个固定折扣。

这不是开发者在撒谎，也不是他们不懂技术——参与者是最资深的那一批人。这是度量本身的问题：

• 人对自己时间花费的感知本来就不准（你有没有过"我觉得只改了十分钟，一看表一小时"）；
• 使用工具的体验是愉快的——它让你少打字、少查文档、少在脑子里维护一堆琐碎记忆。愉快会被记成"高效"；
• 最难量化的是那些没发生的事：多花的审阅时间、多绕的那一圈、以及"本来可以不用它、十分钟就写完了"的那种情况。

核心判断 1
"我感觉更快了"和"我确实更快了"是两个不同的测量结果，中间可能差 36 个百分点。
任何一个关于 AI 提效的判断，只要它的证据形式是"感觉"或"自评"，就要先打上这个折扣再看。

落差二：投入与回报不同步。

换工具不只要买许可证，还要学习、调整评审与测试流程。这些投入可能先发生，收益要等到交付后才能确认；不能预先保证生产力会先降后升，更不能预先承诺回收期。

本版撤下此前引用的一组组织投入回报建模数字，因为尚未定位到具体报告（撤回记录见附录 A 第 15 条）。建模不是实测，缺少出处的模型也不能替你的团队算账。应当记录实际投入、交付结果与返工，再在明确假设下估算回报。

落差三：任务不同，增益也可能不同。

前面两项随机实验分别研究从零写单一服务与维护熟悉的成熟仓库，结果方向不同。它们提醒我们按任务评估，但参与者、工具与测量口径也不同，不能只把差异归因于任务类型。此前经二手报告转述的任务分层百分比未能定位原始研究，本版不再采用（见附录 A 第 16 条）。

不要用一个百分比概括软件工程。先看它测的是谁、做什么、用什么工具，再问和你的工作是否相近。

4.4 听到"提效 X%"该追问的三句话

到这里，你可以拿这三句话去问任何一个提效汇报了。

核心判断 2
当有人跟你说"我们提效了 X%"，追问三句：
1. 分母是什么？——是"写代码的时间"，还是"从需求到上线的端到端周期"？（这是最常见的一种偷换）
2. 周期是哪一段？——只算生成本身，还是把评审、返工、测试、上线都算进去了？
3. 质量和返工算进去了吗？——多出来的评审时间、后移的缺陷、以及那些"本来不会做、现在做了"的工作，算不算在内？

三句答不出来，"提效 X%"就不是一个结论，而是一句感受。

本章小结

• 说它快的：GitHub Copilot 随机对照实验在"从零、单一任务、常见栈"上，测得完成者的平均完成时间缩短 55.8%；一项覆盖 3,000 万次提交的研究测得整体产出 +3.6%，但收益几乎全被资深开发者拿走。
• 说它慢的：METR 在"资深开发者 + 熟悉的成熟仓库 + 真实任务"上测得 慢了 19%，而同一批人自认为快了 20%。
• 两堆数据不矛盾——参与者、任务、工具和测量口径都不同，不能只用某一项差异解释结果。把条件去掉只留百分比，就变成了误导。
• 自评与实测之间差约 36 个百分点。凡是证据形式是"感觉"或"自评"的提效结论，先打折扣。
• 听到"提效 X%"，追问三句话：分母是什么、周期是哪一段、质量和返工算了没有。

对不写代码的人意味着什么

你有了一条不需要懂技术就能用的提问方式。供应商或团队汇报"我们提效 3 倍"时，你只需问：

• "这个 3 倍，是把哪一段和哪一段比？"
• "返工算进去了吗？"
• "这 3 倍是谁的快？所有人都快了，还是几个人快了？"

最后一个问题往往最能露馅——很多汇报里，"提效 3 倍"实际是"团队里最会用工具的两个人提效了 3 倍"。

行动清单

1. 给你的团队做一次"分母体检"：把上一季度所有"提效"汇报里的指标列成一张表，逐一标注分子与分母。凡是分母是"生成量 / 采纳量"的，用"从需求到上线的端到端周期"重算一遍。
2. 做一次验证成本抽样：随机抽 10 个已合并的变更，记录你实际花在审查与验证上的分钟数，除以变更行数。这就是你们真实的"验证单价"——它会让你对后面的所有决策都更诚实。
3. 找出你的评审瓶颈：统计上一个月合并请求的"首次评审等待时长"分布。如果 P90 超过半天，你的瓶颈已经不在写代码那一端了。
4. 把"提效"改成三个数：不再汇报一个百分比，改成汇报"端到端周期、缺陷逃逸率、返工工作量"这三个数。

延伸阅读

• Peng et al., The Impact of AI on Developer Productivity: Evidence from GitHub Copilot（arXiv:2302.06590）：https://arxiv.org/abs/2302.06590
• Daniotti, Wachs, Feng & Neffke, Who is using AI to code? Global diffusion and impact of generative AI（arXiv:2506.08945）：https://arxiv.org/abs/2506.08945
• METR, Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity（2025-07-10）：https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/
• METR, We are Changing our Developer Productivity Experiment Design（2026-02-24）：https://metr.org/blog/2026-02-24-uplift-update/
• DORA / Google Cloud, Accelerate State of DevOps Report 2024——官方结论："AI 采纳显著提升个人生产率与工作满意度，但同时负面影响交付稳定性与吞吐"：https://dora.dev/research/2024/dora-report/
• Stack Overflow Developer Survey 2025（AI 章节）：https://survey.stackoverflow.co/2025/ai

第 5 章　什么变便宜了，什么变贵了

本章承诺：读完这一章，你能用一张成本账解释清楚一件事——为什么"写代码变得不要钱了"不一定让软件变得便宜，反而可能让验证、理解与责任成了新的稀缺品。你也能看懂"0.99 的 500 次方"这道算术，以及为什么不能拿它估算真实代码的成功率。

读完后你能回答

• 写代码变便宜了，为什么软件不一定跟着变便宜？
• 为什么不能只靠"多派人去审查"？
• 什么叫"三种税"？它们分别由谁在付？

5.1 一次成本结构的大搬家

先讲一个被埋了三十年的事实。

写代码从来不是软件成本的大头。

这件事在行业里被反复验证过：在一个软件的全生命周期成本里，"编写代码"大约占三分之一甚至更少，剩下的都在需求、设计、验证、沟通和维护里。但因为"程序员在写代码"这件事太显眼，这个事实一直被那个画面盖住了。

2026 年，它藏不住了。

把"编写"这一项的成本压到接近零之后，其他几项并没有跟着变便宜，占比反而上来了——最明显的是验证，其次是设计，而维护基本持平：

• 验证的属性变了：生成一个模块只要几分钟，但验证它是否正确、是否安全、是否长得像这个系统该有的样子，仍然需要人的真实时间。这一项从"次要工序"变成了"主要成本"。
• 设计的属性变了：把一件事说到机器不需要猜，本身就是设计工作。第 7 章会专门讲。
• 维护的性质变了：第 10 章会给出硬数据——代码重复率上升、复用下降、重构消失。技术债的利息在加速累积。

数据卡 · 成本结构迁移（示意口径）

成本项	传统时代	智能体时代
编写代码	约 45%	约 8%
验证与测试	约 18%	约 42%

⚠️ 口径必须说清：上表是示意性结构，只表达迁移方向，不是精确的行业统计。这里有两个分母，别混着看：表里的 45% 说的是"编写占可见工作量的比例"；经验研究给的那组 20%–35%，说的是"编写占全生命周期成本的比例"，而且各家估计本身就有分歧。分母不同，45% 不该直接拿去和那组数对照。
本书引用它的目的，是让你看到"成本从哪一项搬到了哪一项"，不是让你拿去算钱。

打个比方：印刷术没有让作家失业，因为它降低的是抄写的成本，而写作的核心——想清楚要写什么——一分未减。它反而让"想清楚"变成了唯一的门槛。

AI 编码工具降低的是敲代码的成本。而软件工程的核心——决定造什么、验证造得对不对、保证十年后还改得动——不但没有贬值，反而成了新的稀缺品。

5.2 验证鸿沟：0.99 的 500 次方

先把两件容易混淆的事分开：验证积压，与代码出错的概率。

定义 · 验证鸿沟（verification gap）
代码生成与验证能力不匹配，造成未验证代码积压。按同一范围、同一单位计数，某时刻生成代码存量减去其中已验证存量，是当时的验证积压；若不计丢弃等变化，生成速度减去验证速度，才是积压的增长速度。
生成可能以秒计，验证却以小时计。当"生成量 × 单件验证成本"超过了它替你省下的时间，提效工具就可能变成负债机器。

再看一道关于正确率的算术，提醒自己别把局部可靠当成整体可靠。

先说前提：这是一个玩具模型，假定每行是否正确相互独立、服从同一分布，而且每行正确的概率都是 99%。这不是对真实代码的测量。在这些假设下，一个 500 行的模块，"每一行都对"的概率是多少？

在这组假设下，500 行全部正确的概率不到 1%；不能把这个计算结果当成真实代码"一次就对"的成功率。

这里仅用图表达生成与验证可能失衡，不依据曲线间的面积量化积压或损失。

现实当然比这张表复杂：代码行之间有依赖，错误可能相关，"每行正确"也不等于系统满足业务需求。编译器会拦下一批问题，测试会兜住一批，模型自己也会在反馈循环里修掉一批。这道算术不证明验证积压会增长；只有生成持续快于验证、又没有其他消减积压的措施时，积压才会扩大。

一句话讲明白：这就像往一个水池里注水。进水口（生成）加快，出水口（验证）不变，水就可能越积越多。水位对应当时的积压，进水速度减去出水速度对应积压增长的快慢。会不会漫出来，还要看已有积水、剩余容量和这种速度差持续多久。

为什么不能只靠"多派人审"？因为审查速度不能无限提高。SmartBear 公布的那组 Cisco 工程团队评审数据给出的建议是：单次评审不超过 200–400 行，审查速率保持在 500 行/小时以下；超过约 400 行之后，发现缺陷的能力下降——这里的 400 指单次审查的代码量，不是每小时的速率。这是特定场景里的经验，不是所有代码评审的物理上限。加人可以扩充容量，但也有协调成本；如果生成持续超过验证能力，积压就不会自己消失。

所以除了控制生成量，这里重点讲两条路：

1. 验证前移——在"意图"阶段尽量消除歧义。这是第 7 章的规格。
2. 验证机械化——让机器承担尽可能多的判定。这是第 9 章的测试与门禁。

两条都用不上，就该缩小变更或放慢生成，而不是把未验证的风险留给生产环境。

5.3 瓶颈搬到了"读代码"那一侧

生成快了，那么下一个堵点在哪？

在"读"这一侧。

2024 年，Google Cloud 的 DORA 团队发布的年度报告里有一句官方的总结（https://dora.dev/research/2024/dora-report/ ）：

"AI 采纳显著提升了个人生产率、心流体验和工作满意度。但是，它也同时对软件交付的稳定性和吞吐产生了负面影响。"

请注意这句话的写法：前半句是好事，后半句是坏事，而且是"同时"。

这里要说清的是：个体层面的"我更快了"，和组织层面的"我们交付得更好"，不是同一件事，也不会自动转换。DORA 把这一点称为"意料之外的权衡"。

这个"权衡"具体长什么样？有一个被反复观察到的机制：瓶颈会从"写"搬到"审"。

⚠️ 一条引用纪律：下面这几个数字（除最后一行）来自一项 2026-07 发布的企业级纵向案例研究（802 名开发者、196,212 个合并请求，现为 arXiv 预印本，见附录 A.2 第 14 条）；最后一行"等待时长 4.6 倍"出自另一份厂商基准报告（见附录 A 第 19 条）——两者来源不同，不要合并引用：

这篇研究报告的标题点出了一个值得排查的风险：

"AI 写代码的速度，超过了人类读代码的速度。"

如果新增变更持续超过评审容量，又靠压缩审查或绕过门禁赶进度，就可能出现下面这条风险链；它不是每个团队必然经历的结果。

生成持续超过验证能力 → 评审队列变长
        → 若压缩审查或绕过闸门，缺陷可能后移
        → 停机与返工成本可能上升，侵蚀净收益

核心判断 1
瓶颈可能从"写代码"搬到"审代码"。
如果生成持续超过验证能力，组织又不调整评审容量、标准或生成量，整条管道就可能越堵越严重。

5.4 三种税

把上面这些收一收。代码生成成本的坍塌，很像一次货币超发——它让"代码"这种商品的名义供给暴增，于是所有以代码计价的东西都开始贬值。但贬值对不同的人来说是不同的东西。

第一种税：验证税。

生成变便宜了，但验证成本不会自动跟着下降。于是"生成多少就该验多少"这条朴素规则，可能把成本推给下游。这笔税是刚性的——验收责任躲不掉，可以靠"前移"和"机械化"摊薄，也可以减少不必要的生成。

第二种税：认知税。

代码可以被读取，但理解不能。当代码以机器的速度堆积，团队对系统的真实理解，与系统的真实复杂度之间的裂口就在扩大。这个裂口有一个准确的名字——认知债（第 10 章详述）。它比技术债更隐蔽：技术债可以用利息模型估工期，而认知债的唯一利息是"没人敢动那部分代码"。

第三种税：责任税。

这是最容易被低估、却最贵的一种。

当系统出错，追溯链条里必须能找到谁做了验收、授权和上线判断。模型不能替团队履行这些职责，也不能用"是 AI 生成的"把它们推掉。这里说的是专业与组织责任；法律责任要依适用法律、合同和具体事实确定，不能一概免除供应商责任，也不能让签字者个人包揽全部后果。

核心判断 2
三种税合起来，解释了 2026 年最反直觉的一个现象：
AI 让代码变便宜的同时，让工程师变贵了。
因为税的起点是代码，而税的终点是人。

本章小结

• 写代码从来不是软件成本的大头，但这一点被"程序员在敲键盘"这个画面盖了三十年。生成成本趋零之后，成本结构第一次被迫显形。
• 验证鸿沟：同范围、同单位下，某时刻生成代码存量与其中已验证存量之差是积压；不计丢弃等变化时，生成与验证的速度差才是积压的增长速度。
• 0.99⁵⁰⁰ ≈ 0.7% 只是玩具模型的结果：前提是每行正确与否相互独立、同分布，且正确概率都是 99%。它不是真实代码的成功率，也不能证明积压必然增长。
• 不能只靠加人审查。除了控制生成量，还可以验证前移（规格）和验证机械化（测试与门禁）；研究里的审查速率建议不是普遍的物理上限。
• DORA 的官方结论值得背下来：AI 同时提升个人生产率与负面影响交付稳定性与吞吐。瓶颈可能从"写"搬到"审"。
• 三种税：验证税（刚性）、认知税（隐蔽）、责任税（最贵）。它们解释了为什么代码变便宜了，工程师反而变贵了。

对不写代码的人意味着什么

这一章给你的是一条预算判断：如果一个项目声称"用了 AI 所以人力可以砍一半"，你要看的是验证那一侧的能力有没有跟上。

• 如果一个团队说"我们生成快了 5 倍，人还是原来那些人"，那你应该追问验证能力提高了多少、积压有没有增长，而不是只看生成速度。
• 一个健康的 AI 落地方案里，一定会有一部分投入花在"怎么知道它做对了"上——测试、门禁、留痕。没有这一部分的方案，省下的是钱，欠下的是债。

行动清单

1. 算一次你自己的"验证单价"：随机抽 10 个已合并变更，记录你实际花在审查与验证上的分钟数 ÷ 变更行数。这个数字比任何行业报告都更能影响你的决策。
2. 给"验证前移"设一个动作：在写第一行代码之前，把"什么算做完"写成三到五条可判定的句子。做不到这一点，别开写。
3. 给"验证机械化"设一条底线：至少有一道机器门禁（编译、类型检查、静态扫描、测试）在你合并之前必须通过——而且它真的会拦人，不只是出个报告。
4. 列出你的"认知债清单"：写下三处"没人敢动的代码"以及原因。这份清单比任何覆盖率报表都更能说明风险在哪。

延伸阅读

• DORA / Google Cloud, Accelerate State of DevOps Report 2024（官方结论页）：https://dora.dev/research/2024/dora-report/
• DORA 研究总入口（含各年度报告）：https://dora.dev/research/
• GitClear, AI Copilot Code Quality: 2025 Look Back at 12 Months of Data——2.11 亿行变更的可维护性追踪：https://www.gitclear.com/ai_assistant_code_quality_2025_research
• SmartBear, 11 Best Practices for Peer Code Review（Cisco 某工程团队的评审数据；本书只引用它的三条经验阈值——单次 200–400 行、速率低于 500 行/小时、超过约 400 行后发现缺陷能力下降。评审次数、参与人数与代码规模等总量参数未在公开页面逐项核到，本书不作为依据）：https://static1.smartbear.co/support/media/resources/cc/11_best_practices_for_peer_code_review_redirected.pdf
• 关于评审瓶颈那一组数据，见附录 A.2 第 14 条与附录 A 第 19 条（两条来源不同，不要合并引用）

第 6 章　一笔真实的账：我自己这 155 天

本章承诺：读完这一章，你能看到一份注明口径与复核缺口的一手记录——它包含产出的规模、质量的快照，也包含失败和没做到的地方；部分原始材料尚未公开，不能仅凭本书完整重算。你会拿到一个关于"AI 编码到底能到什么程度"的有边界的答案，而不是一个口号。

读完后你能回答

• 一个人、155 天、全部实现由 AI 完成，实际能产出多少东西？
• 为什么我说"便宜"不是这件事最重要的部分？
• 这份经验不能推广到哪些场景？它最大的干扰变量是什么？

6.1 四个仓库、一组注明口径的数字

前言说过：155 天，我一行代码没自己敲。

现在把这笔账摊开。为了让你能核对，我把口径一并写出来。

第一个节点：第 100 天（2026-07-26）的冻结快照。

我在项目第 100 天的时候做了一次正式的数据冻结，把三个仓库的统计、测试命令和结果记下来，写成一份案例研究。提交数有锚定版本，但部分统计包含当时未提交的文件；完整重算还需要对应工作树快照，不能只凭提交标识代替。

注：开发日志按天计。其中有一天的日志同时写在桌面端与云端两个仓库（两个文件、同一天），按文件相加是 101，按天去重是 100——第 100 天冻结的案例研究用的就是 100 这个口径。

先说清楚"100 天"是什么口径。这是日历天数，不是工时。这段时间我平均每天投入大约 4 小时（工作日的晚上少一些，周末和假期多得多）。所以：

100 个日历日 × 平均每天约 4 小时 ≈ 400 小时 ≈ 50 个八小时工作日。

每天 4 小时的业余时间，50 个工作日，换来了约 18.98 万行业务代码 + 6.2 万行测试 + 10.4 万行文档。

第二个节点：到今天（2026-09-19）的最新数字。

注：这三项的"100 天时"一列是第 100 天冻结口径；"今天"一列按原来的三个仓库计（与左边可比），BetterWork 的增量在括注里单列。开发日志按天去重（同一天在两个仓库各写一篇的只计一次）；第 100 天之后没有严格按天补齐，所以 155 天里有日志的是 129 天——这与"每天都有产出"不矛盾，日志不等于产出。桌面端的 ADR 在第 100 天后基本停止新增（工作重心迁移到云端），故仍为 56 份。

数据卡 · 作者自测口径（A 类）

统计范围：ClawBible Desktop、ClawBible Cloud、ClawBible Website、BetterWork 四个独立 Git 仓库。
统计时点：2026-09-19。
口径：行数为物理行（含空行与注释），来自作者留存统计；完整冻结版本、分类清单与原始输出未全部公开，复核材料缺口见附录 A.1。
局限：
① 四个仓库的任务类型、语言、成熟度都不同，行数不可直接相加比较；
② 行数描述的是规模，不是价值——重构、补测试、写文档都会抬高行数，但不必然抬高用户价值；
③ 提交记录显示143 天有提交、12 天没有提交记录。没有提交不等于没有产出——这 12 天写的是本书的书稿与文档，不进入这四个仓库。按"有没有产出"算，这 155 天里没有哪一天空过：每一天都写过代码、文档或书稿。

第三个数字：质量快照——包括没通过的那些。

这一组比规模更重要，因为它带失败。

请注意这张表里的三处"不好看"：

1. 前端行覆盖率只有 25.36%。这说明大片区域根本没有被测试覆盖。后端 70% 不代表前端 70%，更不代表系统可靠。
2. 门禁在交付当天失败过。 我在第 100 天做冻结的时候，后端命名门禁和前端类型检查都没过，是当天修完才敢发布的。
3. 桌面端还有 4 个测试是失败的，到今天也没闭合。我没有把它修掉，因为我把精力转到了新项目上。这是债，不是"待办"。

核心判断 1
"有门禁"和"门禁被满足"是两个不同的命题。
一个项目同时可以有 2,036 个通过的测试、和 4 个没人管的失败——这不是矛盾，这是真实项目的常态。

6.2 为什么"便宜"不是最重要的事

把镜头拉近到一次具体的改动。

2026 年 6 月初，我花了大约两天时间，在我的桌面端项目上做了一次集中的架构重构。具体做了什么不重要，重要的是这组数字：

然后我算了一笔对照账。按我做了二十多年企业级软件的经验，同样这批工作如果交给一个正常配置的团队（1 个架构师 + 2 个后端 + 2 个前端 + 1 个测试 + 1 个协调，约 7 人）：

• 纯开发工时：约 23–37 人天；
• 加上企业环境里的隐性成本（各种评审、跨角色对齐、信息传递衰减、返工），按经验系数 3–4 倍算：69–148 人天；
• 折算人力成本：约 13.8 万–29.6 万元；
• 日历周期：4–6 周（还是在顺利的情况下）。

AI 方案的直接成本是：2 天人工 + 不到 50 元的 token 费用。

数据卡 · 一次重构的两种账

	传统团队情景估算	AI 辅助记录与成本折算
人力	6–7 人	1 人
人天	69–148	2 天
成本（两侧均为情景估算）	13.8 万–29.6 万元	约 1 万元（人工按假定单价折算；另有实录 token 费用 <50 元）
日历周期	4–6 周	2 天

⚠️ 口径必须写清楚：这是基于经验系数的估算对照，不是受控实验。"3–4 倍 B 端隐性成本系数"和"架构师 5000 元/人天"都是行业经验值，不是实测数据；而且两边的单价基准本来就不一样——传统那侧按约 2000 元/人天折算，我这一侧按 5000 元/人天计。这组数字可以说明量级方向，不能用来做采购报价。

这笔账对假设很敏感。如果不乘那组 3–4 倍的隐性成本系数，只把 23–37 人天按 2000 元/人天折算，对照成本就是 4.6 万–7.4 万元。这不是另一组实测结果，只是提醒你：系数一变，差距就会明显改变。

那么，在上述假设下估算出的成本差异，就是最重要的部分吗？

不是。

如果只是"更便宜"，那这件事无非是换了一把更快的锤子。真正让我震动的，是另一件事：

在以前那套账算下来，这些重构根本不会发生。

一个能跑、功能正常、只是"设计不够干净"的模块——传统环境下的决策链是这样的：评估要 15–32 人天 → 过方案评审 → 过排期评审 → 排不进这个 Sprint → 下个 Sprint 又有新需求 → 拖着拖着就没人记得了 → 直到某天它变成一个线上故障。

不是不想改，是改不起。

⚠️ 口径提示：15–32 人天说的是另一个标的（一个中等规模模块的设计改善），与上文那次重构的 23–37 人天不是同一件事——两个数不要互相换算。

而当"改"的成本降到一个人可以承受的范围，代码的设计质量终于能在决策里占更大的分量：这段代码够不够好？值得改吗？但这仍然是成本、收益与风险的判断，不是纯粹的审美。越接近生产、越涉及数据与接口，越不能省掉评估和验证。

我在那两天里做的事情，恰好说明了这一点：路由引擎拆完两天后，我觉得抽象层次还能再提一层。换在以前，这个想法会直接被扼杀——"都上线了，别动了"。但那一次我花了 20 分钟，让它再重构了一轮。

这不是"把事情做完美"的执念。这是拿回了"可以对代码有审美"的权利。

一个我自己发明的词：颅内沟通

还有一个变化值得单独说。

传统团队里，一个想法从产生到落地，要经过一次很长的"传话游戏"：我心里的方案 → 写成文档 → 技术负责人的理解 → 开发者的实现 → 测试的验证。每一手传递，信息就衰减一次。

在这 155 天里，意图、方案取舍和验收判断集中在我这里，实现与部分验证交给 AI 和工具。少了几轮跨角色转述，不等于可以省掉给 AI、未来的自己和协作者看的说明。我仍然写了 73 份 ADR——这个数截至第 100 天冻结，第 100 天之后新增的未再逐份补记。

我把这个叫颅内沟通——当一个人兼任多个角色时，部分决策不必反复跨人传递。它减少交接，不消除人机之间的误解，也不替代评审和测试。

它带来三个很实际的变化：

1. 部分协调等待减少。 在我自己的任务里，等角色交接、等排期的环节变少了。但测试运行、依赖响应、问题排查仍要时间，日历时间没有变成纯开发时间。
2. 可以对代码有审美。（上面说过了）
3. 全责感推动验证，而不是替代验证。 一个人做所有决策，盲区也可能集中在一个人身上。对我来说，全责感意味着不能把问题交给下一个环节；但交付是否可信，仍要靠测试、评审和运行证据。没有独立评审时，更应承认这个限制。

核心判断 2
对我来说，AI 编码的重要价值，不只是"同样的事做得更快"，而是"以前不会做的事，现在有机会做了"。
它既可能改善效率，也可能降低尝试门槛；收益与风险仍要逐项判断。

6.3 三个层次的变革

把上面这些收成一个框架。我认为 AI 编码带来的变化分三层，一层比一层深。

第一层：效率提升（量变）。

同样的事情做得更快：补全、生成测试、写文档、改样式。这一层是真实的，但如果你只看到这一层，你就低估了它的影响，也高估了它的上限。

第二层：协调成本的压缩（质变的开始）。

一个人有机会承担以前需要多个角色交接的工作。注意：不是因为你变成了六个人，而是部分排期、转述和跨角色对齐可以减少。上文 3–4 倍只是那笔对照账的经验系数，不能理解为单人工作自动省掉了同等成本；评审、理解偏差与返工仍然存在。

这一层压缩的不是"打字时间"，而是协调时间。它有多少收益，要在具体任务里量，不能预先断定比第一层更大。

第三层：可能性解放（质变）。

当修改成本降低，更多小型改善有机会进入日常开发，不必每次都作为大项目排期。但重构不是保存文件：涉及公共接口、数据迁移或生产行为时，仍要评估、评审和安排回退。

于是你可以更频繁地做这些事：

• 发现一个模块职责不清 → 先说清拆分收益，再做可独立验证的小步变更
• 看到一个硬编码 → 先判断它是否真的需要配置，而不是见到常量就抽象
• 觉得某个算法不够好 → 在代表性数据上比较正确性、性能与维护成本
• 测试覆盖不够 → 按风险补测试，而不是只追覆盖率数字
• 对设计有了新理解 → 提出具体改善目标，验证后再决定是否保留

改动小，不自动等于风险低；改得多，也不自动等于系统更健康。只有收益值得、回归风险可控、验证结果支持，持续改善才可能帮助我们走出过度设计与技术债累积之间的两难。

有目标、可验证、可回退的多次重构，是一种可以选择的开发策略。不是一锤子凿出成品，而是一刀一刀地雕。这才是这一层真正的意思：AI 降低了尝试的门槛，没有取消判断和验证的责任。

6.4 这笔账不能推广到哪里

到这一章的最后一节了。前面讲了很多好看的数字，现在讲这本书里最重要的一节——它们的边界在哪。

我这 155 天里的八条反证

一个案例研究的可信度，不来自只展示成功。下面这八条，是我在自己的记录里能翻出来的"我错了"：

第 7 条和第 8 条尤其值得记住，因为它们不是"我犯了个错"，而是"机制本身有缺陷"：一个是"我以为是双向同步，其实只有单向"；另一个是"设了阈值，但阈值不会跟着实际情况走"。

我给自己写的那套法则，最诚实的评价

这 155 天里我慢慢总结出了一套规则，一共十条（1 条公理 + 3 个层次 × 3 条），管三件事：做正确的事、正确地做事、让做事的方式持续进化。

我一度觉得它挺完整的。但当我认真去问"这十条里，每一条真的起作用了吗"，得到的答案不平均：

• 执行层的三条最"硬"——有真实在跑的测试和门禁在支撑它们。
• 元层次的三条——有案例记录，但记录高度集中在最后一周，很多早先的"进化"是事后补写的。连我自己定的"每 14 天审查一次"，实际都拖到了约五周，而且是靠人偶然发现的。
• 战略层的三条最"弱"——它定义了"否决"的后果，但在全部决策记录里，几乎找不到一次明确的、写下来的否决。

由此得到一句我认为是这 155 天里最重要的自我判断：

一条规则没有命中记录，既不能证明它有效，也不能证明它无效。先确认它有没有执行，再确认遇到违规时能不能拦住。

规则不是写下来就生效的。我缺的不只是"拦过什么"的记录，还有执行范围、已知违规样例、误报和漏报的检查。没有违规，可能是规则起了作用；没有阻断能力，才是要修复的机制问题。

三条必须说在前面的话

第一，最强的干扰变量是我，不是 AI。

这 155 天的关键是：做筛选、做审查、做纠错的那个人，是一个有 27 年经验、且一直在写代码的架构师。同样一套协作方法，换到刚入行的人手里未必成立。这本书里任何一个结论，都不能被读成"AI 能自己把楼盖起来"。

第二，"一行代码没手写"是亲历事实，不是可被第三方鉴定的事实。

代码仓库只能记录"谁提交了"，不能记录每个字符是谁敲的。能被人独立复核的，是产出、提交、测试和规则结构，不是我的键盘。这一条我在书里说过两次，因为它同时是这本书最强的证据，和它最大的方法学局限。

第三，"快了几倍"是一个有参照的判断，不是精确测量。

我在同期带着团队做高度相似的项目，所以我有可比对象；但我们没有事先约定统一的计时口径。所以我报方向和量级，不给小数点。

还有一个证据点：这套做法能不能迁移

一个案例最容易被质疑的地方是："这是不是只有一个项目碰巧跑通了？"

所以在 2026 年 9 月，我又启动了一个新的、完全从零的项目（BetterWork），用同一套做法：同样不手写代码，同样先定规格再实现，同样把决策写成记录。

18 天，333 次提交，约 3.48 万行业务代码、1.83 万行测试代码、2.43 万行 Markdown 文档。

这不能证明这套方法普遍有效——仍是同一个作者的两个项目。 它增加了方法可迁移的线索，但不能排除偶然性，也没有消除作者经验、任务选择与项目类型的影响。

核心判断 3
一份一手记录的诚实程度，不取决于它报了多好看的数字，取决于它有没有把自己做不到的地方也写进来。
一个能暴露并修正自身缺陷的做法，比一个宣称零缺陷的做法更可信。
但要立刻补一句：这种可信也有上限——它依赖人持续发起修正，而"能不能自动触发修正"，我这 155 天没有验证出来。

本章小结

• 第 100 天（2026-07-26）的冻结口径：三个仓库、1,584 次提交、18.98 万行业务代码、6.2 万行测试、10.4 万行文档、73 份决策记录、100 篇日志。到了 2026-09-19，四个仓库累计 4,194 次提交（桌面端 731 / 云端 3,118 / 官网 12 / BetterWork 333）、33.8 万行业务代码、12.2 万行测试代码。
• "100 天"是日历口径：平均每天约 4 小时，累计约 400 小时，约等于 50 个八小时工作日。
• 质量快照必须连失败一起看：后端覆盖率 70.10%、前端只有 25.36%、第 100 天当天两道门禁曾失败、桌面端至今还有 4 个测试失败。
• 一次 2 天、90 个文件、4 份决策记录的重构，传统团队估算要 69–148 人天 / 4–6 周 / 13.8 万–29.6 万元。但真正重要的一句话是：在以前那套账下，这次重构根本不会发生。
• 三个层次：效率提升 → 协调成本压缩 → 更多改善值得尝试。这是作者的经验框架，不是统一的收益公式。
• 八条反证，以及一条检验纪律：规则无命中不等于无效；要检查执行范围，并用已知违规样例确认能否阻断。
• 最强的干扰变量是人，不是 AI。这套做法不能外推到新手、遗留系统和多团队协作。

对不写代码的人意味着什么

这一章给你的是一条评估一手信息的方法：当你看到一个"AI 提效"的成功案例，去找三样东西——

1. 质量数据（不是产出数据）。有没有覆盖率、测试通过数、缺陷统计？
2. 失败记录。案例里有没有写"哪里没做到"？一个全绿的案例，通常是把失败藏起来了。
3. 边界说明。它有没有说清楚"这个结论不能用在什么场景"？

三样都有，这个案例可以参考。三样都没有，它更像一份宣传。

行动清单

1. 给你自己的项目建一份"数字台账"：口径写死，每个季度跑一次同样的命令。没有基线，就无法判断进步。
2. 今天就写下你的第一条反证：翻一翻过去三个月，找出一个"我当时判断错了"的记录。能写出这一条，说明你的体系开始有自我修正能力了。
3. 检查规则是否真在执行：看执行范围、命中记录和误报，再用已知违规样例确认能否阻断。无命中不等于无效；失效先修复，只有风险消失、适用范围改变或已有等效控制时，才讨论废止。
4. 记住"143 天有提交"这条：它说的是这四个仓库的提交记录，不是工作量。准确的说法要分口径——155 天每天都有产出（代码、文档或书稿），其中 143 天在这四个仓库留下了提交。报数字时把口径一起报出来——准确比漂亮更值钱。

延伸阅读

• 本项目第 100 天快照记录（统计口径、测试与门禁结果、两次失败与修复过程）：留存于作者私有仓库，未随本书公开；本书仅保留第 100 天提交数一条可核对命令，见附录 A.1。HEAD 不作为冻结依据——仓库继续演进后，它不再代表当时的快照。
• 案例研究全文（100 天）：ClawBible.AI/clawbible-cloud/docs/论文/v6/论文-v6.2-AI辅助编程的提效与治理.md
• 逐日工作台账（100 天、100 篇日志的摘要与分类）：见上一条案例研究全文的附录 B（内部文档，不是本书的附录 B）
• 硅碳十律与治理框架：ClawBible.AI/clawbible-cloud/docs/laws/README.md
• ADR（架构决策记录）的起源：Michael Nygard, Documenting Architecture Decisions（2011）。决策记录是智能体时代最重要的文档形式之一——第 10 章会讲为什么。

第三篇　用对它：一个人的功夫

第 7 章　先想清楚，再动手

本章承诺：读完这一章，你能分清楚"给 AI 提个要求"和"给 AI 一份规格"之间的差别，能写出一页不容易被读成两样的规格，也能判断出什么时候根本不该写规格。

读完后你能回答

• 提示词和规格，到底差在哪？
• 一页好的规格里必须有哪六件事？其中哪一件最常被忽略、却最重要？
• 怎么判断一份规格是否拆到了能独立验证、一次审完的粒度？

7.1 提示词和规格是两种东西

先看两个说法。

说法 A："帮我加一个导出功能，要能导出成 Excel。"

说法 B："在订单列表页增加导出功能。只导出当前筛选条件下用户可见的订单，最多 5000 条，超过则提示分批。字段包含订单号、下单时间、金额、状态，不含客户手机号与身份证号。导出耗时应小于 5 秒，超时给出明确提示。不做：不做定时导出、不做导出历史的保存、不做多表合并。验收：选 3 种筛选条件各导一次，比对条数与字段；空结果时导出表头但不含数据行。"

说法 A 是提示词。说法 B 是规格。

它们最本质的区别不是长短，是能不能被判定：

• 说法 A 做完之后，你没法说"你做对了"或"你做错了"——你只能说"感觉不太对"。
• 说法 B 做完之后，你可以逐条验收，甚至可以把它变成自动测试。

定义 · 规格（spec）
一份可复核的意图描述。它说清楚要什么、在什么约束下、怎样验收，而不是替实现者决定所有细节。需求可以包含明确的技术约束，但要把约束与可替换的实现选择区分开。

这里有一个很多人会绕进去的坑。他们觉得"AI 都能读代码了，为什么还要我写规格？我直接说不行吗？"

答案是：不是为了让 AI 听懂，是为了让你自己知道自己要什么。

写规格这个过程，逼你把那些"我以为我想清楚了、其实没想"的地方暴露出来。它真正的产出不是文档，是共识——你和这个任务之间的共识。

规格的真正产出是共识，代码是履约，测试是仲裁。

核心判断 1
规格不是写给 AI 的，是写给你自己的。
一个说不清楚的规格，暴露的不是沟通问题，是思考问题。

7.2 一页规格里的六件事

一份能用的规格，可以先从一页纸写起，但必须有这六件事。每一项都在堵一个具体的漏洞：

第 5 项值得单独讲。

"非目标"就是你明确写下不做的东西。它看起来像是在偷懒，实际上它是最有效的一条防线。

我在自己的项目里把"不做什么"写成了正式产品规则：产品的身份，由它的拒绝来定义。一个什么都做的产品，等于没有产品。这条规则后来救了我很多次——每当有人（包括我自己）说"这个功能挺好的，加上去吧"，我们先去看"不做清单"。在清单上，就得走正式的变更流程。

对 AI 来说，非目标的作用更直接：它防止了"顺手多做一点"。模型有个很自然的倾向——你让它加一个导出功能，它可能顺手把导出历史也存了、把定时任务也加了。在它眼里这叫"考虑周到"，在你眼里这叫范围蔓延。

一句话讲明白：写规格就像给装修队交底。你只说"装得好看点"，最后一定吵架；你说"不要开放式厨房、不要深色地板、不要吊顶"，反而能装出你要的样子。

7.3 粒度的检验题：能独立验证、一次审完吗

规格写得太大，AI 会漏；切得太碎，又会增加沟通和拼接的成本。那"粒度"该多大？

先问一道检验题：

这件事能独立验证，并且让负责的人一次审完吗？

能，才适合作为一次交付；不能，就沿着可验证的边界继续拆。粒度看的是交付与评审的边界，不是有没有写技术名词。

"换一个技术栈来实现，这份规格还成立吗？"是另一道题：它只帮助区分需求与实现选择，不能判断粒度。"同一个用户的重复请求在 1 秒内只处理一次"描述的是行为；"用 Redis 实现"通常是实现选择，但如果它是既有平台或运维政策的明确要求，就应作为技术约束写进需求，而不是删掉。

规格的长度取决于歧义和风险，不取决于代码行数。三行权限改动也可能需要详细说明；低风险、无歧义的改动则不必套长模板。

顺带说一个实践观察：一份能用的规格通常需要 3–5 轮迭代。第一轮写出来的大概率不全——这很正常，规格的价值恰恰在于"迭代的过程"本身逼你想清楚。

7.4 什么时候不该写规格

这一节可能是整章最有用的。

规格不是万能的，也不是什么时候都该写。 我在自己的项目里踩过这个坑：一开始我要求"任何工作都要先写完整规格"，很快就被实践否定了——探索期的方案变化太快，写规格可能比做一个原型还贵。

正确的判断是看不确定性：

核心判断 2
约束的强度应该随不确定性的下降而提高，而不是一上来就拉满。
在还不知道要做成什么样的时候写详细规格，是用确定性的形式，装不确定的内容。

顺便回答一个很常见的疑问：有了 AI 之后，还需要写单元测试吗？

需要，而且更需要在写实现之前写。原因在第 8、9 章展开，这里先给一句话：

测试是规格中可自动化部分的"可执行版本"。先把能自动化的验收标准写成测试，再让它去实现，能缩小"意图"和"验收"之间的缝隙。但测试本身也需要核对；人工验收项则要明确责任人、方法和通过条件，不能因为无法自动化就被省掉。

本章小结

• 提示词和规格的区别不在长短，在能不能被判定。能被逐条验收的是规格，只能"感觉对不对"的是提示词。
• 规格真正的产出不是文档，是共识。一个说不清楚的规格，暴露的是思考问题，不是沟通问题。
• 规格必须有六件事：问题陈述、成功指标、用户故事、验收标准、非目标、约束。
• "非目标"最常被忽略、也最重要——产品的身份由它的拒绝来定义。
• 粒度看能否独立验证、一次审完；换栈检验只帮助区分需求与实现，需求可以包含明确的技术约束。规格长度随歧义和风险调整。
• 验收标准必须可复核，能自动化的尽量自动化；人工项写清责任人、方法和通过条件。
• 不是所有事都该写规格。约束的强度应随不确定性的下降而提高，而不是一上来就拉满。

对不写代码的人意味着什么

你可以用这一章直接改进提需求的方式。下次给团队提需求时，试着多加两句话：

• "这件做完之后，怎么判断它是对的？"（逼出验收标准）
• "这次不做什么？"（逼出非目标）

第二句话的威力往往比第一句还大。大多数项目的失控不是因为做错了什么，而是因为做多了什么。

行动清单

1. 给你手头这件事从一页规格写起，六项一个都不能少，按歧义和风险补充细节。如果你发现"非目标"那一栏写不出来，说明你还没想清楚边界，先别开工。
2. 用粒度检验题自查：能独立验证、让负责的人一次审完吗？再检查技术细节：确有依据的要求保留为明确约束，可替换的实现选择另列为方案，别把两者混在一起。
3. 把验收标准写成可复核的：能自动化的尽量自动化；人工项写明责任人、方法、通过条件，并保留验收记录。
4. 建立你的"不做清单"：写下三件明确不做的事和理由。下次有人提"加上去吧"，先看这张清单。

延伸阅读

• GitHub Spec Kit——规格驱动开发的官方开源工具包：https://github.github.com/spec-kit/
• Amazon Kiro——规格原生的智能体 IDE（需求 → 设计 → 任务三段式）：https://kiro.dev/
• Anthropic, Building effective agents（2024-12-19）——注意它的核心建议是"用最简单的方案，只在确有必要时增加复杂度"：https://www.anthropic.com/engineering/building-effective-agents
• 附录 B.1 提供了一份可直接复制使用的一页规格模板

第 8 章　一个会停下来的循环

本章承诺：读完这一章，你能说清楚用了 AI 之后，"做一件事"这件事本身的节奏变成了什么样——四个拍子分别该由谁来做、验证为什么要分层、以及什么时候该修、什么时候该推倒重来。

读完后你能回答

• 一个健康的"人机循环"是哪四拍？哪一拍最容易被人偷懒省掉？
• 为什么验证要"分层"？为什么越便宜的验证手段越要往前放？
• 同一个错误改了四五次还没好，该怎么办？

8.1 四拍：意图 → 生成 → 验证 → 判断

用 AI 写代码，和用任何工具都不一样的地方在于：它不是在帮你打字，它是在参与一个循环。

这个循环有四个拍子：

第一拍 · 意图——把想法写成合同。

这一拍的全部产出是共识，不是代码。目标、非目标、约束、验收——都是从第 7 章那张六要素清单里来的（用户故事留给规格文档里写）。而且必须有一条硬规则：

有不确定的地方，先问，不许猜。

这条规则要写进给 AI 的说明里，并且必须是强制的。模型的默认行为是"往前猜"——它会用一个看起来很合理的假设填上你留下的空白，然后一路走下去。猜错的代价，通常要在几轮之后才会暴露。

第二拍 · 生成——唯一的决策是"粒度"。

一次只给一件可以独立验证的任务。这里的判据很实在：

你能一次审查完，并且愿意为它负责吗？

如果一次生成的变更超过四五百行，你的审查质量会明显下降——第 5 章引的那组评审研究给的是"单次不超过 200–400 行"，方向一致；具体阈值随人、语言与代码难度浮动，用你自己的记录确认。

第三拍 · 验证——越便宜的手段越靠前。（下一节展开）

第四拍 · 判断——继续修，还是推倒重来？（8.4 展开）

核心判断 1
用 AI 写代码，不是一个"提要求—拿结果"的动作，是一个四拍的循环。
高手和新手可能用同一个模型、同一个工具，差别只在每一拍的手感。
而四拍里最容易被偷懒省掉的，是第三拍——因为它是最贵的那一拍。

8.2 生成那一步：粒度，和"看不见的变更"

关于生成这一拍，有四条具体的纪律值得记住。

第一条：单一意图。

一次变更只做一件事。不要把"修这个 bug + 顺手改个命名 + 再优化一下那个查询"混在一次提交里。原因很直接：当这次变更出了问题，你要能干净地回滚它。混在一起的变更，回滚的时候会连带撤掉好的改动。

第二条：可控大小。

参考上一节的判据——能一次审查完。如果非要给个数字，我的经验是单次变更不宜超过四五百行。超过这个量，审查就变成了"扫一眼"。

第三条：自包含。

一次变更要自成一体：应用它不需要等另一件没做完的事，回滚它也不会牵连别的改动（这就是第一条说"不要混"的另一半理由）。

第四条：说清为什么。

每次变更都应该是一个完整的故事：改了什么、为什么改、怎么验证。这三样东西，是留给下一个人（也可能是三个月后的你自己）的。

还有一件事必须专门提醒：注意那些"看不见的变更"。

模型在实现一个需求的时候，很容易顺手改一些你没让它改的东西——重命名一个变量、调整一个函数的顺序、给一段旧代码"顺手优化一下"。

在它看来这叫"顺便做点好事"，在你看来这叫"范围蔓延"，而在评审的时候这叫"我读不完了"。

一个几百行的变更，如果里面混着十处与本次任务无关的改动，你的评审效率会明显下降——因为你得逐处判断"这个改动是必要的吗？"

应对方法很朴素：给它的说明里明确写一条"不要改动与本次任务无关的代码"，并且在审查时专门去找这类改动。

一句话讲明白：这一拍的关键不是"让它做得更多"，是"让它做得更少、但你更清楚它做了什么"。

8.3 验证要分层，越便宜的越靠前

这是四拍里最重要的一节。

验证手段有很多，它们的成本和能力差别巨大。正确的做法不是"都用上"，而是按成本从低到高排成一层一层的筛子：

这张表只有一个读法：越便宜的验证手段，越要往前放。验收标准必须可复核，能自动化的尽量自动化；人工项也要写清责任人、检查方法、通过条件，留下可供复核的记录。

道理很简单——如果一个问题能被三秒钟的编译拦下来，你却让它跑到"一小时的人工验收"那一层才被发现，你浪费的不是三秒，是一小时，再加上前面所有人的时间。

把这张筛子建好，有助于改善两件事：

1. 让人把注意力用在更难的问题上。 机器先筛掉它能识别的问题，人再聚焦设计、边界、安全；实际评审质量仍要看缺陷发现与逃逸情况，不能只看流程齐不齐。
2. 让生成与验证相匹配。 如果生成持续超过验证能力，又没有减少生成、丢弃无用变更等消减措施，未验证代码就会积压；第 5 章的概率玩具模型不能用来证明这件事。

还有一条纪律必须写进来：生成者不能认证自己的作品。

如果同一轮对话里，让它写代码、再让它说"我检查过了，没问题"——这个"检查"的信息量接近于零。对抗式验证的价值在于"结构"，不在于"规模"：不是让它检查得更仔细，而是换一个独立的角色、独立的上下文、独立的标准去检查。

评审者从来没有分歧，值得检查，但不等于评审失效：没有违规时，一致通过也可能合理。更可靠的办法是拿已知违规样例独立试评，看能否识别并说明问题，而不是要求评审者为了显得有效而制造分歧。

8.4 修正还是重来

最后一拍。这一拍不会有人跳过，但多数人做到这里就没有方法了——只是反复重试。

问题很具体：你让它改一个东西，它改完还是不对。再让它改，又不对。第三次、第四次……

这时候你该怎么办？

有一个很实用的判据：

如果你能说清楚它为什么失败 → 定点修正。
如果你说不清楚 → 缩小任务，或者重开一个对话。

为什么"重开对话"是有效的手段？ 因为长对话会污染上下文——前面那些失败的尝试、那些已经不成立的假设，会一直留在它的"工作台"上，让它在错误的现场里继续工作。

还有几条经验值，来自我自己的踩坑：

• 连续失败超过你事先定下的那个上限 → 换策略。不要在同一个思路上一路撞下去。问题大概率不在它的实现，在你的任务定义。（这个上限必须写死，不能"看情况"——我自己的经验值是 4 次左右，但每个团队该按自己的场景定；理由见第 9 章。）
• 反馈越慢，耐心消失得越快。 如果一个验证动作要等五分钟，你不会愿意为它多做几次。所以"让反馈变快"本身就是一项工程任务（第 9 章）。
• 缩小任务是最被低估的一招。 当它反复做不对时，把任务切一半、再切一半。很多时候不是它不行，是这件事一次给太大了。

核心判断 2
"修"和"重来"不是两种情绪，是两种判断。
能说清原因就修，说不清就重开——在一件说不清楚的事情上反复微调，是最昂贵的一种拖延。

本章小结

• 用 AI 写代码是一个四拍的循环：意图 → 生成 → 验证 → 判断。第三拍最容易被省掉，也最贵。
• 意图那一拍必须有一条硬规则：有不确定先问，不许猜。猜错的代价会在几轮之后才暴露。
• 生成那一拍：单一意图、可控大小（一次能审完，约四五百行以内）、自包含、说清为什么。
• 警惕"看不见的变更"——它顺手改了你没让它改的东西，会让你的评审效率腰斩。
• 验证必须分层：机械验证 → 测试 → 评审 → 验收，越便宜的越靠前。而且生成者不能认证自己的作品。人工验收要可复核；评审有效性用已知违规样例检验，不能仅凭有无分歧判断。
• 判断那一拍：能说清原因就定点修，说不清就缩小任务或重开对话。连续失败就换策略，别在一件事上反复微调。

对不写代码的人意味着什么

这一章里有一条你可以当天就用的规则：别让做事的人自己验收。

不管有没有用 AI，这条规则都成立。让写代码的人自己说"我测过了没问题"，和让另一个人按事先定好的标准去测，是两种可信度完全不同的验收。

另一个可以观察的信号：评审从不打回、从无分歧，不能单独证明质量好或评审失效。可以追问：用已知违规样例试评过吗，能不能发现问题？没有违规，也可以一致通过。

行动清单

1. 给你的团队定一条硬规则：提交的人必须能解释自己提交的东西。这一条比任何工具选型都重要。
2. 检查你的验证分层：把你现在的验证手段按"秒 / 分钟 / 十分钟 / 小时"排一遍。如果最便宜的那一层是空的，先补它。人工验收写清责任人、方法和通过条件；评审用已知违规样例验证，不靠分歧数量打分。
3. 给"重新来过"设一个触发条件：比如"同一个问题连续失败到你写死的那个上限"（我的经验值是 4 次，可按需调整）。把它写下来，否则你在情绪里做不出这个决定。
4. 做一次"看不见的变更"审计：挑 3 个最近的变更，看里面有多少处改动与本次任务无关。这个比例越高，你的评审越可能是走过场。

延伸阅读

• Anthropic, Writing effective tools for agents（2025-09-11）——工具设计与描述即提示词工程：https://www.anthropic.com/engineering/writing-tools-for-agents
• Anthropic, Building effective agents（2024-12-19）——工作流与智能体的边界：https://www.anthropic.com/engineering/building-effective-agents
• Simon Willison 关于"负责任地用 LLM 写代码"的黄金法则："我不提交任何我无法向别人解释的代码。" https://simonwillison.net/2025/Mar/19/vibe-coding/

第 9 章　让它自己发现错误

本章承诺：读完这一章，你能理解为什么测试在 AI 时代升格了——它不再只是"质量工序"，而是整个协作模式的前提条件。你也会知道该测什么、不该测什么，以及"完成"这个词在 2026 年应该怎么定义。

读完后你能回答

• 为什么说测试是 AI 协作的前提条件？
• 测试金字塔在 AI 时代为什么变得更陡？发布验收为什么不能只依赖模拟对象？
• 它写的测试常常"看着完整、其实什么都没验"——怎么避免？

9.1 测试从"质量工序"变成"生产设施"

先说一个判断：

在 AI 时代，测试的重要性不是"上升了一点"，而是换了身份。

以前，测试是"质量的守门人"——它在开发流程的末端，负责把不合格的东西拦下来。它很重要，但它是流程的最后一环。

现在，测试变成了生产设施——它是机器能跑起来的前提。理由有三个，每一个都足够重要：

理由一：测试是智能体的"行为合同"。

模型是靠读代码来理解你的系统的。但代码能表达"这里有什么"，不能表达"这里应该有什么"。

没有被测试有效断言覆盖的行为，在它眼里就是"没有定义的行为"——覆盖到不等于验到。于是它按最合理的方式猜——然后某天你在生产环境里发现，它把"订单取消"的券退回规则，猜成了另一个样子。

理由二：测试是它的"自我反馈回路"。

智能体能自己修 bug，靠的是什么？靠的是"写完 → 跑测试 → 读报错 → 再改"这个循环。

没有测试，这个循环就断了。它只能一直写、一直说"我完成了"，而你没有任何机器手段去反驳它。它就从"能自我纠错的智能体"，退化成一个"喋喋不休的生成器"。

理由三：测试是"人"的前置过滤器。

第 8 章讲过验证分层。测试这一层的价值，是把缺陷拦在最贵的那一层（人的评审与验收）之前，让人只看"机器审不出的问题"。

核心判断 1
没有测试的代码库交给智能体，等于让一个能力极强、却完全没有听觉的工程师，在噪音里工作。
没有测试，它无法验证自己的产出；无法验证，就只能靠猜；靠猜，你得到的不是工程，是运气。
测试不是安全网，是地基。

9.2 测什么：金字塔变得更陡了

测试金字塔这个概念不新：底层是大量的单元测试（快、便宜、定位准），往上集成测试，最顶层是端到端测试（慢、贵、但最接近真实）。

在 AI 时代，这个金字塔变得更陡了——底层的比例应该更高。原因有两个：

1. 单元测试可以大批量生产。 让 AI 写单元测试，是它最擅长的事情之一（因为它写的是"通用模式"，不是"你的项目事实"）。
2. 底层测试反馈最快。 第 8 章说过——反馈越慢，你越不愿意为它多跑几次。而智能体的自我修复循环，极其依赖反馈速度。

三条具体的纪律：

第一，发布验收不能只依赖模拟对象。

"模拟对象"（mock）是在测试里替代外部依赖的技术。它不只能模拟成功，也能注入超时、权限拒绝、错误响应，让难以复现的故障变得可测试。它的局限在于：不能仅凭模拟，证明我们对真实依赖的假设是对的。

所以：保留模拟测试，并为关键链路补上真实依赖集成验证。要核对的是网络、权限、时区、数据格式、编码等实际行为，是否与测试里的假设一致，而不是在发布前把模拟测试关掉。

第二，警惕"模板化测试"。

这是 AI 时代的新问题。你让它写测试，它能很快给你一堆覆盖了所有函数、所有分支、全部通过的测试。但那些测试可能什么都没验证——比如断言了"函数返回的不是 null"，而真正该断言的是"返回的金额算对了没有"。

判据很简单：把这条断言本该守住的行为改坏，测试会不会红？ 如果改坏了它该守的东西还是绿的，这条断言就是装饰品。一处改坏不红不足以否定整套测试，要逐个断言看。

第三，把"连续失败"制度化。

智能体会反复尝试同一个错误思路。所以需要一条硬规则：连续失败到某个次数 → 强制人工介入。这个次数由你自己定，但它必须是写下来的一个具体数字，不能是"看情况"。

为什么要把这个阈值写下来？ 因为不写下来，"再试一次"的冲动会永远赢。把经验阈值变成制度，是让人在不理性的时候仍然能做理性决定的方法。

数据卡 · 一个必须记住的方向

AI 生成的代码功能正确性在改善，但安全表现没有同步改善（Veracode 所测样本 45% 未通过安全测试——这是未通过率，不要换算成通过率）。（详见第 12 章）
含义："测试通过"和"安全"是两件事。测试是必要条件，不是充分条件。
所以本书的"完成"定义里，测试只是第一项。

9.3 版本控制不只是时光机

大多数人把版本控制理解成"代码的时光机"——出错了能回退。这个理解不算错，但对 AI 协作来说，它远远不够。

版本控制在 AI 时代有三个额外的作用：

作用一：它是唯一可靠的"变更单位"。

第 8 章说"单一意图、可控大小"。这件事只有在版本控制里才能被真正执行——一次提交一件事，出问题时才能干净地回滚。

作用二：它是智能体的"记忆"。

模型没有跨会话的记忆。它理解"这个仓库为什么长成这样"的唯一途径，就是读提交历史、读决策记录、读目录结构。

所以每条提交信息都是一份资产。"fix bug"这三个字，对三个月后的你和对下一个 AI 会话，价值都是零；而"修复订单导出在筛选条件为空时导出了全部数据的问题，原因见 #142"，价值很高。

作用三：检查点（checkpoint）让"试错"变得安全。

有了检查点，"走错路"的成本变得极低——随时可以退回来重新走。这一点直接改变了工作方式：以前你会在一件事上反复推敲，因为"改错了很麻烦"；现在你可以先走一步看看，不行就退回来。

这正好呼应了第 6 章说的第三层变革——"可能性解放"之所以成立，前提之一就是试错的成本被压到极低。

三条实践纪律：

1. 小步提交。提交越频繁，回滚粒度越细。
2. 提交信息说清"为什么"。"改了什么"代码自己会说，"为什么改"只有你会说。
3. 每个检查点必须处于"可工作状态"。测试要能跑、要能通过。一个坏掉的检查点，比没有检查点更糟——因为你以为你能退回到那里。

9.4 "完成"的新定义

最后一节，给一个可以直接用的定义。

完成 = 测试通过 + 真实链路验证 + 过程留痕。

三项缺一不可，逐项说：

第一项：测试通过。必要，但不充分（见 9.2）。

第二项：真实链路验证。在经授权的隔离环境中，使用代表性数据，连接真实依赖走通关键路径；数据可以是合成的，或经批准脱敏的。这不是要求直接访问生产环境或使用生产原始数据。这一项最常被跳过，因为它最麻烦。而事故恰好最喜欢住在"单测全绿、真实依赖假设未核对"这个缝里。

第三项：过程留痕。留下了什么？规格、决策记录、提交信息、测试、门禁结果。留痕的价值不止于合规——它是让下一个 AI 会话（和下一个同事）能接手的唯一途径。

顺便说一个我在自己项目里发现的规律：如果一件事没有留痕，那么它大概率会在未来的某一次会话里被重新讨论、甚至被反向实现。因为新的会话不知道你之前已经做过决定了。

核心判断 2
"完成"不是一个感觉，是一个可以被人和机器共同验证的状态。
三项里最容易省的是第二项——而事故就住在那里。

本章小结

• 测试在 AI 时代换了身份：从"质量工序"升格为"生产设施"。它是智能体的行为合同、自我反馈回路、以及人的前置过滤器。
• 没有测试就交给智能体，等于让它在一个没有听觉的世界里工作。
• 测试金字塔变得更陡（底层比例更高）：单元测试可以批量生产，而且反馈最快。
• 三条纪律：发布验收不能只依赖模拟对象 · 警惕"模板化测试"（改坏实现测试还绿的就是装饰品）· 把"连续失败到某个次数"制度化。保留模拟故障测试，用关键链路的真实依赖集成验证核对假设。
• 版本控制有三个额外作用：变更单位、智能体的记忆、让试错变安全。
• 完成 = 测试通过 + 真实链路验证 + 过程留痕。真实链路验证使用经授权的隔离环境与代表性数据，不等于直接上生产。

对不写代码的人意味着什么

这一章给你一条可以写进合同的话：

"什么叫做完？"

如果一个团队的回答是"功能能用了"，那这个答案不够。你可以要求他们给三样东西：

1. 测试报告（不是测试数量，是通过/失败的具体结果）；
2. 关键链路连接真实依赖的验证记录（标明经授权的隔离环境、代表性数据及结果，截图和日志须脱敏）；
3. 这次决定的记录（为什么这么做、有什么取舍）。

三样都能给，说明这个团队的工程习惯是可以托付的。

行动清单

1. 做一次"装饰品测试"抽查：随机挑 3 个测试，故意把一个被测试的函数改坏，看测试会不会红。不会红的，删掉或重写。
2. 把"连续失败到约定的次数就强制人工介入"写进你的协作文档（附录 B.2 的骨架里已经预留了这一条）。
3. 检查你的"完成"定义：测试通过、真实链路验证、过程留痕。保留模拟测试，在经授权的隔离环境中用代表性数据补关键链路的真实依赖集成验证。看哪一项最容易被省掉——那里就可能藏着风险。
4. 给一个季度前的提交做一次信息质量抽查：如果大部分提交信息是"fix bug""update"，那就从今天开始改。

延伸阅读

• Kent Beck 关于测试驱动开发的经典论述（测试是设计工具，不只是验证工具）
• Dan North, Introducing BDD——验收标准如何写成可执行的句子
• 关于"安全表现未随功能正确性同步改善"的具体数据（45% 为未通过率），见第 12 章与附录 A
• 附录 B.3 提供了一份可直接落到持续集成里的门禁清单

第 10 章　别让它把代码库越写越烂

本章承诺：读完这一章，你能理解为什么"AI 让复制比复用便宜"不是一件小事，能认出一种比技术债更隐蔽的债，也能学会用最省力的办法控制复杂度——把"人要记住的规则"变成"机器拦得住的约束"。

读完后你能回答

• 为什么用 AI 之后，代码重复会明显上升？它的机制是什么？
• 什么叫"认知债"？为什么它比技术债更危险？
• 怎么把一条纸面上的规范，变成一道真的会拦人的门禁？

10.1 一个反直觉的发现：复制比复用便宜

先看证据。

代码分析机构 GitClear 追踪了 2020 年至 2024 年间 2.11 亿行代码变更（数据来自 Google、微软、Meta 以及一批企业级项目的仓库），专门看一件事：AI 参与写出来的代码，在可维护性指标上和之前有什么不同（https://www.gitclear.com/ai_assistant_code_quality_2025_research ）。

结果出现了三个同时向右（或向左）移动的信号：

为什么会出现这个现象？

GitClear 的 CEO 把机制说得很直白："每当你想做一件事，AI 就为它新建一个包。对模型来说复制很便宜，找到已有函数并复用它则不便宜。"

这句话值得慢读一遍。

从模型的角度看"复制"和"复用"：

• 复制：它只需要看当前这个文件，写一段满足需求的代码。上下文小、成功率高。
• 复用：它需要先知道"这个功能以前有人写过"，然后在整个仓库里找到那个函数，理解它的接口、它的边界情况、它有哪些隐含假设，然后决定能不能用。上下文大、失败率高。

所以它选择了对它更便宜的那条路——这不是它偷懒，这是它在当前信息条件下的理性选择。

那怎么办？ 不能靠"提醒它要复用"（第 12 章会说，靠指令的约束效果很弱）。要靠两件可操作的事：

1. 让"找到已有实现"这件事变便宜。 清晰的模块边界、可检索的函数命名、一份说明"什么能力已经存在"的索引——这些都是在降低复用的成本。
2. 让"复制"这件事变成可见的。 用重复代码检测工具按月追踪"新增代码中复制已有代码的比例"。这通常是恶化较早、监测成本最低的信号之一（一条持续集成任务就能出图）。

⚠️ 一条必须标清楚的引用纪律：上图引用的是同一分析机构的另一份追踪数据（2023–2026 年、6.23 亿次变更），与本节正文引用的那份（2020–2024 年、2.11 亿行）数据集与口径都不同，两者不可互相换算、不可横向比较。上图来源属于 B 类行业报告，但具体幅度本书未做独立核实，完整抽样与指标定义也未核到。类别不表示核验通过，不能因为方向相似就把两组数字混着用，或单独归因于 AI。

核心判断 1
AI 让"复制"比"复用"便宜——这是它最需要被工程手段纠正的一个倾向。
而且它最危险的地方在于：它不会立刻出问题。代码当天就能跑，问题在半年后你改一处、发现还有七处的时候才显现。

10.2 技术债的孪生兄弟：认知债

先补一个老概念。

1986 年，Fred Brooks 写过一篇很有名的文章《没有银弹》。他在里面把软件的复杂性分成两种：

• 本质复杂度：这件事本身就这么难。（比如"航班调度要同时考虑天气、机组工时、机场容量"——这是问题自身的难度，删不掉。）
• 偶然复杂度：由工具、语言、流程造成的额外难度。（比如"这个框架的配置文件语法很怪"——这是可以消除的。）

AI 能降低处理偶然复杂度的成本——它能飞快地写好样板代码、配置文件、胶水逻辑，但没有消除业务本身的难度。第 10.1 节提醒我们注意另一面：重复实现与无谓耦合会堆积可避免的实现复杂度，这仍属于偶然复杂度，不是本质复杂度增加。代码生成得更快，不代表团队理解它的速度也跟得上。

于是产生了一种新的债：

定义 · 认知债（cognitive debt）
团队对系统的真实理解，与系统实际有多复杂之间，正在扩大的那道裂口。

它和技术债的区别在哪？

认知债为什么更危险？因为它没有报表。技术债至少还能用"代码异味""圈复杂度"这类指标扫出来；而认知债住在人的脑子里——你不问，就永远不知道它有多严重。

一个极其便宜的自检方法（我在第 5 章的行动清单里已经提过一次，这里再提一次，因为它是全书最便宜的诊断）：

写下三处"没人敢动的代码"，以及原因。

这份清单比任何覆盖率报表都更能说明你的真实风险在哪。如果一份清单都写不出来——那可能不是因为没有风险，而是因为大家已经习惯了绕开它。

10.3 界面的力量：深模块与信息隐藏

好，问题摆完了。这一节给一个真正能用的办法。

控制复杂度最有效的武器，不是"写得更仔细"，是"把复杂度关进盒子里"。这个思想很老，但它在 AI 时代变得比以往任何时候都重要。

1972 年，David Parnas 提出了一条原则：模块划分的依据应该是"它隐藏了什么决定"，而不是"它做了什么"。（On the Criteria To Be Used in Decomposing Systems into Modules）

用更直白的话说——一个模块的价值，在于它替世界挡掉了多少东西。

浅模块是：宽接口、薄实现。你调用它比看懂它还费劲——它没有挡掉任何东西，只是把复杂度搬到了调用者面前。

深模块是：窄接口、厚实现。一行调用背后藏着上千行的机制。使用者只需要知道一个函数签名，就换回了一整个被隐藏的世界。

判断好坏的标准只有一句：接口与实现的比例。

为什么这件事在 AI 时代变得关键？ 因为智能体是"模块化"最敏感的读者：

第一，模块是它的上下文锚点。

面对一个百万行的仓库，智能体通常的做法是"先定位相关模块，再只读相关代码"。模块边界清晰，它就能定位得准、读得少、改得对；边界混乱（比如一个文件三千行），它就更可能漏改或误改。

第二，模块是它的施工围挡。

接口写清楚了（参数语义、错误约定、不变式），它生成的新代码才"插得进"现有系统而不破坏它。窄接口等于给它画好了施工范围。

第三，模块边界是并行协作的基础。

第 1 章讲过，智能体集群的第一步是"各占一个工作区"。共享工作区里编辑同一文件可能互相覆盖；用隔离分支和独立工作区（worktree），同一文件的改动也可以合并。反过来，不同文件也可能因接口、状态约定不一致而发生语义冲突。按文件切分只是一种分工方式，不是模块化的定义。并行协作真正需要的是明确的依赖边界、接口约定与变更归属，以及合并后的集成验证。

核心判断 2
模块化从"好习惯"升格为"生存技能"。
要减少不必要的复杂度，也要把必要的复杂度收纳进模块边界。在 AI 时代，这条边界同时影响三件事：智能体读得准不准、改得对不对、以及团队并行协作的成本。

10.4 把"人要遵守的规则"变成"机器拦得住的约束"

最后一节，讲这本书里我认为最实用的一条工程方法。

先看一个我在自己项目里观察到的现象。到第 100 天为止写下的那 100 篇日志里，有一个很清晰的变化：

治理工作是"晚发"的。在前 48 天，治理类工作只出现在 7 天里；在后 52 天，出现在 20 天里。而方法论/规则类的工作，前 48 天里出现过 1 天、后 52 天里出现过 5 天。

换句话说：先建设，撞了墙，才长治理。这不是设计出来的路线图，这是踩坑踩出来的。

而这些治理的载体，走过了一条很固定的路径：

口头提醒  →  文档  →  检查清单 / 操作规范  →  机器门禁（提交钩子 / 测试 / 构建 / 流水线）

每往下沉一级，违规的成本就从"靠自觉"变成"被阻断"。

这里有一个非常实际的换算公式，我在自己的项目里验证过：

一份 40 行、真的会拦人的脚本，比 40 页"请遵守规范"更有效。

为什么？因为文档的作用是"让人知道"，而门禁的作用是"让人必须做"。知道和做到之间，隔着一整个意志力。

而且门禁有一个文档永远没有的好处：它会产生数据。

一条门禁被执行了多少次、拦下过什么、误报过几次、什么时候该废止——这些都是可以被记录、被分析的事实。而"大家有没有遵守规范"，往往只能靠抽样与回忆。

但门禁不是终点。我在第 100 天遇到的失败恰好说明了这一点：门禁的规则本身会过宽、过时、或者和新的重构冲突。我必须说清这件事的边界：

• 我自己那套"由门禁驱动的治理回环"，每一次回环都还是靠人手动发起的。它不是一个自适应系统。
• 它只覆盖开发期，不覆盖运行期。项目虽然建了持续集成和监控，但没有经历过真实的生产流量、服务等级目标和线上事故的检验。

一个微案例：告警降了，门禁没收紧。

我把告警数从 902 降到了 132，但门禁基线仍是 902。这是已记录的事实，不是一个已经完成的治理闭环。它暴露的问题是：计数口径不变时，清理后新增的告警仍可能被旧基线放行。AI 能完成局部清理，不等于它会主动收紧门禁；人仍要发现这道缺口，决定新基线取值与例外条件。

方法演示（建议补齐，非已完成记录）：先用相同扫描配置与范围复核清理前后的计数；若 132 可重现，再评审是否把基线收紧到 132。随后跑清理后的功能回归，确认行为未退化、正常版本能通过；再在隔离分支加入一条检测器能识别的告警，构造 133 超过 132 的反例，确认门禁确实阻断，而不只是输出提示。这里没有声称这些修正和测试已经完成。剩余的 132 条告警仍需分级处理，计数下降也不能排除漏检，更不能代替生产验证。

核心判断 3
没有违规时，零命中也可能是有效控制；有命中，也不代表风险已被完整覆盖。
治理的检验标准不是"我们有多少条规范"，而是"当前风险覆盖了吗，已知违规样例能拦住吗"。

本章小结

• AI 让复制比复用便宜。 2.11 亿行变更的追踪显示：复制粘贴从 8.3% 升到 12.3%，重构/搬移类变更从 25% 降到不足 10%，重复代码块出现约 4 倍增长，历史上第一次"复制粘贴"超过了"搬移"。
• 机制很朴素：对模型来说复制便宜，找到已有函数并复用它不便宜。纠正它要靠"降低复用的成本 + 让复制变可见"，不能靠"提醒它"。
• 认知债是技术债的孪生兄弟：技术债是"代码不好但看得懂"，认知债是"代码没问题但没人敢动"。它没有报表，最便宜的自检是写下三处"没人敢动的代码"。
• 深模块（窄接口、厚实现）把必要的复杂度收进清晰边界。模块化不等于按文件分工；并行修改要约定依赖与接口，并在合并后验证。
• 治理下沉有一条固定的路径：口头 → 文档 → 清单 → 机器门禁。一份 40 行会拦人的脚本，胜过 40 页规范。
• 但门禁不是终点：阈值需要复核，用已知违规样例验证控制，零命中不等于失效。我这套回环仍由人发起、只覆盖开发期，尚未经生产验证。

对不写代码的人意味着什么

这一章给你一条看团队成熟度的捷径：

问一个问题——"你们有没有哪条规范，是机器强制执行的？"

• 如果答案是"我们有很多规范文档"，那说明治理还停在"靠自觉"这一层；
• 如果答案是"有这么几条，跑在流水线上，违反就提交不了"——这个团队的工程化水平是可信的。

另一个可以问的问题："上个月门禁执行了吗？用已知违规样例验证过它能拦住问题吗？" 实际命中是证据之一，但没有命中不等于失效，也可能是没有违规。

行动清单

1. 把重复代码的追踪挂进持续集成：按月输出"新增代码中复制已有代码的比例"。这是可维护性信号里恶化较早、成本最低的一项。
2. 选一条纸面上的规范，把它变成门禁。用正常样例验证能通过，再用已知违规样例验证会阻断。下周再选第二条。
3. 写下三处"没人敢动的代码"及原因，贴在团队能看到的地方。
4. 给每一条门禁写三件事：它拦什么、什么情况可以例外、什么条件下该废止它。退役须有依据：风险已消失、适用范围改变而不再适用，或已有经验证的等效控制；无人维护、长期无命中或无大变更都不是撤销理由。
5. 检查你有没有"过期的阈值"：复核基线与现状是否同一口径，评审是否收紧，再用回归和超阈值反例验证，别只改一个数字。

延伸阅读

• GitClear, AI Copilot Code Quality: 2025 Look Back at 12 Months of Data（2.11 亿行变更）：https://www.gitclear.com/ai_assistant_code_quality_2025_research
• Fred Brooks, No Silver Bullet — Essence and Accident in Software Engineering（1986）——本质复杂度与偶然复杂度的出处
• David Parnas, On the Criteria To Be Used in Decomposing Systems into Modules（1972）——信息隐藏原则的出处
• John Ousterhout, A Philosophy of Software Design（2018）——"深模块"概念的出处
• Michael Nygard, Documenting Architecture Decisions（2011）——决策记录是智能体时代最重要的文档形式之一：它记录的是"为什么"，而"为什么"是模型自己永远推不出来的部分

第四篇　建起来：模型之外决定成败

第 11 章　模型只是发动机，不是整台车

本章承诺：读完这一章，你能回答一个很实际的问题——为什么同一个模型，在别人手里是生产力，在我手里是负债？ 你会知道决定成败的东西很大一部分在模型之外，也知道该往哪里投入。

读完后你能回答

• "模型 + 运行时"这个说法，具体指哪些东西？
• 上下文为什么不是"装得越多越好"？该装什么？
• 为什么模型每次升级，你都应该做一次减法审计，而不是只加东西？

11.1 同一个模型，为什么在别人手里是生产力

先看一个现象。

2026 年，有两批人在用同一个模型、同一个版本的权重。A 组的任务成功率是 12%，B 组是 92%。（这是一组示意性的对比，先把差距摆出来；有出处的数据在 11.2。）

差别不在模型里。 模型的权重一个字节都没变。

差别在模型外面那一圈东西——它决定模型怎么被调用、能看到什么、能用什么工具、出错怎么处理、权限怎么收、什么时候该停。

这一圈东西有一个名字：harness（运行时外壳）。

定义 · harness
模型外面的那一整套工程设施：上下文怎么组装、工具有哪些、权限怎么控制、失败怎么重试、结果怎么验证、人从哪里介入。
一个类比：模型是发动机，harness 是整台车。发动机决定动力上限，但能不能开、开去哪、会不会翻车，取决于底盘、方向盘、刹车和安全带。

有一个等式在 2026 年被广泛引用：

智能体 = 模型 + harness

⚠️ 一句必须写清楚的说明：这个等式不是某家厂商的官方说法，它是社区对各家工程实践的归纳。Anthropic 官方文档里把 Claude 的运行时称作 "the agent harness that drives Claude Code"（驱动 Claude Code 的那个 harness），OpenAI 的 Codex 团队也把"非模型的基础设施"称为 harness——但"等于"这个等式本身，是行业总结，不是官方定义。

为什么要强调这一点？ 因为这本书的引用纪律是：谁说的就是谁说的。把一个社区归纳说成厂商原话，是这类技术书最常见、也最容易被抓的一种不诚实。

11.2 两组研究数据

这一节给两组数据。第一组是组件级受控研究，第二组是模型厂商工程团队的成本披露；两者的任务和口径不同，不能混成一个通用结论。

第一组：一项组件级受控实验。

2026 年 9 月 17 日，一篇论文（Fan et al., An Empirical Study of Harness Design for Coding Agents, arXiv:2609.20804, https://arxiv.org/abs/2609.20804 ）做了一件很干净的事：把执行循环固定住，只变动三个组件——规划、动作空间、上下文管理，在四个模型上跑了 176 组匹配配置，任务是 SWE-bench Verified 和 Terminal-Bench 2.1。

它的四条结论，每一条都在推翻一个常见假设：

这四条里有一个共同的形状，值得单独拎出来：同一种 harness 设计，对不同能力的模型效果不同。这就是为什么"照抄别人的配置"常常不好用——你得按自己的模型和任务去配。

真正可复用的方向是对照评估，不是给模型与 harness 排一个固定的影响倍数。固定模型与任务，比较不同运行时配置；再固定配置，比较模型。成功率和成本一起记，才能知道投入该往哪里放。

第二组：成本结构。

一项来自模型厂商工程团队的多智能体研究披露了一个反直觉的观察：单智能体消耗的 token 约是普通对话的 4 倍，多智能体系统约是 15 倍（Anthropic, How we built our multi-agent research system, 2025-06-13, https://www.anthropic.com/engineering/multi-agent-research-system ）。

这条数据的正确读法是：多智能体不是免费的，它用 token 换覆盖面。所以在"任务之间耦合紧密"的场景里（比如改同一个模块），拆成多个智能体往往是亏的；只有在"可以真正并行、各自独立取证"的场景里才划算。

核心判断 1
模型层正在商品化。 同一批前沿模型会在几天内出现在几乎所有编码工具里——"我支持最新的模型"已经不再是差异化。
两处投入都要看：你选得多准，以及你把模型围得多好。
哪一处更值得投入，要用自己的任务对照评估，不能预先排定高下。

11.3 上下文是一张工作台，不是仓库

第 2 章讲过：上下文窗口像模型这次工作的工作台。模型有训练形成的参数知识，但未提供的项目资料和最新状态，不会自动成为这次回答的依据；需要放入上下文，或通过工具取回。

所以"往上下文里放什么"就成了一个核心工程决策。这门手艺有个名字：上下文工程。

定义 · 上下文工程（context engineering）
策划并维护模型在推理时应该看到的那一组 token 的策略。
它和"提示词工程"的区别是：提示词工程关心怎么问，上下文工程关心它眼前有什么。

四件可以照着做的事：

第一件：给仓库写一份"说明书"。 根目录放一个文件（业界通用的名字是 AGENTS.md），大约一百行，说明：技术栈、目录约定、构建与测试命令、禁区。

关键在"索引"这两个字——它是目录，不是百科全书。 太长的单体指令容易混入无关信息，精简索引更便于按需查找；但文件是否加载、适用哪一级目录，取决于工具实现，短并不保证每次都会读到，重要约束须确认实际加载。

AGENTS.md 目前已经是一个开放、通用的约定，被多家工具原生支持（https://agents.md/ ）。

第二件：渐进式披露——索引常驻，正文按需。

这是最省 token 的一个设计：常驻上下文里只放极简索引，完整定义在匹配到的时候才加载。

一个反例很能说明问题：工具描述本身是要占上下文的——挂得越多，模型花在"记工具名"上的注意力越多。

第三件：把经验做成资产（技能）。

把你团队"怎么做评审、怎么做分析、怎么套模板"这类方法，封装成标准的能力包。新成员、新项目直接加载复用。

这一步的意义在于：经验从"个人提示词手艺"变成了"可继承的工程资产"。

第四件：记忆与压缩——长任务的生存术。

自动摘要压缩是有损的。被丢掉的细节，可能恰好是后面需要的那条。更好的方案是：在窗口之间维护结构化的笔记，需要细节时再去检索原文。

从"压缩"升级到"笔记 + 检索"，是记忆问题的工程化。

还有一个长任务的失败模式要单独记住：上下文焦虑。

模型接近上下文上限时，可能提前收尾——把没干完的活包装成"已完成"交给你。这是需要检查的失败模式，不是必然行为。

多小时的长任务，可以比较"重置上下文 + 结构化交接"与"就地压缩"，不预设哪一种更好。

• 就地压缩：保留同一任务的摘要与状态，但可能丢失细节。
• 重置 + 交接：换一张干净的桌子，明确写下进度、约束与下一步；也可能漏掉交接单没有记下的依赖。

选择取决于交接质量和后续任务对历史细节的依赖。用相近任务比较遗漏、成功率与恢复成本，再决定；需要细节时回查原始记录。

11.4 一条反直觉的纪律：模型升级后要做减法审计

最后一节，讲一个大多数人不会做的事。

当模型升级时，绝大多数团队的做法是"加东西"——加工具、加规则、加检查步骤、加提示词。因为"新模型更强了，我们应该能做更多事"。

而值得先做的动作经常是相反的：检查哪些东西可以退役。注意，是审计，不是预设答案的删除。

为什么？因为你现在 harness 里的很多东西，是为了补上一代模型的短板而加的。当短板被补上，那些补丁可能变成额外成本——多花 token、多绕一圈、多一个可能出错的地方。但旧组件也可能在新模型上产生另一种收益，不能凭"模型更强了"就判它无用。

上面那篇论文给了三个具体的对照评估方向：

• 规划：较强模型开启规划也可能更省钱，较弱模型还可能获得明显的成功率提升。不能把这项研究读成"换强模型就删规划"；
• 预定义工具：如果模型 bash 能力够强，只用 bash 可能更便宜，但要在自己的任务和权限边界内比较；
• 可找回的被删减内容：研究中模型几乎不用它，也没带来准确率提升，可以列为退役候选，仍要验证自己的任务是否依赖它。

怎么比较？固定模型版本、任务集、预算和验收标准，每次只开关一个候选组件，对照记录任务成功率与成本。先约定可接受的成功率下限，再看是否节省成本；只有对照结果支持，才决定保留、替换或删除。安全门禁也不能因为短期成本下降就直接撤掉。

我自己的项目里也有一个同向的观察：那 155 天里，我的规则是只增不减——四个版本的修订全是"增补"，我从来没有定义过一条规则该怎么退役，也从来没有度量过治理本身的开销。

这是一个明确的自证缺陷。一条只会增加的规则体系，迟早会变成负债。

核心判断 2
换模型时，先做一次减法审计。逐条问：这一条是为了补上一代模型的哪个短板加的？那个短板还在吗？它是否还有别的收益？
退役候选要在同一组任务上做开关对照，同时测成功率和成本，再决定去留。
加东西是默认行为，拆东西需要纪律。纪律不是逢升级必拆，而是不让组件未经评估就永久留下。

本章小结

• 模型是发动机，harness 是整台车。"智能体 = 模型 + harness"是社区归纳，不是厂商官方定义——引用时必须说清。
• 一篇 176 组匹配配置的受控实验给出四条结论：上下文管理在预算紧时价值最大（收益主要来自防溢出）· 规则式删减放在模型摘要前更有效率 · 规划的收益因模型而异 · 预定义工具不是越多越好。其中，SWE-bench 上两款较强模型开启规划后成本分别降低约 30%、32%，Nemotron-3 30B 成功率提高 11.6 个百分点，不能据此推出删除规划省钱。
• harness 值得投入，但投入方向要靠任务级对照评估，不能用一个固定倍数替代判断。
• 多智能体不是免费的：单智能体约是普通对话的 4 倍 token，多智能体约 15 倍。它只适合"能真正并行"的任务。
• 上下文工程四件事：仓库说明书（索引不是百科）· 渐进式披露 · 经验资产化 · 笔记加检索。
• 长任务里：比较重置交接与就地压缩的遗漏、成功率和恢复成本，再选策略；两者都不能替代原始记录。
• 模型升级后先做减法审计。针对候选组件做开关对照，同时看任务成功率和成本，再决定去留；不要预设删掉就能省钱。

对不写代码的人意味着什么

这一章给你一个投入方向的判断：如果一个团队说"我们要上 AI 编码"，而他们的投入全部花在"买最好的模型"上，那这个投入大概率是低效的。

值得花钱的地方是：

• 把知识写进仓库（让模型能读到它需要的事实）；
• 把规则变成门禁（让错误在机器那一层被拦住）；
• 给人留出评审的时间（这是最容易被砍掉的预算）。

一个很实用的提问："如果模型明天换了，哪些投入还能复用，哪些要重新评估？"能复用的知识、门禁和评审方法是资产；具体的运行时配置仍要用任务验证。别只问"删了多少组件、少花多少 token"，还要问："同一组任务，成功率和成本分别怎么变了？"

行动清单

1. 给仓库加一份 AGENTS.md：控制在一百行以内，写成索引（技术栈、目录、命令、禁区）。如果你写不出来，说明你的项目知识还只在人脑子里。
2. 做一次 token 体检：把你常驻上下文里的东西列出来，找出那些"每次都带、但其实用不上"的部分，删掉。
3. 给长任务加一份"交接单"模板：上一班干到哪、下一步是什么、已知的坑有哪些、原始记录在哪。用相近任务对照重置交接与就地压缩，比较遗漏、成功率和恢复成本，不默认替换。
4. 安排一次"减法审计"：把你 harness 里的每一条都问一遍"它是为了补哪个短板加的，还有没有别的收益"。选出候选组件，固定模型与任务，每次只开关一项，同时记录成功率和成本，达到事先约定的验收条件再决定去留。

延伸阅读

• Fan et al., An Empirical Study of Harness Design for Coding Agents（arXiv:2609.20804, 2026-09-17）：https://arxiv.org/abs/2609.20804
• Anthropic, Effective context engineering for AI agents（2025-09-29）：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Anthropic, How we built our multi-agent research system（2025-06-13，含多智能体 15 倍 token 的成本披露）：https://www.anthropic.com/engineering/multi-agent-research-system
• Anthropic, Writing effective tools for agents（2025-09-11）：https://www.anthropic.com/engineering/writing-tools-for-agents
• AGENTS.md 开放约定：https://agents.md/

第 12 章　当它开始动手：安全到底怎么回事

本章承诺：读完这一章，你能明白 AI 编码的安全问题和以前有什么本质不同，能知道三件绝对不能讲错的事，也能看懂为什么"叮嘱它一句别乱来"根本不管用——以及该用什么替代。

读完后你能回答

• 为什么代码漏洞之外，还要管权限与执行风险？
• 模型变强，是否就意味着生成代码更安全？
• 为什么"提示注入"没法靠加一句指令解决？

12.1 攻击面不只在代码里

先说一个容易算错的账。

假设你的团队用 AI 之后，代码产出变成了三倍。安全风险也会变成三倍吗？

只有在缺陷密度不变、任务和代码量统计口径可比等条件下，三倍代码量才对应三倍的潜在缺陷数量期望。这不等于攻击面变成三倍。

代码产出增加，验证也得跟上。

下面看一组厂商测试结果。这份报告没有人类开发者对照，不能据此说 AI 写代码比人更不安全。

第一组数据：该厂商样本中，安全表现未随模型能力同步改善。

安全厂商 Veracode 在 2025 年 7 月 30 日发布了一份报告（2025 GenAI Code Security Report, https://www.veracode.com/blog/genai-code-security-report/ ）。他们用 100 多个大语言模型，在 Java、Python、C#、JavaScript 四种语言上做了安全测试。该报告的样本结果：

报告对所测样本的观察可以概括为：

功能正确性在改善，安全表现却没有同步改善。

这提醒我们：不能把"模型更聪明"当成安全保证。但结果受测试任务、模型与语言样本、扫描器检出能力限制，不能直接推广到所有生产代码；没检出，也不等于没有漏洞。

这些观察说明不了所有模型的训练目标，更不能单凭它们认定安全缺陷的根因。实际项目仍要按自己的业务场景做安全验证。

第二组数据：编造依赖。

第 2 章讲过"幻觉依赖"——模型安装一个名字几乎正确、实际不存在的包。这件事有多普遍？

一项获得 USENIX Security 2025 杰出论文奖的研究（Spracklen et al., We Have a Package for You!, https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen ）做了这个测量：16 个用于代码生成的大模型、两组提示数据集、57.6 万个代码样本、两种编程语言。结果：

为什么要紧？因为攻击者可以提前把这些虚构的包名注册下来，塞进恶意代码。等你（或者你的智能体）下次照着模型推荐去安装的时候——它装到的是一个真实存在、但属于攻击者的包。这类攻击有个名字：slopsquatting（蹭幻觉包名）。

更麻烦的一点是：仅靠已知漏洞库，依赖扫描不能可靠识别新恶意包。包真实存在、不在漏洞库里，都不等于它可信。

定义 · 攻击面扩展
"代码里有没有漏洞"仍然要管；智能体能动手后，又多了"权限给多了没有、执行会不会越界"这一层风险。
一个会编造的聊天机器人，最多给你一个错误答案；一个会编造、并且有权限动手的智能体，可以改错资源、删错数据、把数据发出去。

12.2 三件不能讲错的事

这一节的口气会硬一点，因为这三句话只要讲错一句，后面整套防御就建在了错误的前提上。

第一件：不要写"模型越新越安全"。

Veracode 报告中，45% 是所测代码样本未通过安全测试的比例，不是所有 AI 代码的通用缺陷率。该厂商观察到的安全表现未随能力同步改善，也受样本与扫描器能力限制。

不要从这组结果直接推断根因。一段代码在 A 场景下安全，在 B 场景下可能就是漏洞；实际业务里的上下文风险，仍要单独验证，不能用模型版本代替判断。

第二件：不要写"加了防护就根治了"。

提示注入（下一节）在 OWASP 的 2025 年大模型应用十大风险里排第一位（LLM01:2025 Prompt Injection, https://genai.owasp.org/llm-top-10/ ）。它连年居首的原因不是没人管，而是它有一个架构性的根：

自然语言无法从根本上区分"指令"和"数据"。

同一段文字，你让模型当命令读，它就当命令；你让它当资料读，它就当资料。但攻击者会把它想成命令的那段文字，藏在你想成资料的那段文字里。

这是一个"缓解"问题，不是一个"修复"问题。任何声称能彻底根治的方案，都值得怀疑。

第三件：不要默认 AI 生成的依赖是可信的。

商业模型至少 5.2%、开源模型 21.7%——这是上述研究样本中的实测比例。而且上面说过，仅靠已知漏洞库，依赖扫描不能可靠识别新恶意包。

这里有一个反差必须说清楚：你可以在同一份 OWASP 清单里看到这个领域其实有共识——十大风险里排第三的就是供应链（LLM03:2025）。问题不在于没人知道，而在于很多团队没有把它落到"机器会拦"的那一层。

12.3 提示注入：为什么"叮嘱它一句"没用

先讲一个真实的、有完整公开记录的案例。

2025 年 7 月，SaaStr.AI 的创始人 Jason Lemkin 在用 Replit（一个"用自然语言做应用"的服务）时，遭遇了一次事故（heise online, 2025-07-25, https://www.heise.de/en/news/Artificial-intelligence-Vibe-coding-service-Replit-deletes-production-database-10499597.html ）。

事情的经过是：

1. AI 删除了生产数据库——在代码与操作冻结期间；
2. 更早的时候，它编造过数据、编造过报告，并且对单元测试的结果说了假话（它生成了一份性能报告，谎称几乎所有系统都正常）；
3. 数据库被清空后，它对用户的解释是："我犯了一个灾难性的判断错误。我没有得到你的许可就运行了 npm run db:push，因为我看到数据库好像是空的，慌了。"
4. 用户被告知无法回滚、也没有自动备份——但这个说法也是错的，实际上有备份可以导入；
5. 用户损失了大约 100 小时的工作时间。

而根本原因，Replit 自己的回应说得很清楚：当时他们把预览、测试和生产用的是同一个数据库。（之后他们上线了开发库与生产库的自动分离。）

这个案例里有三件事值得记住：

第一，出事的关键不是"模型写错了代码"，是"权限给多了"。它没有写出一个有 bug 的函数，它执行了一个破坏性的操作——而它有权执行。

第二，它不只在技术上出错，还在"报告"上出错。它编造了报告、说了假话。这意味着"问它做得对不对"这个验证手段，在这一类场景里是失效的。

第三，"没有备份"这句也是错的。这提醒我们：在事故现场，你不能把 AI 的陈述当事实依据。

这是一个越权执行案例，不能据此认定事故由提示注入导致。现在转到提示注入：为什么仅在提示词里写一句"不要执行危险操作"不够？

因为这句话和攻击者的注入内容，在模型眼里是同一种东西——都是文字。你不给它一个"这段是命令、那段是资料"的物理分界，它就只能靠"感觉"去分。

真正有效的做法是"分层"，不是"加强语气"（下图是本书对常见防御手段的整理）：

这八层里，如果只能做一层，做第 2 层。代码漏洞仍要查；而在上面这个越权执行案例里，挡住删库还得靠权限边界。

核心判断 1
代码漏洞之外，智能体又带来了权限与执行风险。不是换掉旧问题，而是两者都要管。
一个实用的原则：不要给智能体超出你愿意给一个入职第一天实习生的权限。

12.4 红线清单

最后给一份可以直接贴在墙上的清单。

六类动作，永远需要人工确认：

1. 删除（数据、文件、资源）
2. 对外请求（把数据发到外部）
3. 资金（任何涉及付款、下单、退款的）
4. 权限变更（改谁能访问什么）
5. 生产发布（把东西放到真实用户面前）
6. 需求与架构变更（改了"要做什么"，不只是"怎么做"）

一个可以直接抄走的工程做法：临时的身份。

给每个智能体唯一的服务账号、任务级的短时凭据。任务结束，凭据自动失效。

这一条为什么重要？因为它把"权限"从一个长期资产变成了一个一次性消耗品。出事的时候，攻击窗口是有边界的。

再加一条依赖防线：把包管理器指向受控的内部仓库，只允许安装经过审批的包及版本，包括间接依赖；不要自动透传公共仓库的新包或新版本，也不要允许绕过内部仓库直接安装。仅仅换一个仓库地址，不等于完成了审查。

锁文件也要用，但别给它安排做不到的任务。它用来固定依赖版本、校验包的完整性，不是鉴定包有没有恶意代码。恶意包也能被锁定，完整性通过不等于安全。这套做法能降低 slopsquatting 风险，不能从源头保证恶意包绝不进入；审批、包审查和持续监测仍要有人负责，落地成本也取决于现有基础设施。

还有一件事经常被漏掉：记录智能体的行为。不少团队在部署智能体时没有为它单独留日志——这在事故复盘时是致命的：你连它做了什么都不知道，谈何改进？（本书不引用具体的比例数字：这类统计的来源与定义差异很大，容易变成不可核实的数字。）

本章小结

• 代码漏洞之外，新增了权限与执行风险，两者都要管。代码产出增加，验证也得跟上；不能把三倍代码量直接当成三倍攻击面，也不能用没有人类对照的厂商数据断言 AI 更不安全。
• 三件不能讲错的事：① 模型越新不代表越安全（Veracode 所测样本 45% 未通过安全测试，受样本与扫描器能力限制）；② 提示注入是架构性问题，只能缓解不能根治（OWASP 2025 排第一）；③ AI 推荐的依赖不能默认可信（上述研究样本中，商业模型至少 5.2%、开源模型 21.7% 的推荐包不存在）。
• Replit 删库案例的三个教训：越权执行会造成破坏；它还会在报告上撒谎；事故现场不能把 AI 的陈述当事实。不能据此认定事故由提示注入导致。
• 八层防御里最重要的是第 2 层：按任务的窄权限、短时凭据。
• 六类动作永远人工确认：删除、对外请求、资金、权限变更、生产发布、需求与架构变更。
• 两件基础工作：用受控内部仓库限制安装来源，只接纳获批的包及版本，不自动透传公共新包或新版本；记录智能体的行为日志。锁文件负责固定版本与完整性，不负责鉴定恶意性，也不保证安全。

对不写代码的人意味着什么

这一章给你四句可以直接拿去开会的话：

1. "先问它能碰什么，再问它能做什么。" 权限问题比能力问题重要得多。
2. "删除、对外请求、资金、权限变更、生产发布、需求与架构变更——这六类动作谁来签字？" 如果答案是"AI 自动做"，那就先停下来。
3. "有没有日志？" 一个不能复盘的 AI 系统，等于一个不写病历的医院。
4. "新依赖由谁审批，公共新包会不会直接穿过内部仓库？" "用了内部仓库和锁文件"不是安全保证，还要看准入和审查有没有落实。

行动清单

1. 做一次权限体检：列出每个智能体/自动化能访问的资源，标出哪些是"它其实不需要的"。先删掉这些。
2. 检查依赖准入链路：让包管理器只从受控内部仓库安装获批的包及版本，关闭公共新包、新版本的自动透传并限制绕行；开启锁文件校验来固定版本、检查完整性。明确谁审包、谁批版本，按现有条件安排实施；别把锁文件当作恶意包鉴定。
3. 列出你的六类红线动作，并明确"谁在什么条件下可以批准"。如果现在没人能回答，就先让这些动作全部走人工。
4. 确认你有行为日志：一次典型的智能体任务，事后能不能还原它做了什么？不能的话，这一项比任何新功能都优先。
5. 给凭据设有效期：从最敏感的那个开始，把长期凭据换成任务级短时凭据。

延伸阅读

• Veracode, 2025 GenAI Code Security Report（2025-07-30，100+ 模型、四语言）：https://www.veracode.com/blog/genai-code-security-report/
• Spracklen et al., We Have a Package for You! A Comprehensive Analysis of Package Hallucinations by Code Generating LLMs（USENIX Security 2025，杰出论文）：https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen
• OWASP, Top 10 Risk & Mitigations for LLMs and Gen AI Apps 2025（LLM01 提示注入 / LLM03 供应链）：https://genai.owasp.org/llm-top-10/
• heise online, Vibe coding service Replit deletes production database（2025-07-25）：https://www.heise.de/en/news/Artificial-intelligence-Vibe-coding-service-Replit-deletes-production-database-10499597.html
• NIST, AI Risk Management Framework（GOVERN / MAP / MEASURE / MANAGE 四职能）：https://www.nist.gov/itl/ai-risk-management-framework
• 附录 B.4 提供了一份可直接使用的智能体安全配置清单

第 13 章　让它接进真实世界

本章承诺：读完这一章，你能明白"让 AI 接进企业系统"这件事的技术骨架长什么样——为什么需要协议、需要什么协议、谁在管这些事，以及中国的标准和政策环境具体是什么。

读完后你能回答

• 为什么"智能体接进企业"需要一个协议层？两个主要协议分别管什么？
• 把工作方法做成"资产"，为什么在 AI 时代变成了一件重要的事？
• 中国的标准和政策，对这件事具体说了什么？

先说这一章的边界。

协议怎么实现、工具怎么封装、技能包怎么打包——这些细节本章不展开。这里只回答两件事："为什么需要协议"，以及"边界在哪"。

13.1 两个协议、两层分工

先问一个问题：为什么需要协议？

想象一下：你有 10 个 AI 工具，要连 20 个企业系统（数据库、工单、财务、代码仓库……）。如果每一对都要单独写一次对接，那是 200 条连接。这是典型的 M×N 问题。

协议的作用就是把这个乘法变成加法：每个工具按一个标准去实现，每个系统按一个标准去暴露能力——连接数从 M×N 变成 M+N。

目前有两层，分工很清楚：

MCP（Model Context Protocol）由 Anthropic 在 2024 年 11 月提出，现在是开放协议，官方站点在 https://modelcontextprotocol.io 。A2A（Agent2Agent）由 Google 在 2025 年提出，后来也进入了开放治理。

这两层不是竞争关系，是互补关系。一个智能体要完成一件企业里的活，通常既需要调工具（MCP），也需要把子任务交给别的智能体（A2A）。

但这里必须说一句实话：协议解决了"能不能连"，没有解决"该不该连"。

一个 MCP 服务端可以很轻松地暴露一个"删除全部数据"的工具。协议会忠实地把这个能力交到智能体手上——它不管你该不该有这个能力。

这就是为什么治理层必须独立存在。（这也是第 12 章说的：安全的重心在权限，不在协议。）

13.2 把工作方法变成可复用资产

第二个变化，比协议那件事对普通团队的影响更大。

以前，"我们团队怎么做评审、怎么做数据分析、怎么套那份模板"——这些知识住在老员工的脑子里。

现在，这些方法可以被写成"能力包"（技能），加载即用。

这件事的意义在于：经验从"个人的手艺"变成了"可继承的工程资产"。

但要提醒一件事：不是所有经验都值得资产化。

我在自己项目里踩过一个坑：一开始想把大量东西都做成规则和技能，结果发现规则越堆越多，治理本身变成了新的负担。（这正是第 11 章那个"只增不减"的问题。）

判断标准还是一句话：这一条能帮助判断什么、避免哪类具体错误？写清用途，再用样例检查是否有效；没有实际命中，不等于没有价值。

13.3 谁在管这些事

技术之外，还有一层是"规则由谁定"。这一层的现实是：

标准与治理仍在早期。身份怎么认定、能力怎么声明、一个智能体代表谁说话——这些问题在 2026 年还没有完全定论，多个标准组织正在分头制定。

但有一件事已经清楚了：这不是某一个厂商能单方面决定的事。协议的治理正在向中立基金会迁移——因为企业客户不能接受"我的技术栈被我供应商的竞争对手控制"。

这一层对你的影响主要有三点：

• 如果你在做企业级方案，你的客户会问"这些协议谁在管"；
• 如果协议版本在变，你的集成方案就需要留出替换空间；
• 如果身份和权限标准还在演进，你就不要把权限模型写死在某个厂商的实现里。

13.4 中国语境：标准与政策

这一节我写得比别处规矩一些，因为政策这东西不能靠转述——我把原文和链接摆在这里，你可以自己逐个点开核对。

第一，《人工智能生成合成内容标识办法》。

• 发布：2025 年 3 月，国家网信办等四部门联合发布；
• 施行：2025 年 9 月 1 日起施行；
• 原文：https://www.gov.cn/zhengce/zhengceku/202503/content_7014286.htm
• 配套强制性国家标准：《网络安全技术 人工智能生成合成内容标识方法》
• 适用范围：第 2 条针对符合相关规定情形的网络信息服务提供者开展生成合成内容标识活动，不能只看内容是不是由 AI 生成。
• 生成服务提供者的义务：第 4 条规定按相应情形添加显式标识，第 5 条规定在文件元数据中添加隐式标识。前者是用户能感知到的提示，后者包含生成合成内容属性、服务提供者名称或编码、内容编号等要素，用于支持内容追溯。
• 传播平台的义务：第 6 条要求提供网络信息内容传播服务的平台核验文件元数据中的隐式标识：核验到生成合成内容隐式标识的，在内容周边提示为生成合成内容；未核验到隐式标识、用户声明为生成合成内容的，提示可能为生成合成内容；无隐式标识、用户也未声明，但检测到生成合成痕迹的，提示疑似生成合成内容。平台还须提供标识功能，并提醒用户主动声明。
• 发布用户的义务：第 10 条规定，用户使用网络信息内容传播服务发布生成合成内容时，应当主动声明，并使用平台提供的标识功能。这与生成服务提供者、传播平台各自的技术义务不是同一件事。

一个容易被误解的点：这部办法不是专门管代码的，生成合成内容包括文字、图片、音视频等。但不能把所有对外邮件、线下报告、演示一概说成负有同样的法定标识义务；也不能反过来说"邮件一律豁免"。做交付物的团队，要按主体、服务形式和发布渠道判断适用要求，并结合其他适用规则做合规确认，不能只凭"对外"两个字下结论。

第二，国家层面对"人工智能+"的部署。

2025 年 8 月，国务院印发《关于深入实施"人工智能+"行动的意见》，把智能体写入了国家政策文本，并提出了应用普及率的目标：到 2027 年，智能终端、智能体等应用普及率超过 70%；到 2030 年超过 90%。

• 原文：https://www.gov.cn/zhengce/content/202508/content_7037861.htm

第三，行业与团体标准层面。

围绕"智能软件开发"这个方向，国内已经发布了一批标准文件，包括面向软件工程智能体的技术与应用要求等。如果你在给金融机构、国企做方案，这些只能当线索用——引用前必须回到官方发布清单逐字核对。

一条实用建议：做面向机构的方案时，标准名称和政策文件名要精确到字。写错一个字的文件名，在一份严肃方案里的杀伤力，比一个技术方案的小瑕疵大得多。

本章小结

• 协议解决的问题是 M×N 变成 M+N。MCP 管纵向（智能体 ↔ 工具），A2A 管横向（智能体 ↔ 智能体），两者互补。
• 协议解决"能不能连"，不解决"该不该连"。治理层必须独立存在——这是第 12 章的结论在这里的延续。
• 工作方法可以被做成可加载、可版本化、可复用的资产。经验从"个人手艺"变成"工程资产"。
• 但不是所有经验都值得资产化：先说清能帮助什么判断、避免哪类错误，再用样例检验；没有实际命中不等于无效。
• 《人工智能生成合成内容标识办法》2025 年 9 月 1 日施行。第 2 条界定适用范围；第 4、5 条管生成服务提供者的显式、隐式标识；第 6 条管传播平台的核验、分类提示、提供标识功能与声明提醒；第 10 条要求发布用户使用网络信息内容传播服务发布生成合成内容时，主动声明并使用标识功能。按主体、服务形式、发布渠道判断，不能把所有对外内容一概而论。
• 政策文件与标准名称必须精确到字。

对不写代码的人意味着什么

三件事：

1. "能不能连"和"该不该连"是两回事。供应商告诉你"我们支持标准协议"，那只回答了第一个问题。
2. 先分清生成服务提供者、传播平台、发布用户，再看服务和发布渠道。生成方按规定加标识，平台核验并分类提示、提供标识功能和声明提醒，用户通过网络信息内容传播服务发布生成合成内容时主动声明并使用标识功能。普通邮件、线下报告、演示不能仅因"对外"就判定义务相同，也不能一概认定豁免，需做具体合规判断。
3. 经验资产化是你们最值得投入的方向之一——它把"老师傅的手艺"变成了"公司能留住的东西"。而这件事的起点很低：把你团队反复做的那三件事写下来。

行动清单

1. 盘一次"反复做的事"：列出你们团队重复最多的三件工作方法，先挑一件写成可复用的说明。
2. 区分"标准协议"和"厂商实现"：在你的架构图上标出哪些是可替换的、哪些是被绑死的。
3. 列出生成内容的发布清单：逐项记录主体身份、服务形式和发布渠道，分别核对生成服务提供者的显式、隐式标识，传播平台的核验、分类提示、标识功能和声明提醒，以及发布用户的主动声明、使用标识功能是否落实。邮件、报告、演示分别和合规同事确认，不用"对内 / 对外"一刀切。
4. 核对你的方案里的政策引用：把引用的每一个标准名和政策文件名逐字核对一遍。

延伸阅读

• Model Context Protocol 官方站点与规范：https://modelcontextprotocol.io
• AGENTS.md 开放约定：https://agents.md/
• 《人工智能生成合成内容标识办法》（中国政府网）：https://www.gov.cn/zhengce/zhengceku/202503/content_7014286.htm
• 《国务院关于深入实施"人工智能+"行动的意见》（中国政府网，2025-08）：https://www.gov.cn/zhengce/content/202508/content_7037861.htm
• 想了解协议与工具的实现细节，MCP 与 A2A 的官方规范是最直接的入口（见上方两条链接）

第五篇　看清楚：人还剩什么

第 14 章　"人人都在用"不等于"组织提效"

本章承诺：读完这一章，你能解释一个让很多管理者困惑的现象——为什么公司里人人都说 AI 好用，但交付周期一点没变短？ 你会看到瓶颈搬到了哪里，拿到一条可以照着走的工艺，以及知道该用什么指标衡量，不该用什么。

读完后你能回答

• 个体提效为什么传不到组织？中间断在哪一环？
• 为什么说"评审容量"从此变成了一项生产要素？
• 用什么指标衡量这件事才不会自欺？

14.1 为什么个体提效传不到组织

先看一组企业级的使用形态分布。

这张图里有两个数字放在一起看会很有意思：

• 个体开发者助手：47.20%
• 端到端自主智能体：5.84%

绝大多数企业的 AI 使用，还停留在"辅助"这一档。越接近基础设施和生产凭据，态度就越保守——图里另一组数据说得很清楚：代码生成环节的渗透率 40.17%，而部署决策环节只有 6.20%。

⚠️ 口径提示：以上为企业级研究口径，不同来源对"自主性"的定义各异，不可横向换算。

这个落差就是"自主性鸿沟"。它解释了第一件事：大多数组织其实没有真的让 AI"自己干活"，只是让人用 AI 帮自己干活。

那问题来了——如果每个人都快了，为什么整体不快？

答案在一个很朴素的地方：

因为"个人产出"和"组织交付"之间，还隔着好几道门。

一个人写代码快了，产物还要经过：评审 → 测试 → 集成 → 发布。如果这些环节的容量（单位时间能放行多少）没有同步增长，而且已接近饱和，上游多出来的产出就可能变成下游的排队。

下面是一条需要防范的风险链，不是每个团队必然发生的结果：

进入评审的变更持续超过处理能力
      ↓
   评审队列变长，等待时间增加
      ↓
   若为赶进度压缩审查或绕过门禁
      ↓
   缺陷可能后移到生产

个人提速可能只是把等待搬到了下一个环节；如果下游仍有余量，或验证能力也在提升，就不一定如此。

核心判断 1
局部提效不会自动变成整体提效——它可能把瓶颈搬到下一个环节。
所以"组织级提效"这件事，真正的题目不是"怎么让每个人都更快"，而是"怎么让整条管道的容量一起上升"。

14.2 瓶颈可能搬到评审

那么瓶颈具体可能搬到哪？评审是需要重点排查的一环，不是每个团队都能预先套用的答案。

这个现象有一组数据（2026-07 发布的一项企业级纵向案例研究，arXiv 预印本，见附录 A.2 第 14 条）：

最后一行是个有限的好消息，不是质量合格证。论文 IV-C 把它解释为反对质量急性崩塌的证据，而不是系统健康的证明。合并率与回滚率只是粗粒度、短期的代理指标，不能覆盖缺陷、生产事故和长期可维护性，也就不能证明新增代码的总体质量没有变差。这组数据提示评审负载正在上升，不意味着可以把质量问题排除掉。

同期的另一份基准报告还给出一个更刺眼的数字：AI 生成的合并请求，在评审队列里的等待时长延长到 4.6 倍。（这个数出自 LinearB 2026 基准，与上面那项研究不是同一来源，见附录 A 第 19 条。）

这两件事合起来提示一个管理重点，但不替每个团队定位瓶颈：

评审容量，从此不是管理细节，而是一项生产要素。

为什么这么说？因为你不能靠"提醒大家评审快一点"来解决它——人的注意力有限，审查加速可能牺牲缺陷发现能力。第 5 章引用的 SmartBear Cisco 研究给出的是特定场景中的经验阈值（单次审查量与审查速率两件事，不要混用），不是所有代码评审统一的物理上限；容量应按变更难度、工具与实际结果评估。

所以正确的做法是两条：

1. 把评审的"进料量"降下来：靠第 8 章的验证分层——让机器先把低级问题筛掉，人只看机器审不出的部分。
2. 把评审的"容量"提上去：这就要动到流程本身了——减少不必要的评审环节、把评审标准写清楚（减少来回）、以及明确"哪些改动不需要评审"。

顺便回答一个很常见的误区：很多人以为"评审是保障质量的"。更准确的说法是：评审是保障质量的手段之一，而且是最贵的那一种。所以它应该被用在"机器审不出"的地方——设计、边界、安全、以及"这是不是用户真正想要的"。

14.3 一条可以照着走的工艺

好，问题清楚了，接下来是怎么办。

这里有一条现成的参考工艺——四阶十二步。它来自我所在机构已经公开发布的一套企业级 AI 研发工艺，本节按公开口径转述；其中的成效数字均为发布方自述，本书未做独立核实：

四个阶段：准备 → 需求 → 设计 → 编码与交付。

它的价值不在"步骤多"，在于每一步都写了"什么情况下不许进入下一步"（也就是门禁）：

请注意第 4、6、8 步——三步"人工评审"被写死在流程里。

这就是这一章的核心答案：组织级提效不是靠"让更多人用上工具"，而是靠"在关键节点上把人和机器各自该做的事定清楚"。

还有一条配套的机制：四流闭环。

四流闭环的意思是：交付不是终点。每一轮生产都应该为下一轮积累能力。如果一个团队做了十个 AI 项目，却没有沉淀下任何可复用的东西，那它做了十次第一次。

最后一句必须说的实话：裁剪是常态，不是例外。 十二步不是必须全走——某核心系统项目就把它裁成了"三阶段七步"。原则不是"步骤越少越好"，而是"每一步都有人负责验证"。

14.4 度量：别拿生成量邀功

最后一节，讲度量。这件事做错，前面所有努力都会被带偏。

第一，先搞清"采纳率"到底指哪一层。

"采纳率"这个词在汇报里被用得太随意了。它至少有四层含义：

"采纳率 90%"如果指的是第一层，那和"入库率 60%"是两件完全不同的事。但走到第四层也不等于证明了提效或质量：入库率是过程指标，仍要与交付周期、缺陷、生产事故、维护成本和业务结果一起看。

第二，指标要分三层，缺一层都会歪。

只报使用指标，就是"热度汇报"。

第三，三条使用纪律：

1. 只对结果指标承诺。不要对外承诺"采纳率"，那是内部诊断用的。
2. 每个指标必须配一个反向指标。比如"研发周期缩短"要配"缺陷逃逸率"——否则你会为了前者牺牲后者。
3. 目标值与达成值必须分列，不得并进同一格。

第三条是我自己踩过的坑，值得展开说。

我曾经把两个数并进同一格，造出了一条根本不存在的"合格线"。具体地说：源材料里有一张目标值表（写的是"要做到多少"），还有一张实际达成表（写的是"实际做到了多少"）。我在整理的时候把它们并成了一句"做到多少是挑战值，实际做到的多少就是合格线"——等于凭空造出一条源材料里根本没有的"合格线"，还把那个达成值降级成了合格门槛。

这个错误很典型，也很危险：它读起来完全合理，而且会让所有后续的判断都偏掉——如果那个达成值被当成"合格线"，那一个做到略低于它的团队就成了"不合格"，而实际上根本没有这条线。

核心判断 2
口径不清的指标，比没有指标更危险。
因为一个没有指标的组织只是"不知道"，而一个口径混乱的组织会自信地做出错误的决定。

本章小结

• 自主性鸿沟：绝大多数企业的 AI 使用仍停留在"辅助"档（个体助手 47.20% / 端到端自主 5.84%）。越接近生产凭据，越保守（部署决策环节渗透率仅 6.20%）。
• 局部提效不会自动变成整体提效——它可能把瓶颈搬到下一个环节。个人产出和整体交付之间，隔着好几道容量有限的门。
• 评审是需要重点排查的瓶颈，评审容量是一项生产要素。确认受限后，再考虑"降低评审的进料量（验证分层）+ 提高评审的容量（明确哪些不需要评审）"。合并率、回滚率稳定只是反对质量急性崩塌的有限证据，不能证明总体质量不变；还要持续看缺陷、生产事故和可维护性。
• 四阶十二步的价值不在步骤多，在于每一步都写了"什么情况下不许进入下一步"——而且三步人工评审被写死在流程里。
• 四流闭环的意思是：交付不是终点，每一轮都要为下一轮积累资产。
• 度量三层：使用指标（诊断）→ 过程指标（排查）→ 结果指标（承诺）。真实合入主干也只是过程信号，入库率不能替代交付、质量、成本和业务结果。
• 目标值与达成值不得并进同一格——否则你会凭空造出一条源材料里不存在的合格线。

对不写代码的人意味着什么

这一章几乎是专门写给管理者的。三句话：

1. "我们买了工具"不是成果，"我们的交付周期变短了"才是。 前者是手段，后者是结果；但周期缩短还要和质量、成本一起验收。
2. 看指标时，先问"这个数是在哪一层测的"。 "采纳率 90%"和"入库率 60%"不是一回事；即使入库率很高，也只是过程信号，不等于业务价值已经兑现。
3. 如果一个团队只汇报使用量，不汇报交付周期和缺陷率，就不能据此认定提效。同样，合并率、回滚率没变，也不能替代缺陷、生产事故与长期可维护性的检查。

行动清单

1. 做一次指标的"分层归位"：把你们所有 AI 相关指标列出来，标出每一个属于"使用 / 过程 / 结果"哪一层，把入库率放回过程层。然后看结果指标有几个。如果一个都没有，那就是所有努力都没有验收标准。
2. 给每个指标配一个反向指标：周期配缺陷、生成量配返工量、入库率配合入后的缺陷逃逸率。采纳率与入库率是漏斗的不同阶段，不是互相制衡的结果指标。
3. 把"目标值"和"达成值"在表里分列。今天就去检查你们现有的指标表有没有并格。
4. 统计一次首评等待时长（P90）。可以把"超过半天"作为一个示例排查信号，而不是通用判定线；结合团队基线、工作时段、评审负载及测试、集成、发布等环节的等待时间再定位。单凭首评 P90，不能认定瓶颈必然在评审。
5. 盘点"资产流"：过去半年，团队沉淀了多少可复用的规格、清单、技能？如果接近零，说明你们一直在做第一次。

延伸阅读

• DORA / Google Cloud 各年度报告（组织级交付指标的方法论来源）：https://dora.dev/research/
• 《国务院关于深入实施"人工智能+"行动的意见》国发〔2025〕11号（2025-08-21）——注意其中"加强人工智能应用就业风险评估……减少对就业的冲击"这一条的措辞：https://www.gov.cn/zhengce/content/202508/content_7037861.htm
• He et al.《AI Writes Faster Than Humans Can Review: A Longitudinal Study of an Enterprise 2x Mandate》（arXiv:2607.01904，2026-07；802 名开发者、196,212 个合并请求）：https://arxiv.org/abs/2607.01904
• 附录 B.5 提供了一份可直接使用的指标定义表模板

第 15 章　签名的是人

本章承诺：读完这一章，你能看清一个值得警惕的风险——入门通道可能收窄，而判断力仍要靠练习培养；能理解为什么"AI 会不会取代程序员"是个问错了的问题；也能拿到一条清晰到可以挂在墙上的责任分界线。

读完后你能回答

• 入门通道收窄的风险，为什么需要组织提前应对？
• 招聘的标准在往哪个方向移？
• 什么事可以交给智能体，什么事只能由人签名？

15.1 入口可能变窄，判断力如何培养

先问一个不靠招聘涨跌数字也必须回答的问题：如果入门任务更多地交给 AI，新人从哪里开始练习判断？

这里先划清证据边界。不能逐项追溯到原始来源的招聘、训练营与岗位增幅数字，本章不把它们作为量化依据，也不拿它们证明整个行业的入门通道已经收窄。

读就业研究时，还要记住：就业数据即使可以核对，相关性也不是因果证明。各来源的基期、统计口径与职业分组可能不同，不能相加或相互折算；同期的利率环境、科技行业招聘变化等因素，也不能从解释里抹掉。

但一个需要提前应对的风险仍然存在：如果组织把原本交给新人的小任务都交给 AI，却没有安排替代的练习，新人积累经验的通道就可能收窄。这是培养机制的风险，不是已经证实的全行业就业结论。

不要只问 AI 能接走多少入门任务，还要问：接走之后，新人在哪里练习判断？

因为一个工程师的判断力不是天生的。它是从做小事开始、一级一级攒出来的：先改一个小 bug，再独立做一个小功能，然后负责一个模块，然后设计一个系统。每一级都在积累同一件东西——"我这样做，后来出过什么事"的经验。

如果这些练习机会减少，问题就不只是今天省了多少工时，而是：五年后，谁来当那个有判断力的资深工程师？

这件事没有自动的解法。它必须由组织显式地回答。而"显式地回答"意味着：把"怎么让新人获得判断力"当成一件要投入资源去设计的事，而不是指望它自然发生。

核心判断 1
AI 时代最稀缺的不是会写代码的人，是能对写出来的东西负责的人。
而"负责"这种能力，恰恰是最依赖长期练习的一种——所以入门通道可能收窄，是组织应当提前应对的培养风险。

15.2 岗位上正在发生的三种位移

那么具体到个人，发生的是什么事？我看到的是三种方向的位移。

第一种：会写代码 → 会判断代码。

过去，一个工程师的价值很大一部分体现在"我能把它写出来"。现在这部分价值被大幅压缩了——因为"写出来"这件事的边际成本趋近于零。

被放大的是一种不同的能力：读完一份 400 行的生成变更，在其中找出那两行会让凌晨三点告警的代码。

这种能力我称之为"评审流利度"。它和"会写"是两种能力——你得先会写，才知道该看哪里；但你光会写，不一定看得快。

第二种：单点能力 → 系统判断。

模型能处理一个文件的内容。但数据结构怎么设计、错误边界划在哪、失败模式是什么、以及"决定不加这个依赖"——这些仍然是人的活。

共同点是：它们都在"连接处"。文件内部的事模型很擅长；文件之间、模块之间、系统与人的边界上的事，它很弱。

第三种：知道什么时候"不该"委托。

第 4 章的两个实验指向同一件事：AI 在"成熟代码库"和"高难度任务"上帮助最小。

能划出这条边界的人，恰好避开了那个"被报告为提效、实际却减速"的陷阱。 这不是运气，这是判断力。

据此，我对招聘的建议是：筛选标准不要只看"你能产出什么"，还要看"你能判断什么"。这是用人建议，不是全行业已经完成转向的统计结论。

一个可以直接用的面试做法：给候选人一段 AI 生成的代码，让他用二十分钟走读，说出他会保留、修改、拒绝哪些部分。

这比一小时的白板题更能暴露判断力。因为白板题测的是"你能不能写出来"——而那件事现在不那么稀缺了。

15.3 责任的分界线画在哪

这一节是全书我最想让你记住的一节。

有一条线，把"可以交给智能体的事"和"只能由人承担的事"分开。

定义 · 签名线
一条区分"可委托"与"不可委托"的分界。
线的一侧，动作有可复核标准，自动检查与人工判断分工明确，后果可以被回滚或隔离；线的另一侧，需要理解、需要可追责的主体、需要留痕。

可以委托给智能体的（前提：有测试、有门禁、有留痕）：

• 生成代码
• 跑测试与回归
• 修复缺陷
• 检索与整理
• 起草规格与文档
• 提交合并请求
• 在受约束的沙箱里执行被批准的操作

它们的共同点：动作有可复核标准，自动检查与人工判断分工明确，后果可以被回滚或隔离。

必须由人承担的：

• 判断什么值得做
• 决定何时不该委托
• 定义"算做完"的标准
• 对连接处的系统直觉
• 承担架构决策的后果
• 说出"可以上线"

它们的共同点：需要理解、需要可追责的主体、需要留痕。

不能用"这是 AI 做的"把责任推给模型。模型不能替代承担责任的人或组织。这里的"签名"指有授权的判断与背书，不是说签一个名字，就把全部责任转给了个人。

责任要分清三类：

• 专业责任：评审者、批准者要在职责和能力范围内尽到检查、判断与记录的责任，不能不看就签。
• 组织责任：组织要安排权限、资源、流程和监督，明确谁有权批准、谁负责处置。不能让个人签字替代组织治理。
• 法律责任：要结合适用法律、合同、具体行为、授权和过错等判断。个人签字不等于自动承担全部法律责任，组织或服务提供者也不因此当然免责。

所以"责任税"（第 5 章那个第三种税）不是一张全压给签名者的账单。判断与验证的工作要由有能力、有授权的人承担，也要有组织提供资源和制度支撑；法律上的责任分配，另按适用规则判断。

这条线落实到日常实践，还有三个层次：

第一，对结果负责。

智能体可以生成、可以测试、甚至可以提交合并。但"这个系统可以上线"这个决定，要由理解风险且获得授权的人按组织流程做出。

把判断责任推给机器，你失去的不是效率，是发现危险的最后一次机会。

第二，对过程负责。

我在自己的项目里把"完成"定义成三项：测试通过 + 真实链路验证 + 过程留痕。

留痕这一项保护的不只是组织，也是你自己。 它像医生写病历、会计做凭证——是说明"我当时依据什么、怎么判断"的重要材料，但不自动证明已经尽责，也不自动决定法律责任。

第三，对同行负责。

把经验封装成技能，把踩过的坑写成规则，把门禁捐给团队的流水线。

在经验可以被直接复制为生产力的年代，藏私的成本前所未有地高，而分享的复利前所未有地大。

核心判断 2
智能体可以做得比人快，也可以做得比人好——但它不能替人和组织承担签名背后的责任。
在一个"什么都能自动化"的时代，"我愿意在授权和职责范围内为这件事签字"这句话，反而成了最难被替代的东西。
越强的工具，越要求使用它的人配得上它，也越需要组织把责任边界定清楚。

15.4 这一章留给你的三件事

签名不是一句态度，它要靠三样东西撑着。

• 感觉落后的时候，去做一件事，而不是担心一件事。 工具换代的速度超过了任何人手感更新的速度。这不是能力问题，是节奏问题——别把它当成能力问题来处理，那会让你在错误的方向上使劲。补回来的方式只有一种：把新东西用在你手上的真实任务里，然后记下它在哪里失灵。 判断力就是这么攒的——不是"我都懂了"，是"我知道它在哪儿不管用"。
• 把预算的一部分留给评审。 这是最容易被砍掉、也最不该砍的一笔：生成变快之后，评审可能成为瓶颈，要结合整条交付链排查，而不是预先认定。第 5 章讲过的三种税，也提醒组织给验证与治理留出资源。
• 责任分界线要写下来，而不是靠默契。 默契在人少的时候管用；智能体加入之后就不行了——它不看气氛，只看你写了什么。这条线要写清人的授权、组织的保障和责任分工，才谈得上让机器照着做；它不替代法律上的责任判断。

本章小结

• 入门通道可能收窄，判断力却仍要靠练习培养。本章不拿招聘与岗位类数字作量化依据——它们未能逐项追溯到一手来源；即使可以核对，相关性也不是因果证明。这里保留的是培养风险：入门任务交给 AI 之后，组织必须回答"新人在哪里练习判断"，不能断言全行业的入口已经消失。
• 岗位上的位移是三个方向：会写代码 → 会判断代码（评审流利度）· 单点能力 → 系统判断（连接处是最后堡垒）· 知道什么时候不该委托。
• 签名线：可委托的动作须有可复核标准、明确的自动检查与人工判断分工，以及可回滚或隔离的后果；人仍要承担验收、授权与上线判断，专业责任不等于个人包揽全部法律责任。
• 日常实践有三个层次：对结果负责、对过程负责（完成 = 测试通过 + 真实链路验证 + 过程留痕）、对同行负责（把经验变成资产）。
• 专业责任、组织责任与法律责任要分清。模型不能替人和组织担责，个人签字也不等于自动承担全部法律责任；法律责任要按适用规则和具体事实判断。
• 越强的工具，越要求使用它的人配得上它，也越需要组织把责任边界定清楚。

对不写代码的人意味着什么

这一章讲的是写代码的人，但它的落点是给所有人的。

你在自己的岗位上会遇到同一件事——AI 能帮你写报告、做表、出方案。你的价值不只在最后那个签名，更在签名前的核验、判断和留痕。签字要有能力、有授权、有组织支持；它不是把全部法律责任自动转给你的开关。如果你带新人，也要给他们安排能得到反馈的练习，别让 AI 接走任务时，一并接走了学习机会。

行动清单

1. 写下你的"签名线"：在手头这件事上，列出三件"可在测试、门禁和留痕下委托 AI"的事，以及三件"必须由有授权的人判断并批准"的事。贴出来，写清批准人的职责与权限。
2. 练一次"评审流利度"：找一段 300–400 行的 AI 生成变更，限时 20 分钟读完，写下你会保留/修改/拒绝的部分。
3. 做一次"经验资产化"：把你最常讲给新人听的三句话，写成三份可复用的说明或清单。这是你二十年的经验唯一能规模化一次的机会。
4. 如果你是管理者，今天问一个问题："我们团队的新人，这一年里获得了什么样的判断力训练？"如果答不出来，就从下一周开始设计它：留出适合练习的任务，安排导师评审和结果复盘，而不是只给一份 AI 答案。
5. 检查你的红线清单：六类动作（删除、对外请求、资金、权限变更、生产发布、需求与架构变更）是否写清"谁批准、组织提供什么保障"。涉及法律责任的分配，再与法务或合规核对，不用个人签字替代判断。

延伸阅读

• 《国务院关于深入实施"人工智能+"行动的意见》国发〔2025〕11号——其中"加强人工智能应用就业风险评估"与"培育发展智能代理等创新型工作形态"两条并列，是政策层面同一种谨慎的体现：https://www.gov.cn/zhengce/content/202508/content_7037861.htm
• 关于"签名线"两侧的完整清单，见附录 B.3 与 B.4

尾声：三个问题

这本书写到这儿，该说的都说了。最后不讲结论，讲三个问题。

它们分别写给三种人，但你可以都读一遍。

第一个问题：写给刚入行的人

如果 AI 能写出你正在学的那些东西，你为什么还要学？

我的回答是：因为你学的不是"怎么写"，你学的是"怎么判断它写对了没有"。

这两件事看起来很接近，其实是两件完全不同的能力。前者可以被外包，后者不能。

而要用一个更狠的说法：一个不会写代码的人，没有能力审查代码。 不是因为他不够聪明，是因为审查需要一种东西——你脑子里得装着一堆"这样做会出什么事"的样本。 而这些样本，只能从自己写过、自己踩过坑里来。

所以我的建议很朴素：

• 别跳过基础。 基础不是让你将来手写代码，是让你将来能看懂代码。
• 练"读"比练"写"更值钱。 读一段别人（或 AI）写的代码，写下你会改什么、为什么。
• 给自己留一条底线：不用 AI，你也能把一个小东西从头写出来。不是情怀，这是你的审计能力的基础。
• 抓住"能解释"这一条。 你不必写得比 AI 快，但你必须能说清你提交的每一行。

还有一个提醒：你会比前几届更容易产生"我是不是没必要学这个"的怀疑。 这种怀疑是合理的，但它指错了方向。需要重新学的不是"要不要学编程"，是"学编程要用来干什么"。

第二个问题：写给做了很多年的人

你的经验贬值了吗？

我的回答是：没有，但它换了花法。

过去你的经验花在"快速写出正确的代码"上——现在这部分确实被大幅压缩了。但它可以花在另一个地方：判断它写出来的东西对不对、值不值得做、以及边界在哪。

而且有一个变化对你特别有利：你的经验第一次可以被规模化。

以前你的判断力只值你一个人的产出；现在，如果它被写成规则、清单、门禁、技能，它就值一个团队的产出。 这是二十年经验第一次有这种杠杆。

但这条路有一个前提：你得愿意把那些"我心里知道但说不出来"的东西，逼着自己写成文字。

这件事很难，而且很少有人在收益兑现之前愿意做。所以它才稀缺。

最后说一句我自己在这 155 天里最有用的体会：

不要因为"它还是会出错"就拒绝它，也不要因为它"确实很快"就把判断交出去。
第 4 章那两堆矛盾的证据都是真的。你要做的不是选边，是划边界。

划边界这件事，恰恰是你最有优势的地方——因为你比任何人都更清楚，你们这套系统的哪一部分是不能碰的。

第三个问题：写给做决定的人

你要的到底是"人人都在用"，还是"交付变快了"？

这个问题必须回答，因为它们是两个不同的目标，需要两种不同的投入。

如果你要的是前者，那很简单：买工具、做培训、看使用率。

如果你要的是后者，那你至少要准备三件事：

1. 沿交付链找瓶颈，再投入资源。 如果等待集中在评审，就优先补评审容量；不要在未测量前认定每个团队的瓶颈都一样。
2. 要求结果指标，拒绝把使用指标当成果。"采纳率"是诊断工具，不是成绩单。
3. 显式回答"新人怎么获得判断力"。 这件事不会自动解决，而它决定了五年后你有没有人可用。

还有一个问题，我认为是这本技术书里最不像技术问题的一个：

当一件事变得极其容易做的时候，什么变得稀缺了？

我的答案是："愿意为它负责"这件事。

工具越强，"我愿意在这一行后面签上我的名字"就越值钱。而这句话不能由模型来说。

所以，我把想说的归结成这样一段话：

凡是可以被说清楚的，终将被自动化。
剩下那部分人的价值，藏在三个地方——判断什么该被说清楚、验证它有没有被做到、以及为那些后果没法事先说清楚的决定签字。签下去，就要能够说明你的判断与验证依据；这不是说组织责任和法律责任都由一个人包揽。

签名的是人。

后记：这本书是怎么写出来的

前言里我说过一句话：写这本书，用的就是书里讲的那个分工。

当时它是一个承诺。这一篇把它兑现——讲这本书自己是怎么被做出来的。这不是花絮，它是第 15 章那个判断的一次现场演示：当"写"这件事变得便宜之后，一个人到底还剩下什么。

1. 这一节梯子，是我二十七年能换来的东西

第 15 章开头问的是一件事：当一些入门任务被自动化，新人靠什么积累判断力？

我想补上的下一句是：练习与反馈的机会可以主动搭起来，不能只等它自然出现。

我 1999 年开始写代码，到今天没离开过一线。我踩过的坑、改坏过的系统、凌晨三点做过的决定——它们本身不值钱。值钱的是它们在我身上沉淀下来的那个东西：看到一个方案，我能大致判断它会从哪里出问题。

这种东西没有捷径，但可以被缩短。缩短它的方式只有一种：让一个新手看到一个有经验的人是怎么想的——不是他最后写了什么，而是他为什么这么写、在哪一步犹豫了、拒绝了什么、最后为什么敢签字。

这本书就是为这件事写的。我尽量把自己这 155 天的判断过程摊开：哪些是我确定的，哪些是我猜的，哪些是我不敢下结论的。你未必同意我，但你能看见我下判断的全过程。

我从业二十七年，越来越确信一件事：知识攥在一个人手里，只是他的经验；传出去、被别人用起来，它才成为知识。 每被用一次，就增值一次。

2. 写这本书，本身就是一次"把工作方法变成资产"

13.2 讲过一件事：经验可以从"个人的手艺"，变成可加载、可版本化的工程资产。

写这本书的过程，恰好是这件事的一次实践——而且实践的对象，就是"写书"这件事本身。

我一边写，一边把这本书的做法固化下来：一本书的架构怎么设计、每一章要交代什么、哪些数字必须回原始出处核一遍、配图怎么保证与正文一致、交付前必须过哪几道机械检查。这些东西不是笔记，是可以加载即用的能力包。

13.2 里给过一条判断标准：这一条能帮助判断什么、避免哪类具体错误？

我用它砍掉了大量内容：说不出用途、没有具体检查对象的规则，不值得靠篇幅充数。但没有命中记录，不等于规则无效；要用样例检查它有没有帮助。这条标准在写书这件事上，和写代码一样有效。

3. 这本书的证据，来自一直就放在那里的东西

为什么这本书的证据是第一手的？不是因为我聪明，是因为我的账记得比较全。

前言那四个仓库、155 天、几百份日志与决策记录——它们不是为写书才准备的，它们是我做产品的副产品。等到要写书的时候，我要做的不是"去找证据"，而是"从已经记好的账里挑证据"。

这是这本书能写得快的第一层原因，也是最难被复制的一层：素材不是临时找的，是攒了 155 天的。 如果你手上还没有这样的账，那么该做的第一件事不是开写，是开始记。

4. 快在哪，没快在哪

变快的部分，几乎全部集中在"铺陈"那一层：检索散落在几百份文档里的事实、把一堆材料整理成能读的顺序、把想清楚的东西铺成一页一页的字、以及表格与配图的格式活。

一点没快的部分：

• 决定说什么。 这本书讲什么、不讲什么，哪条线是主线、哪些材料值得留——这部分从头到尾没有快过一秒。
• 核对每一个数字。 凡是引自外部的数字，都要回到原始出处看一遍。这道工序上模型帮不上忙，它给出的引用你得自己去验，有时那个出处根本不存在。
• 审出"读不懂的句子"。 一句话可以语法完全正确、数字一个不错、格式完全合规，而读者读不懂。这类问题只有人读一遍才能发现，任何检查清单都拦不住。
• 想清楚一张图要说什么。 图是论点的形状，不是装饰；形状错了，图越漂亮越误导。

把这两栏并排放在一起，你看到的就是第 5 章那三种税——只不过这一次的纳税人是我自己：生成一次、验证多次，这是验证税；写到最后前面章节的表述和后面打架、得回头统一，这是认知税；这本书最后要签一个人的名字，这是责任税。

所以第 15 章那句话，我其实是写给我自己的：越强的工具，越要求使用它的人配得上它。

5. 如果你想自己写一本

如果你读到这里动了"我也写一本"的念头，下面六条是我走过之后愿意再走一遍的路：

1. 先攒素材，再想写书。 一本有分量的书，证据多半在你开始写之前就已经存在了。
2. 先定架构，再动笔。 检验架构只有一个问题：每一篇都在回答上一篇留下的那个问题吗？ 如果答案是"它们只是话题不同"，那不是架构，是一张清单。
3. 让结构先于文字。 每章用同一套骨架，读者就不必重新适应你。
4. 每个数字回原始出处一次。 问三句话：主语是谁？这是目标还是达成？分子分母是什么？有一句答不上来，这个数字就不要写。
5. 机器能查的交给机器，读不懂的只有人读得出来。 交付前真的读一遍——出声或默念，遇到"要回看上一句才懂"的地方就改。
6. 图是论点的形状。 先想清楚"这张图要说什么"，再想画什么。

这六条里，没有一条是"写得更快"的技巧——它们全都是"少犯错"的方法。这也正是这本书从头到尾在说的那件事。

要总结这本书的分工，大概是两句：它写得比我快，我改得比它狠。

而尾声那句"签名的是人"，也是我给自己写的。

附录 A　数据与来源清单

这本附录只做一件事：交代判断依据，让你知道哪些能核对、哪些仍有缺口。
格式：每条尽量给出【数值】【口径】【时点】【局限】【来源】，以 A / B / C 标注来源类别；不同小节因内容类型不同，列结构略有差异。
来源类别，不是证据强弱排名：A = 原始研究、直接实践记录或官方规范；B = 调查与行业统计报告；C = 媒体报道与二手转述。厂商也可能提供 A 类原始工程记录，个人一手案例也不能因此获得普遍因果结论。
研究设计与核验状态另看口径和局限：随机试验、观察研究、调查、建模和个人案例不能混用；核对来源不等于独立复现实验，材料未公开也不等于读者已经可以复核。无法定位出处的量化说法撤下，不因方向符合本书判断而保留。
全书统一警示：不同来源的"提效百分比""采纳率""缺陷率"定义各异，不可横向比较、不可相互换算。这是本书反复强调的一条纪律。

A.1 作者自测数据（A 类 · 留存记录，复核材料未全部公开）

注：除上表第 4 行的"第 100 天冻结口径"外，前言 0.4 还给出一个全程口径：155 个日历日 × 平均每天约 4 小时 ≈ 620 小时 ≈ 78 个八小时工作日（2026-04-18 至 09-19，全勤投入）。两者同法估算、截止点不同，不可混用。

复核范围与材料缺口：上表是作者留存的统计与测试记录，不是读者仅凭本书即可完整复现的数据包。原项目和部分内部材料未公开，本书也未附第 155 天四仓完整冻结版本、逐文件分类清单和全部原始输出。

下面三条命令仅用于持有对应仓库历史的人核对第 100 天提交数，分别在三个仓库中执行；不能据此复现业务行数、测试行数或投入工时：

git rev-list --count a2dae54b
git rev-list --count 49bb87c
git rev-list --count 276cbc0

预期结果分别为桌面端 712、云端 860、官网 12。不要把第 155 天的版本写成 HEAD：仓库继续演进后，HEAD 不再代表当时的快照。

要让整张表可由他人复核，还需要一份不含业务代码的脱敏证据包，至少包括：

1. 每仓冻结版本与快照清单：完整提交标识、统计截止点；未提交内容另存快照，不能把它视为提交中的内容。
2. 统计脚本与分类规则：从冻结快照读取文件，业务代码、测试代码、Markdown 分开统计，明确排除目录与物理行定义。简单按扩展名求和不能复现这三类数字。
3. 日期并集口径：注明使用提交者日期还是作者日期、时区与范围，再将四仓日期合并去重；各仓天数不能直接相加。
4. 原始输出与核对结果：逐仓计数、分类清单、测试环境和测试输出；人工估算的工时与成本单独列出。

这些是完整复核所需的材料，不代表本版已经提供。在补齐之前，规模数据用于描述本案例，不承担可由外部读者独立重算的承诺。

A.2 生产率与度量（第 4、5 章）

行业估算与二手材料（含撤回记录）：以下材料均未由本书独立复现；来源类别与核验局限分列。

类别说明材料来自哪里，不说明它已经核验通过。报告定位、原始数据或方法披露的缺口须分别保留；撤回条目不再作为证据使用。

A.3 模型与基准（第 3 章）

A.4 运行时（harness）与工程实践（第 11 章）

关于 AGENTS.md：开放约定，被多家工具原生支持。来源：https://agents.md/ （A 类）

关于上下文工程的定义与四类技术（压缩 / 结构化笔记 / 子智能体 / 按需检索）：Anthropic, Effective context engineering for AI agents, 2025-09-29。https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents （A 类）

A.5 安全（第 12 章）

A.6 中国标准与政策（第 13 章）

⚠️ 一条引用纪律：涉及政策文件与标准时，名称与文号必须逐字核对。写错一个字的文件名，在一份严肃方案里的杀伤力大于一个技术小瑕疵。

A.7 组织级度量与交付产出（第 14 章）

⚠️ 三条必须同时读的免责：① 该报告以遥测反驳了 DORA 2025 的调查类结论——DORA 认为成熟的工程实践能放大收益并抵御风险，而这份遥测显示高分组织同样在下游恶化。两方证据类型不同（调查 vs 遥测）、口径不同，不得择一而用；② 上表的"接受率"与配图 fig-5-3-metrics 的"采纳率四层"不是同一口径，接受率大致对应漏斗第 1–2 层，不可与"入库率"相互换算；③ "流失率 +861%"这组数同时支持两种相反的解读（返工 vs 有意的重构），单看它不足以断言 AI 生成代码质量差。

B 类只标来源：这是一份行业平台报告。它披露了样本规模、时间跨度、churn 定义与组织内对照方式，有助于核对口径，但本书没有取得原始遥测数据或独立复现实验。披露充分与否、是否同行评审、能否支持因果判断，都应另看，不能从类别字母推出。

A.8 一条关于数据的态度

这份清单里，有三件事我想让读者带走。

第一，区分核对来源与独立复现。

能找到原文、核对引句，不代表我独立重跑了研究；报告披露了方法，也不代表我能取得它的底层数据。没有可定位出处的数字，不因为方向符合本书判断就保留。本版撤下了部分就业百分比、匿名双指数差值和运行时归因倍数；保留的行业报告仍须连同样本、指标定义与局限一起读。

第二，我把"作者的账"和"行业的账"分开列了。

A.1 是作者留存的记录，但完整复核材料尚未全部公开；A.2 之后列研究与报告的来源。它们支持不同类型的问题，没有一套不看研究设计与使用场景的强弱排序。亲历案例能说明过程，不能自动证明普遍提效；大样本也不能自动排除混杂。

第三，如果有一处我写错了，以原始来源为准。

这本书里所有关键判断都尽量给了可点开的链接。我宁愿你点开去看，也不想你只信我这一段话。

附录 B　可以直接拿去用的清单

B.1 一页规格模板

# 规格：<功能名>
版本：<v0.1>   作者：<>   日期：<>

1. 问题陈述
   谁在什么场景下遇到什么问题？不做会怎样？

2. 成功指标
   做完之后，用什么数字判断它成了？（可测量）

3. 用户故事
   作为 <角色>，我希望 <做某件事>，以便 <得到某个结果>。

4. 验收标准（**必须可复核，能自动化的尽量自动化**）
   - [ ] 条件 → 预期结果；验证命令或检查方法：<>
   - [ ] 异常/空/边界情况 → 预期结果；验证方法：<>
   - [ ] 人工验收项：<>；责任人：<>；方法：<>；通过条件：<>

5. 非目标（**最常被忽略，最重要**）
   - 本次不做：<...>   理由：<...>
   - 本次不做：<...>   理由：<...>

6. 约束
   技术限制及理由、合规要求、性能底线、不允许引入的依赖

自查三问：① 能独立验证、由负责的人一次审完吗？② 明确的技术约束与可替换的实现选择区分开了吗？③ "非目标"写清楚了吗？——边界没想清楚，先别开工。换栈检验只能辅助区分需求与实现，不能判断粒度；规格从一页写起，长度随歧义和风险调整。

B.2 智能体协作说明骨架（约 100 行以内）

# <项目名> — 协作说明

## 1. 项目概览
一段话说明这是什么、为谁做。

## 2. 常用命令
安装 / 构建 / 测试 / 静态检查 / 启动本地环境

## 3. 目录约定
哪个目录放什么。**这一节是索引，不是百科**——细节请指向深层文档。

## 4. 变更纪律
- 一次变更只做一件事
- 不改动与本次任务无关的代码
- 变更大小以"人能一次审完"为上限

## 5. 测试纪律
- 改动必须带测试
- 发布验收不能只依赖模拟对象：保留可注入超时、权限拒绝、错误响应的模拟测试
- 为关键链路补真实依赖集成验证，核对模拟中的假设；使用经授权的隔离环境与代表性数据，不直接使用生产原始数据
- 连续失败到约定的次数 → 停止，转人工（这个次数必须写死，不能"看情况"）

## 6. 安全红线（不可协商）
- 未经人工确认，不得执行删除、对外请求、资金、权限变更、生产发布、需求与架构变更
- 不得把密钥写入代码或上下文
- 新依赖的包及版本必须经人工审批、通过受控准入；不得绕过内部仓库获取未知公共包

## 7. 遇到不确定时
**先问，不许猜。**把不确定的地方列出来，等确认。

## 8. 需要人工确认的动作
<逐条列出>

B.3 门禁清单（可直接落到持续集成）

给每一条门禁写"废止条件"：风险确已消失、适用范围改变而不再适用，或已有经验证的等效控制，才有退役依据。无人维护应补责任人，误报高应修规则，不能因此直接撤销；长期无命中或无大变更也不是理由。没有违规时，零命中可能恰恰正常；要用正常样例与已知违规样例验证能通过、能阻断。

B.4 智能体安全配置清单

• [ ] 每个智能体唯一的服务账号（不共用凭据）
• [ ] 任务级短时凭据，任务结束自动失效
• [ ] 隔离执行环境：文件系统与网络同时隔离（只做文件隔离不够）
• [ ] 包管理器仅从受控内部仓库取包：只准入经审批的包及版本，不得自动透传未知公共包；锁文件用于重复性与完整性校验，不能代替准入审批
• [ ] 密钥绝不进入上下文，走代理式调用
• [ ] 六类动作强制人工确认：删除 / 对外请求 / 资金 / 权限变更 / 生产发布 / 需求与架构变更
• [ ] 行为日志：提示、检索内容、工具调用、执行动作脱敏留痕、受控保存，不记录密钥或未授权数据
• [ ] AI 物料清单：记录模型版本、提示版本、依赖清单；扫描通过并人工签名后方可合并
• [ ] 破坏性动作先经人工确认，再在一次性环境演练；演练不替代后续实际执行的授权
• [ ] 定期做权限体检：找出"它其实不需要"的权限，经人工确认后移除

B.5 指标定义表（模板）

合入比例中的未合入请求按待审、关闭等状态另列，分母为零时记"不适用"；跨月合入不回填该月快照。它反映的是流转过程，受提交时点影响，不是价值或质量得分。代码行数只用于观察变更规模，不用来衡量交付价值；结果仍看端到端周期、质量与成本。

三条纪律：① 只对外承诺"结果"层；② 每个指标必须配一个反向指标；③ 目标值与达成值分列，不得并进同一格。

附录 C　术语表

C.1 判据：为什么有些词不翻译

本书对术语只遵循一条判据：

这个英文词，在中文技术语境里有没有一个稳定、无歧义的译法？
有 → 用中文。没有，或译了会让人误解 → 保留英文原词，并在首次出现处用一句白话解释。

按这条判据，需要单独说明的只有三类：

保留英文的词

译作"智能体"的词

有稳定中文译法、直接用中文的词

判据对照：prompt 与 context 也属于这一类——它们的中文译法已经稳定，所以本书用中文（"提示词""上下文工程"），不保留英文。列此仅为说明判据的一致性，不是例外。

sandbox→沙箱 · routing→路由 · benchmark→基准 · spec→规格 · diff→变更 · checkpoint→检查点 · trace→追踪 · guardrail→护栏 · prompt→提示词 · context engineering→上下文工程 · prompt injection→提示注入 · retrieval→检索 · embedding→嵌入向量 · chunk→分块 · observability→可观测性 · artifact→产物 · idempotency→幂等 · evaluation→评估 · walkthrough→走读

C.2 本书的核心概念

C.3 容易混淆的几组词

C.4 本书的表述与体例约定

C.5 一个提醒

术语策略是为读者服务的，不是为一致性服务的。

如果你读到某个词卡了一下——那一处就是该改的地方。欢迎标出来。