Context Engineering就是架構：650個檔案之後的心得

我的CLAUDE.md最初只有50行。六個月後，它已經發展成一個橫跨七個層級、包含650個檔案的分散式架構。這段演進過程揭示了一個事實：context engineering不是「多加幾個檔案的prompt engineering」，而是針對一種記憶會隨每個token衰減的基底所做的軟體架構設計。

Context不是設定檔。它是決定AI代理能思考什麼、記住什麼、遺忘什麼的架構基底。所有其他設計決策都是context的下游產物。以下是六個月在Claude Code上進行生產環境context engineering的成果：架構、失敗，以及最終存活下來的系統。

重點摘要

Böckeler在martinfowler.com發表的context engineering文章（2026年）¹以及Miessler的清晰思維框架²推進了這場討論，但兩者都低估了生產環境的實際需求。Context engineering需要設計一套系統，讓正確的指令在正確的時機到達代理，同時確保錯誤的指令永遠不會被載入。我的系統使用了九條規則、40個技能模組、19個代理、84個hook腳本和14個設定檔，分布在七層階層架構中。架構的精髓不在於檔案本身，而在於哪些檔案在什麼時候載入，以及什麼被排除在外。

---

Context不是一個檔案

每週都會出現的「如何撰寫CLAUDE.md」文章其實搞錯了重點。撰寫一份好的CLAUDE.md是必要但不充分的，就像撰寫好的程式碼對於建構好系統來說是必要但不充分的一樣。架構是決定元件如何互動的結構。在代理系統中，context就是那個結構。

我的第一個CLAUDE.md是一個單體式檔案：200行涵蓋了程式碼規範、專案結構、偏好設定、修正事項、開發哲學、憑證管理和活躍專案狀態。它運作了一個月。然後三件事同時發生：

1. 檔案膨脹超過300行，開始自相矛盾（規則A說「保持簡單」，規則B說「加入完整的錯誤處理」）
2. 專案A的context洩漏到專案B（iOS專用規則污染了網頁開發工作階段）
3. 代理花費token閱讀與當前任務無關的指令

這些症狀指向的是架構問題，而非文件問題：耦合、範圍洩漏和資源浪費。驅動軟體架構決策的正是同樣的力量。³

---

七層架構

經過六個月的重構，我的context系統穩定成一個七層階層架構。每一層服務於不同的目的，並在特定的時機載入：

層級	內容	載入時機	數量
1. 核心層	CLAUDE.md：開發哲學、活躍專案、修正事項	每次工作階段啟動	一個檔案，205行
2. 規則層	領域特定約束（API設計、安全性、測試、Git）	每次工作階段啟動	九個檔案
3. 技能層	可重用的知識模組，含程序與範例	按需載入（手動呼叫或由hook自動觸發）	40個目錄
4. 代理層	專門化的審查者/生成器規格	按需載入（透過Task工具）	19個檔案
5. Hook層	在生命週期事件中自動注入context	事件驅動（工作階段啟動、pre-commit、post-tool）	84個腳本
6. 設定層	數值參數（閾值、預算、上限）	由hook和技能模組引用	14個JSON檔案
7. 狀態層	即時追蹤（代理譜系、信心校準、成本）	由hook引用	36個檔案

關鍵洞察在於層級分離。規則在每次工作階段載入，因為它們具有普遍適用性。技能按需載入，因為它們是領域特定的。Hook在事件發生時觸發，因為時機至關重要。如果在工作階段啟動時載入全部650個檔案，context窗口會在代理讀到第一則使用者訊息之前就耗盡。⁴

---

塑造架構的三次失敗

失敗一：單體式CLAUDE.md

我最初的CLAUDE.md包含了iOS規則、網頁規則、API設計模式、Git慣例、憑證管理和開發哲學原則——全部放在同一個檔案裡。代理在每次工作階段都會讀取全部內容，即使當前是在建構一個永遠不會碰到SwiftUI的網頁專案。

