Agentic Technical Debt

資料來源#

• OpenAI Codex lead on the new shape of product work
• The Founder's Playbook: Building an AI-Native Startup

摘要#

The Founder's Playbook: Building an AI-Native Startup 描述了一種 AI 建構的程式碼庫中特有的失敗模式：技術債務不是線性累積，而是會複利增長，因為當不存在持久化的規格或 context files 時，每次 agentic-coding 工作階段都會從頭重新推導基礎架構決策。結果是一個各部分都能運作、卻「背後沒有一致的心智模型；不是因為任何單一部分很糟，而是因為這些部分從未被設計成彼此契合」的程式碼庫。問題往往很晚才浮現——在 iteration 或 scale 迫使整個程式碼庫重寫之前，它都能正常執行。

這與一般技術債務有何不同#

一般債務會逐步累積，也可以透過專門的 sprint 清理。工程師知道自己在哪裡採取了哪些捷徑；工作範圍是有界的。

Agentic technical debt 具有三項結構上全新的特性：

1. 漂移，而不只是捷徑。 每個工作階段的「first principles」推理都會落在略有不同的位置。程式碼庫不只包含妥協；還包含妥協之間的不一致。
2. 在問題顯現前都不可見。 一項能運作的功能不會揭示它所依據的架構前提。只有讀完整個程式碼庫才能觀察到這種漂移，而 founder 通常不會這麼做，因為他們正在持續交付。
3. 沒有自然的 feedback loop。 傳統 engineering team 擁有共同的設計討論、code review、ADR——這些都會建立「為什麼要這樣做」的人類記憶。solo founder + agent 兩者皆無，因此每個工作階段確實都會從意圖的零點開始。

機制#

「如果沒有把 specs 與 architectural constraints 寫在 AI 能讀到的某個地方，每個工作階段都會從頭重新推導基礎決策，而這些決策會逐漸漂移。」

每個 agentic 工作階段都始於 agent 從目前的程式碼狀態推斷自身的結構假設。讀取相同程式碼的兩個工作階段，可能推斷出兩種不同的意圖（這個模式是刻意的嗎？那個 abstraction 是 constraint 還是巧合？）。接著，agent 會根據推斷出的意圖建構下一項功能。數月重複下來，程式碼庫中便交錯存在多個「隱含架構」。

補救措施：持久化 context#

playbook 的處方，是把架構意圖編碼在 CLAUDE.md markdown 檔案中，讓 Claude Code 在每次工作階段開始時自動讀取。這些檔案扮演 project-level instructions 的角色——實際上是專案持久化的「memory」。具體做法如下：

1. **開啟 Claude Code 之前，**先開啟 Claude（chat），定義你要建構的內容：核心問題、使用者、六個月的 scale、架構原則、要避免的 dependencies，以及有意識接受的 tradeoffs。將其儲存為 CLAUDE.md。
2. **開始每個 Claude Code 工作階段時，**先 (1) 重新檢視 scope document，再 (2) 將 CLAUDE.md context document 提供給 model。
3. **結束每個工作階段時，**更新 CLAUDE.md，記錄該工作階段浮現的任何決策。

playbook 的主張是：「每個工作階段花五分鐘做文件化，是防止架構漂移複利成為無法管理程式碼庫的廉價保險。」

債務成熟時#

playbook 指出兩個時刻：一般的 AI 建構債務會變成結構性負擔：

• MVP → Launch transition。 Production traffic、新功能與日益增加的複雜度會暴露捷徑。「那項債務開始產生利息，而越久不處理，修復成本就越高。」
• Pre-enterprise audit。 Enterprise contracts 會暴露原型階段不適用的 compliance requirements（SOC 2、GDPR、HIPAA）。AI scans 能提供協助，但明確地不能取代合格的 compliance review。

Launch-stage 的補救措施是系統化的架構 audit（Claude Code 找出結構性弱點、test-coverage gaps、refactoring candidates）→ Claude 進行 triage 並排序 remediation → 更新 CLAUDE.md，記錄 MVP 階段只存在於 founder 腦中的架構決策。

「從頭重建」失敗模式#

「讓 Claude Code 在沒有 guardrails 的情況下建構，會產生一個功能完整但結構不一致的程式碼庫；而在不一致的程式碼庫上 iteration 與 scale，最終只是在浪費時間與 tokens。遲早會出現程式碼不可避免地崩潰、迫使你從頭重建的時刻。」

經濟層面的論點是：從一開始就維護一致的程式碼庫，所需 tokens 少於在不一致的程式碼庫上 iteration（更長的 context、更多重新閱讀、更多 clarification）。成本主要不是 human time——而是 compute。追求零成本 iteration 的 founder，是用當下的幾分鐘換取未來的 rewrite 成本。

相關連結#

