CLAUDE.md 設計哲學：讓 AI 記住你是誰

沒有 CLAUDE.md 的世界 vs 有 CLAUDE.md 的世界

想像一下，你每天上班走進辦公室，助理都要重新自我介紹一次。你叫什麼？做什麼研究？偏好什麼工具？昨天談到哪裡了？全部重來。一天下來，光是重複交代指令就吃掉大量時間。你跟 AI 的合作，大概也在過這種日子。

根據我自己半年的紀錄，一個中度使用者平均每天會開 5 到 8 個新對話。每次對話前 3 到 5 則訊息幾乎都在重複同樣的偏好設定。加起來，一個月浪費的 token 數以萬計。時間更不用說。

問題不在 AI 笨。是它根本沒有「持久的指令記憶」。CLAUDE.md 就是解決這件事的入口。幫你的 AI 助理寫一本操作手冊，打開第一頁就知道老闆是誰、什麼能做、什麼不能碰。

CLAUDE.md 是 Claude Code 的專案級設定檔，定義了 AI 的身份、行為規則和記憶路由入口。它在每次啟動時自動載入，讓 AI 帶著完整上下文開始工作，而非每次從零出發。

我是大學助理教授兼生技公司研發總監，工作同時涵蓋學術研究跟產品開發。過去半年我反覆改這份設定檔。從最初三行規則，長到現在好幾百行的模組化架構。中間踩的坑堆積如山。這篇文章講的是設計思路，不是配置教學。最後有一份你能直接拿去改的簡化範例。

先看看沒有 CLAUDE.md 會怎樣。三個痛點，你中幾個？

痛點一：每天在貼同一段話。「我是做生醫研究的，請用繁體中文回答，程式碼偏好 Tailwind CSS 和 React，統計用 R 不用 Python。」這段話我曾經每天貼 3 次以上。每開一個新 session？所有偏好歸零。我數過，一天浪費在重複指令上的時間至少二十分鐘。就像每天早上跟同一個人重新握手。

痛點二：口頭約定不是規則。 口頭說「不要用 rm 指令」也沒用。那只是建議。像在沙地上畫線，一陣風就沒了。AI 在某次複雜操作中可能就「忘了」。結果呢？設定檔被刪了。沒有寫進設定檔的規則，根本不算規則。

痛點三：踩過的坑白踩了。 上次對話做的決策、踩過的坑、選定的技術方案。全部埋在那次對話的歷史裡。下次遇到一模一樣的情境？AI 完全不知道你已經做過這個決定了。從頭來。

有了 CLAUDE.md 之後呢？

	沒有 CLAUDE.md	有 CLAUDE.md
偏好設定	每次手動貼，平均 3-5 則訊息	啟動即載入，零重複
安全規則	口頭約定，偶爾失效	寫死在設定檔，每次生效
歷史決策	埋在對話紀錄裡，找不到	透過記憶路由自動索引
跨專案切換	每個專案重新設定	全域設定 + 專案覆寫

CLAUDE.md 一次解決這三件事。它是 Claude Code 啟動時自動讀取的設定檔。寫在裡面的指令，每一次都會生效。不是建議。是指令。

CLAUDE.md 的載入機制

Claude Code 的設定檔載入有明確的階層順序：

