意图债务

意图债务（Intent Debt）是 Addy Osmani 近期提出的一个软件健康概念。他指出，技术债务生活在代码里，认知债务生活在人的头脑中，而意图债务则生活在那些你可能从未写下的资料里——系统之所以成为现在这个样子，背后的目标、约束和理由。如果幸运，部分内容会散落在团队文档或讨论里，但往往并不完整。在智能体编程时代，这是唯一一种你的 AI 帮手无法替你还清的债务，同时也是成本最高的一种。

Margaret-Anne Storey 的三重债务模型提供了一个清晰的思考框架。技术债务存在于代码中，是那些让系统日后更难修改的实现选择，比如纠缠不清的模块、赶工时的捷径、泄漏的抽象。认知债务存在于人身上，指共享理解的流失，也就是代码量与人能理解的程度之间的鸿沟。即便代码本身无可挑剔，团队也可能背负沉重的认知债务，因为没有人真正理解那些“完美”的代码。意图债务则存在于文档和工件中，指外部化的理由、目标和约束缺失或模糊。关键在于“外部化”——理由必须写下来，让同事、未来的你或智能体能够读到，而不是只存在某人的脑子里。

这三种债务相互独立。你可以拥有低技术债务却背负高意图债务；你也可以自己完全理解系统，但意图只存在于你的大脑中，对其他人来说就是巨大的意图债务。它们从内部感受相似，但每一项都单独向你收费。

为什么意图债务是智能体无法帮忙的那种？AI 生成代码的速度比以往更快，这让技术债务变得更容易承担，也更容易偿还；让智能体去重构一个混乱的模块，它就能完成。认知债务也可以得到恢复，当你无法理解系统的一部分时，让智能体解释一下，它可以把代码读给你听，从而重建部分丢失的 mental model。但意图不同。智能体无法生成意图，因为意图是必须来自你本人的输入。模型可以从代码中推测出看似合理的理由，就像你能猜测前一位工程师为什么这样做一样，但猜测不等于真正的意图。模型不知道那个 300ms 的 debounce 是有意的 UX 决策、是基准测试结果，还是某人随手输入之后再也没碰过的数字。它会编造一个听起来自信的理由，这比承认自己不知道更糟糕。

智能体让未记录的成本以更快的速度复利。过去，团队可以长期忍受高意图债务，因为信息可以靠人际交流传递：走廊里的对话、代码评审的评论、“2023 年出事之后我们就不这么做了”等等。知识在人与人之间流动并沉淀。一个待了四年的工程师本身就相当于活体意图文档，虽然昂贵且有损耗，但至少有效。智能体打破了这种模式。把智能体加入团队，等于一夜之间让团队规模扩大一倍，而且新增的都是没有长期记忆、每次会话都从零开始的“新人”。任何你没有外部化到它可读工件中的隐性问题，它都无法得知。这改变了“不写下来”的经济账。过去，未外部化的意图只在入职或有人离职时偶尔让你付出代价；现在，每次会话都得付，而且还要乘以智能体的数量。你所热衷的 20 个并行智能体，每个都像从未见过你、无法读懂你心思的队友，会把你遗留的理由空缺统统用合理的猜测填上。

那么应该如何偿还？几乎可以说，把意图从脑子里拿出来，放到智能体可读的地方。首先，写规格时记录意图而非实现细节：目标、约束、不可妥协的底线，以及明确的“完成”定义。其次，把 AGENTS.md 当成意图账本，而不是配置文件；别用 /init 自动生成一个只描述代码现状的文件，而要让它描述团队的真实意图、约定和隐藏约束。再次，在决策发生时记录决策，轻量级 ADR 是纯粹的意图债务清偿工具。最后，让学习循环把意图写回去：让智能体在会话结束时更新 learnings 文件，把“我们试过 X，因为 Y 没成功”这类经验记录下来，否则它们只会存在于你对糟糕下午的记忆里。

软件行业中稀缺且有价值的东西曾经是写出正确实现的能力，代码昂贵，所以我们为编写而优化。AI 让代码变得廉价，理解能力也可以通过工具恢复。而意图——那些目标、约束和理由——仍然必须由人类产生，偏偏它又是我们最不擅长的外部化对象。过去团队只有几个人时，这还可行；但当团队的一半是每次会话都像陌生人一样的智能体时，就行不通了。技术债务让系统难以更改，认知债务让系统难以理解，意图债务则让你难以判断系统是否还符合最初的期望。它是三者中唯一无法由你的智能体代为偿还的，这部分必须留给你自己。把“为什么”写下来，因为它正在成为你可以在代码仓库里留下的最有价值的东西。