• AI-Native Startup Lifecycle — MVP 與 Launch 階段的主要危險
• Deep Modules for Agents — Ousterhout-style deep modules + persistent-context discipline 是架構上的反作用力；Matt Pocock 的 Sandcastle pattern 是一個具體實例
• Claude Code Best Practices — Anthropic 對 CLAUDE.md 的官方指引；playbook 將同一套 discipline 定義為 founder survival，而不只是 best practice
• Claude Code — 這項債務累積的工具
• Zero-Friction Scope Creep — companion failure mode；scope creep 會更快累積債務
• Harness Shrinkage as Models Improve — counter-pressure：如果 harness（包括 session-context plumbing）縮小，CLAUDE.md 也可能需要演化
• Context Window Smart Zone — CLAUDE.md 必須放進 smart zone；過長的 context files 會成為自身的問題
• Design Concept Grilling — Matt Pocock 的 grill-me pattern 在程式碼之前先抵達 Brooks 的「design concept」，與 CLAUDE.md-as-architectural-context 互補
• Founder as Agent Orchestrator — non-technical founder pipeline 提高了風險：最能辨識問題的 founder，往往最無力撰寫能防止這項債務的架構 context
• Problem-Solution Fit Discipline — MVP 階段的另一項危險；epistemic discipline（建構前先驗證）與 architectural discipline（建構前持久化 context）都是承重結構
• Agentic Work Systematization — 未 systematized 的 agent 使用，就是從零重新推導／意圖債務的失敗模式；skills 是 persistent-context antidote——但腐朽、未維護的 skills 本身也會成為債務表面，因為 conventions 會漂移
• Unknowns as the Agentic Bottleneck — implementation-notes.md 中的 Deviations log 是在執行中償還意圖債務：agent 記錄迫使它偏離計畫的 edge cases，讓下一個工作階段不必重新推導

待解決的問題#

• CLAUDE.md 隨著程式碼庫演化，能維持準確多久？playbook 只概略提到逐工作階段更新；沒有關於 rot rate 的資料。
• 這項補救措施假設 founder 有能力以白話表達架構。非技術 founder（playbook 標題所指的主要受益群體）可能既沒有詞彙，也沒有直覺把這件事做好——這是 playbook 未處理的 recursion failure。
• Anthropic 的 harness-shrinkage thesis 暗示，CLAUDE.md 最終可能會由 model 自行推斷。在那之前，這套 discipline 仍是承重結構。

相關連結#

• Code as Source of Truth — Fiona Fung 對抗這項債務的正向方案：將 specs/skills 納入 repo，讓 context 保持最新，並讓 Claude 能驗證 spec drift，而不是讓每個工作階段重新推導
• Harness Shrinkage as Models Improve — CLAUDE.md 是可能最終由 model 推斷的 harness asset；在那之前，persistent context 是對抗複利債務的 antidote
• Founder as Agent Orchestrator — recursion problem：非技術 founder 可能缺乏撰寫有效 CLAUDE.md 的詞彙
• Loop Engineering — Osmani 的意圖債務是從 loop 角度看待的同一種複利漂移機制：沒有 skills，loop 會「每個 cycle 都從零重新推導整個專案」，每個工作階段都用自信的猜測填補意圖缺口；skills（寫在外部的意圖）就是 antidote，正如這裡的 CLAUDE.md
• Outsource Your Thinking, Not Your Understanding — 認知上的孿生概念：理解債務（存在的程式碼與你理解的內容之間的落差）是這種架構債務在理解層面的對應物，而兩者都會以 agentic-coding 的速度複利增長
• Acceleration Whiplash — 同一種複利機制在產業規模上的量測；Faros AI 的「context engine」（從程式碼庫如何演化而非其目前狀態推導意圖）是 CLAUDE.md 補救措施的組織規模版本
• AI as Primary Author — 沒有持久化意圖的 AI author 會在每個工作階段重新推導架構；這項債務就是該 authorship/accountability gap 的結構性成本
• Andrew Ambrosino — 關於 complexity-ratchet 的 frontier-lab 報告：model 會增加程式碼、卻不擅長刪除，阻礙 unsupervised development
• Vibe Coding vs. Agentic Engineering — deletion gap 正是「loops are so last week」尚未演變成 fully-unsupervised autonomous development 的原因
• Review as the Control Point — 理解債務是這項架構債務在 CMU code-review theory 中的認知孿生：低 review depth + code opacity 會累積它，並餵養侵蝕 maintainability、ownership 與未來 review skill 的 reinforcing loops——即使 review depth 維持高水準，它仍會累積（「品嚐菜餚，而不是閱讀食譜」）

複雜度棘輪：model 會增加，卻很少刪除（Ambrosino）#

founder's-playbook 的說法關於漂移（每個工作階段以不同方式重新推導意圖）。Andrew Ambrosino（OpenAI Codex）則從 frontier-lab 角度指出第二個彼此正交的機制：model 預設會增加複雜度，而且不擅長刪除程式碼。

「目前所有 model 都面臨的一件事，是它們通常會增加複雜度。如果任何公司的 research team 正在聽——請讓 model 更擅長刪除程式碼。」

這是方向性偏誤，不只是 inconsistency：任由 agent 執行，它增加 abstraction、guards 與程式碼的速度會快於刪除它們，因此複雜度在每個工作階段都會向上棘輪。這正是 Ambrosino 認為要讓 development「完全進入 autopilot」的具體障礙（unsupervised loops）——他提出「夜間進來替程式碼庫做 garbage collection，把它清理乾淨」作為期望的能力，正因為預設的漂移方向是增加程式碼，而不是減少。playbook 的補救措施是 persistent context（對抗漂移）；frontier 問題則是缺失的能力（model 無法可靠地簡化）。在 autonomous development 值得信任之前，兩者都必須解決；一間 first-party frontier lab 已報告 deletion gap 尚未解決。

資料來源#

• The Founder's Playbook: Building an AI-Native Startup — MVP Stage 與 Launch Stage chapters
• OpenAI Codex lead on the new shape of product work — Ambrosino：「model 通常會增加複雜度……請讓 model 更擅長刪除程式碼」