「CLAUDE.md、Skill、記憶系統，講白了不就是幾份給 AI 讀的說明文件嗎？寫清楚一點不就好了，有什麼好『設計』的？」
我一開始也是這麼想的。直到有一次，我請 AI agent 幫忙查一批東西「有沒有真的在用」，AI 很快回報都沒有。我追問了一句「你查的範圍夠不夠廣」，AI 才發現自己只查了一部分情境，重查之後結論完全反過來。事後回頭看，這不是 AI 能力不夠，是我們給 AI 用的規則文件、記憶系統，根本沒有設計成「會逼 AI 誠實標注查證範圍」的樣子——它只是一份寫得很長、看起來很完整的文件，僅此而已。
這個系列要記錄的，是另一種踩坑經驗：不是「怎麼用 AI 重構程式碼」，而是「怎麼設計 AI 協作用的工具本身」——CLAUDE.md 該放什麼、不該放什麼；Skill 什麼時候該寫、什麼時候是浪費;記憶系統怎麼分類才不會變成一堆互相矛盾的筆記;多個 AI agent 同時工作時，怎麼避免它們互相踩到對方。
有一個團隊在用 AI coding agent 協助日常開發，一開始只有幾條規則：程式碼風格、commit 訊息格式。這份規則文件很短，AI 幾乎每次都能準確遵守。
隨著專案推進，規則越加越多——這個模組要怎麼寫、那個情境要注意什麼、某次犯過的錯誤要記得別再犯。半年後，這份文件變成好幾千行，涵蓋了幾十個不同情境的規則。照理說規則更完整了，AI 應該表現得更好才對。
實際發生的卻相反：AI 開始頻繁忘記規則，甚至同一個錯誤反覆犯。不是 AI 變笨了，是每一條規則在這份文件裡的「權重」被稀釋了——當文件裡混雜著幾十種情境的規則時，AI 沒辦法每次都精準抓到「這次任務該套用哪幾條」，而且每次載入這份巨大的文件本身就有成本，長期下來反而讓最重要的那幾條規則被淹沒在雜訊裡。
用一組對照來看這個差異：
❌ 什麼規則都塞進同一份文件：
「這份文件涵蓋全部規則：程式碼風格、資料庫存取規範、
特定模組的例外處理、某次事件後補的教訓……」
→ 文件越長，每次任務要在幾千行裡找出真正相關的那幾條，
AI 越容易漏看，或者乾脆平均分配注意力,結果每條都記不牢
✅ 按情境分層，只在需要時載入：
「全站都適用的規則放在主文件（很短）；
特定情境才需要的細節，拆成獨立規則檔，
只有真的碰到那個情境才載入細節。」
→ 每次任務只需要處理跟自己相關的那一小塊，
規則的權重不會被無關的內容稀釋
問題不是「規則寫得不夠清楚」，是沒有人把這份規則文件當成一個需要被設計的系統——只是把每次想到的東西往同一份文件裡加，跟軟體開發裡「把所有邏輯塞進同一支函式」是同一種失誤。
AI 開發工具本身（skill、CLAUDE.md、memory、多 agent 協作）也需要被當成軟體來設計——沒有清楚的分工跟驗證機制，這些工具會用最省事的方式退化成一堆互相矛盾、逾越範圍的雜訊。
這句話會貫穿整個系列。後面會看到同一種模式反覆出現在不同情境：記憶系統如果沒有分類，會變成一堆混在一起、沒人知道哪些還有效的筆記；委派給多個 AI agent 同時工作時，如果沒有明確限制範圍，會出現互相覆蓋對方成果的狀況；一份技術主張如果沒有查核機制，錯誤的資訊會一路被複製貼上到看起來很有說服力的文章裡。這些表面上是不同的問題，骨子裡都是同一件事——工具沒有被當成需要驗證、需要分工、需要邊界的系統來設計，只是被當成「寫一份東西讓 AI 看」這麼簡單。
如果你也在用 AI agent 協助日常工作，回想一下：你給 AI 的規則文件，是從一開始就被設計過的，還是每次想到什麼就往裡面加？如果是後者，你上一次檢查這份文件有多長、有沒有互相矛盾的規則，是什麼時候？
明天要具體拆解 CLAUDE.md 這份文件——它該放什麼、不該放什麼，跟「特定情境才需要的規則」之間的分界該怎麼劃。
延伸閱讀：本次鐵人賽同時並行的其他四個系列，會從不同角度處理相關的經驗，有興趣可以一起追：
iThome鐵人賽
看影片追技術