每次開啟 Claude Code，它都是從一張白紙開始。你的專案用什麼框架？程式碼風格有什麼規範？常用的指令是什麼？如果每次都要重新說明一遍，那效率就大打折扣了。這就是 CLAUDE.md 存在的意義——它是 Claude Code 的「專案記憶」，讓你把專案知識寫下來，Claude 每次啟動時都會自動讀取。搭配自動記憶（Auto Memory）功能，Claude 還能在工作過程中自己累積經驗，越用越懂你的專案。
CLAUDE.md 是什麼（What is CLAUDE.md）
CLAUDE.md 是一個純 Markdown 文字檔，Claude Code 在每次對話開始時都會自動讀取它。你只需要寫一次，Claude 就會在每次啟動時載入其中的指示。你可以把它想像成給 Claude 的一份「專案手冊」，裡面記載了 Claude 需要知道的一切：專案架構、程式碼規範、常用指令、命名慣例等等。
簡單來說，CLAUDE.md 解決了以下問題：
- 避免重複說明：不需要每次開啟 Claude 都重新解釋專案背景
- 確保一致性：團隊成員使用相同的 CLAUDE.md，Claude 的行為就會一致
- 提升效率：Claude 一開始就知道你的專案慣例，可以更快進入狀態
- 知識傳承：新進成員可以直接從 CLAUDE.md 了解專案規範
CLAUDE.md vs 自動記憶（Auto Memory）
Claude Code 有兩套互補的記憶系統，兩者都會在每次對話開始時載入。了解它們的差異，才能更有效地使用：
| 比較項目 | CLAUDE.md 檔案 | 自動記憶（Auto Memory） |
|---|---|---|
| 誰來寫 | 你自己 | Claude 自動寫入 |
| 內容性質 | 指示與規則 | 學習到的模式與知識 |
| 適用範圍 | 專案、使用者或組織層級 | 每個工作目錄 |
| 載入方式 | 每次對話完整載入 | 每次對話載入前 200 行或 25KB |
| 適合用來記錄 | 程式碼規範、工作流程、專案架構 | 建置指令、除錯心得、偏好設定 |
建議做法是：用 CLAUDE.md 記錄你希望 Claude 遵守的規則，用自動記憶讓 Claude 從你的修正中學習。兩者搭配使用，效果最佳。
CLAUDE.md 的放置位置
CLAUDE.md 可以放在不同位置，每個位置有不同的作用範圍。越具體的位置優先權越高：
| 範圍 | 位置 | 用途 | 分享對象 |
|---|---|---|---|
| 組織層級（Managed Policy） | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md | 由 IT/DevOps 管理的全組織指示 | 組織內所有使用者 |
| 專案層級（Project） | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 團隊共用的專案指示 | 透過版本控制分享給團隊成員 |
| 使用者層級（User） | ~/.claude/CLAUDE.md | 個人偏好，適用所有專案 | 僅自己 |
| 本地層級（Local） | ./CLAUDE.local.md | 個人的專案特定偏好，加入 .gitignore | 僅自己（當前專案） |
工作目錄上方的 CLAUDE.md 和 CLAUDE.local.md 會在啟動時完整載入。子目錄中的 CLAUDE.md 則會在 Claude 讀取該目錄的檔案時按需載入。
建立你的第一個 CLAUDE.md
使用 /init 自動生成
最快的方式是在 Claude Code 中執行 /init 指令。Claude 會自動分析你的程式碼庫，生成一份包含建置指令、測試指示和專案慣例的 CLAUDE.md 檔案。如果已經存在 CLAUDE.md，/init 會建議改善內容而不是覆蓋它。
# 在專案目錄中啟動 Claude Code
cd your-project
claude
# 執行 /init 生成 CLAUDE.md
/init你也可以設定環境變數 CLAUDE_CODE_NEW_INIT=1 來啟用互動式多階段流程。這個模式會詢問你要設定哪些項目（CLAUDE.md、Skills、Hooks），然後用子代理探索程式碼庫，透過追問填補資訊缺口，最後在寫入任何檔案前讓你審核。
手動建立
你也可以直接在專案根目錄建立 CLAUDE.md 檔案。以下是一個完整的範例：
# 專案概述
這是一個使用 Next.js 14 + TypeScript 的電商平台後台管理系統。
# 技術棧
- 前端：Next.js 14（App Router）、React 18、TypeScript 5
- 樣式：Tailwind CSS 3
- 狀態管理：Zustand
- API：RESTful API with Express.js
- 資料庫：PostgreSQL + Prisma ORM
- 測試：Jest + React Testing Library
# 常用指令
- 開發伺服器：`npm run dev`
- 執行測試：`npm test`
- 建置專案：`npm run build`
- 資料庫遷移：`npx prisma migrate dev`
- Lint 檢查：`npm run lint`
# 程式碼規範
- 使用 2 格空白縮排
- 元件使用 PascalCase 命名（例如：UserProfile.tsx）
- 工具函數使用 camelCase 命名
- API 路由放在 src/app/api/ 目錄下
- 所有 API 回應使用統一的 ApiResponse 型別
- 提交前必須通過 ESLint 和 TypeScript 檢查
# 專案結構
- src/app/ — Next.js App Router 頁面
- src/components/ — 可重用元件
- src/lib/ — 工具函數和共用邏輯
- src/types/ — TypeScript 型別定義
- prisma/ — 資料庫 Schema 和遷移檔案
# Git 規範
- Commit message 使用 Conventional Commits 格式
- 格式：type(scope): description
- 類型：feat, fix, docs, style, refactor, test, chore 撰寫高效的 CLAUDE.md
CLAUDE.md 的內容會在每次對話開始時載入到 Context Window 中，消耗寶貴的 Token。因此，寫得精準且簡潔非常重要。以下是幾個關鍵原則：
控制大小：目標 200 行以內
每個 CLAUDE.md 檔案建議控制在 200 行以內。過長的檔案會消耗更多 Context，導致 Claude 對指示的遵循度下降。如果你的指示越來越多，可以使用匯入語法或 .claude/rules/ 來拆分。
結構清晰：善用 Markdown 標題和列表
使用 Markdown 標題和項目符號來分組相關指示。Claude 掃描結構化內容的方式和人類閱讀一樣——組織良好的段落比密集的文字更容易遵循。
指示具體：寫出可驗證的規則
模糊的指示容易被忽略，具體的指示更容易被遵守：
| 不好的寫法 | 好的寫法 |
|---|---|
| 格式要正確 | 使用 2 格空白縮排 |
| 測試你的修改 | 提交前執行 npm test |
| 檔案要有組織 | API handlers 放在 src/api/handlers/ 目錄 |
避免衝突：定期檢查一致性
如果兩條規則互相矛盾，Claude 可能會隨機選擇其中一條。建議定期檢視你的 CLAUDE.md 檔案、子目錄中的 CLAUDE.md 和 .claude/rules/ 規則，移除過時或衝突的指示。
進階功能：匯入、規則與排除
匯入其他檔案（@import）
CLAUDE.md 支援使用 @path/to/file 語法匯入其他檔案。被匯入的檔案會在啟動時一起展開並載入到 Context 中。支援相對路徑和絕對路徑，匯入可以遞迴（最多 5 層）。
# 參考 README 了解專案概述
See @README.md for project overview and @package.json for available npm commands.
# 額外指示
- Git 工作流程 @docs/git-instructions.md
- API 設計規範 @docs/api-design.md如果你的專案已經有 AGENTS.md 檔案（給其他 AI 工具使用），可以在 CLAUDE.md 中匯入它，避免重複撰寫：
@AGENTS.md
## Claude Code 專屬指示
在修改 src/billing/ 下的檔案時使用 plan mode。.claude/rules/ 規則目錄
對於大型專案，你可以把指示拆分到 .claude/rules/ 目錄中的多個檔案，每個檔案專注一個主題。這讓指示更容易維護，也能設定路徑範圍，讓規則只在 Claude 處理特定檔案時載入：
your-project/
├── .claude/
│ ├── CLAUDE.md # 主要專案指示
│ └── rules/
│ ├── code-style.md # 程式碼風格
│ ├── testing.md # 測試慣例
│ └── security.md # 安全要求你還可以使用 YAML frontmatter 設定路徑範圍，讓規則只在處理特定檔案時觸發：
---
paths:
- "src/api/**/*.ts"
---
# API 開發規則
- 所有 API 端點必須包含輸入驗證
- 使用標準的錯誤回應格式
- 加入 OpenAPI 文件註解排除特定 CLAUDE.md 檔案
在大型 Monorepo 中，其他團隊的 CLAUDE.md 可能會被讀取到。你可以用 claudeMdExcludes 設定來跳過不相關的檔案：
// .claude/settings.local.json
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}自動記憶（Auto Memory）詳解
自動記憶讓 Claude 在工作過程中自動累積知識，不需要你手動寫入任何內容。Claude 會自行判斷哪些資訊值得記住：建置指令、除錯心得、架構筆記、程式碼風格偏好等等。
開啟與關閉自動記憶
自動記憶預設是開啟的。你可以透過以下方式切換：
- 在對話中執行
/memory指令，使用自動記憶切換開關 - 在專案設定中設定
"autoMemoryEnabled": false - 設定環境變數
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
儲存位置與結構
每個專案的自動記憶存放在 ~/.claude/projects/<project>/memory/ 目錄下。同一個 Git Repository 的所有 worktree 和子目錄共享同一個記憶目錄：
~/.claude/projects//memory/
├── MEMORY.md # 精簡索引，每次對話都會載入
├── debugging.md # 除錯模式筆記
├── api-conventions.md # API 設計決策
└── ... # Claude 自行建立的其他主題檔案 其中 MEMORY.md 是索引檔，每次對話會載入前 200 行或 25KB（以先到者為準）。Claude 會將詳細內容移到獨立的主題檔案中，保持 MEMORY.md 精簡。
查看與編輯記憶內容
自動記憶的檔案都是純 Markdown，你可以隨時查看、編輯或刪除。在 Claude Code 中執行 /memory 指令，可以瀏覽所有載入的記憶檔案，也可以開啟自動記憶資料夾。
你也可以在對話中告訴 Claude「記住 XXX」，例如「記住這個專案一律使用 pnpm 而不是 npm」，Claude 就會將它存入自動記憶中。如果你想把指示加到 CLAUDE.md 而不是自動記憶，可以明確說「把這個加到 CLAUDE.md」。
CLAUDE.md 的載入機制
了解 CLAUDE.md 如何被載入，有助於你更好地組織檔案。Claude Code 會從你目前的工作目錄開始，向上逐層搜尋每個目錄中的 CLAUDE.md 和 CLAUDE.local.md。例如，如果你在 foo/bar/ 啟動 Claude Code，它會載入：
foo/bar/CLAUDE.md和foo/bar/CLAUDE.local.mdfoo/CLAUDE.md和foo/CLAUDE.local.md- 繼續向上直到根目錄
所有找到的檔案會串接在一起，而不是互相覆蓋。在同一個目錄中，CLAUDE.local.md 會附加在 CLAUDE.md 之後，所以當指示衝突時，你的個人設定會是 Claude 最後讀到的內容。
另外，CLAUDE.md 中的 HTML 區塊註解（<!-- 維護者筆記 -->）會在注入 Claude 的 Context 前被移除。你可以用它來留下給人類維護者的筆記，而不消耗 Context Token。
CLAUDE.md 最佳實踐
- 從 /init 開始：讓 Claude 先分析專案，再根據需要調整生成的內容
- 保持精簡：目標 200 行以內，過長的指示反而降低遵循度
- 寫具體的指示：「使用 2 格空白縮排」比「格式要正確」有效得多
- 版本控制：將 CLAUDE.md 加入 Git，讓團隊成員共享相同的指示
- 個人偏好用 CLAUDE.local.md：將 CLAUDE.local.md 加入 .gitignore，存放個人的沙箱 URL、測試資料等
- 大型專案用 rules/：善用 .claude/rules/ 目錄拆分規則，並搭配路徑範圍
- 定期維護：隨著專案演進，定期更新 CLAUDE.md，移除過時的指示
- 善用匯入：用 @import 引用 README、API 文件等現有文件，避免重複內容
常見問題排除
| 問題 | 原因與解決方法 |
|---|---|
| Claude 沒有遵守 CLAUDE.md 的指示 | 執行 /memory 確認檔案有被載入。檢查是否有衝突的指示，並將模糊的描述改為具體的規則 |
| /compact 後指示消失了 | CLAUDE.md 會在壓縮後重新載入，不會遺失。如果指示消失，表示它只是在對話中提到而未寫入 CLAUDE.md |
| CLAUDE.md 太大了 | 超過 200 行會降低遵循度。使用 @import 匯入或拆分到 .claude/rules/ 目錄 |
| 不知道自動記憶存了什麼 | 執行 /memory 瀏覽自動記憶資料夾，所有內容都是純 Markdown，可以自由編輯或刪除 |
總結
CLAUDE.md 是 Claude Code 最重要的設定機制之一。透過良好的 CLAUDE.md 設定，你可以讓 Claude 從第一句對話就理解你的專案規範，大幅減少溝通成本。搭配自動記憶功能，Claude 還能隨著使用時間越來越了解你的工作方式和偏好。
建議現在就到你的專案中執行 /init，生成你的第一份 CLAUDE.md，然後根據實際需求逐步調整。下一篇文章我們將介紹 Claude Code 的完整 CLI 指令參考，幫助你掌握所有可用的命令。
延伸閱讀
- Claude Code 是什麼？完整介紹與安裝教學
- Claude Code 新手上路：第一次使用就上手
- Claude Code CLI 指令完整參考
- Context 管理與 Token 優化技巧
- Slash Commands 與快捷鍵完整指南
