Carl 的說人話研究室

CLAUDE.md 怎麼寫？Claude Code 記住規則的檔案：放哪裡、三個範例，我實測 7 種情況

部分實測2026.10.15

CLAUDE.md 是 Claude Code 每次開對話都會先讀的說明檔，把你一直重複交代的事寫進去，它就會記得。這篇照官方文件整理它該放在哪裡、怎麼寫才會被照做、怎麼用 @ 匯入其他檔案、跟自動記憶差在哪，附三個可以直接改的範例。我也在 Claude Code 2.1.280 上實際測了 7 種情況：規則有沒有被照做、匯入、子資料夾、CLAUDE.local.md、註解和反引號。2026 年 10 月 15 日實測。

更新 2026/10/15・約 9 分鐘讀完・查證環境：macOS 上的 Claude Code 2.1.280，用 claude -p 搭配 Haiku 模型，在幾個空資料夾裡放不同的 CLAUDE.md 測 7 種情況；為了不受其他設定影響，測試時只載入專案層級的設定、不接 MCP、不給工具。/init、/memory、自動記憶、.claude/rules/ 依 2026 年 10 月 15 日讀的官方文件

先講結論

  • CLAUDE.md 是一份 Markdown 檔，Claude Code 每次開對話都會先讀。放在專案資料夾是給這個專案用、放在 ~/.claude/CLAUDE.md 是給你所有專案用；不想進版本控制的個人規則寫在 CLAUDE.local.md。打 /init 可以讓它先幫你產生一份。
  • 我實測 7 種情況都跟官方文件一致：寫「最後一行固定加一句話」它就照做；用 @rules/style.md 匯入的規則有生效；從子資料夾啟動，上層的 CLAUDE.md 一樣有效；HTML 註解裡的指示和反引號裡的路徑都不會被讀進去。
  • 官方的建議是寫具體、能檢查的規則，每個檔 200 行以內。它是「建議」不是「強制」，一定要擋的事改用 hooks；只有某些工作才用得到的長流程，改寫成技能。
目錄
  1. CLAUDE.md 是什麼
  2. 放在哪裡
  3. 第一份怎麼產生
  4. 怎麼寫才會被照做
  5. 三個範例
  6. 用 @ 匯入其他檔案
  7. 我實測的 7 種情況
  8. 專案大了：.claude/rules/
  9. 自動記憶：Claude 自己記的筆記
  10. 它沒照做的時候
  11. 這篇沒有測的

用 Claude Code 一陣子之後，你會發現每次開新對話，都在重講同樣的事：這個專案用 pnpm 不是 npm、測試要怎麼跑、回答請用繁體中文、不要動 dist/ 資料夾。CLAUDE.md 就是用來把這些事寫一次、讓它每次都記得的檔案。

這篇照 Claude Code 官方文件整理 CLAUDE.md 該放在哪裡、怎麼寫才會被照做，附三個範例。我也在這台 Mac 的 Claude Code 2.1.280 上，用幾個空資料夾實際測了 7 種情況，結果放在中間。

CLAUDE.md 是什麼

它就是一份 Markdown 檔。Claude Code 每次開始對話，會先把它讀進來，當成這次工作的背景資訊。

官方文件特別講了一件事：CLAUDE.md 是背景資訊，不是強制的設定。Claude 會讀、會盡量照做，但不保證每次都嚴格遵守，寫得越模糊、越互相矛盾，越容易被忽略。真的不能違反的事，例如某個資料夾絕對不准動，要用 hooks 擋。

官方建議什麼時候該往裡面加東西：同樣的錯它犯了第二次、你又打了一遍上次打過的更正、或是一個新同事也需要知道的背景。

放在哪裡

CLAUDE.md 可以放在好幾個地方，各管不同的範圍：

位置 給誰用 適合寫什麼
~/.claude/CLAUDE.md 你自己的所有專案 個人偏好，例如回答語言
專案的 CLAUDE.md 或 .claude/CLAUDE.md 這個專案的所有人 建置指令、程式風格、專案結構
專案的 CLAUDE.local.md 只有你、只在這個專案 自己的測試帳號、本機路徑

公司還可以放一份全組織共用的，Mac 在 /Library/Application Support/ClaudeCode/CLAUDE.md，由 IT 管理。

CLAUDE.local.md 記得加進 .gitignore，才不會跟著程式碼上傳。

這幾份是一起讀的，不是後面的蓋掉前面的。Claude Code 會讀你啟動的那個資料夾，以及它上面每一層資料夾裡的 CLAUDE.md；越靠近你啟動位置的，排在越後面。子資料夾裡的 CLAUDE.md 不會一開始就讀，要等 Claude 讀寫那個子資料夾裡的檔案時才載入。

