複利工程：讓程式碼庫加速而非衰退

大多數程式碼庫隨著規模增長而變慢，我的卻在加速。在建構了95個hook、44個skill和14個設定檔組成的.claude/基礎架構後，每個新功能的成本都比前一個更低，因為基礎架構承擔了更多工作。¹

重點摘要

複利工程描述的是一種程式碼庫狀態：每新增一個功能，後續功能的建構成本就會降低。我親身經歷了這個過程：我的Claude Code hook系統從3個hook起步，成長到95個。第一個hook花了一小時建構，最近的hook只需10分鐘，因為基礎架構（生命週期事件、設定載入、狀態管理、測試工具）已經存在。相反的模式——熵增工程——則描述每新增一個功能就會增加後續功能成本的程式碼庫。一個團隊在第三年比第一年交付更快，與一個逐漸停滯的團隊之間的差異，在於他們的工程決策是正向複利還是負向複利。

實踐中的複利：我的.claude/基礎架構

成長曲線

第一個hook（git-safety-guardian.sh）需要建構整個hook生命週期：理解PreToolUse事件、撰寫解析JSON輸入的bash腳本、處理錯誤情況、手動測試。第95個hook繼承了所有這些基礎架構。每個hook的所需時間降低了6倍，不是因為hook變簡單了，而是因為基礎架構承擔了更多工作。

什麼會產生複利效應

模式一致性。每個hook遵循相同的結構：讀取JSON輸入、用jq解析、檢查條件、輸出決策JSON。任何開發者（或AI代理）閱讀任何hook時都能立即辨識出這個模式。我的12模組部落格檢查工具遵循相同的一致性原則：每個模組匯出相同的介面（check(content, meta) -> findings），讓新增模組變得極為簡單。

設定驅動的行為。所有14個JSON設定檔編碼了原本寫死在程式碼中的閾值和規則。當我把deliberation共識閾值從Python中寫死的0.70移到deliberation-config.json時，我獲得了按任務類型調整的能力（安全性=85%、文件=50%），無需修改程式碼。相同的模式也驅動著我的訊號評分管線，其中可調整的權重與閾值以確定性的方式分流7,700多筆知識項目。²

測試基礎架構。最初的20個hook沒有測試。新增測試工具（48個bash整合測試、81個Python單元測試）花了兩週。此後每個hook在5分鐘內就能附帶測試一起交付，因為fixture、斷言輔助函式和測試執行器已經存在。

記憶系統。我的MEMORY.md檔案跨會話記錄錯誤、決策和模式。累積54個條目後，它防止我重複犯同樣的錯誤。hook #23中的((VAR++))bash陷阱已經防止了hook #24到#95中出現相同的bug。每個條目在未來的每個會話中都產生複利效應。³

複利模型

正向複利

工程生產力遵循複利公式：

Productivity(n) = Base × (1 + r)^n

其中r是每個功能的生產力變化率，n是已交付的功能數量。

正r值（複利）：每個功能讓下一個便宜2-5%。50個功能後：1.03^50 = 4.38倍生產力提升。

負r值（熵增）：每個功能讓下一個貴2-5%。50個功能後：0.97^50 = 0.22倍生產力，衰退了78%。

這兩條軌跡在50個功能後形成20倍的工程速度差距。⁴

我的實際數據

我的blakecrosley.com網站從單一FastAPI路由和一個HTML模板開始。九個月後：

最後一項就是複利的回報：新增一個檢查模組只需15分鐘，因為模組介面、CLI整合、測試工具和CI管線已經存在。第一個模組花了3小時，因為那些基礎架構都不存在。⁵

我自己程式碼庫中的熵增案例

複利不是自動發生的。我也經歷過熵增：

ContentMeta Schema的捷徑

我在一次會話中定義了部落格文章的ContentMeta資料類別：title、slug、date、description、tags、author、published。我沒有納入category、series、hero_image、scripts或styles。之後每次新增都需要修改解析器、更新每個使用該metadata的模板，並重新測試整個管線。三個月內的五次新增，總成本超過了一開始仔細設計schema所需的時間。這就是決策時機問題：不可逆的決策值得事前分析。

i18n快取鍵衝突

翻譯快取的快速實作使用部落格slug作為快取鍵。當同一個slug在不同語系有兩個翻譯時，快取回傳了錯誤的語言。除錯花了3小時。修復只花了15分鐘（在快取鍵加上語系前綴）。實作時省下的5分鐘捷徑，導致了3小時的除錯時間和整個系統快取鍵的架構審查。⁶

3.2GB的除錯目錄

Hook的除錯輸出累積在~/.claude/debug/中，沒有清理機制。三個月內，該目錄增長到3.2GB。我後來建構的context audit skill發現了這個問題，並清理了超過7天的檔案，但清理機制應該在第一次除錯輸出時就一起建構。

產生複利效應的實踐

一致的模式優於最佳模式

一個團隊在50個功能中使用相同的「夠好」模式，運作速度會快於針對每個功能使用各自「最佳」模式的團隊。一致性降低認知負荷、啟用自動化工具，並加速程式碼審查。⁷

