用 AI 代理寫程式、管專案，最讓人崩潰的不是它不會，是同一個錯它會一犯再犯。上週教過的事，這週開新對話又忘了。

很多人的第一反應是換更強的模型。但這類代理每次開新對話都是從零開始，它能記住的只有一個地方：專案裡那份指令檔。Claude Code 叫它 CLAUDE.md，有些工具叫 AGENTS.md。這篇講怎麼讓這份檔案越用越聰明，最後用這個部落格自己的指令檔當例子。

第一層：指令檔要分層，不要一份塞到底

AI 出錯，大致來自三種原因：資訊錯誤、資訊遺漏，以及雜訊太多。第三種最常被忽略——你把所有規則塞進同一份檔案，它在改前端的時候也得讀一遍後端的資料庫規範，真正重要的那條反而被淹沒。

Claude Code 啟動時會從當前工作目錄往上逐層載入 CLAUDE.md；子目錄裡的 CLAUDE.md，則是在它讀到那個資料夾的檔案時才載入。所以可以這樣分：

  • 根目錄：每次對話都需要的——專案在做什麼、命名慣例、commit 規則、整體架構。
  • 子目錄：只跟那一塊有關的——前端元件規則放 frontend/，資料庫規則放 backend/。
  • 當索引用：大份的說明文件、API 速查表不要整份貼進來，只寫「需要時去哪裡找」。

第二層：任務做完，叫它把教訓寫回去

社群上有一篇很完整的實測分享，作者做了一個自訂指令 /Lesson：每次任務完成後，讓 Claude 回頭看這段對話，把「這次繞了哪些遠路」整理出來，寫進對應層級的 CLAUDE.md——通用的寫根目錄，某個框架的坑寫子目錄。

缺點很明顯：要靠人記得下這個指令。

第三層：用對話紀錄找出真正的摩擦點

同一位作者更進一步：Claude Code 會把每段對話存在本機（~/.claude/projects/ 底下的 JSONL 檔），官方的 /insights 也會替對話打上「目標、結果、摩擦點」之類的標籤。他寫了一個 skill，把幾百 MB 的紀錄濃縮後交給 Claude 分析，直接產出指令檔的修改建議。

他從數據裡長出來的三條規則，很有代表性：

  • 統計發現 AI 用 Bash 指令的次數比用專用讀檔工具還多 → 加一張「優先使用專用工具」對照表。
  • 「方法用錯」出現 24 次 → 加一條「收到明確指令就直接做，不要先寫計畫文件」。
  • 程式錯誤多半出在第三方 API 用法 → 加一份這個專案專屬的 API 速查表。

這些規則不是憑感覺寫的，是從實際失敗次數長出來的。要注意的是，這是單一作者、單一專案的自述數字，沒有第三方重現過；/insights 的行為也可能隨版本改變。

2026-10 補記：這個部落格的指令檔

這個網站本身就是這樣維護的。根目錄的 CLAUDE.md 很短，只做兩件事：叫 AI 先去讀完整的 .agents/AGENTS.md，以及列出「最容易踩的地雷」。真正的規則都在 AGENTS.md 裡，其中一整節叫「AI 代理人特別守則」，到 2026 年 10 月已經有 30 條，幾乎每一條都是真的出過事才寫進去的。舉幾個例子：

  • 清單符號不能縮排：Markdown 清單縮排四格以上會被當成程式碼區塊，清單符號原樣印出來。踩過一次，寫成規則。
  • 手寫文章檔名要帶特定關鍵字：網站有一支匯入腳本會清掉舊的匯入檔，手寫的公告如果檔名不對，會被當成過期檔一起刪掉。
  • 外部腳本要鎖版本加完整性檢查：資安檢查後新增的規則，附上雜湊值怎麼算，避免下次有人升級版本時忘記一起改。
  • 時區要寫死：網站在雲端建置時用的是世界協調時間，台灣的文章日期整整差了一天。查出原因後，把「建置時固定用台北時區」寫成一條規則。

每次踩坑之後，我會讓 AI 把「發生什麼事、為什麼、以後怎麼避免」寫回這份檔案。久了之後，新開的對話一讀進來，就知道哪些路不要走。

實務上的幾個建議

  • 規則要寫原因：只寫「不要用 - 當清單符號」，下一個 AI 會在例外情況亂套；寫清楚「因為縮排會被當成程式碼」，它才知道什麼時候可以變通。
  • 規則會過期：環境改了，舊規則要刪或改。我們這份檔案裡就有一條註明「舊版本條曾寫……，搬家後已不成立」，把錯的那段留著當警示。
  • 私密資訊不要寫進去：指令檔通常會進版本控制，密鑰、密碼、個人資料一律不寫，只寫「存在哪裡、由誰處理」。

小結

模型會換代，但一份越寫越好的指令檔可以一直帶著走。它的價值不在一開始寫得多完整，在於每踩一次坑就多一條規則——把「AI 一犯再犯」變成「AI 只犯一次」。

資料來源

  • 社群實測長文〈CLAUDE.md 進化論：打造自動優化的 AI 指令架構〉（2026-02，作者附自身專案數據，單一樣本）
  • 本站 CLAUDE.md 與 .agents/AGENTS.md 的實際內容（2026-10 補記）

封面圖由 AI 生成。