Intent Debt（意图债）

[!info] 知识库定位 这是一篇 权威概念页，用于作为「意图债」的统一解释入口。 概念源自 Margaret-Anne Storey 的 Triple Debt Model（三重债模型），Addy Osmani 在 agent 语境下展开（原文）。首次在知识库中沉淀，并统一了知识库里「软件债」的命名框架。

[!abstract] 一句话定义 意图债（intent debt）是软件三重债模型中的第三种债——它活在「你从未写下的工件」里：那些解释系统为什么是这样、要满足什么目标与约束的理由。它是唯一一种 agent 帮你还不了的债（代码它能写、理解它能恢复，但「为什么」只能由你提供），也是 agent 时代变得最贵的一种。

为什么需要它？

团队过去能长期容忍高意图债，靠的是隐性知识在人脑间慢慢传递：走廊对话、code review 评论、「我们不那样做因为 2023 年那次事故」——资深工程师本身就是意图文档。贵、有损，但 work。

Agent 打破了这个模型：把 agent 带入团队，就像一夜之间用「无长期记忆的全 junior」翻倍团队规模。Agent 每次会话冷启动，不带团队积累的隐性意图。于是「不把意图写下来」的成本从「偶尔付」（入职、离职）变成「每会话 × 每 agent」。没有这个词，这种「代码能跑、我也懂，但为什么这么设计只活在某人脑子里」的缺口无从命名、无法偿还。

核心直觉

[!tip] 三重债模型：债住在三个不同的地方 Margaret-Anne Storey 的三重债模型把软件健康拆成三种互相独立的债：

债类型	住在哪	是什么
技术债	代码里	实现选择的累积，让系统更难改
认知债（= 理解债）	人脑里	共享理解的侵蚀——代码量 vs 人类理解量的鸿沟
意图债	从未写的工件里	缺失/侵蚀的「外部化理由」——系统为什么是这样

[!warning] 关键洞见：意图债是 agent 唯一帮不了你的债

• 技术债：agent 能 refactor 还（指向纠缠模块，它能重构）。
• 认知债：可恢复——你不懂某段，让 agent 读代码解释给你，心智模型能部分按需重建。
• 意图债：agent 结构性无力偿还。意图是必须来自你的唯一输入。模型能从代码推断一个看似合理的理由（就像你猜前任工程师为什么那么做），但对意图的猜测不是意图。它会自信地编一个理由（300ms debounce 是刻意的 UX 决定？benchmark 结果？谁随手打的数？），这比承认「不知道」更糟。

一句话：Code is the answer. Intent is the question the answer was supposed to be solving.（代码是答案，意图是那个本该被解决的问题）——而 AI 极擅长给你「你忘了写下来的问题」的答案。

它是怎么工作的？

流程图：三重债 × agent 的偿还能力

flowchart TD
    subgraph Triple["三重债模型（Margaret-Anne Storey）"]
        T["技术债<br/>住在代码里"]
        C["认知债 = 理解债<br/>住在人脑里"]
        I["意图债<br/>住在从未写的工件里"]
    end
    T -->|"agent 能 refactor 偿还"| TA["✅ agent 可还"]
    C -->|"agent 能读代码解释<br/>按需恢复心智模型"| CA["✅ 可恢复"]
    I -->|"意图必须源自你<br/>agent 只能 fabricate 编造"| IA["❌ agent 无法还"]

为什么 agent 让意图债复利更快

• 隐性知识传递模型失效：过去 intent 靠人传人（有损但 work）；agent 是「每次会话都是陌生人」的协作者，读不到任何没写进工件的意图。
• 成本结构反转：未外部化的意图，成本从「偶尔付」变成「每会话 × 每 agent」。你并行的 20 个 agent，每个都是「没见过你、读不了你心思、会自信地用合理猜测填满你意图每个空洞」的队友。
• 编排税 部分就是意图债税：管理多 agent 之所以累，很大一部分是在反复补充你从没写下的意图。

关键组件 / 核心要素

与相关概念的关系

[!info] vs Comprehension Debt（理解债 = 三重债里的认知债） 两者是同一三重债模型的互补项，Addy 原文明说「cognitive debt is the thing I’ve been calling comprehension debt」。comprehension 的论点是「别因代码存在就信它对」；intent 的论点是「别因代码存在就信它的理由还在」。前者关注「能不能读懂」，后者关注「为什么这么做」是否还留有记载。

