意圖債務

意圖債務（Intent Debt）是 Addy Osmani 近期提出的一個軟件健康概念。他指出，技術債務生活在代碼裏，認知債務生活在人的頭腦中，而意圖債務則生活在那些你可能從未寫下的資料裏——系統之所以成為現在這個樣子，背後的目標、約束和理由。如果幸運，部分內容會散落在團隊文檔或討論裏，但往往並不完整。在智能體編程時代，這是唯一一種你的 AI 幫手無法替你還清的債務，同時也是成本最高的一種。

Margaret-Anne Storey 的三重債務模型提供了一個清晰的思考框架。技術債務存在於代碼中，是那些讓系統日後更難修改的實現選擇，比如糾纏不清的模塊、趕工時的捷徑、泄漏的抽象。認知債務存在於人身上，指共享理解的流失，也就是代碼量與人能理解的程度之間的鴻溝。即便代碼本身無可挑剔，團隊也可能揹負沉重的認知債務，因為沒有人真正理解那些“完美”的代碼。意圖債務則存在於文檔和工件中，指外部化的理由、目標和約束缺失或模糊。關鍵在於“外部化”——理由必須寫下來，讓同事、未來的你或智能體能夠讀到，而不是隻存在某人的腦子裏。

這三種債務相互獨立。你可以擁有低技術債務卻揹負高意圖債務；你也可以自己完全理解系統，但意圖只存在於你的大腦中，對其他人來説就是巨大的意圖債務。它們從內部感受相似，但每一項都單獨向你收費。

為什麼意圖債務是智能體無法幫忙的那種？AI 生成代碼的速度比以往更快，這讓技術債務變得更容易承擔，也更容易償還；讓智能體去重構一個混亂的模塊，它就能完成。認知債務也可以得到恢復，當你無法理解系統的一部分時，讓智能體解釋一下，它可以把代碼讀給你聽，從而重建部分丟失的 mental model。但意圖不同。智能體無法生成意圖，因為意圖是必須來自你本人的輸入。模型可以從代碼中推測出看似合理的理由，就像你能猜測前一位工程師為什麼這樣做一樣，但猜測不等於真正的意圖。模型不知道那個 300ms 的 debounce 是有意的 UX 決策、是基準測試結果，還是某人隨手輸入之後再也沒碰過的數字。它會編造一個聽起來自信的理由，這比承認自己不知道更糟糕。

智能體讓未記錄的成本以更快的速度複利。過去，團隊可以長期忍受高意圖債務，因為信息可以靠人際交流傳遞：走廊裏的對話、代碼評審的評論、“2023 年出事之後我們就不這麼做了”等等。知識在人與人之間流動並沉澱。一個待了四年的工程師本身就相當於活體意圖文檔，雖然昂貴且有損耗，但至少有效。智能體打破了這種模式。把智能體加入團隊，等於一夜之間讓團隊規模擴大一倍，而且新增的都是沒有長期記憶、每次會話都從零開始的“新人”。任何你沒有外部化到它可讀工件中的隱性問題，它都無法得知。這改變了“不寫下來”的經濟賬。過去，未外部化的意圖只在入職或有人離職時偶爾讓你付出代價；現在，每次會話都得付，而且還要乘以智能體的數量。你所熱衷的 20 個並行智能體，每個都像從未見過你、無法讀懂你心思的隊友，會把你遺留的理由空缺統統用合理的猜測填上。

那麼應該如何償還？幾乎可以説，把意圖從腦子裏拿出來，放到智能體可讀的地方。首先，寫規格時記錄意圖而非實現細節：目標、約束、不可妥協的底線，以及明確的“完成”定義。其次，把 AGENTS.md 當成意圖賬本，而不是配置文件；別用 /init 自動生成一個只描述代碼現狀的文件，而要讓它描述團隊的真實意圖、約定和隱藏約束。再次，在決策發生時記錄決策，輕量級 ADR 是純粹的意圖債務清償工具。最後，讓學習循環把意圖寫回去：讓智能體在會話結束時更新 learnings 文件，把“我們試過 X，因為 Y 沒成功”這類經驗記錄下來，否則它們只會存在於你對糟糕下午的記憶裏。

軟件行業中稀缺且有價值的東西曾經是寫出正確實現的能力，代碼昂貴，所以我們為編寫而優化。AI 讓代碼變得廉價，理解能力也可以通過工具恢復。而意圖——那些目標、約束和理由——仍然必須由人類產生，偏偏它又是我們最不擅長的外部化對象。過去團隊只有幾個人時，這還可行；但當團隊的一半是每次會話都像陌生人一樣的智能體時，就行不通了。技術債務讓系統難以更改，認知債務讓系統難以理解，意圖債務則讓你難以判斷系統是否還符合最初的期望。它是三者中唯一無法由你的智能體代為償還的，這部分必須留給你自己。把“為什麼”寫下來，因為它正在成為你可以在代碼倉庫裏留下的最有價值的東西。