我的hook系統對所有95個hook使用相同的bash模式，儘管有些hook用Python表達會更自然。這種一致性意味著任何讀過一個hook的人（或AI代理）都能讀懂任何hook。語言選擇上的次優被新hook零學習曲線的效益所抵消。

基礎架構作為第一個功能

我在blakecrosley.com建構任何產品功能之前，先建構了CI/CD管線、測試工具和部署流程。這項投資當時感覺很慢。此後每個功能都能在2分鐘內通過自動化測試完成部署。⁸

記憶宮殿模式

我的.claude/目錄就像一座「記憶宮殿」——一組為人類和AI閱讀而最佳化的結構化文件：

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

記憶宮殿之所以能產生複利效應，是因為每個新條目都豐富了未來開發會話可用的脈絡。在54個MEMORY.md條目後，AI代理會避免我已經解決過的錯誤。在95個hook後，新hook幾乎能自動編寫，因為它們遵循既定模式。越豐富的脈絡產生越貼合需求的AI生成程式碼，從而讓下一個功能更便宜。⁹

AI時代的複利

AI放大兩個方向

AI程式碼助手會加速程式碼庫已有的任何模式。我的95個具有一致模式的hook能產生優秀的AI生成hook，因為AI匹配了既定結構。一個擁有5種不同hook風格的程式碼庫會產生更差的AI生成程式碼，因為AI沒有一致的模式可以匹配。¹⁰

複利效應加倍了：一致的模式讓人類開發更快（降低認知負荷），同時也讓AI輔助開發更快（模式匹配）。不一致的模式則讓兩者都變慢。

對AI代理友善的程式碼庫

我為AI代理的使用而設計了.claude/基礎架構：

• 結構化設定（JSON，非寫死的值），代理可以程式化解析
• 一致的命名慣例（hook使用verb-noun.sh，skill定義使用SKILL.md）
• 機器可驗證的品質檢查（141個代理能自主執行的測試）——後設認知層在其之上加入自我監控
• 明確的文件（MEMORY.md、handoffs、docs/），代理在會話開始時讀取

每一項對代理可讀性的投資，都隨著AI工具變得更強大而產生複利效應。¹¹

關鍵要點

給工程師： - 追蹤程式碼庫成長過程中的「每個功能所需時間」；如果增加代表熵增，如果減少代表複利 - 在抽取抽象化之前套用三次法則：先建構兩次具體解決方案，第三次再提取可重用模式 - 每個sprint投入15-20%在基礎架構和工具改善上；複利回報在3-5個sprint內就會超過短期功能速度的成本

給工程主管： - 透過隨時間變化的每個功能前置時間來衡量工程健康度；前置時間增加代表熵增 - 將文件和測試基礎架構視為功能而非額外開銷；我的測試基礎架構投資（2週）在95個hook中已節省超過50小時

常見問題

什麼是複利工程？

複利工程描述的是一種程式碼庫狀態：每新增一個功能，後續功能的建構成本就會降低。其運作機制是把正向複利套用到工程基礎架構上：一致的模式、設定驅動的行為、測試基礎架構與逐漸累積的記憶，讓每個功能的成本隨時間下降。以每個功能3%的改善率計算，50個功能之後生產力提升4.38倍。相反的熵增工程以同樣的算式侵蝕生產力，在複利與衰退的程式碼庫之間拉開20倍的差距。⁴

AI代理如何隨著時間改善程式碼庫？

AI代理會放大程式碼庫既有的模式。模式一致時，模型能夠比對既定結構，因而產出品質優異的程式碼。我的95個hook使用完全相同的bash模式，第一個hook需要60分鐘，如今產出一個高品質的AI生成hook只要10分鐘。¹ 複利效應是雙重的：一致的模式既加快人工開發（降低認知負荷），也加快AI輔助開發（模式比對）。不一致的程式碼庫會產出較差的AI結果，因為模型沒有可靠的模式可循。¹⁰

我要如何判斷程式碼庫是在複利還是在衰退？

追蹤程式碼庫成長過程中的「每個功能所需時間」。時間增加代表熵增，時間減少代表複利。更細緻的訊號是團隊層級的每個功能前置時間隨時間的變化。我的數據顯示，新hook的所需時間在9個月內從60分鐘降到10分鐘，新檢查模組則從3小時降到15分鐘。⁵ 如果您的對應指標呈上升趨勢，代表工程決策正在負向複利。

啟動複利所需的最小投資是什麼？

三項基礎架構投資回收最快：具備自動化測試的CI/CD管線（第3個功能時回本）、解析方式一致的內容或資料管線（第5個功能時回本），以及具備共用fixture和斷言輔助函式的測試基礎架構（第5個模組時回本）。⁸ 經驗法則是每個sprint投入15-20%在基礎架構和工具改善上，複利回報在3-5個sprint內就會超過短期功能速度的成本。

為什麼一致性比最佳化更重要？

一個團隊在50個功能中使用相同的「夠好」模式，運作速度會快於針對每個功能使用各自「最佳」模式的團隊。一致性降低認知負荷、啟用自動化工具，並加速程式碼審查。⁷ 我的hook系統對所有95個hook使用相同的bash模式，儘管某些hook用Python表達會更自然。新hook零學習成本的優勢，足以彌補個別hook在語言選擇上的次佳。

參考資料