CLAUDE.md 實戰模板集：五種專案類型的寫法
這是 CLAUDE.md 系列的實戰延伸篇。如果你還沒看過基礎篇： 📖 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（上） 📖 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（中）
🎯 前言
CLAUDE.md 指南系列介紹了「怎麼寫」，但最常收到的問題是：
「你的 CLAUDE.md 長什麼樣子？能給我看嗎？」
問題是，每種專案需要的 CLAUDE.md 完全不同。前端專案要寫元件規範，後端專案要寫 API 慣例，monorepo 要寫 package 之間的關係。
這篇文章提供五種常見專案類型的 CLAUDE.md 模板，你可以直接複製、根據自己的專案修改。
📋 模板使用說明
每個模板都遵循相同的結構原則（來自 CLAUDE.md 指南系列）：
- 專案概述：一段話說清楚這是什麼
- 開發指令：怎麼跑、怎麼測、怎麼建置
- 架構：Claude 需要知道的結構和慣例
- 注意事項：這個專案特有的地雷
模板中用 {大括號} 標示需要你替換的部分。
1️⃣ 前端專案（React / Vue / Astro）
適用於 SPA、SSR、SSG 類型的前端專案。
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code)
when working with code in this repository.
## 專案概述
{框架名稱} 前端專案，使用 {語言} 開發。
{一句話描述專案功能}。
部署至 {部署平台}。
## 開發指令
- `{套件管理器} install` — 安裝相依套件
- `{套件管理器} run dev` — 啟動開發伺服器（`localhost:{port}`）
- `{套件管理器} run build` — 建置正式版本
- `{套件管理器} run test` — 執行測試
- `{套件管理器} run test -- {測試檔案路徑}` — 執行單一測試
- `{套件管理器} run lint` — 程式碼檢查
- `{套件管理器} run type-check` — TypeScript 型別檢查
## 架構
### 目錄結構
- `src/components/` — 可重用元件
- `src/pages/` 或 `src/views/` — 頁面元件
- `src/hooks/` 或 `src/composables/` — 邏輯抽取
- `src/stores/` — 狀態管理（{Zustand / Pinia / Redux}）
- `src/api/` — API 呼叫層
- `src/types/` — TypeScript 型別定義
### 元件慣例
- 元件使用 {函式元件 / SFC / Astro 元件}
- 命名規則：{PascalCase / kebab-case}
- 樣式方案：{CSS Modules / Tailwind / styled-components / scoped style}
- 狀態管理：{方案名稱}，store 定義在 `src/stores/`
### 路由
- {檔案式路由 / 集中式路由設定}
- 路由定義位置：`{路由檔案路徑}`
### API 呼叫
- 所有 API 呼叫透過 `src/api/` 中的函數
- 基底 URL 設定在 `{環境變數或設定檔}`
- 使用 {fetch / axios / ky} 作為 HTTP client
## 注意事項
- 不要直接修改 `{鎖定檔}` — 用 `{套件管理器} install` 管理
- 環境變數放在 `.env.local`（不提交 git）
- 圖片放在 `{圖片目錄}`，建置時會自動最佳化2️⃣ 後端 API 專案（Node.js / PHP / Python）
適用於 REST API、GraphQL、微服務。
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code)
when working with code in this repository.
## 專案概述
{框架名稱} 後端 API 服務，使用 {語言} {版本} 開發。
{一句話描述功能}。
資料庫：{資料庫類型} {版本}。
## 開發指令
### 啟動開發環境
{如果用 Docker}：
- `docker-compose up -d` — 啟動所有服務
- `docker-compose logs -f {服務名稱}` — 查看 log
- `docker-compose down` — 停止服務
{如果不用 Docker}：
- `{啟動指令}` — 啟動開發伺服器（`localhost:{port}`）
### 測試
- `{測試指令}` — 執行所有測試
- `{單一測試指令} {測試路徑}` — 執行單一測試
- `{覆蓋率指令}` — 產生覆蓋率報告
### 資料庫
- `{migration 指令}` — 執行 migration
- `{seed 指令}` — 填入測試資料
- 連線資訊在 `{設定檔路徑}` 或環境變數
### 測試帳號
| 角色 | 帳號 | 密碼 |
|------|------|------|
| 管理員 | `{帳號}` | `{密碼}` |
| 一般用戶 | `{帳號}` | `{密碼}` |
## 架構
### API 慣例
- RESTful 風格，路徑使用 {kebab-case / snake_case}
- 回應格式：`{ "data": ..., "error": ... }`
- 認證方式：{JWT / Session / API Key}
- API 版本控制：{URL prefix / Header}
### 目錄結構
- `{路由目錄}/` — 路由定義
- `{控制器目錄}/` — 業務邏輯
- `{模型目錄}/` — 資料模型 / ORM
- `{中間層目錄}/` — 中間層（認證、日誌等）
- `{migration 目錄}/` — 資料庫 migration
### 資料庫
- ORM / Query Builder：{名稱}
- 命名慣例：表名 {複數小寫}，欄位 {snake_case}
- Migration 命名：`{格式}`
### 錯誤處理
- 使用 HTTP 標準狀態碼
- 錯誤格式：`{ "error": { "code": "...", "message": "..." } }`
- {框架的錯誤處理機制說明}
## 注意事項
- 不要在程式碼中寫死資料庫連線資訊，使用環境變數
- Migration 只能新增，不要修改已發布的 migration
- {其他專案特有的地雷}3️⃣ 全端專案（Next.js / Nuxt / Laravel + Blade）
前後端在同一個 repo，需要說清楚兩邊的邊界。
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code)
when working with code in this repository.
## 專案概述
{框架名稱} 全端應用，前端使用 {前端技術}，後端使用 {後端技術}。
資料庫：{資料庫}。部署至 {平台}。
## 開發指令
- `{啟動指令}` — 啟動開發伺服器（前後端同時）
- `{建置指令}` — 建置正式版本
- `{測試指令}` — 執行所有測試
- `{lint 指令}` — 程式碼檢查（前後端都跑）
- `{migration 指令}` — 執行資料庫 migration
## 架構
### 前後端分界
| 層級 | 位置 | 技術 |
|------|------|------|
| 頁面 / UI | `{前端目錄}` | {React / Vue / Blade} |
| API 路由 | `{API 目錄}` | {Node.js / PHP / Python} |
| 資料庫 | `{模型目錄}` | {ORM 名稱} |
| 共用型別 | `{型別目錄}` | TypeScript |
### Server Actions / API Routes
{框架特有的前後端通訊方式}：
- {Server Actions / tRPC / API routes / Controller}
- 定義位置：`{路徑}`
- 呼叫方式：{說明}
### 認證
- 方案：{NextAuth / Nuxt Auth / Laravel Sanctum}
- Session 儲存：{Cookie / Database / Redis}
- 設定位置：`{路徑}`
### 資料庫
- ORM：{Prisma / Drizzle / Eloquent / TypeORM}
- Schema 定義：`{路徑}`
- Migration：`{migration 指令}` — 只能新增，不能修改已發布的
## 注意事項
- 前端元件不要直接 import 後端模組（反之亦然）
- 環境變數：前端用 `{NEXT_PUBLIC_ / NUXT_PUBLIC_}` 前綴，後端不加
- 敏感邏輯（認證、付款）必須在 server 端處理4️⃣ 資料分析 / ML 專案（Python）
適用於 Jupyter notebook、資料管線、ML 模型專案。
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code)
when working with code in this repository.
## 專案概述
{專案名稱}：{一句話描述}。
使用 Python {版本}，主要用途為 {資料分析 / 機器學習 / ETL}。
## 開發指令
### 環境設定
- `python -m venv .venv` — 建立虛擬環境
- `source .venv/bin/activate` — 啟動虛擬環境
- `pip install -r requirements.txt` — 安裝相依套件
- `pip install -e .` — 以 editable 模式安裝（如有 setup.py）
### 執行
- `jupyter lab` — 啟動 Jupyter Lab
- `python -m {模組名稱}` — 執行主程式
- `python scripts/{腳本名稱}.py` — 執行特定腳本
### 測試
- `pytest` — 執行所有測試
- `pytest tests/{測試檔案}.py -v` — 執行單一測試
- `pytest -k "{關鍵字}"` — 執行符合關鍵字的測試
## 架構
### 目錄結構
- `notebooks/` — Jupyter notebooks（探索性分析、實驗）
- `src/{專案名稱}/` — 正式程式碼
- `data/` — 資料載入與前處理
- `features/` — 特徵工程
- `models/` — 模型定義與訓練
- `utils/` — 工具函數
- `scripts/` — 獨立執行腳本
- `tests/` — 測試
- `data/` — 資料檔案（不提交 git，見 .gitignore）
- `models/` — 訓練好的模型檔案（不提交 git）
### 資料慣例
- 原始資料放 `data/raw/`，不修改
- 處理後資料放 `data/processed/`
- 中間結果放 `data/interim/`
- 資料檔案不提交 git（用 .gitignore 排除）
### Notebook 慣例
- Notebook 用於**探索和原型**，正式邏輯抽到 `src/`
- 命名格式：`{編號}-{作者縮寫}-{描述}.ipynb`
- 例：`01-wl-exploratory-analysis.ipynb`
- 每個 notebook 開頭寫清楚目的和結論
### 程式碼風格
- 型別提示：所有函數都加 type hints
- Docstring 風格：{Google / NumPy / Sphinx}
- Formatter：{black / ruff}
- Linter：{ruff / flake8}
## 注意事項
- 大型資料檔案不要提交 git — 用 DVC 或 .gitignore
- 不要在 notebook 中硬寫絕對路徑
- 隨機種子（random seed）要固定，確保可重現
- 敏感資料（API key、資料庫連線）放環境變數5️⃣ Monorepo（Turborepo / Nx / pnpm workspaces）
多個 package 共存的大型 repo，最需要說清楚 package 之間的關係。
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code)
when working with code in this repository.
## 專案概述
Monorepo，使用 {Turborepo / Nx / pnpm workspaces} 管理。
包含 {N} 個 package：{簡述主要 package}。
## 開發指令
### 全域指令（從根目錄執行）
- `{套件管理器} install` — 安裝所有 package 的相依套件
- `{套件管理器} run build` — 建置所有 package（依照相依順序）
- `{套件管理器} run test` — 執行所有 package 的測試
- `{套件管理器} run lint` — 所有 package 的 lint
### 針對特定 package
- `{套件管理器} run dev --filter={package名稱}` — 只啟動特定 package
- `{套件管理器} run test --filter={package名稱}` — 只測試特定 package
- `{套件管理器} run build --filter={package名稱}...` — 建置特定 package 及其相依
## 架構
### Package 總覽
| Package | 路徑 | 用途 | 依賴 |
|---------|------|------|------|
| `{名稱}` | `apps/{名稱}` | {說明} | {依賴哪些 package} |
| `{名稱}` | `apps/{名稱}` | {說明} | {依賴哪些 package} |
| `{名稱}` | `packages/{名稱}` | {說明} | — |
| `{名稱}` | `packages/{名稱}` | {說明} | — |
### 相依關係
```text
apps/web ──→ packages/ui
──→ packages/shared
apps/api ──→ packages/shared
──→ packages/db關鍵規則：
packages/中的是共用 library，不能依賴apps/apps/可以依賴packages/packages/之間的相依要明確宣告在 package.json
共用設定
- TypeScript 設定：
packages/tsconfig/中的基礎設定，各 package 繼承 - ESLint 設定：
packages/eslint-config/ - 建置設定：
turbo.json（定義 task 的相依和快取策略）
注意事項
- 修改
packages/中的共用程式碼時，要確認所有依賴它的apps/都不會壞 - 新增 package 間的相依時，要更新
turbo.json的 pipeline - 不要在 package 之間用相對路徑 import，用 package 名稱
- 安裝套件要指定目標 package：
{套件管理器} add {套件} --filter={package名稱}
---
## 💡 跨類型的通用建議
### 不要寫太長
CLAUDE.md 超過 200 行就開始失去效果。Claude 會把整份文件載入 context，太長會稀釋重要資訊。
**如果你的 CLAUDE.md 超過 200 行**，考慮：
- 把詳細的 API 文件移到別的 `.md` 檔案
- 只在 CLAUDE.md 中放「Claude 需要知道才能正確工作」的資訊
- 刪掉 Claude 自己能從程式碼推斷出來的內容
### 不要寫顯而易見的事
```markdown
❌ "使用 git 進行版本控制"
❌ "遵循 DRY 原則"
❌ "寫有意義的變數名稱"
✅ "Migration 只能新增，不能修改已發布的"
✅ "前端環境變數必須加 NEXT_PUBLIC_ 前綴"
✅ "所有 API 回應都包在 { data, error } 結構中"定期更新
模板是起點，不是終點。隨著專案演進，CLAUDE.md 也要跟著更新。搭配 Git Hooks 自動提醒，讓你不會忘記。
🎉 結語
好的 CLAUDE.md 不需要從零開始寫。挑一個最接近你專案的模板，花 10 分鐘填入你的具體資訊，就有一個堪用的 CLAUDE.md。
之後隨著使用 Claude Code 的過程，你會自然發現「Claude 又搞錯了，我應該在 CLAUDE.md 補一條」——這些修正累積起來，就是最貼合你專案的 CLAUDE.md。
📎 相關文章：