【2026 最新】Cognitive Debt 是什麼？用 Comprehension Budget 擋下 AI 大型 PR

你請 AI 幫忙加一個功能，去泡杯咖啡，回來看到幾十個檔案一起改了。測試是綠的，畫面也能動；但同事問「資料從哪裡進來、哪個錯誤會重試、出事怎麼退回去」，你只能重新打開 Claude 或 ChatGPT 問一次。本文把這個能力落差稱為 Cognitive Debt（研究也使用 Comprehension Debt 等名稱）；Comprehension Budget 則是在合併前擋住新債的容量閘門。

2026 年 8 月，一名匿名開發者在 Reddit 自述一天提交三個、每個約 20,000 行的 AI PR。貼文沒有提供 repository、diff 組成或獨立查核，20,000 也不是科學門檻；真正值得處理的是它提出的問題：當產生程式碼的速度超過人類理解速度，誰還能接管？

這篇專為剛開始用 AI coding agent 的開發者與小團隊寫。我不要求你把每一行重新手打，而是帶你建立一套可複製的合併閘門：先寫 intent、限制變更範圍，再做 explain-back、冷啟動除錯與 recovery drill，最後用 learning ledger 決定這個 PR 應該全收、暫停補證據、拆單，還是拒收。

先說結論

• Cognitive Debt 描述存量：系統已交付的能力，超過團隊能解釋、驗證與接手的能力。
• Comprehension Budget 控制流量：它不是行數配額，而是團隊在合併前能完成「解釋、除錯、恢復、交接」的最大變更範圍。
• 超過預算不等於功能不能做。先按行為、依賴與風險切成能獨立成立的 PR；切不開、說不清，或沒有可接受的 recovery，才拒收。
• 測試通過只是入場券。高風險邏輯的簽名者，必須能在沒有原聊天紀錄的情況下接手。

Cognitive Debt 與 Comprehension Budget 有什麼不同？

Cognitive Debt ＝ 已交付的系統能力－團隊能解釋、驗證與接手的能力

程式碼主權 ＝ 能解釋 × 能除錯 × 能恢復 × 能交接

Comprehension Budget ＝ 團隊在合併前，能把這四把鑰匙逐一驗完的最大變更範圍。

上面是記憶公式，不是經研究驗證的心理量表或代數模型。可以把 Cognitive Debt 想成水庫裡已經累積的水，把 Comprehension Budget 想成入口閘門。前者問「現在欠多少理解」，後者問「這一批變更進來前，我們有沒有容量驗完」。乘號只是提醒：高風險變更少一項接管能力，就留下明確缺口。你也許能說明 happy path，卻不知道 timeout 後會不會重複扣款；也許能修 bug，卻沒有可行的恢復方式；也許本人懂，休假後卻沒人能接手。這就像房子看起來蓋好了，但關鍵鑰匙只有承包商手上。

本文把既有工程實務整理成 Comprehension Budget 這個名稱，不把它宣稱成通用度量。Google 的 code review 指南明說，變更大小沒有硬性公式；一個自足、只處理一件事的 change 才是核心，行數、檔案數與 reviewer 的既有脈絡只是警報器。GitHub 的 AI-generated code review 指南也把測試與靜態分析放在前面，接著要求核對 intent、架構、依賴與 AI 特有的失敗。這套 budget 做的，是把要求轉成一次合併前能回答的 ownership test。

為什麼 AI 寫得越快，Cognitive Debt 越容易累積？

Simon Willison 把瓶頸描述成 cognitive capacity：agent 能更快長出功能，人卻沒有同步增加理解整個系統的容量。他借用「conceptual integrity」提醒，軟體若不斷加蓋互不相干的房間，最後每個房間都能用，整棟房子卻沒有人說得清。他文中的行數與倍數是實務估計，不是經實驗驗證的門檻。