層級	檔案位置	作用範圍	載入時機
全域	~/.claude/CLAUDE.md	所有專案共用	每次啟動
專案	專案根目錄 CLAUDE.md	該專案限定	每次啟動
本地覆寫	.claude/CLAUDE.local.md	該專案限定（不進版控）	每次啟動
規則目錄	.claude/rules/*.md	該專案限定	每次啟動

載入順序很關鍵：後載入的會覆寫前者。所以你可以在全域設定「台灣繁體中文」，然後在某個英文專案裡單獨蓋掉。

還有一個容易漏掉的機制：子目錄也可以放 CLAUDE.md。但 Claude Code 要實際進入那個目錄操作時才會載入。monorepo 架構超好用。前端跟後端各有各的規則，互不干擾。

四個設計層：像蓋房子一樣搭你的設定檔

好的 CLAUDE.md 不是把所有想到的規則塞成一大坨。它需要結構。我把設計分成四層，跟蓋房子一樣：地基打穩了才疊骨架，骨架有了才做裝潢，最後定家規。

第一層（地基）：身份宣告

告訴 AI「你在跟誰工作」和「你應該用什麼語氣」，兩行字省掉每次解釋背景的麻煩。

## 身份
契約者: CYH | 時區: GMT+8 | 語言: 嚴格台灣繁體中文
角色: 大學助理教授 + 生技公司研發總監

這不是虛榮心。身份宣告是整棟房子的地基。AI 知道你在學術圈，處理文獻跟統計時就會自動用更專業的框架。知道你 GMT+8？排程就不會把你的下午三點當凌晨三點。兩行字。省掉每次解釋背景的麻煩。

具體例子： 我的 CLAUDE.md 寫了「角色: 大學助理教授 + 生技公司研發總監」。有一次我請 AI 幫我寫一封 email。它自動用了學術界的正式語氣，附上 institutional affiliation。換一個沒寫身份的 session 做同樣的事？出來的語氣像在寫行銷文案。差很多。身份宣告讓 AI 切到完全不同的工作模式。

第二層（骨架）：行為規則

規則必須具體到可執行，模糊的建議等於沒有。

這是 CLAUDE.md 最核心的部分。你對 AI 發號施令的地方。把「不希望 AI 做的事」和「希望 AI 遵守的慣例」寫成明確規則。這一層就是你家的護欄和紅線，劃清哪些事絕對不能踩。

## 規則
1. rm 禁止，改用 mv + _DELETE_ 前綴
2. API Key 嚴禁寫死在程式碼裡，使用環境變數
3. 不可逆操作前必須取得我的許可
4. 新工具安裝前必須執行安全審查

這裡有一個鐵律：規則要具體到可執行。「請注意安全」是廢話。寫了等於沒寫。「rm 禁止，改用 mv + _DELETE_ 前綴」才是規則。AI 能從具體規則推導出行為。但你丟一句「注意安全」給它？它每次的理解都不一樣。

好規則 vs 壞規則：

壞規則（模糊）	好規則（具體）
請注意安全	rm 禁止，改用 mv + DELETE 前綴
保持程式碼品質	每個函式必須有 docstring
commit 要寫好	commit message 格式: type(scope): description
不要亂裝東西	新工具安裝前必須執行安全審查

不過要承認一件事：即使規則寫得再具體，AI 在複雜操作鏈裡偶爾還是會違反。CLAUDE.md 是軟性約束。不是程式碼層級的硬性攔截。真正要命的安全規則？還得搭配 Hook 系統。這是它的限制。

第三層（裝潢）：偏好設定

偏好設定省去每次開頭的「我要用 X 不要用 Y」儀式。

你的技術偏好、工具選擇、常用路徑。這一層就是房子的裝潢，讓 AI 的回應風格和工具選擇貼合你的日常習慣。

## 偏好
- 前端: Tailwind CSS + React
- 統計: R 優先（假設檢定/效應量/圖表），其餘 Python
- 行事曆: Apple Calendar
- 任務管理: Apple Reminders

偏好設定省去的就是每次開頭那段「我要用 X 不要用 Y」的儀式。寫了這一段之後，AI 要幫你跑統計？直接寫 R。不會再問你「要用 Python 還是 R？」這種你已經回答過一百次的問題。

第四層（家規）：記憶路由

記憶路由讓 AI 知道去哪裡找過去的決策和偏好紀錄。

這一層是連結 CLAUDE.md 和整個記憶系統的橋樑。前三層讓 AI 知道「現在該怎麼做」。這一層讓它知道「過去發生過什麼」。記憶路由的角色就像快遞分揀中心：不同類型的資訊，送到不同的存放位置。

## 記憶路由
- 用戶偏好/設定 → memory/fact.yml
- 決策紀錄/踩坑經驗 → memory/episodic.jsonl
- 當前任務暫存 → memory/scratchpad.md
- SOP 觸發路由 → memory/fact_sop_dispatch.yml

這一層做的事情很單純：告訴 AI「你要找偏好，去讀 fact.yml」。要找過去的教訓？去讀 episodic.jsonl。CLAUDE.md 本身保持精簡。當索引用就好，不用把所有細節都塞進來。塞太多反而會拖慢載入。

關於三層記憶架構的完整設計，AI Agent 記憶系統設計：三層架構實作 有更深入的說明。

模組化的秘密武器：@import

當你的 CLAUDE.md 長到上百行，全部寫在一個檔案會變成一鍋粥。這時候 @import 就是救星。

# CLAUDE.md（主檔，只留索引）
@import AGENTS.md
@import MEMORY.md

主檔變成一張目錄。乾乾淨淨。身份規則放 AGENTS.md，記憶路由放 MEMORY.md，安全規則放 .claude/rules/safety.md。改一條規則不用在 300 行裡大海撈針。直接打開對應的檔案改就好。

一份可以直接用的簡化範例

以下是一份精簡版 CLAUDE.md，適合剛開始使用 Claude Code 的人。直接複製到你的專案根目錄，根據自己的需求修改。

# CLAUDE.md

## 身份
使用者: [你的名字]
時區: GMT+8
語言: 台灣繁體中文

## 規則
1. 使用繁體中文回應，禁止簡體字
2. rm 指令禁止使用，改用 mv 搭配 _DELETE_ 前綴
3. 不可逆操作前必須確認
4. API Key 不可寫死在程式碼中

## 偏好
- [填入你的技術偏好，例如：前端 React + Tailwind]
- [填入你的語言偏好，例如：Python 為主]

## 常用路徑
- 專案根目錄: /path/to/your/project
- 輸出目錄: /path/to/output

## 記憶（進階，初期可省略）
- 偏好紀錄: memory/fact.yml
- 任務暫存: memory/scratchpad.md

這份範例大約 20 行。我的完整版比這複雜得多，但核心邏輯是一樣的：身份、規則、偏好、路由。

常見的設計錯誤

我走過的彎路，你不用再走一次。

把 CLAUDE.md 當作文寫。「Claude Code 是一個很棒的工具，它可以幫助我...」別鬧了。直接寫「語言: 台灣繁體中文」。AI 不需要你的前言跟心得感想。CLAUDE.md 是操作手冊。不是讀書心得。

規則太抽象。「請保持程式碼品質」寫了等於沒寫。「每個函式必須有 docstring」「commit message 格式: type(scope): description」。這才是 AI 能照做的東西。

全部塞在一個檔案裡。 超過 200 行？拆。Claude Code 支援 .claude/rules/ 目錄和 @import。安全規則、語言規則、工具設定各一個檔案。主 CLAUDE.md 只留索引跟身份宣告。我第一版就是因為不拆，改一條規則要在 300 行裡面找位置。超痛苦。

忘了版控。 CLAUDE.md 要進 Git。它是你專案的一部分。只限本機的設定？丟 .claude/CLAUDE.local.md，加進 .gitignore。

規則寫了但沒測試。 新加一條規則之後，馬上開一個新 session 去觸發它。比如你寫了「禁止 rm」？就去叫 AI 刪個檔案，看它是不是真的改用 mv。我試過好幾次才學到教訓：自以為寫清楚的規則，AI 的理解跟你想的不一樣。測試的成本遠低於事後維修。

CLAUDE.md 與其他工具的對照

不是每個人都只用 Claude Code。如果你同時跑好幾個 AI 工具？搞清楚各家的設定機制差異會省很多冤枉路：

特性	Claude Code	GitHub Copilot CLI	Antigravity CLI（agy）	Codex CLI
設定檔名	CLAUDE.md	copilot-instructions.md（也支援 CLAUDE.md）	GEMINI.md	codex.toml + AGENTS.md
格式	Markdown	Markdown	Markdown	TOML + Markdown
全域 + 專案分層	有	有	有	有
規則目錄	.claude/rules/*.md	無	無	無
大小限制	寬鬆	中等	最寬鬆（1M context）	32 KiB
模組化匯入	@import 支援	無	支援（透過 GEMINI.md）	無

Claude Code 跟 agy 都支援 @import，可以把記憶檔案、規則檔案動態引入。不用全部硬寫在一份文件裡。系統長大之後？沒有 @import 你根本管不動。

跨工具同步的懶人包做法：維護一份共用的 AGENTS.md 作為「單一真相來源」。各工具的設定檔去引用它。改一個地方，所有平台同步更新。詳細做法在 多平台同步：一套記憶跑遍 Claude/Copilot/agy。

從第一行開始

如果你現在打開終端機，在專案根目錄建一個 CLAUDE.md，寫下這三行：

語言: 台灣繁體中文
rm 禁止
偏好: [你最常用的框架]

你就已經比「每次手動重複指令」前進了一大步。

CLAUDE.md 的設計哲學就一句話：把你會重複說的話寫下來，讓機器自己讀。不是什麼高深技巧。是紀律。每寫下一條規則，未來就少一次重複溝通。

從身份宣告開始，慢慢加規則、加偏好、加記憶路由。不用急。你的 CLAUDE.md 會自然長大。三行也好，三百行也好，重要的是開始寫。這是建立 AI Agent 系統的第一步。也是最划算的一步。

想看基礎操作從哪裡開始，回到 Claude Code 完全入門：不只是聊天機器人。準備好往下走的話，AI Agent 記憶系統設計：三層架構實作 會帶你進入記憶系統的設計。

---

常見問題

CLAUDE.md 一定要叫這個名字嗎？

是的。Claude Code 固定讀取專案根目錄的 CLAUDE.md（大寫，含副檔名）。放在其他位置或改名都不會被自動載入。也可以用 .claude/CLAUDE.md 的路徑。

CLAUDE.md 的內容有大小限制嗎？

Claude Code 對 CLAUDE.md 的大小限制相對寬鬆，不像 Codex CLI 有 32 KiB 的硬上限。但實務上建議控制在 200 行以內。超過的部分？拆到 .claude/rules/ 目錄或外部記憶檔案。

CLAUDE.md 有什麼安全風險或限制？

有。最大的風險是你把敏感資訊（API Key、密碼、內部路徑）寫進 CLAUDE.md 然後推到公開 Git 倉庫。解法是：敏感資訊放 .claude/CLAUDE.local.md，加進 .gitignore。另一個限制？CLAUDE.md 的規則是「軟性約束」。AI 偶爾會在複雜操作中違反。需要硬性保障的規則，得搭配 Hook 系統。

我可以在 CLAUDE.md 裡寫中文嗎？

完全沒問題。CLAUDE.md 是給 AI 讀的指令，中文、英文、日文都行。用你最順手的語言寫，AI 的理解反而更準。我自己就是中英混寫，看哪個順就用哪個。

CLAUDE.md 寫了規則，AI 一定會遵守嗎？

大部分時候會遵守。但 AI 不是程式執行器，複雜情境下偶爾會偏。我就遇過明明寫了「禁止 rm」，結果在一連串自動化操作裡它還是偷偷塞了一個 rm 進去。所以真正要命的安全規則？別只靠 CLAUDE.md 的軟性約束。搭配 Hook 系統做硬性攔截才穩。Hook 設計看 Hook 守門系統：AI 寫的每一行 code 都過品管。

多人協作時 CLAUDE.md 怎麼處理？

團隊共用規則寫在專案根目錄的 CLAUDE.md，進 Git。個人偏好寫在 .claude/CLAUDE.local.md，加進 .gitignore。團隊一致性跟個人彈性兩邊兼顧。

---

想更深入？

我整理了一份完整的《CLAUDE.md 設定模板》，包含身份、規則、偏好、記憶路由四大區塊。附上每一行的說明和填寫指引。

免費下載 CLAUDE.md 模板（不用註冊）

下一篇：AI Agent 記憶系統設計：三層架構實作