最近看到一個關於 AI 編程全域記憶文件的討論：專案裡使用 Claude.md、AGENTS.md 這類文件之後，效果不一定會變好，甚至可能讓成功率下降，同時推理成本還會上升。

這件事乍看有點反直覺。我們通常會覺得，給 AI 更多專案背景、更多規則、更多說明，它應該更容易寫對程式碼。
但實際問題在於：Claude.md 不是普通文件，而是每次對話都會被塞進上下文的全域記憶。它寫得越多，模型每次都要讀得越多；它寫得越含糊，模型每次都要多做判斷；它寫進了不該寫的流程，模型還可能在不相關的任務裡觸發多餘動作。

所以，Claude.md 真正難寫的地方，不是怎麼把內容寫全，而是怎麼判斷哪些內容值得長期佔用上下文。

Claude.md 到底是什麼

在 AI 編程工具裡，Claude.md、AGENTS.md 這類文件本質上都是全域記憶文件。

普通對話會進入上下文，但上下文長度有限。對話長了以後，歷史內容會被壓縮，部分細節會丟失。全域記憶文件的作用，是把一些重要規則固定下來，讓模型在每次任務開始時都能看到。

這意味著兩件事：

• 寫進去的內容更不容易被遺忘
• 寫進去的內容也會在每次任務裡產生成本

它不像一份 README，只在需要時被閱讀。它更像一套長期有效的工作約束。只要放進去，就預設每次都會影響模型的判斷。

因此，Claude.md 不是專案介紹，也不是經驗合集，更不是把所有開發流程都塞進去的地方。它應該只存放那些模型如果不知道，就容易反覆犯錯的規則。

為什麼寫了反而可能變差

全域記憶文件寫得不好，主要會帶來三類問題。

第一，它會佔用上下文。

如果 Claude.md 有一千行，那麼這些內容會長期進入模型上下文。真正與當前任務有關的程式碼、錯誤資訊、需求說明，反而會被擠壓。上下文不是免費的空間，越大的全域規則，越容易稀釋當前任務的重點。

第二，它會觸發多餘行為。

比如在全域文件裡寫：

1
2

每次開始任務前，都要完整閱讀專案目錄。
每次修改後，都要執行完整鏈路測試。

這些話看起來很負責，但放在全域記憶裡就會變成「所有任務都預設執行」。哪怕只是改一行文案，模型也可能因為這條規則去做不必要的探索和測試。結果就是任務變慢、成本變高，甚至引入新的干擾。

第三，它會增加判斷負擔。

像「保持程式碼優雅、簡潔、可維護、可擴展」這類話，聽起來正確，但實際約束很弱。模型每次生成程式碼時都要判斷什麼叫優雅、什麼叫可擴展，卻沒有得到明確邊界。

更好的寫法不是堆抽象美德，而是寫具體禁令或反例。比如：

1
2
3

不要為了單個調用點新增通用抽象。
不要在沒有測試覆蓋的情況下改動共享解析邏輯。
不要把臨時腳本放進業務源碼目錄。

這些規則更具體，也更容易被執行。

應該寫什麼

判斷一條內容要不要寫進 Claude.md，可以用一個簡單標準：

如果不寫，AI 就會反覆犯同一種錯誤，那它值得寫進去。

適合寫進全域記憶文件的內容，通常有這些特點：

• 長期有效
• 與當前倉庫強相關
• 無法從程式碼結構自然推斷
• 能明確改變模型行為
• 最好是約束、禁令、路徑規則或固定命令

比如：

1
2
3
4

所有 Hugo 文章只改 index.zh-cn.md，不自動生成其他語言版本。
文章 front matter 必須包含 title/date/draft/tags/categories/slug/description。
不要修改 public/ 目錄裡的構建產物。
PowerShell 下執行部署時使用 scripts/deploy.ps1。

這些內容不是泛泛而談，而是和倉庫的真實工作方式綁定。模型如果不知道，就可能做錯；模型知道以後，確實能減少誤操作。

不該寫什麼

很多人容易把 Claude.md 寫成專案說明書，這通常沒有必要。

不太適合寫進去的內容包括：

