Claude Code 的 CLAUDE.md 模板：前端、後端、數據分析各一份，附拆分與自檢方法

本文根據 Claude Code 官方《How Claude remembers your project》和《Set up Claude Code in a monorepo or large codebase》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。官方沒有給出分技術棧的模板，三份模板是本站自己擬的示例。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 剛裝好 Claude Code（見 /guides/claude-code-getting-started），不知道 CLAUDE.md 具體怎麼落筆的人；
• 已經看過 /guides/claude-md-agents-md 裏的通用骨架，想要更貼近自己技術棧的版本的人；
• 項目裏同時有前端、後端、數據腳本，想按目錄拆開管理的人。

結論先說

1. 官方的核心要求只有幾條：每個文件目標少於 200 行；寫成能檢查的句子；用標題和列表分組；不要互相矛盾。
2. 只寫 Claude 讀代碼猜不到的東西：啟動、檢查、測試的真實命令，目錄約定，容易踩的坑。
3. 只對一部分文件有用的規則，別塞進根文件：放進 .claude/rules/ 並用 paths 限定，官方說它們只在 Claude 處理匹配文件時才加載。
4. 模板是起點不是終點：先用 /init 出初稿，再對照下面的模板刪減，最後用 /context all 確認真的加載了。
5. CLAUDE.md 不是強制規則：官方寫明 Claude 把它當上下文，要硬性攔截請用 hook（見 /guides/claude-code-hooks）。

圖：本站根據 Claude Code 官方《How Claude remembers your project》 整理的示意圖

一、先記住官方的寫法原則

官方給的示例是把含糊的話換成可驗證的話：「使用 2 個空格縮進」比「代碼格式要規範」好，「提交前運行 npm test」比「記得測試」好，「接口處理函數放在 src/api/handlers/」比「文件要組織好」好。

另外官方說明了加載方式：從當前工作目錄一直到上層各級目錄裏的 CLAUDE.md 都會在啟動時加載，並且是拼接而不是互相覆蓋；子目錄裏的 CLAUDE.md 則是在 Claude 讀寫那個子目錄裏的文件時才按需加載。塊級 HTML 註釋（<!-- 給維護者的備註 -->）會在注入上下文前被去掉，可以放心寫給人看的說明，不佔 token。

放在哪個位置，通用教學已經講過，簡單說：團隊共享的寫在項目根目錄的 ./CLAUDE.md 或 ./.claude/CLAUDE.md 並提交到倉庫；只給自己看的寫在 ./CLAUDE.local.md 並加入 .gitignore。

二、模板一：前端項目

下面以「React + TypeScript + 組件庫」為例。命令都是佔位，請換成你 package.json 裏真實存在的腳本。

markdown
# 項目說明
[公司官網前端]，React + TypeScript，包管理器 [pnpm]。

## 常用命令
- 本地啟動：`pnpm dev`
- 類型檢查：`pnpm typecheck`（改完一組文件後必須通過）
- 單個測試：`pnpm test -- src/components/Button`（優先跑單個，別每次跑全量）
- 代碼檢查：`pnpm lint`

## 目錄約定
- `src/components/`：通用組件，每個組件一個文件夾，含 `index.tsx` 和同名測試
- `src/pages/`：頁面，只做組裝，不寫業務邏輯
- `src/hooks/`：自定義 hook，以 `use` 開頭命名
- 接口請求統一走 `src/api/client.ts`，頁面裏不要直接寫 fetch

## 代碼規範（只寫和預設習慣不同的）
- 組件用函數組件，不寫 class 組件
- 樣式用 [CSS Modules]，不寫內聯 style
- 用戶可見的文案統一放 `src/locales/`，不要寫死在組件裏

## 工作流程
- 新增或修改組件時，同時補一個最小的測試
- 提交資訊用 `feat:` / `fix:` 開頭
- 不要直接修改 `src/generated/` 下的文件，運行 `pnpm codegen` 重新生成