研究訊號也值得謹慎看。2026 年一項以 207 位大學生、621 篇自陳反思日誌、八週專案為材料的單一課程質性研究，作者從日誌歸納並命名出黑箱接受、脈絡錯配、dependency-induced atrophy 與跳過驗證等 comprehension debt 模式；把 AI 當理解鷹架則是緩解模式。另一項以 15 位研究生做的 brownfield programming 實驗發現，Copilot 條件下任務表現改善，但整體理解分數沒有顯著改善；其中 verification-loop 行為與理解呈強相關，作者也不認為 AI 必然傷害理解。兩項研究都有學生、小樣本或自陳資料限制，相關也不等於因果，不能直接外推所有職場團隊。它們支持的是「做得出來」與「建立理解」要分開驗；沒有一項直接測試本文五道閘門能否降低事故或維護成本。

Comprehension Budget 的 5 道合併閘門

五道閘門是五個必須有答案的問題，不是每個變更都跑同樣重的儀式。低風險 generated data 或可信 codemod 可以抽樣與驗生成器；金流、權限、個資、migration、併發與外部副作用則要加深測試、專家 review 與恢復演練。單人專案可以用隔日 fresh checkout 驗 future-self，但不能把它說成獨立交接；不可逆操作也不硬寫假 rollback，而要準備 disable、補償或 roll-forward。

① Intent Contract：「先決定不能外包的事」

痛點：AI 很會補完模糊需求，也很容易順手多做。解法：在生成程式碼前先寫 intent；低風險小改一段即可，高風險多檔變更再展開成一頁。至少包含目標、non-goals、輸入輸出、不可破壞的 invariant、允許的新依賴、owner 與 recovery 入口。AI 可以提出初稿，但產品與架構取捨要由負責的人確認，不能在 diff 出現後才倒推。

如果用 Claude Code，截至 2026 年 8 月 21 日，官方 permission-mode 文件提供 claude --permission-mode plan：Claude 可讀檔、執行用於探索的 shell command 並寫計畫；一般 session 會阻擋 source edit 直到你批准計畫，可用 bypassPermissions 的 session 例外，命令是否直接執行也取決於分類器與權限設定。工具不是重點；你也可以用任何 agent，先下這句：只讀專案，列出 intent、non-goals、受影響依賴、風險與可拆分的行為切片；不要寫程式。 驗收方式很簡單：人先修正這一頁，再允許實作。

② Diff Budget：「不是幾行，而是一次能懂幾件事」

痛點：只設 500 行上限，agent 可以把大改動壓成難讀的一行，也可能讓自動產生的 lockfile 白白吃滿額度。解法：先用 git diff --stat 和 git diff --name-status 看表面，再按四個維度盤點：改了幾個使用者可感知行為、跨了幾個信任邊界、加入幾個陌生依賴、需要幾個 owner 才能完整說明。

起步規則可以很樸素：一個 PR 只承諾一個主要行為；高風險未知要驗證，其他未知要有 accepted-risk、owner 與期限；每個高風險路徑都有 owner；每一層能在它宣告的 parent baseline 上建置、測試與恢復，整個 stack 再做整合驗證。Google 建議按自足變更拆小，並把 refactor 與功能改動分開；GitHub 也說明 stacked PR 能把大型變更切成有依賴順序的小層，但截至查核日仍是 public preview，且每層仍需要完整脈絡與整合驗證。超額時先拆行為與風險，不是機械切檔案。

Budget 要有期間與單位。以一個 review window（例如一週）盤點可排程的 accountable reviewer-hours 與高風險 WIP slots；估完 explain-back、cold debug、專家 review 和 recovery drill 所需容量後，只有餘額足夠才讓 PR 進 merge queue。若阻塞未知沒有 owner／期限，或所需容量超過本期餘額，先 HOLD 或 SPLIT。不要照抄別人的小時與 slot 數；先記自己的 review lead time、reopen／revert 和演練結果，再調下一期預算。

③ Explain-back：「關掉聊天紀錄，自己說一次」

痛點：AI 產生的摘要也可能和程式一起錯。解法：作者關掉 agent 對話，只看 intent、依賴圖與程式碼，用自己的話走一次：入口 → 狀態變化 → 外部副作用 → 失敗路徑 → 保護機制。Reviewer 再追問兩題：「哪個假設一改就會壞？」與「哪個測試會先叫？」

