Agentic Technical Debt

資料來源#

The Founder's Playbook: Building an AI-Native Startup

摘要#

這是 AI 建構的程式碼庫中一種特定的失敗模式，出自 The Founder's Playbook: Building an AI-Native Startup：技術債以複利方式增長而非線性累積，因為每次 agentic engineering 編碼 session 在沒有持久性規格或上下文檔案的情況下從頭重新推導基礎架構決策。結果是一個局部功能正常但「背後沒有一致心智模型的程式碼庫——不是因為任何單一部分寫得差，而是因為這些部分從未被設計為彼此契合。」這個問題往往很晚才浮現——程式碼庫運作正常，直到迭代或規模迫使全面重寫。

為何這與一般技術債不同#

一般技術債逐漸累積，可以在一個專門的衝刺中清除。工程師知道自己在哪裡走了捷徑；工作量是有界的。

Agentic Technical Debt 具有三個結構性的新特性：

漂移，而非僅是捷徑。 每次 session 的「第一性原理」推理落在略有不同的位置。程式碼庫不只包含妥協；它包含妥協之間的不一致。
在暴露之前不可見。 一個能運作的功能不會宣告它是基於什麼架構前提建構的。這種漂移只有在閱讀整個程式碼庫時才能觀察到，而創辦人通常不會這樣做，因為他們忙著出貨。
沒有自然的回饋迴路。 傳統工程團隊有共同的設計討論、程式碼審查、ADRs——這些都會建立「為什麼這樣做」的人類記憶。獨立創辦人加上 agent 兩者皆無，因此每次 session 在意圖上真正從零開始。

機制#

「如果沒有將規格和架構約束寫在 AI 能讀取的地方，每次 session 都會從頭重新推導基礎決策，而這些決策會漂移。」

每次 agentic session 開始時，agent 會從當前程式碼狀態推斷自己的結構性假設。兩次 session 讀取相同程式碼可能推斷出兩種不同的意圖（這個模式是刻意的嗎？那個抽象是約束還是巧合？）。然後 agent 基於其推斷的意圖建構下一個功能。經過數月重複，程式碼庫包含了多個交錯的「隱式架構」。

解方：持久性上下文#

該手冊的處方是將架構意圖編碼在 CLAUDE.md markdown 檔案中，Claude Code 會在每次 session 開始時自動讀取這些檔案。這些檔案作為專案層級的指令——功能上是專案的持久性「記憶」。紀律如下：

在開啟 Claude Code 之前， 先開啟 Claude（聊天）並定義你要建構的東西：核心問題、使用者、六個月規模、架構原則、要避免的依賴、有意識接受的取捨。儲存為 CLAUDE.md。
每次 Claude Code session 開始時，(1) 重新檢視範圍文件，(2) 提供模型 CLAUDE.md 上下文文件。
每次 session 結束時，用該 session 浮現的任何決策更新 CLAUDE.md。

該手冊的主張：「每次 session 五分鐘的文件記錄，是對抗架構漂移複利化為不可管理程式碼庫的廉價保險。」

債務到期時#

該手冊標記了兩個時刻，此時一般的 AI 建構債務會變成結構性負債：

MVP → 上線轉換。 生產流量、新功能和日益增長的複雜度暴露了捷徑。「那些債務開始產生利息，拖得越久不處理，修復成本就越高。」
企業審計前。 企業合約浮現合規要求（SOC 2、GDPR、HIPAA），這些在原型階段並不適用。AI 掃描有幫助，但明確不能替代合格的合規審查。

上線階段的解方是系統性架構審計（Claude Code 找出結構性弱點、測試覆蓋率缺口、重構候選項）→ Claude 分類並排序修復工作 → CLAUDE.md 更新那些在 MVP 期間只存在於創辦人腦中的架構決策。

「從頭重建」的失敗模式#

「讓 Claude Code 在沒有護欄的情況下建構，會產生一個功能正常但結構不連貫的程式碼庫，而在不連貫的程式碼庫上迭代和擴展最終是浪費時間和 token。遲早會有一個程式碼不可避免地崩潰的時刻，迫使你從頭重建。」

經濟論點：在不連貫的程式碼上迭代比從一開始維護連貫的程式碼庫花費更多 token（更長的 context window、更多重新閱讀、更多澄清）。成本主要不是人類時間——而是算力。追求零成本迭代的創辦人是在用當下的分鐘換取未來的重寫成本。

開放問題#

隨著程式碼庫演進，CLAUDE.md 能保持準確多久？該手冊提到逐 session 更新；沒有關於腐化速率的數據。
該解方假設創辦人能夠用白話表達架構。非技術創辦人（該手冊的主要受益群體）可能既缺乏詞彙也缺乏直覺來做好這件事——一個該手冊未處理的遞迴失敗。
Anthropic 的 harness-shrinkage 論點暗示 CLAUDE.md 最終可能由模型自行推斷。在那之前，這個紀律是承重的。

資料來源#

The Founder's Playbook: Building an AI-Native Startup — MVP Stage and Launch Stage chapters

Agentic Technical Debt

資料來源#

摘要#

為何這與一般技術債不同#

機制#

解方：持久性上下文#

債務到期時#

「從頭重建」的失敗模式#

相關連結#

開放問題#

相關連結#

資料來源#