CLAUDE.md 規範

CLAUDE.md 是專案的「憲法」，讓 Claude 了解你的專案規範和偏好。

為什麼需要 CLAUDE.md？

1. 解決長期記憶問題 — AI 不知道你昨天做了什麼
2. 統一規範 — 確保 AI 產出符合團隊標準
3. 減少重複溝通 — 不用每次都重新說明規範
4. 累積學習 — 記錄常見錯誤，讓 AI 不再犯

建立 CLAUDE.md

在專案根目錄建立 CLAUDE.md 檔案：

touch CLAUDE.md

基本結構

# CLAUDE.md

## 專案資訊
[專案描述]

## 技術棧
[使用的技術]

## 開發規範
[程式碼規範]

## 常見錯誤
[AI 常犯的錯誤提醒]

## 測試流程
[測試步驟]

完整範例

# CLAUDE.md

## 專案資訊
這是一個旅遊規劃網站，讓使用者可以建立和管理旅行行程。

目標使用者：想要規劃旅遊行程的一般用戶
核心功能：行程建立、活動安排、行程分享

## 技術棧
- **框架：** Next.js 16 + App Router
- **UI：** shadcn/ui + Tailwind CSS v4
- **語言：** TypeScript (strict mode)
- **資料庫：** Supabase (PostgreSQL)
- **部署：** Vercel
- **測試：** Vitest + Playwright

## 目錄結構

├── app/ # Next.js App Router 頁面 │ ├── (auth)/ # 認證相關頁面 │ ├── (dashboard)/ # 登入後頁面 │ └── api/ # API Routes ├── components/ # React 元件 │ ├── ui/ # shadcn/ui 元件 │ └── features/ # 功能元件 ├── lib/ # 工具函數 │ ├── supabase/ # Supabase 客戶端 │ └── utils/ # 通用工具 ├── types/ # TypeScript 型別定義 └── public/ # 靜態資源

## 開發規範

### TypeScript
- 使用 strict mode
- 不使用 `any` 類型
- 介面使用 `interface`，型別別名使用 `type`
- 匯出類型時使用 `export type`

### React / Next.js
- 優先使用 Server Components
- 有用到 hooks 或事件的元件必須加 `"use client"`
- 避免在 Server Component 中使用 client-only 的程式碼
- 使用 Next.js 的 Image 元件處理圖片

### 元件命名
- 元件檔名使用 PascalCase：`UserProfile.tsx`
- 元件內部函數使用 camelCase
- CSS class 使用 Tailwind utility classes

### shadcn/ui
- 從 `@/components/ui` 匯入元件
- **不要**直接從 `@radix-ui` 匯入
- 使用 `cn()` 函數合併 class names

### API Routes
- 使用 Route Handlers (app/api/*/route.ts)
- 回傳統一格式：`{ success: boolean, data?: T, error?: string }`
- 錯誤使用正確的 HTTP status code

## 常見錯誤提醒

### 必須注意
- [ ] 不要直接 import from @radix-ui，使用 shadcn/ui
- [ ] 有 hooks/事件的元件要加 "use client"
- [ ] Server Component 不能使用 useState、useEffect
- [ ] 使用 `@/` 路徑別名而非相對路徑
- [ ] 表單驗證使用 zod + react-hook-form

### 常見 Bug
- Hydration error：Server/Client 渲染不一致
- 解法：確認 Server Component 和 Client Component 的界線

### 套件使用
- 日期處理：使用 `date-fns`，不要用 `moment`
- 表單：使用 `react-hook-form` + `zod`
- 動畫：使用 `framer-motion`

## 測試流程

每次完成一個 feature 要執行：

```bash
# 1. 確認編譯通過
npm run build

# 2. 確認沒有 lint 錯誤
npm run lint

# 3. 執行測試（如果有）
npm run test

# 4. Docker 測試
docker build -t travel-planner .
docker run -p 3000:3000 travel-planner

Git 規範

Commit Message 格式

<type>: <description>

[optional body]

Type

• feat: 新功能
• fix: 修復 bug
• refactor: 重構（不改變功能）
• style: 格式調整
• docs: 文件更新
• test: 測試相關

常用指令

# 開發
npm run dev

# 建構
npm run build

# Lint
npm run lint

# 測試
npm run test

# Supabase 本地
npx supabase start
npx supabase stop

## 更新流程

當 AI 犯錯時，更新 CLAUDE.md：

AI 犯錯 ↓ 記錄錯誤到 CLAUDE.md ↓ AI 學會（下次不犯）

### 範例

**錯誤：** AI 直接從 @radix-ui 匯入元件

**更新 CLAUDE.md：**
```markdown
## 常見錯誤提醒
- 不要直接 import from @radix-ui，使用 shadcn/ui

進階技巧

1. 分區塊更新

不要每次都重寫整個 CLAUDE.md，只更新需要的區塊：

AI，請更新 CLAUDE.md 的「常見錯誤」區塊，加入：
- 不要使用 moment.js，改用 date-fns

2. 定期整理

每完成一個大功能後，整理 CLAUDE.md：

• 移除過時的規範
• 合併重複的項目
• 更新技術棧版本

3. 團隊共享

把 CLAUDE.md 加入版本控制，讓團隊成員共享規範。

下一步

• Commands 指令 - 自訂可重複使用的指令
• Subagents 使用 - 使用專業 Agent