CLAUDE.md 怎麼寫?Claude Code 的說明書
文 / Coolkid發布：2026-08-01閱讀約 7 分鐘
摘要
短答給趕時間的人:CLAUDE.md 是放在專案資料夾裡的一個文字檔,每次在那個資料夾開對話,Claude Code 都會自動把它整份讀進來 — 等於你寫給 AI 的員工手冊。起步只要三行(你是誰/專案是什麼/絕對別做什麼);寫熟之後照五個欄位長大。最重要的一條原則:「每一場都要遵守的」才寫進來 — 它每場全文載入,塞越肥,重要的規則被稀釋得越淡。
我的 CLAUDE.md 從三行開始,用了三個月長成一套兩層的規則書:一份全域的管「我這個人」,每個專案再各有一份管「這個專案的規矩」。中間犯過最典型的錯就是塞太肥 — 什麼都想讓它記,結果它反而更常忽略重點,2026 年 7 月初大掃除了一次才學會怎麼瘦身。這篇把寫法、分層、瘦身、和「寫了它還是不遵守」的解法一次講完。
CLAUDE.md 是什麼?放哪裡?
它就是一個檔名固定叫 CLAUDE.md 的文字檔,不用任何特殊工具,記事本就能寫。特別的地方在於 Claude Code 對它有約定:開對話時自動全文載入,而且每一場都載 — 所以你寫在裡面的話,等於每次開工前它都會先讀一遍的開工須知。
| 放哪裡 | 管什麼 | 適合放的例子 |
|---|---|---|
| 全域一份(你的使用者資料夾) | 你這個人,所有專案通用 | 「我是非工程師」「回覆用繁體中文」「先講結果再講過程」 |
| 每個專案資料夾一份 | 只在這個專案生效 | 「這是什麼專案」「哪個資料夾不能碰」「這專案的檔案命名規矩」 |
跟「自動記憶」的分工一句話講清:CLAUDE.md 是你手寫的規則書,寫什麼它照什麼;自動記憶是它自己寫的筆記,記相處中學到的事。一個由你主導、一個由它累積,兩層詳細分工在記憶那篇。
從三行到五個欄位(附我的真實演化)
第一天寫三行就夠:你是誰、專案是什麼、絕對別做什麼(記憶篇的起手式)。用了幾週、開始被同樣的事煩第二次之後,自然會長出更多內容 — 我的檔案現在大致就是五個欄位:
| 欄位 | 放什麼 | 我的真實例子 |
|---|---|---|
| 我是誰 | 背景與偏好 | 非工程師、全職交易者;回覆用繁體中文 |
| 專案是什麼 | 一句話定位+目前階段 | 「個人網站,目前在衝新手教學系列」 |
| 鐵律(絕對別做) | 踩過雷的教訓 | 「PowerShell 檔案要用特定編碼存,不然必亂碼」 |
| 做事習慣 | 希望它遵守的風格 | 「產出任何檔案,回覆要附完整路徑」 |
| 去哪找東西 | 情況 → 該讀哪份檔案的目錄 | 「要寫貼文,先讀我的文案風格檔」 |
注意一件事:表裡的鐵律沒有一條是憑空想的,全是真的炸過才寫進去的。「檔案編碼」那條是我被亂碼咬了好幾次的結晶;「附完整路徑」是我被「檔案生好了但我找不到在哪」氣過之後加的。寫的時候順手帶一句為什麼(「不然必亂碼」)— AI 更會當真,而且三個月後回頭看,你也判斷得出這條還需不需要。
最大的坑:把它當倉庫塞
CLAUDE.md 每場全文載入,這是它強的原因,也是它的成本:寫越多,每場對話開工前要先吞的東西越多,留給正事的空間(context)就越少 — 而且規則彼此稀釋,你最在乎的那三條,會被另外五十條淹沒。我塞最肥的時期,明明寫了規則它還是常忽略,問題不在它,在我把手冊寫成了百科全書。
我 2026 年 7 月初做了一次大掃除,方法就一招:長文件外移。詳細的規範各自存成獨立檔案,CLAUDE.md 只留一張目錄 —「遇到什麼情況,去讀哪份檔案」。主檔從什麼都有變成一張路由表,AI 開場變快,也明顯更聽話。誠實揭露:那次大掃除就是叫 Claude Code 重寫自己的規則書,我只負責審 — 它整理自己的手冊,比我手動搬快得多。
寫之前先問一句:「這條是每一場都用得到,還是只有某種情況用得到?」前者留在 CLAUDE.md,後者外移成獨立檔案,目錄留一行就好。
寫了它還是不遵守?兩種原因、兩種解
原因一:塞太肥被稀釋 — 解法就是上一段的瘦身。原因二比較隱形:你寫的其實是「必須每次執行」的事,不是「希望遵守」的風格。AI 是會忘的,再重要的規則寫成文字都只是「拜託它記得」;必須 100% 發生的事(改完檔自動檢查、收工前存進度),該用 hook — 系統在固定時機強制執行,不靠任何人記得(詳見 Hooks 那篇)。我的分工:「風格與判斷」放 CLAUDE.md,「動作與檢查」放 hook。
最後是新陳代謝:規則書是活的。我的習慣是同一件事糾正它第二次,就當場說「把這條寫進 CLAUDE.md」— 讓規則在事故現場出生;然後每隔一陣子回頭刪掉不再適用的。只進不出的規則書,最後連你自己都不會信。
CLAUDE.md 是放在專案資料夾、每場對話自動全文載入的規則書。兩層:全域一份管你這個人(偏好/語言/風格),每專案一份管專案規矩。起步三行(你是誰/專案是什麼/絕對別做什麼),進階五欄位(我是誰/專案/鐵律/做事習慣/去哪找東西)— 鐵律要從真實事故寫起、帶為什麼。最大的坑是塞成倉庫:每場全文載入,越肥越稀釋,判準是「每一場都用得到才進來」,長規範外移成獨立檔案、主檔留路由目錄(我 2026-07 大掃除實測有效)。寫了不遵守的兩種解:瘦身,以及把「必須 100% 執行」的事改用 hook。規則書要新陳代謝:糾正第二次就寫進去,定期刪過時的。
名詞解釋
- Claude Code
- Anthropic 推出的 AI 寫程式工具，裝在自己電腦的終端機裡，能直接讀寫你的檔案、跑指令，把你用中文描述的需求做成真的網站或工具。
- context（上下文視窗）
- AI 一次能「記在腦中」的內容上限，包含你說的話、它讀的檔案跟對話紀錄。塞滿了就會忘掉前面的事，這就是長對話後 AI 開始恍神的原因。
- hook（掛鉤）
- 在工具的固定時機（開始對話、寫完檔案、結束回合）自動執行你指定動作的機制。像是幫 AI 設「進門要換鞋」的家規，設一次每次都自動生效。
- skill（技能包）
- Claude Code 的知識外掛：一個資料夾放一份說明書（SKILL.md），教 AI 特定領域的做事方法。對到相關任務時 AI 會自己翻出來照著做。
- PowerShell
- Windows 內建的指令視窗：用打字下指令的方式操作電腦，Claude Code 在 Windows 上就在這裡面跑。按 Win + X 可以叫出來。
如果內容對你有用就太好了
隨喜斗內
相關文章
▸ 常見問題
CLAUDE.md 是什麼?一定要寫嗎?
放在專案資料夾的文字檔,Claude Code 每場對話自動全文載入,等於你寫給 AI 的員工手冊。不寫也能用,但每個新對話都要重新交代背景,講到煩。第一版只要三行:你是誰、專案是什麼、絕對別做什麼 — 下一場對話立刻有感。
CLAUDE.md 跟記憶功能、skill 差在哪?
CLAUDE.md 是你手寫的常駐規則書,每場全文載入;自動記憶是它自己寫的筆記,記相處中學到的事;skill 是按需翻閱的做事方法,對到相關任務才載入。分工:每場都要遵守的規矩進 CLAUDE.md,過程性的交給記憶,某個領域的 SOP 寫成 skill。
CLAUDE.md 可以寫多長?寫太多會怎樣?
沒有硬上限,但有隱形成本:它每場全文載入,越肥吃掉越多對話空間,而且規則彼此稀釋 — 我塞最肥的時期反而最常被忽略規則。判準:「每一場都用得到」才寫進來;情況限定的長規範外移成獨立檔案,CLAUDE.md 留一行目錄「遇到什麼情況去讀哪份檔」。
寫進 CLAUDE.md 了,AI 還是不遵守怎麼辦?
先檢查是不是塞太肥(規則被稀釋,瘦身通常立刻改善);再檢查這條是不是「必須每次執行」的動作 — 文字規則本質是拜託它記得,必須 100% 發生的事要用 hook 讓系統強制執行。另外規則帶上為什麼(「不然必亂碼」),遵守率明顯比光禿禿的命令高。
看完這篇之前先確認:
- 每次開新對話都在重講一樣規矩,講到煩的人
- 聽過「寫三行 CLAUDE.md」,想知道下一步怎麼寫好的人
- 想要「該寫什麼、不該寫什麼」判斷標準的人
- 還沒裝 Claude Code (先看 Windows 安裝那篇)
- 想找官方完整規格文件 (這是實用寫法分享)
- 公司多人共用規範的治理題 (本篇是個人向)
- 什麼都塞進去 — 每場全文載入,塞越肥留給正事的空間越少
- 把「希望它做」跟「必須每次做」混寫 — 後者該用 hook
- 寫一次就不管 — 規則會過時,只進不出會越來越不準