通過的標準不是講得流利，而是說法能被程式與測試指到。若作者只能請 AI 再解釋一次，把該元件記進 learning ledger，縮小 PR 或換有脈絡的 owner。這是舊版四道還債閘門保留下來的核心；本次更新把它前移到合併前的容量管理，避免先累積 Cognitive Debt 才補救。

④ Cold-start Debug：「沒有作者提示，還找得到根因嗎？」

痛點：同一段對話裡的作者與 agent 共享太多隱藏脈絡，容易把「記得答案」誤當成「系統可維護」。解法：找另一位 reviewer，或至少隔一晚開全新 session；只給 intent、乾淨 checkout、固定失敗案例與允許使用的觀測工具，不給原 prompt。請對方重現失敗、指出最短因果路徑，並說明哪個觀測能推翻自己的判斷。

對新增行為或 bug fix，可觀察的通過條件是：對方能從失敗訊號找到責任模組、提出一個可逆的小修正，且新增測試真的會在舊碼上失敗。純 refactor、刪除、generated artifact 或 codemod 則可改用等價性、property 或 generator 證據。若只能靠作者口述，代表 shared understanding 還沒形成。大型 repo 的 blast radius 與冷審查細節，可接著看 Claude Code 大型 Repo 安全改版。

⑤ Recovery + Handoff：「恢復得了，也交得出去」

痛點：「需要時再 revert」不是演練。GitHub 的 Revert 會建立一個反向 PR；若發生 merge conflict，或原 PR 不是在 GitHub 上合併，按鈕可能不能直接完成 revert。解法：合併前就在本機或 staging 走一次 recovery drill：可逆程式指定 commit 或 feature flag，資料與外部副作用則明寫 migration down、disable、補償或 roll-forward，執行關鍵測試，再把實際步驟寫進 PR。Git revert 不會撤回已寄出的信或已送出的付款。

團隊專案最後填 owner 與 backup owner。GitHub 的 CODEOWNERS 能自動請相關人員 review，配合 protected branch 還能要求 code owner approval、status checks 與最新 push 的他人批准；但路由到一個名字，不等於那個人已經理解。Handoff 要讓 backup owner 在沒有原聊天紀錄時完成 explain-back，並指出適用的 recovery 入口；單人專案則保留 future-self drill 與尚未獨立覆核的風險。

完整案例：同一個「收據重試」功能，為什麼會全收、拆 PR、拒收？

先固定 intent：從唯讀來源查詢收據 PDF，遇到 TimeoutError 時最多嘗試三次；永久錯誤不重試；不加第三方套件、不建立寫入或外部副作用。AlphaLab 這次用 Python 3 標準函式庫做了可重跑小專案，執行 python3 -m unittest -v，三個測試分別覆蓋「第一次 timeout 後成功」「永久錯誤只呼叫一次」「達三次上限後停止」，結果全數通過。這只驗證小範例的三個行為；下面 A／B／C 是用來套用 gate 的假設情境，沒有宣稱重現人類 handoff 或 B／C 實作，也不代表任何真實收據服務的 production 結果。

結果 A｜全收：小而自足，四把鑰匙都在

變更只有唯讀 fetch function、三個行為測試與 intent。作者能說明只有 TimeoutError 進入迴圈；reviewer 能從失敗測試找到 attempts 上限；rollback 是撤回單一 read-path commit；backup owner 能重述行為。這時「全收」不是因為 diff 很少，而是這一個無副作用行為的理解證據完整。如果需求改成寄信或扣款，就必須另加 idempotency contract，不能沿用這個 ACCEPT。

結果 B｜拆 PR：功能合理，但一次跨太多邊界

第二版把查詢擴成快取，並同時加入 cache、資料庫 migration、監控 dashboard 與新告警。測試可能全綠，團隊卻需要 application、data 與 operations 三種 owner 才能回答。做法不是把 800 行平均切成四份，而是拆成：① retry contract＋測試；② behind-a-flag 的 cache path；③ cache／migration 與獨立 recovery；④ metrics／告警。每一層都能單獨驗收，下一層才有清楚基線。

