CLAUDE.md — 你專案的大腦
用單一 markdown 檔給 Claude 永久上下文
⏱ 預估 ~4 分鐘
01 · 讀一讀
每次你開新 Claude Code session,Claude 從空白開始。它不記得你上次對話、你的程式風格、你專案慣例、甚至你用什麼框架。你每次要重新解釋一切。
CLAUDE.md 解決這個。它是 Claude 在每場 session 開始讀的 markdown 檔 — 你專案的永久指令手冊。
💡 想像一下把 CLAUDE.md 想成新團員的 onboarding 文件。不是每天早上解釋團隊慣例，你寫一次。CLAUDE.md 是那份文件 — Claude 每次「開始工作」都讀。
重點整理
- 每場 Claude Code session 從頭開始 — 不記得過去對話
- CLAUDE.md 在每場 session 開始自動載入
- 它告訴 Claude 你專案規則、慣例、重要上下文
- 就是 markdown 檔 — 你跟編其他檔一樣編
02 · 讀一讀
CLAUDE.md 能住三個地方，每個 scope 不同。
Project level — 把 CLAUDE.md 放 repo root(或 .claude/CLAUDE.md)。透過 git 跟團隊共享。用在專案慣例、build 指令、架構模式。
User level — 放 ~/.claude/CLAUDE.md。個人，所有專案都生效。用在你個人偏好。
子目錄 — 子目錄的 CLAUDE.md 檔在 Claude 讀那目錄檔案時按需載入。適合模組特定指令。
重點整理
- Project level(./CLAUDE.md)：跟團隊共享，commit 到 git
- User level(~/.claude/CLAUDE.md)：個人，所有你的專案
- 子目錄 CLAUDE.md：特定模組按需載入
- 衝突時專案規則蓋過使用者規則
03 · 看程式碼
好的 CLAUDE.md 包含 build 指令、程式風格、架構、專案特定慣例。下面是真實例子。
範例 CLAUDE.md
# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)
# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components
# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`
# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin
注意包含什麼：Claude 光讀程式碼不會發現的東西。Build 指令、不尋常命名慣例、跨來源怪癖。不要包含 Claude 探索就能發現的 — 專注在不明顯的。
04 · 看程式碼
你 CLAUDE.md 變大時，可以用 import 跟 rules 目錄切成專注檔。
有 @import 的 CLAUDE.md
# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design
# Code Style
@docs/code-style.md
Rules 目錄結構
.claude/
├── CLAUDE.md (main instructions)
└── rules/
├── api-design.md (API conventions)
├── testing.md (test patterns)
└── security.md (security rules)
@ 前綴把另一個檔內容 import 到 CLAUDE.md。.claude/rules/ 目錄裝主題特定規則，Claude 自動載入。讓主 CLAUDE.md 保持簡潔，給 Claude 詳細領域知識的存取。
05 · 選擇題
你有專案慣例每個團隊開發者都該遵守。你 CLAUDE.md 該放哪、跟團隊分享？
- 你家目錄（~/.claude/CLAUDE.md）
- Repo root(./CLAUDE.md)、commit 到 git
- README 連結的 Google Doc
- Slack 頻道置頂訊息
06 · 填空
要把另一個檔 import 到 CLAUDE.md，路徑前面加 _____
⚠ 完整互動體驗需要 JavaScript。請啟用 JavaScript 後重新整理。
※ 本站為獨立繁中教學專案，非 Anthropic 官方產品。Claude™ 為 Anthropic, PBC 商標。