• 專案願景和背景介紹
• 大段目錄結構說明
• 臨時任務計畫
• 一次性的除錯步驟
• 抽象的程式碼審美要求
• 只在少數情況下才需要執行的長流程

比如「這是一個電商專案，包含商品、訂單、使用者模組」這種描述，對模型完成具體編程任務幫助有限。真正開發時，模型應該根據當前需求、規格文件、程式碼結構和測試來判斷，而不是靠全域記憶裡的粗略介紹。

目錄結構也是類似。除非某個目錄有特殊約定，比如「共享元件只能從這個目錄引用」，否則沒必要把整個樹狀結構都寫進去。模型可以自己讀取專案目錄，硬塞一份靜態目錄說明反而容易過期。

流程更適合做成技能或命令

如果一段內容是「第一步做什麼、第二步做什麼、第三步做什麼」，它未必適合放進 Claude.md。

長期流程可以沉澱成技能、腳本或命令。這樣做的好處是：全域記憶裡只需要保留名稱和觸發條件，真正的詳細步驟只在需要時載入。

比如：

1
2

當使用者要求翻譯 Hugo 文章時，使用 post-translate 技能。
當使用者要求部署站點時，執行 hugo-rsync-deploy 流程。

這比把完整翻譯流程、部署流程都寫進 Claude.md 更輕。全域記憶保持短，具體流程交給可觸發的工具。

Claude 最近的初始化流程也在往這個方向走：不只是生成一個 Claude.md，還會嘗試把可複用流程拆成 skills，把固定事件拆成 hooks。這個變化背後的思路很清楚：全域記憶只做入口，細節按需載入。

Claude.md 需要持續迭代

Claude.md 不應該一次寫完就不管。

更合理的方式是先保持簡短，讓模型在真實任務裡暴露問題。某個錯誤出現一次，可以先人工處理；如果同類錯誤出現兩次以上，就說明它可能值得沉澱為全域規則。

這類迭代比一開始寫一大堆規則更有效。因為一開始你不知道哪些規則真的有用，也不知道哪些內容會變成噪音。隨著專案變大、協作變多、模型行為逐漸穩定，再慢慢把高頻問題寫進去。

還有一個重要趨勢：模型越強，全域記憶文件反而應該越短。

以前很多需要寫進提示詞的要求，現在模型已經能自然做到。繼續把這些基礎要求塞進 Claude.md，只會增加上下文負擔。全域記憶應該隨著模型能力提升而收縮，只保留這個倉庫獨有、模型無法自動推斷的部分。

一個更實用的寫法

寫 Claude.md 時，可以按這個順序思考：

1. 這個倉庫有什麼特殊約定？
2. 哪些錯誤模型已經犯過不止一次？
3. 哪些目錄、文件或命令絕對不能誤用？
4. 哪些流程應該改成技能、腳本或命令，而不是常駐上下文？
5. 哪些內容只是介紹，可以刪掉？

最後得到的文件，可能只有幾十行。它不需要完整解釋專案，而是要精確約束行為。

一個好的 Claude.md，應該像這樣：

1
2
3
4
5
6
7

# 工作規則

- 只改與當前任務相關的文件。
- 不要修改 public/、resources/ 這類構建產物目錄。
- Hugo 文章改寫只處理 index.zh-cn.md，不生成其他語言版本。
- 如果涉及部署，先執行 hugo 構建，再執行既有 rsync 腳本。
- 遇到已有使用者改動時，不要回滾，必須基於現狀繼續修改。

它短，但每一條都能影響實際行為。這樣的內容才值得長期佔用上下文。

最後一句

Claude.md 的價值不在於讓 AI「知道更多」，而在於讓 AI「少犯固定錯誤」。

它不是知識庫，也不是專案百科，而是 AI 編程過程裡的長期約束文件。
寫得越具體、越短、越貼近真實錯誤，它越有用；寫得越泛、越長、越像專案介紹，它越可能拖慢模型，甚至讓結果變差。

把全域記憶當成稀缺資源，而不是無限草稿紙。這大概就是寫好 Claude.md 最重要的一條原則。