代價： 不相關的context每次工作階段大約消耗4,000個token。經過50次工作階段，總共浪費了200,000個token在代理從未使用的指令上。

解決方案： 將領域特定的內容抽取到rules/檔案中。rules/security.md在每次工作階段載入（安全性適用於所有場景）。rules/ios-security.md僅在工作階段涉及iOS專案時才載入。Context窗口管理一文記錄了驅動此決策的token經濟學。

失敗二：過時的技能模組

我建立了一個fastapi技能模組，使用的是FastAPI 0.109的範例。三個月後，專案已經升級到FastAPI 0.115，採用了不同的模式。這個技能模組無聲地教導過時的慣例。代理產出的程式碼能運作，但與當前程式碼庫的模式不一致。

代價： 一次45分鐘的除錯過程，追蹤為什麼一個新端點使用了與其他所有端點不同的依賴注入模式。這個模式來自過時的技能模組，而非程式碼庫本身。

解決方案： 技能模組引用有版本標註的文件，並包含「最後驗證日期」。更重要的是，品質迴圈要求生成的程式碼必須匹配現有程式碼庫的模式——這是一種後設認知檢查，無論技能模組的內容如何，都能捕捉到過時技能的偏移。

失敗三：不同層級的規則互相衝突

CLAUDE.md說「偏好簡單的解決方案」。一個技能模組說「加入完整的錯誤處理，包含重試邏輯和熔斷器」。兩者各自看來都合理。放在一起，它們產生了不一致的輸出——有時極簡，有時過度工程化——取決於代理在特定回合中對哪條指令給予更高的權重。

代價： 不可預測的輸出品質。同類型的任務在不同工作階段會產生不同的品質水準，使系統變得不可靠。

解決方案： 建立明確的優先順序階層。CLAUDE.md設定原則（「偏好簡潔」）。規則設定約束（「驗證所有使用者輸入」）。技能模組設定程序（「以下是建構FastAPI端點的方法」）。當它們衝突時，越具體的層級優先：技能模組的程序在其涵蓋的特定任務範圍內，會覆寫原則的指導。這種解析方式與程式語言處理作用域的方式相同：區域覆寫全域。⁵

---

Context預算作為架構約束

Context窗口不是無限的。Claude的200K token context窗口⁶聽起來很大，直到您衡量什麼在消耗它：

消耗來源	典型token數	佔窗口比例
系統提示 + CLAUDE.md + 規則	8,000-12,000	4-6%
對話歷史	20,000-80,000	10-40%
檔案讀取（每個檔案）	5,000-20,000	2.5-10%
工具輸出（每次呼叫）	1,000-10,000	0.5-5%
技能/代理context（按需）	3,000-15,000	1.5-7.5%

Token消耗量測數據來自我在2025年8月至2026年2月間追蹤的50次Claude Code工作階段。⁷一次90分鐘的密集工作階段，光是正常的檔案讀取和工具互動就能耗盡整個窗口。Context預算迫使我們做出架構取捨：

始終載入核心開發哲學、活躍的修正事項和安全規則。三者成本低廉（佔預算的4-6%）且具有普遍適用性。

按需載入技能模組、代理規格和參考文件。每個技能模組佔窗口的5-15%，且只適用於單一領域。僅在相關時才載入，能為實際工作保留預算。

永不載入過時的交接文件、已棄用的設定或歷史狀態。每個過時的檔案都消耗預算卻不改善輸出。複利工程模式要求定期清理那些不再值得其token成本的context。

Context預算管理與驅動資料庫索引、快取策略和傳統軟體記憶體管理的取捨如出一轍。⁸約束不同（token而非位元組），但架構紀律完全相同。

---

多代理系統中的Context傳播