[!note] 是 Cognitive Surrender 的团队规模版 认知投降是你当下的 posture（放弃构造独立观点）；意图债是 100 个这样的时刻之后留在 repo 里的东西，给下一个人和下一个 agent 继承。一个是瞬间的姿态，一个是累积的负债。

[!tip] 被 Harness Engineering 的工件实践应对 Harness Engineering 的 AGENTS.md、decision log、acceptance criteria，本质都是「把意图外部化成 agent 可读的一等工件」——正是偿还意图债的核心手段。

典型应用场景

• agent 替你做隐式决策时——边界情况、数据结构、错误处理、性能取舍、交互模式，这些 spec 永远列不全的决策，其理由若不记下就蒸发。
• 团队引入 / 扩充 agent——冷启动场景，agent 读不到任何没写下的意图。
• 长期维护的代码库——意图债是复利债，且「8 个月后重建 why」的成本远高于「决策当下记一笔」。
• 多 agent 并行——每个 agent 都需要同一份意图供给，不写下来就得逐个反复喂。

常见误解与陷阱

[!danger] ❌ 误以为：我自己完全懂，就没有意图债 ✅ 实际上：三重债独立。你可以对自己零认知债（你完全懂），同时该系统的意图只存在你颅骨内——对队友、对未来你、对每个 agent，都是巨大的意图债。「我懂」不等于「意图被外部化了」。

[!danger] ❌ 误以为：三种债其实是一回事 ✅ 实际上：它们是三张不同的账单。代码可以 pristine（低技术债）+ 你完全懂（对你零认知债）+ 系统意图只在你脑中（对所有人高意图债）——三者可以同时成立。

[!danger] ❌ 误以为：既然捕获不了所有意图，写不写无所谓 ✅ 实际上：「不能全捕获」≠「一个都不捕获」。agent 替你做的隐式决策里，承重的那些（错了代价大的）必须记下 why——因为它们是事后没人能重建的部分。comprehension debt 说「别信代码存在就正确」，intent debt 说「别信代码存在理由就还在」。

[!danger] ❌ 误以为：用 /init 自动生成 AGENTS.md 就够了 ✅ 实际上：自动生成的文件描述代码是什么；意图文件描述团队意味着什么——约定、「我们不这样因为」、不可见的约束。后者才是 agent 推断不出、又最需要的部分。所以 Addy 反复说「别用 /init」。

如何偿还：把意图外部化为一等工件

核心动作只有一句：把意图从你脑中拿出来，放到 agent 能读到的地方。

1. 为意图写 spec，不是为实现写 spec——好的 spec 是目标、约束、不可妥协项、done 的明确定义（fast / accessible / secure / delightful，而非仅「功能正确」）。
2. 把 AGENTS.md 当意图账本，而非 config——写约定、「我们不这样因为」、不可见约束（这正是本知识库 CLAUDE.md、各 SKILL.md 在做的事）。
3. 在决策发生处捕获——轻量 ADR / decision log 是纯意图债偿还；决策当下记 why 成本极小，8 个月后重建成本巨大。
4. 让学习循环把意图写回——self-improving agent 在会话末更新 learnings file，把「试了 X 因为 Y 不行」记下来，否则只活在某个糟糕下午的记忆里。

延伸阅读

• 想看原始论证 → The Intent Debt — Addy Osmani（本文主要来源，引入三重债模型）
• 想看互补的那半边 → Comprehension Debt（理解债 = 认知债，三重债的另一项）
• 想看 agent 时代它为什么变贵 → Orchestration Tax（编排税部分是意图债税）· 笔记-loop-engineering（Skill 原语的本质就是意图外部化）
• 想看工件实践 → Harness Engineering（AGENTS.md / decision log / acceptance criteria）

关联笔记

前置知识：技术债 · Comprehension Debt 同族概念：Comprehension Debt（三重债·认知债）· 技术债（三重债·技术债）· 三重债模型（Triple Debt Model，待建） 应用场景：Harness Engineering（意图外部化的系统实践）· 笔记-loop-engineering（Skill = 意图写在外面） 学习来源：笔记-loop-engineering（首次在知识库中被引用）