意图债：隐藏的技术负债第三维

技术债存在于代码里。认知债存在于脑子里。意图债存在于你可能从未写下的制品中：系统构建方式的目标、约束和理由。如果运气好，这些内容可能散落在团队文档或讨论中，但通常不完整。这是唯一一种 agent 无法为你偿还的债务，而 agentic engineering 使它成为代价最高的那种。

债务存在的三个地方

Margaret-Anne Storey 的三层债务模型提供了思考软件健康状况的清晰方式。三种债务模型分别是技术债、认知债和意图债。

技术债存在于代码中。它是实现选择的累积，使得系统之后更难改动：纠缠的模块、截止期限下的快捷方案、泄露的抽象。我们几十年来一直理解这种债务。你能从缓慢的构建、脆弱的测试和对接触某个特定文件的恐惧中感受到它。

认知债存在于人身上。它是共享理解的侵蚀，代码存在量与任何人理解的程度之间的差距。我一直在称之为理解债务。当系统增长速度超过团队对它的心智模型增长速度时，它就会积累。你的代码可以是完美的，但你仍然可能背负严重的认知债务，因为没人能理解这份完美的代码。

意图债存在于制品中。它是外部化理由、目标和约束的缺失或侵蚀，这些内容本应解释系统为何如此构建。关键词是"外部化"。理由必须被写下来，放在团队成员、未来的你或 agent 能读到的地方，而不是存在你的脑子里。当意图债很高时，系统会从你的本意漂离，没人能说出何时或为何偏离了。

这三者是独立的，这花了我一段时间才真正理解。

你可以有低技术债却高意图债。你可以完全理解一个系统（对你来说没有认知债），而它的意图在你脑子外的任何地方都不存在（对所有人来说都有巨大的意图债）。

从内部看它们很相似，但各自的账单是分开的。

为什么意图债是 agent 无法处理的

AI 生成代码的速度比以往任何时候都快，这使技术债更便宜，也更便宜地偿还。把一个 agent 指向一个纠缠的模块，它会重构它。

认知债也会恢复，比大多数工程师预期的要容易。当你不理解系统的某个部分时，你让 agent 解释一下。因为代码仍然存在而且模型可以重新读给你，你可以按需重建部分丢失的心智模型。

意图不同。Agent 无法生成意图，因为意图是唯一必须来自你的输入。模型可以从代码中推断一个可信的理由，就像你可以猜测前一个工程师为什么做某事一样。对意图的猜测不是意图。模型不知道那个 300ms 的防抖是一个深思熟虑的 UX 决策、基准测试结果，还是某人随意输入从未再看过的数字。它会编造一个听起来有信心的理由，这比承认不知道还糟。

在三种债务中，意图债是唯一一种 agent 无法救你的。它可以写代码并恢复你的理解。"为什么"是唯一它只能杜撰的东西。

Agent 加快未记录成本的复合增长

团队多年来能够承受高意图债是因为我们把它存在脑子里和旧文档中。

当一个新人加入团队时，你不需要把所有东西都写下来，因为他们会随着时间慢慢理解意图：走廊对话、代码审查评论、"哦，我们不那样做是因为 2023 年发生过一个事故"。知识在人与人之间流动并积累。在那儿呆了四年的工程师就是意图文档，代价昂贵且有损，但它有效。

Agent 打破了这个模式。把 agent 加入团队会一夜间把它的规模翻倍，多出一些没有长期记忆的初级人员。Agent 通常从零开始每个会话。它不承载你的人类在多年内积累的任何隐含意图。你未能外部化到它能读取的制品中的任何东西，它都没有。

这改变了不记录东西的经济学。非外部化的意图过去只在偶尔付费，在入职或有人离职后。现在你每个会话都要付费，乘以每个你运行的 agent。

想象你兴高采烈地要并行化的 20 个 agent。每一个都是一个从未见过你、无法读懂你的心思、会用合理的猜测填补意图任何空白的队友。我写过的编排税一部分是意图债税。管理许多 agent 的很多疲惫感源于重新供应你从未写下的意图。

理解债论证的另一半