當主代理透過Task工具生成子代理時，選擇傳播哪些context決定了所有其他設計決策。我的多代理審議系統使用10個研究代理。每個代理需要足夠的context來獨立評估，但過多的共享context會導致boids文章中記錄的收斂問題：共享過多context的代理會產生完全相同的結論。

傳播規則：

Context類型	是否傳播？	原因
核心哲學	是	確保跨代理的一致性
領域規則	是	共享的品質標準
任務特定指令	是	實際的工作內容
對話歷史	否	獨立性需要隔離
其他代理的發現	否（直到整合階段）	防止過早收斂
技能程序	選擇性傳播	僅傳播與代理角色相關的技能

Ralph架構解決了一個相關問題：跨時間（迭代）的context傳播，而非跨代理（並行程序）的傳播。兩者共享相同的原則：傳播約束和原則，隔離實作細節。

---

衡量Context品質

Token數量只是替代指標。Context品質的真正衡量標準是：代理是否在第一次嘗試就產出正確的輸出？

追蹤50次工作階段後，我識別出三個品質訊號：

首次嘗試成功率。 代理的第一次回應有多常不需要修正？使用單體式CLAUDE.md時，成功率大約是60%。改用七層架構後，提升到大約80%。改善來自移除不相關的context（減少干擾）和新增領域特定的技能模組（增加相關知識）。⁹

修正類型。 當代理確實需要修正時，錯誤是事實性的（錯誤的API、錯誤的模式）還是判斷性的（錯誤的方法、錯誤的優先順序）？事實性錯誤表示缺少context。判斷性錯誤表示context衝突或模糊。追蹤修正類型能揭示哪一層需要關注。

任務完成時的context壓力。 任務完成時還剩多少context預算？如果任務只完成一半，窗口就已經使用了90%，那代表context架構載入了太多不相關的材料。我的hook系統包含一個context壓力監控器，當使用率超過70%時會發出警告。

---

分散式架構模式

七層系統中沒有任何東西是AI代理獨有的。它對映了既有的軟體模式：

軟體模式	Context對應項
環境變數	核心CLAUDE.md（始終載入，全域性）
設定檔	規則（啟動時載入，領域特定）
函式庫/模組	技能（按需載入，自包含）
微服務	代理（隔離的，透過協定通訊）
事件處理器	Hook（由生命週期事件觸發）
資料庫	狀態檔案（持久化，可查詢）
API合約	設定schema（共享的數值參數）

這種對應不是隱喻。相同的力量（耦合、內聚、範圍、生命週期）驅動了完全相同的架構決策。¹⁰ Context engineering就是軟體工程——只是其基底的「記憶體」是一種稀缺且會衰減的資源，而非充裕且持久的資源。¹¹

---

關鍵要點

給建構代理系統的工程師：

• 像設計軟體架構一樣設計context，而非當作文件來寫。 什麼時候載入什麼、什麼覆寫什麼、什麼傳播給子代理——這些決定了代理行為，其影響遠超任何單一指令。請運用您在程式碼上使用的同等關注點分離紀律。

• 按生命週期分離層級。 通用規則在每次工作階段載入。領域特定知識按需載入。每次工作階段的狀態保持暫時性。將不同生命週期混在一個檔案中，會產生軟體架構之所以存在就是為了解決的耦合問題。

給擴展AI工作流程的團隊：

• 將context窗口視為預算。 系統提示、檔案讀取和工具輸出消耗200K token的窗口。每一條持久化的指令都在與工作記憶體競爭。衡量您載入的內容，並清理那些不值得其token成本的部分。

• 傳播規則決定多代理品質。 子代理需要共享的原則來確保一致性，需要隔離的狀態來確保獨立性。傳播過多context會導致收斂。傳播過少context會導致不連貫。

---

本文建立在Context窗口管理（token經濟學）和Ralph系統（檔案系統記憶體）之上。Claude Code hook系統實現了自動化層。關於代理協調模式，請參閱多代理審議和從Boids到代理。

---