## 已知的坑
- 本地需要 `.env.local`，字段見 `.env.example`

這份模板大約 25 行，離 200 行的上限很遠。繼續往裏加之前先問一句：這條規則只對一部分文件有效嗎？如果是，見第五節。

三、模板二：後端接口項目

以「Python + FastAPI + 數據庫」為例，同樣只是佔位示例。

markdown
# 項目說明
[訂單服務]後端，Python [3.12] + FastAPI + PostgreSQL，依賴管理用 [uv]。

## 常用命令
- 啟動開發服務：`uv run fastapi dev app/main.py`
- 運行測試：`uv run pytest tests/ -x`（單個文件：`uv run pytest tests/test_orders.py`）
- 代碼檢查：`uv run ruff check .`
- 生成遷移：`uv run alembic revision --autogenerate -m "說明"`
- 應用遷移：`uv run alembic upgrade head`

## 目錄約定
- `app/routers/`：路由，只做參數校驗和調用服務層
- `app/services/`：業務邏輯
- `app/models/`：數據庫模型；改模型後必須生成遷移
- `tests/`：與 `app/` 結構一一對應

## 代碼規範
- 金額一律用整數「分」存儲，不用浮點數
- 所有接口返回統一的錯誤結構：`{"code": ..., "message": ...}`
- 不要在路由函數里寫原始 SQL

## 工作流程
- 改動超過 3 個文件時，先列出計劃再動手
- 已合併的遷移文件不能再修改，需要變更就新建遷移
- 不要把任何密鑰寫進代碼，讀取環境變量，示例見 `.env.example`

## 已知的坑
- 測試依賴本地數據庫，先執行 [docker compose up -d db]

後端的坑多半在「怎麼跑起來」和「遷移怎麼走」，所以命令和遷移規則要寫在最前面。至於「不要把密鑰寫進代碼」，官方的提醒是：CLAUDE.md 本身也會進入上下文，所以密鑰、密碼、連接串也別寫進這個文件裏，只寫「從哪個環境變量讀」。

四、模板三：數據分析項目

數據項目最容易出問題的是「環境」和「口徑」，模板就圍繞這兩點寫。

markdown
# 項目說明
[月度銷售分析]，Python + pandas + Jupyter，結果輸出為圖表和 Markdown 報告。

## 環境與命令
- 創建環境：`[uv sync]`
- 運行全部分析腳本：`[uv run python run_all.py]`
- 只重跑某個月：`[uv run python run_all.py --month 2026-10]`

## 數據位置
- 原始數據：`data/raw/`（只讀，任何情況下都不要修改或刪除）
- 清洗後數據：`data/clean/`（可由腳本重新生成）
- 輸出：`reports/`

## 口徑約定
- 「銷售額」= 訂單實付金額，不含退款；詳細定義見 @docs/metrics.md
- 日期統一用 [UTC+8]，列名用小寫下劃線

## 工作方式
- 先說明準備怎麼算，再寫代碼；結果必須同時給出樣本量
- 畫圖時每張圖寫明數據時間範圍
- 不要在 notebook 裏寫死文件的絕對路徑

## 已知的坑
- `data/raw/` 裏有幾個月份缺少 [退款] 列，腳本里已特殊處理，改動前先看 `clean.py`

注意最後一節裏的 @docs/metrics.md：官方的 @路徑 導入語法會把被引用文件和 CLAUDE.md 一起展開加載，相對路徑以包含它的文件為準，最多遞歸四層。官方特別提醒：導入只是幫你組織內容，不會減少上下文佔用，因為被導入的文件會一起加載。想省上下文，要靠下一節的規則拆分。

五、把只管一部分文件的規則拆出去

官方的做法是在 .claude/rules/ 下放一個主題一個文件的 Markdown，並用前置字段 paths 限定適用範圍。沒有 paths 的規則和 .claude/CLAUDE.md 一樣在啟動時加載；有 paths 的規則只在 Claude 對匹配文件進行讀、寫、編輯時才加載。paths 是規則文件裏唯一會被讀取的字段。