結果 C｜拒收：看似省事，卻沒有人敢接手

第三版偷偷加入陌生 cache 套件、用 except Exception 吞掉所有錯誤、把完整 Email 寫進 log，測試只看「最後有成功」。即使 diff 比 B 小，也應拒收：它違反 non-goals，改變永久錯誤語意，引入未審依賴與個資風險，而且 revert 無法清除已送出的 log。先回到 intent，移除越界設計，再生成一個新的小變更；不要在失去形狀的 diff 上繼續補洞。

可直接複製：用 Comprehension Budget 擋住 Cognitive Debt

把下面貼進 .github/pull_request_template.md；GitHub 的官方文件說明了 template 的放置方式。先用人類語言填完，再讓 agent 補檔案清單與測試收據；template 本身不會強制真實性，因此任何 STOP 沒關閉，就不進 merge queue。

## Intent
- [ ] 一句話目標：
- [ ] Non-goals：
- [ ] 不可破壞的 invariant：

## Budget
- [ ] 本 PR 只有一個主要行為
- [ ] 受影響的信任邊界／依賴／owner 已列出
- [ ] 高風險陌生假設已驗證；其餘有 accepted-risk、owner、期限或 STOP

## Ownership test
- [ ] Explain-back：入口 → 狀態 → 副作用 → 失敗 → 保護
- [ ] Cold debug：另一人能重現、定位並提出可逆修正
- [ ] Recovery drill：rollback／disable／補償／roll-forward 已走過
- [ ] Handoff：owner 與 backup owner（單人則 future-self drill）能指出接管入口

## Decision
- [ ] ACCEPT：四把鑰匙齊全
- [ ] SPLIT：按行為／風險／owner 拆單
- [ ] REJECT：intent 越界、沒有可接受的 recovery 或無人能接手

Learning Ledger：把「我不懂」變成可管理工作

Learning ledger 不是心得日記，而是尚未取得哪一把鑰匙的排程。每碰到陌生 framework、資料流或假設，就留下這六欄；deadline 到了仍不能關閉，先 HOLD、補證據、重新設計、換 owner 或 split；intent 越界或沒有可接受的 recovery 才 reject。

unfamiliar:
  - component: "receipt retry policy"
    assumption: "只有 TimeoutError 可安全重試"
    evidence: "source path + failing test + trace"
    owner: "payments-team"
    deadline: "before merge"
    stop_condition: "無法證明永久錯誤只呼叫一次"
    handoff_question: "若下一版改成寄信，哪個 idempotency contract 防止重複副作用？"

如果規格本身還不穩定，先讀 Specification-First Convergence，把可被反駁的行為鎖定；如果想讓第二個 agent 專門找反例，再接 Claude＋Codex 對抗式 Reviewer。兩者都能提供證據，但最後仍由 owner 關閉 ledger。

把 Checklist 變成真正的合併規則

固定項目交給機器：build、unit／integration tests、lint、static analysis、dependency review、secret scan 與 coverage policy。GitHub protected branch 可以要求 PR、approvals、status checks、conversation resolution，以及最新可 review push 由另一人批准；若要形成硬閘門，還要檢查 admin／bypass roles，並啟用 Do not allow bypassing、指定可信的 required checks。敏感目錄再加 CODEOWNERS：

/src/payments/       @your-org/payments-team
/migrations/         @your-org/data-team
/.github/CODEOWNERS  @your-org/platform-team

需要判斷的項目留給人：intent 是否仍是對的問題、explain-back 是否能被追問、cold debug 是否真的找得到根因、recovery 是否處理了外部副作用。不要讓同一個 agent 同時寫碼、產生說明、勾完 checklist、批准自己；自動 reviewer 適合當第二雙眼睛，不是 ownership 的唯一證明。

最常見的 6 個失敗方式

