注意：這篇文章同樣適用於 AGENTS.md，這是 CLAUDE.md 的開源等價物，適用於 OpenCode、Zed、Cursor 和 Codex 等代理和工具。

原則：大語言模型（絕大部分）是無狀態的

大語言模型（LLM）是無狀態的函數。它們的權重在進行推理時是固定的，因此它們不會隨時間學習。模型對你代碼庫的唯一瞭解，來源於你輸入給它的 token。

同樣，像 Claude Code 這樣的編碼代理工具通常需要你顯式地管理代理的記憶。CLAUDE.md（或 AGENTS.md）是唯一一個默認會包含在你與代理的每一次對話中的文件。

這有三個重要的含義：

1. 編碼代理在每次會話開始時對你的代碼庫一無所知。

2. 每次開始會話時，必須告知代理關於你代碼庫的重要信息。

3. CLAUDE.md 是實現這一點的首選方式。

CLAUDE.md 幫助 Claude 入門你的代碼庫

由於 Claude 在每次會話開始時對你的代碼庫一無所知，你應該使用 CLAUDE.md 來幫助 Claude 熟悉你的代碼庫。從高層次來看，這意味着它應該涵蓋：

• WHAT（是什麼）：告訴 Claude 關於技術、你的技術棧、項目結構的信息。給 Claude 一張代碼庫的地圖。這在單一代碼庫（monorepo）中尤為重要！告訴 Claude 應用程序有哪些，共享包有哪些，以及每樣東西的用途，以便它知道去哪裏找東西。

• WHY（為什麼）：告訴 Claude 項目的目的以及倉庫中每樣東西的作用。項目不同部分的目標和功能是什麼？

• HOW（怎麼做）：告訴 Claude 它應該如何在項目上工作。例如，你是否使用 bun 而不是 node？你需要包含它在項目上進行有意義工作所需的所有信息。Claude 如何驗證它的更改？它如何運行測試、類型檢查和編譯步驟？

但是，你如何做這件事很重要！不要試圖把 Claude 可能需要運行的每條命令都塞進你的 CLAUDE.md 文件裏——你會得到次優的結果。

Claude 經常忽略 CLAUDE.md

無論你使用的是哪個模型，你可能會注意到 Claude 經常忽略 CLAUDE.md 文件的內容。

你可以通過在 claude code CLI 和 Anthropic API 之間放置一個日誌代理（使用 ANTHROPIC_BASE_URL）來親自調查這一點。Claude Code 會在給代理的用户消息中注入以下系統提醒（system reminder）連同你的 CLAUDE.md 文件：

XML

<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

結果是，如果 Claude 認為 CLAUDE.md 的內容與當前任務不相關，它就會忽略這些內容。如果你在文件中放入越多不適用於當前任務的信息，Claude 就越有可能忽略文件中的指令。

Anthropic 為什麼要添加這個？很難確切地説，但我們可以推測一下。我們遇到的大多數 CLAUDE.md 文件都包含大量並不廣泛適用的指令。許多用户把這個文件當作一種通過追加大量指令來“熱修復”他們不喜歡行為的方式，而這些指令並不一定廣泛適用。

我們只能假設 Claude Code 團隊發現，通過告訴 Claude 忽略糟糕的指令，工具實際上產生了更好的結果。

創建一個優秀的 CLAUDE.md 文件

以下部分提供了一些關於如何遵循上下文工程最佳實踐來編寫優秀的 CLAUDE.md 文件的建議。

你的情況可能會有所不同。並非所有這些規則對每個設置都是最優的。像其他任何事情一樣，一旦你理解了何時以及為什麼可以打破規則，並且你有充分的理由這樣做，就儘管打破規則吧。

少即是多（關於指令）

試圖把 Claude 可能需要運行的每一條命令，以及你的代碼標準和風格指南都塞進 CLAUDE.md 是很誘人的。我們不建議這樣做。

雖然這個話題還沒有經過非常嚴格的調查，但已有一些研究表明：

• 前沿的思維型 LLM 可以保持合理一致性地遵循約 150-200 條指令。

• 較小的模型比較大的模型能處理的指令更少，非思維型模型比思維型模型能處理的指令更少。較小的模型表現會迅速惡化。具體來説，隨着指令數量的增加，較小模型的指令遵循性能往往呈現指數級衰減，而較大的前沿思維型模型則呈現線性衰減。

• 因此，我們不建議使用較小的模型來處理多步驟任務或複雜的實施計劃。

• LLM 偏向於關注提示（prompt）邊緣的指令：最開始的部分（Claude Code 系統消息和 CLAUDE.md）和最末尾的部分（最近的用户消息）。

• 隨着指令數量的增加，指令遵循的質量會均勻下降。這意味着當你給 LLM 更多指令時，它不會簡單地忽略較新的（“文件下方”）指令——它會開始均勻地忽略所有指令。

指令遵循

我們需要意識到：我們對 Claude Code 工具的分析表明，Claude Code 的系統提示（system prompt）已經包含了約 50 條獨立指令。取決於你使用的模型，這已經佔用了代理能夠可靠遵循的指令的近三分之一——這還是在規則、插件、技能或用户消息之前。

這意味着你的 CLAUDE.md 文件應包含儘可能少的指令——理想情況下只包含那些對你的任務普遍適用的指令。

CLAUDE.md 文件長度與適用性

在其他條件相同的情況下，當 LLM 的上下文窗口充滿聚焦的、相關的上下文（包括示例、相關文件、工具調用和工具結果）時，其在任務上的表現要優於上下文窗口包含大量不相關上下文時。