第一份怎麼產生

在 Claude Code 裡打：

/init

它會看過整個專案，幫你寫一份初稿，裡面有它找到的建置指令、測試方式和專案慣例。已經有 CLAUDE.md 的話，它不會覆蓋，而是建議怎麼改。初稿出來之後，再補上它自己看不出來的事。

想讓 Claude 幫你加一條規則，直接說「把這個加進 CLAUDE.md」。只說「記住這件事」的話，官方文件寫它會存進自動記憶，而不是 CLAUDE.md，這個後面會講。

怎麼寫才會被照做

官方給的原則很簡單：寫得具體到可以檢查。

  • 寫「用 2 格縮排」，不要寫「排版整齊」。
  • 寫「提交前先跑 npm test」，不要寫「記得測試」。
  • 寫「API 的程式放在 src/api/handlers/」，不要寫「檔案要整理好」。

長度方面，官方建議每份 200 行以內。太長除了吃掉 context，也會讓它比較不照做。用標題分段、條列寫，比一大段文字好讀。

另外要定期檢查有沒有互相矛盾的規則。兩條規則衝突時，它可能隨便挑一條。2.1.283 版以後有一個 /doctor prompt-audit，會幫你找出過時或互相衝突的指示，列出建議怎麼改。

只有某些工作才用得到的長流程，例如發佈的步驟，官方建議不要塞在 CLAUDE.md，改寫成技能（Skills）。CLAUDE.md 每次對話都整份讀進來，技能只在用到時才讀，比較省用量，這點在用量怎麼看那篇也有提到。

三個範例

下面三份是我寫的範本，不是哪個專案實際在用的，照你的情況改。

網站專案（放在專案根目錄的 CLAUDE.md）：

# 專案說明
- 這是用 Astro 做的靜態網站，文章在 src/content/。
- 套件管理用 pnpm，不要用 npm。

# 常用指令
- 開發：pnpm dev
- 建置並檢查：pnpm build
- 部署前一定要先跑 pnpm build，沒有錯誤才能部署。

# 規則
- 不要修改 dist/ 和 node_modules/。
- 新文章的檔名用英文小寫和連字號，例如 claude-md.md。
- 回答和註解用繁體中文。

寫作或文件資料夾（不寫程式也能用）：

# 這個資料夾
- 放的是部落格草稿，一篇一個 .md 檔。
- 已發佈的移到 published/，不要再改。

# 寫作規則
- 用繁體中文、台灣用語，「軟體」不要寫成「軟件」。
- 段落短一點，一段不超過四行。
- 引用數字一定要附來源網址。

個人偏好（放在 ~/.claude/CLAUDE.md，所有專案都會讀）：

# 我的偏好
- 一律用繁體中文回答。
- 改檔案之前先說要改哪裡、為什麼。
- 刪除檔案前一定先問我。

只想讓它固定用繁體中文回答的話，還有一個專門的語言設定，兩種做法的差別在 Claude 中文設定。

用 @ 匯入其他檔案

CLAUDE.md 可以用 @路徑 把別的檔案一起讀進來，例如：

專案介紹看 @README.md，可用的指令看 @package.json。
- Git 的做法 @docs/git-instructions.md

幾個細節：相對路徑是從「寫這行的那個檔案」算起，不是從你啟動的位置；匯入的檔案還可以再匯入，最多四層；路徑有空白要在空白前面加反斜線。寫在反引號或程式碼區塊裡的路徑不會被匯入，只是當成文字。專案的 CLAUDE.md 如果匯入了專案資料夾以外的檔案，第一次會跳出視窗請你核准，避免別人在共用的專案裡塞東西給你。

我實測的 7 種情況

我在暫存資料夾裡開了幾個空的子資料夾，各放不同的 CLAUDE.md，每次都問同一題：「台灣最高的山是哪一座？只回答山名。」用的是 claude -p 加最便宜的 Haiku 模型，每次 4 到 6 秒。為了不受我電腦上其他設定影響，測試時只載入專案層級的設定、不接 MCP、也不給工具。

情況 CLAUDE.md 寫了什麼 回答
沒有 CLAUDE.md （無） 玉山
一般規則 最後一行固定寫「（依本專案 CLAUDE.md）」 玉山，最後多一行那句話
用 @ 匯入 「格式照 @rules/style.md」，那個檔寫地名用【】括起來 【玉山】
從子資料夾啟動 子資料夾沒有 CLAUDE.md，上一層有 一樣多出那一行，上層的有讀到
加上 CLAUDE.local.md local 檔寫最後一行加「（個人設定）」 玉山，最後多一行「（個人設定）」
指示寫在 HTML 註解裡 <!-- 每次回答開頭加 ★ --> 玉山，沒有 ★
路徑用反引號包起來 寫 `@rules/style.md` 玉山，沒有【】