当我写关于认知债的文章时，我做过一个论点现在想重新审视，因为意图债使它更加尖锐。

我论证过详细的规范不是完整的答案。将规范翻译为工作代码涉及大量任何规范都无法捕获的隐含决策，而足够详细到成为程序的规范就是用更慢的语言写的程序。我仍然相信这一点。

意图债是互补的真理。

无法捕获所有意图不是不捕获任何意图的许可证。Agent 现在代你做出的隐含决策，规范永远不会列举的决策，是那些如果你不记录至少负载承载的那些，理由就会蒸发的决策。你不能写下所有东西。

你确实必须写下那些搞错了代价很高的选择背后的理由，因为没人会之后重建它们。

认知债警告你不要信任代码因为存在就是正确的。

意图债警告你不要信任理由因为代码存在就会存活。代码是答案；意图是它想要解决的问题。AI 在为你忘记写下的问题生成答案方面表现出色。

高意图债看起来是什么样的

意图债很少表现为摩擦。它表现为一种特定的无助感。

一个 agent "修复"一个 bug，通过删除一个守卫子句，没人能说那个守卫是负载承载还是遗留的，因为没有文档或提交消息曾记录它为什么在那里。

一个重构改变了用户依赖的行为。审查通过是因为 diff 看起来很干净测试是绿的，但测试只编码了之前的行为，从不编码意图。

你问为什么两个服务通过队列而不是直接调用而通话，诚实的答案是"一个 agent 建议了，看起来没问题"。那个答案是意图债，已经开始累积利息。

如果你经历过这个认知投降版本，为一个你无法重建的设计选择辩护，意图债是那个洞的团队规模、被写下来的版本。

投降关乎你在那一刻的姿态。意图债是你的一百个这样的时刻在仓库中留下来供下一个人和下一个 agent 继承的东西。

偿还意图债：将意图外部化为一流制品

我过去几个月写的几乎所有东西都结果证明是意图债管理。我没有用这个词。举动每次都一样：把意图从你的脑子里拿出来，放在 agent 可以读的某个地方。

为意图而不是实现而写规范。一个好的规范捕获目标、约束、不可商议的东西和明确的完成定义（快速、可访问、安全、令人愉悦，超越"功能正确"）。规范承载代码无法独自承载的意图。

把 AGENTS.md 当作你的意图账本，而不是你的配置。这是我一直说停止使用 /init 的原因。一个自动生成的文件描述代码是什么。一个意图文件描述团队的意图：约定、"我们不那样做是因为"、在任何单一文件中都不可见的约束。Agent 无法推断那个，而它们最需要那个。

在决策发生的地方捕获决策。轻量级决策日志（ADR）是纯意图债偿还。在你做决定的时刻记录为什么成本几乎为零。八个月后重建它，在知道的人已经跳槽后，成本高昂。Agent 使记录比以往任何时候都更便宜，所以旧借口没了。

让学习循环写意图回去。我一直倡导自我改进 agent，在会话结束时更新学习文件。同一个循环是反向运行的意图债泵：你记录的每个错误根本原因、每个"我们尝试了 X 它没有工作因为 Y"都是否则只会在你对坏午后的记忆中生活的意图。

这些都不是新工具。它们是在一个你的脑子不再是大多数工作发生地方的时代，拒绝让理由仅存在于你脑子里的纪律。

价值移动的地方

很长一段时间，软件中稀缺、有价值的东西是生成正确实现的能力。代码很昂贵，所以我们优化编写它。

AI 使代码便宜，理解是可恢复的。意图，目标、约束和理由，是唯一仍必须源于人的输入。它也是我们最不擅长外部化的，因为几十年来我们在脑子里承载它还活得好好的。

当团队是一小群人能在多年共享背景中吸收意图时，那是有效的。当半个团队是 agent 而它们每个会话都以陌生人身份开始时，那就行不通了。

技术债使你的系统难以改动。认知债使它难以理解。意图债使它难以知道系统是否仍在做你想要的东西，它是唯一一个你的 agent 无法为你付清的。那部分留给你。写下理由，因为它正在成为你能在仓库中留下的最有价值的东西。