比如把前端模板中的組件規範拆出來：

markdown
---
paths:
  - "src/components/**/*.tsx"
---

# 組件規則

- 每個組件一個文件夾，含 `index.tsx` 和同名測試文件
- 組件的 props 類型用 `interface` 聲明並導出
- 不要在組件內直接發請求，通過 `src/hooks/` 裏的 hook 獲取數據

儲存為 .claude/rules/components.md 即可。官方還說可以用花括號一次寫多個後綴，例如 "src/**/*.{ts,tsx}"。

如果你的倉庫把前後端放在一起，官方的大倉庫指南給出另一條路：根目錄一個 CLAUDE.md 寫全倉庫通用規則，每個子目錄（比如 packages/api/）再放自己的 CLAUDE.md。兩者怎麼選，官方的區分是：希望由各目錄的負責人自己維護、規則跟着代碼走，用子目錄 CLAUDE.md；希望所有規則集中在一處，或同一條規則要作用於很多分散的路徑，用 .claude/rules/ 加 paths。更詳細的大倉庫設定見 /guides/claude-code-large-repo-focus-directories。

六、寫好之後怎麼驗證

圖：本站根據 Claude Code 官方《How Claude remembers your project》 整理的示意圖

1. 在項目裏運行 /init。已有 CLAUDE.md 時它只會提出改進建議而不是覆蓋。如果想要多輪問答式的流程，官方說法是先把環境變量 CLAUDE_CODE_NEW_INIT 設為 1 再運行。
2. 開一個新會話，運行 /context all，在 Memory files 列表裏確認你的文件出現了。
3. 運行 /doctor prompt-audit，讓 Claude 找出過時、互相矛盾或引用了不存在文件的內容。官方說明它只給報告和修改建議，你要求之後才會改文件；這個命令需要 Claude Code v2.1.283 或更高版本。
4. 觀察真實行為：讓 Claude 做一件小事，看它有沒有按模板裏的命令去跑。沒有的話，多半是寫得太含糊或和別的規則衝突。

什麼時候該往裏加內容？官方列了幾個信號：Claude 第二次犯同一個錯；代碼審查發現了它本該知道的約定；你在新會話裏又敲了一遍上次的糾正；新同事也需要同樣的背景。反過來，沒人遇到過的問題不用提前寫。

常見問題

Q：寫了「不要修改 xxx」，Claude 還是改了？

官方明說 CLAUDE.md 是上下文而非強制配置。要硬性禁止，用 PreToolUse hook，或在權限裏寫 deny 規則，見 /guides/claude-code-hooks 和 /guides/claude-code-settings-json。

Q：模板可以直接整份複製嗎？

可以當起點，但方括號和命令必須換成真實的。寫了不存在的命令，比不寫更糟。

Q：文件越寫越長怎麼辦？

官方的做法：超過 200 行就把只管一部分代碼的內容挪到帶 paths 的規則裏，多步驟流程挪到技能裏（見 /guides/skill-vs-mcp-vs-subagent-vs-hook）。

Q：用得多了額度不夠？

CLAUDE.md 越長，每次會話佔用的上下文越多。如果日常使用 Claude Code 額度吃緊，可以了解 Claude Code 訂閱方案，同時也應當先把文件精簡。

相關教學

• /guides/claude-md-agents-md：CLAUDE.md 放置位置與 AGENTS.md 的區別
• /guides/claude-code-best-practices：官方最佳實踐
• /guides/claude-code-context-compact：上下文與壓縮

參考資料

• Claude Code 官方：How Claude remembers your project — https://code.claude.com/docs/en/memory
• Claude Code 官方：Set up Claude Code in a monorepo or large codebase — https://code.claude.com/docs/en/large-codebases