1. 把行數當 KPI：大家開始壓縮、搬 generated files 或拆成沒有意義的小 PR。改看一個行為能否獨立解釋、測試與恢復。
2. 讓 AI 代答 explain-back：輸出很完整，人卻無法回答追問。要求 owner 關掉對話後重述，並指向程式與測試。
3. 把全綠測試當理解：測試可能只複製同一個錯誤假設。冷啟動 reviewer 要先預測哪個測試應該失敗，再看結果。
4. 切 PR 只按資料夾：一個使用者行為被拆到四個永遠不能單獨運作的 branch。按可成立的 vertical slice 與 recovery 單位切。
5. 只有一位英雄 owner：本人能救火，團隊仍沒有主權。團隊專案要求 backup owner 完成 handoff question；單人則留下未獨立覆核風險。
6. Checklist 劇場：每格都勾了，沒有 trace、失敗測試或 recovery 結果。每個勾選都要連到可重跑證據。

Comprehension Budget 常見問題 FAQ

1. 20,000 行一定要拒收嗎？

不以行數單獨判決。自動產生資料、刪檔或受信任 codemod 可能很大，十行權限變更也可能很危險。20,000 是停下來重做 scope review 的強烈警報，不是普世法規。

2. 測試全綠，可以跳過 explain-back 嗎？

高風險人工邏輯不能只靠全綠測試跳過。測試證明指定輸入在指定環境得到指定結果，不會自動證明需求、測試 oracle 或依賴假設正確。GitHub 的 AI code review 流程也把 functional checks 與 intent／context 核對分成不同步驟。Generated data 或可信 codemod 可以改驗 generator、規格與抽樣輸出，不必逐行口試。

3. 人一定要理解每一行嗎？

一般人寫的邏輯，assigned reviewer 應理解自己負責的範圍；generated data、lockfile 與可信 codemod 可以用不同證據。重點是明寫誰 review 哪一部分、用了什麼工具、哪些例外仍由專家覆核，而不是默默略過。

4. Explain-back 可以請 AI 先整理嗎？

可以先整理，不能代替人的最後一遍。讓 AI 產生候選依賴圖與問題清單，再由 owner 關掉對話、修正並重述；被追問時不能只貼回模型答案。

5. 一人團隊怎麼做 cold-start debug？

隔開時間與上下文。今天保存 intent、固定失敗案例與 branch，明天開乾淨工作目錄，不讀昨天的 agent transcript，先寫出根因預測再動 debugger。它不等於獨立同儕審查，但能減少短期記憶造成的假熟悉。

6. 趕 hotfix 時也要跑五關嗎？

至少保留 intent、最小 scope、針對性測試、owner 與 recovery。緊急情況可以縮短 explain-back 與 cold debug，但不能把不可逆資料操作藏在「先上再說」裡；穩定後再補完整 handoff 與 ledger。

7. 新手使用陌生技術，預算是不是永遠很小？

一開始應該較小，理解證據累積後再放大。先讓 AI 當鷹架：請它指出入口、官方文件、可觀察行為與練習題；每關掉一個 learning-ledger 假設，才提高下一個 PR 的範圍。

8. 怎麼知道這套方法有沒有幫助？

同時看結果與成本，不看勾選數。追蹤 escaped defects、reopen／revert、incident recovery time、cold reviewer 找到第一個可驗證根因的時間、handoff 結果，也記 review lead time、reviewer-hours 與誤擋比例。大型 PR 被拆分率只能當流程訊號，不能當 KPI。先記基線，再調整團隊自己的 budget。

給新手的 5 個重點

1. 先寫 intent 與 non-goals，再讓 AI 寫碼。
2. 行數只負責示警；真正的 budget 是一次能驗完幾個行為、風險與依賴。
3. 合併前，關掉聊天紀錄做 explain-back。
4. 用全新上下文重現 bug，並真的走一次 rollback、disable、補償或 roll-forward。
5. 團隊專案要讓 backup owner 接手；單人專案要留下 future-self drill 與未獨立覆核的風險。