CLAUDE.md 寫到 1,300 行的那天，我覺得自己很厲害
所有規則都在裡面，每個專案的細節、每個 API 的慣例、每個我不希望 AI 搞錯的地方，全部塞進去，邏輯是直覺的：想讓 AI 表現好，就給它更多資訊，越完整越好
結果是 AI 開始給我模糊的回答，它知道所有事情，但什麼都做不準，像是一個員工把公司的所有文件都背下來了，卻因為資訊太多不知道當下應該做什麼
我把 CLAUDE.md 刪到 300 行，事情變好了
我花了很長時間才真正理解為什麼
錯誤的心智模型
大多數人（包括六個月前的我）把 CLAUDE.md 當作「說明書」
說明書的邏輯是：越詳細越好，你希望 AI 知道什麼，就寫進去，這個直覺非常合理，因為我們對「文件」的經驗就是這樣——文件越完整，讀的人越能照著做
問題是 AI 的注意力不是無限的，每次對話，AI 都要載入 CLAUDE.md 的全文，這份文件越長，每一條規則能分到的「注意力」就越少，在一份 1,300 行的文件裡，你認為最重要的那五條規則，和第 1,200 行的某個細節，在 AI 眼裡的權重差距比你想像的要小得多
正確的心智模型是：CLAUDE.md 是公司章程，不是員工手冊
章程放在辦公室的牆上，所有人都看得到，但它只寫最根本的事——這家公司存在的目的、不可違背的底線、最高層級的決策原則，細節的作法、執行的流程、特定情況的 SOP，放在別的地方
章程短，是因為它只需要短
Anthropic 的六層架構
去年底，Anthropic 發布了一篇文章，描述他們在 Claude Code 裡設計的 agent 架構，同期，Tw93 也整理了一份詳盡的使用手冊，我讀到這些資料的時候，有一種奇特的感覺——我花六個月踩坑摸索出來的系統，他們用一個框架說清楚了
六層架構是這樣的：
第一層：CLAUDE.md 永遠載入，不需要呼叫，它是最高層級的規則，字數要少，每一條都是你覺得 AI 在沒有任何提示的情況下最容易搞錯的事
第二層：Rules（路徑規則） 根據當前工作目錄自動載入的規則，當你在不同的子目錄工作時，適用不同的規則集，這讓你不需要把所有情境的規則都塞進根目錄的 CLAUDE.md
第三層：Skills（技能） 按需呼叫的 SOP，AI 在需要的時候才讀，不需要的時候不佔注意力，一個技能可能是「如何處理資料庫 migration」，也可能是「如何提交 PR」，它在需要時完整展開，在不需要時靜靜待機
第四層：Hooks（鉤子） 確定性的控制，不依賴模型的判斷，Hooks 在特定事件發生時自動執行——commit 前、命令執行前、工具呼叫後，它不問 AI 的意見，它就是跑
第五層：Agents（代理） 在獨立 context 中工作的執行者，Agent 和主要對話是隔離的，它有自己的任務，自己的工作空間，自己的 context window，主 agent 把任務交給它，它回報結果
第六層：Verifiers（驗證器） 完成後檢查結果是否符合預期，你交給 AI 一個任務，Verifier 確認輸出符合規格
這六層的關係不是堆疊，是職責分離，每一層只做自己的事
公司治理的比喻
這個架構第一次讓我真正理解，是透過一個比喻：這是一家公司的治理結構
你管理 AI agents 的方式，和你管理一個組織是一樣的問題
CLAUDE.md = 公司章程，掛在辦公室牆上，隨時可見，寫的是不能違背的根本原則，你不會把所有作業流程都寫進章程，你只寫最核心的東西
Skill = SOP 手冊，放在倉庫裡，需要的時候拿出來讀，處理客訴有客訴的 SOP，上架新功能有新功能的 SOP，你不會每天早上發給所有員工，你只在相關情境才分發
Agent = 派出去獨立工作的員工，你給他任務，給他授權範圍，送他去執行，他有自己的辦公室（獨立的 context），和大本營的溝通是明確的交接，不是持續的監視
Hook = 法遵部門，他不問你的意見，他自動檢查，你要 push code，法遵自動跑一遍，符合規定才放行，他的存在不依賴任何人記得要呼叫他，他就是在那裡
這個比喻最有價值的地方：Skill 和 Agent 是平行關係，不是層級關係
Skill 不是「輕量版 Agent」，Agent 也不是「進階版 Skill」，它們解決不同的問題
Skill 解決的問題是：「我需要 AI 在某個任務中參考一份詳細的流程，但不需要隔離 context」，任務在主要對話裡跑，Skill 是它按需讀取的說明文件
Agent 解決的問題是：「我需要把這個任務完全獨立出去，不讓它污染主要 context，讓它用自己的 context window 跑完再回報」
簡單的任務用 Skill，需要隔離的任務用 Agent，判斷標準不是任務的難度，是任務是否需要獨立的工作空間
從實際事故反推架構
我的系統現在有 53 個 agents、142 個 skills、34 個 hooks
但這些數字不是從一開始就規劃好的，它們大多數是從失敗中長出來的
事故一：有一次，我讓主 agent 直接分析一個 bug，它讀了很多程式碼，花了十分鐘，給我一堆分析，但沒有打開瀏覽器確認，我用三十秒打開瀏覽器看到了問題，AI 卻花了十分鐘沒找到
這個事故告訴我：bug 調查是一個需要獨立執行、有固定流程的任務，它應該是一個 Agent，配一個 Skill（debug SOP），主 agent 的工作是把任務交出去，不是自己調查
現在 CLAUDE.md 裡有一條規則：任何 bug 調查，必須 spawn bug-fixer agent，不得自行處理，這條規則的存在，是因為沒有它，AI 會做錯
事故二：某個功能修改直接被 commit 到主分支，沒有建 feature branch，沒有開 PR，沒有 staging 驗證，直接進了 production，技術上 AI 沒做錯任何事——我沒有告訴它不能這樣做
這個事故催生了一個 Hook：commit 前自動檢查是否在主分支，如果是，攔截，這個 Hook 不依賴 AI 記得規則，不依賴 CLAUDE.md 的某條文字有沒有被讀到，它就是跑
CLAUDE.md 只寫 AI 會搞錯的事
這是我後來意識到最重要的原則
CLAUDE.md 不是知識庫，你的 API 文件不應該在那裡，你的技術架構說明不應該在那裡，這些東西很重要，但它們應該是 Skill，按需載入
CLAUDE.md 只放一種東西：你發現 AI 在沒有提示的情況下，會做出你不希望的行為的那些事
不是「AI 可能會搞錯的事」，是「AI 實際上已經搞錯過的事」
每一條寫進 CLAUDE.md 的規則，背後都有一個具體的失敗案例，它不是預防性的指南，它是事後的矯正，這也是為什麼它應該短——因為真正反覆出現的錯誤模式並不多，但每一條都必須在那裡
這個做法跟 Tw93 的 Claude Code 使用手冊不謀而合——他在六個月的實戰中也得出類似結論：覆寫規則應該來自實際觀察到的失敗，不是預防性指南
這是系統設計問題，不是 Prompt 工程問題
大多數關於「如何讓 AI 表現更好」的文章，談的是 Prompt，換個措辭，加個 chain-of-thought，在前面放個角色設定
這些技巧有用，但它們解決的是對話層級的問題
當你管理的不是一次對話，而是跨越數週、數個專案、數十個 agents 的持續工作，你面對的問題變成了系統設計問題：如何讓規則在沒有人記得的情況下依然生效？如何確保 AI 在獨立工作時不會超出它的授權範圍？如何讓 500 個小決策加起來不會偏離你的本意？
這些問題的答案不在 Prompt 裡，答案在架構裡
CLAUDE.md 的字數限制是架構，Skill 的按需載入是架構，Hook 的確定性執行是架構，Agent 的 context 隔離是架構
我現在看 CLAUDE.md 的方式，是這樣的：如果我在一個月後讀它，每一行都應該讓我想起某個具體的失敗，如果有一行讓我想不起來為什麼它在那裡，那它可能不應該在那裡
參考資料
- Anthropic: Equipping agents for the real world with agent skills
- Tw93: My Claude Usage Handbook
- Claude Code: Skills Documentation
有在建類似的系統，或剛開始想整理自己的 AI 工作流？歡迎找我聊聊