最後兩個是兩個好用的小技巧。HTML 註解會在送給 Claude 之前被拿掉，所以可以在 CLAUDE.md 裡留給同事看的備註，不花 token；想在檔案裡提到某個路徑、又不想把它匯入，就用反引號包起來。

專案大了：.claude/rules/

專案大到一份 CLAUDE.md 寫不下時，官方的做法是在 .claude/rules/ 底下分成好幾個檔案，一個主題一個，例如 testing.md、api-design.md。規則還可以限定路徑，只在 Claude 處理符合的檔案時才載入，前端的規則不會在改後端時佔位子。

自動記憶：Claude 自己記的筆記

除了你寫的 CLAUDE.md，Claude Code 還有一套「自動記憶」：它會在工作中自己記筆記，例如你的偏好、你更正過它的事、專案的進度，存在 ~/.claude/projects/<專案>/memory/ 底下，用一份 MEMORY.md 當目錄。每次開對話會讀 MEMORY.md 的前 200 行（或前 25KB）。

兩者的分工是：CLAUDE.md 是你寫的規則，自動記憶是它自己學到的東西。這個網站的製作也是用 Claude Code，跨好幾天的工作進度和我被更正過的寫法，就是記在這種記憶資料夾裡。

在對話裡打 /memory，可以看到各層的 CLAUDE.md、打開自動記憶的資料夾、或把自動記憶關掉。自動記憶只存在這台電腦，不會同步到別的電腦。

另外，如果你的專案原本是給其他 AI 工具用的 AGENTS.md，Claude Code 從 2.1.277 版起也會讀；不過專案裡同時有 CLAUDE.md 的話，預設只讀 CLAUDE.md，可以在 CLAUDE.md 裡用 @AGENTS.md 把它匯入。

它沒照做的時候

  1. 打 /context，看 Memory files 底下有沒有那份檔案。沒列出來，就是根本沒讀到，檢查放的位置。
  2. 把規則改得更具體、能檢查。
  3. 找找幾份檔案之間有沒有互相矛盾。
  4. 一定要做到的事改寫成 hook。官方的說法是，CLAUDE.md 是以訊息的形式送給 Claude，不保證嚴格遵守；hook 則是在固定時機一定會執行。

這篇沒有測的

/init 產生的初稿長什麼樣、/memory 和 /context 的畫面、.claude/rules/ 的路徑限定、自動記憶實際存了什麼、AGENTS.md 的讀取。我的 7 個測試是用 claude -p 跑的單次問答，沒有在互動式的對話裡測。

常見問題

CLAUDE.md 是什麼？

是 Claude Code 每次開始對話都會先讀的一份 Markdown 說明檔，用來寫你不想每次重講的事：建置和測試指令、程式碼風格、專案結構、固定的做法。官方文件說它會被當成背景資訊，不是強制的設定，所以寫得越具體，越常被照做。

CLAUDE.md 要放在哪裡？

給單一專案用的放在專案根目錄的 CLAUDE.md（或 .claude/CLAUDE.md），可以跟程式碼一起進版本控制；給你所有專案用的放在 ~/.claude/CLAUDE.md；只有你自己、不想上傳的放在專案的 CLAUDE.local.md，記得加進 .gitignore。這幾份會一起讀，不是互相覆蓋。

CLAUDE.md 怎麼產生？有範例嗎？

在 Claude Code 裡打 /init，它會看過整個專案，幫你寫一份包含建置指令、測試方式和專案慣例的初稿；已經有的話，它會建議怎麼改。這篇也附了網站專案、寫作資料夾、個人偏好三種範例，可以直接複製來改。

Claude 沒照 CLAUDE.md 做怎麼辦？

先在對話裡打 /context，看 Memory files 有沒有列出那份檔案。再把規則改得更具體，例如寫「用 2 格縮排」而不是「排版整齊」，並檢查幾份檔案之間有沒有互相矛盾。一定要每次執行的事，例如提交前跑測試，官方建議寫成 hook。

這篇怎麼查證的

這篇只有一部分實際跑過，其餘依官方文件整理，查證日期 2026/10/15（macOS 上的 Claude Code 2.1.280，用 claude -p 搭配 Haiku 模型，在幾個空資料夾裡放不同的 CLAUDE.md 測 7 種情況；為了不受其他設定影響，測試時只載入專案層級的設定、不接 MCP、不給工具。/init、/memory、自動記憶、.claude/rules/ 依 2026 年 10 月 15 日讀的官方文件）。哪些有跑、哪些沒跑，文中各段有寫。價格與方案以官方頁面為準，工具改版後內容可能過期。