由於 CLAUDE.md 會進入每一個會話，你應該確保其內容儘可能普遍適用。

例如，避免包含關於（比如）如何構建新數據庫模式的指令——當你正在處理其他不相關的事情時，這不僅無關緊要，還會分散模型的注意力！

在長度方面，少即是多的原則同樣適用。雖然 Anthropic 關於 CLAUDE.md 文件長度沒有官方建議，但普遍共識是 < 300 行是最好的，越短越好。

在 HumanLayer，我們的根 CLAUDE.md 文件不到 60 行。

漸進式披露 (Progressive Disclosure)

編寫一個簡潔且涵蓋你想讓 Claude 知道的所有內容的 CLAUDE.md 文件可能具有挑戰性，特別是在大型項目中。

為了解決這個問題，我們可以利用漸進式披露原則，確保 Claude 僅在需要時才看到特定於任務或項目的指令。

與其將所有關於構建項目、運行測試、代碼規範或其他重要上下文的指令都包含在 CLAUDE.md 文件中，我們建議將特定於任務的指令保存在項目中某個位置的單獨 Markdown 文件中，並使用自描述的文件名。

例如：

Plaintext

agent_docs/
|- building_the_project.md
|- running_tests.md
|- code_conventions.md
|- service_architecture.md
|- database_schema.md
|- service_communication_patterns.md

然後，在你的 CLAUDE.md 文件中，你可以包含這些文件的列表以及每個文件的簡要描述，並指示 Claude 決定哪些文件（如果有）是相關的，並在開始工作之前閲讀它們。或者，要求 Claude 在閲讀之前先向你展示它想要閲讀的文件以獲得批准。

優先使用指針而非副本。 如果可能，不要在這些文件中包含代碼片段——它們很快就會過時。相反，包含 file:line 引用，將 Claude 指向權威的上下文。

從概念上講，這與 Claude Skills 的預期工作方式非常相似，儘管 Skills 更側重於工具使用而非指令。

Claude (不) 是一個昂貴的 Linter

我們看到人們放入 CLAUDE.md 文件的最常見內容之一是代碼風格指南。永遠不要派 LLM 去做 Linter 的工作。 與傳統的 Linter 和格式化程序相比，LLM 相對昂貴且速度極慢。我們認為只要可以，你就應該始終使用確定性工具。

代碼風格指南將不可避免地向你的上下文窗口添加大量指令和大部分不相關的代碼片段，從而降低 LLM 的性能和指令遵循能力，併吞噬你的上下文窗口。

LLM 是上下文學習者！如果你的代碼遵循一套特定的風格指南或模式，你應該會發現，只需對代碼庫進行幾次搜索（或一份好的研究文檔！），你的代理就會傾向於遵循現有的代碼模式和慣例，而無需被告知。

如果你對此非常堅持，你甚至可以考慮設置一個 Claude Code Stop 鈎子（hook），運行你的格式化程序和 Linter，並將錯誤展示給 Claude 讓其修復。不要讓 Claude 自己去發現格式問題。

加分項：使用可以自動修復問題的 Linter（我們喜歡 Biome），並仔細調整你的規則，確定哪些可以安全地自動修復，以獲得最大的（安全）覆蓋率。

你還可以創建一個 Slash Command（斜槓命令），其中包含你的代碼指南，並指向版本控制中的更改、你的 git status 或類似內容。這樣，你可以將實現和格式化分開處理。結果你會發現兩者的效果都更好。

不要使用 /init 或自動生成你的 CLAUDE.md

Claude Code 和其他帶有 OpenCode 的工具都提供了自動生成 CLAUDE.md 文件（或 AGENTS.md）的方法。

因為 CLAUDE.md 會進入與 Claude Code 的每一次會話，它是該工具最高槓杆率的點之一——取決於你如何使用它，結果可能更好也可能更壞。

一行糟糕的代碼就是一行糟糕的代碼。實施計劃中糟糕的一行有可能會產生大量糟糕的代碼。一項研究中對系統工作原理理解錯誤的一行，有可能會導致計劃中出現大量糟糕的行，進而導致更多糟糕的代碼。

但是 CLAUDE.md 文件影響你工作流程的每一個階段以及由此產生的每一個工件。因此，我們認為你應該花時間非常仔細地思考進入其中的每一行內容。

結論

CLAUDE.md 用於幫助 Claude 入門你的代碼庫。它應該定義你項目的 WHY（為什麼）、WHAT（是什麼） 和 HOW（怎麼做）。

• 少（指令）即是多。 雖然不應省略必要的指令，但應在文件中包含儘可能少的指令。

• 保持 CLAUDE.md 的內容簡潔且普遍適用。

• 使用漸進式披露——不要告訴 Claude 你想讓它知道的所有信息。相反，告訴它如何找到重要信息，以便它可以找到並使用它，但僅在需要時才這樣做，以避免通過膨脹你的上下文窗口或指令計數。

• Claude 不是 Linter。 使用 Linter 和代碼格式化程序，並在必要時使用 Hooks 和 Slash Commands 等其他功能。

• CLAUDE.md 是工具的最高槓杆點，因此避免自動生成它。你應該精心編寫其內容以獲得最佳結果。

如有想了解更多軟件設計與架構, 系統IT,企業信息化, 團隊管理 資訊，請關注我的微信訂閲號：

作者：Petter Liu
出處：http://www.cnblogs.com/wintersun/
本文版權歸作者和博客園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文連接，否則保留追究法律責任的權利。 該文章也同時發佈在我的獨立博客中-Petter Liu Blog。