會話初始化流程：
    ↓
加載 Claude Code 系統(tǒng)提示（內(nèi)置，約15-20K token）
    ↓
發(fā)現(xiàn)并加載 CLAUDE.md 文件（從當(dāng)前目錄向上查找，直到 git root）
    ↓
加載 .claude/rules/ 目錄下的規(guī)則（按需或全量）
    ↓
會話就緒，等待用戶輸入

monorepo/
+-- CLAUDE.md               # 倉庫級規(guī)范（總是加載）
+-- apps/
|   +-- frontend/
|   |   +-- CLAUDE.md       # 前端特定規(guī)范（在前端目錄工作時(shí)加載）
|   +-- backend/
|       +-- CLAUDE.md       # 后端特定規(guī)范（在后端目錄工作時(shí)加載）
+-- packages/
    +-- shared/
        +-- CLAUDE.md       # 共享包規(guī)范

# 刪掉這行，會發(fā)生什么？

"使用 TypeScript 編寫代碼"
→ Claude 可能默認(rèn)用 JavaScript，有價(jià)值 ?

"代碼要清晰可讀"
→ Claude 本來就會寫清晰代碼，沒有價(jià)值 ?

"所有錯誤處理必須記錄到 logger，不能用 console.log"
→ 不寫，Claude 可能用 console.log，有價(jià)值 ?

"請保持代碼的高質(zhì)量"
→ 廢話，刪除 ?

# 不好（教程式，Claude 早就知道這些）
API端點(diǎn)應(yīng)該處理錯誤并返回適當(dāng)?shù)腍TTP狀態(tài)碼。
使用404表示資源不存在，400表示請求無效，500表示服務(wù)器錯誤。

# 好（約束式，告訴 Claude 項(xiàng)目特定規(guī)范）
所有API錯誤必須使用 ErrorResponse 結(jié)構(gòu)體，不能直接返回字符串。
錯誤代碼使用項(xiàng)目定義的 ErrorCode 枚舉，參見 pkg/errors/codes.go。

# 項(xiàng)目：用戶行為分析平臺

## 技術(shù)棧
- 后端：Go 1.21，使用 Gin 框架，gorm + PostgreSQL
- 前端：React 18 + TypeScript，Vite，Zustand 狀態(tài)管理
- 部署：Docker，k8s，使用 GitHub Actions CI/CD

## 關(guān)鍵約定

### Go 后端
- 錯誤處理：必須使用 `pkg/errors` 包的 `AppError`，不能用 `errors.New` 或 `fmt.Errorf`
- 日志：使用 `pkg/logger` 的結(jié)構(gòu)化日志，不能用 `fmt.Println` 或 `log.Print`
- 數(shù)據(jù)庫：所有查詢必須通過 Repository 層，不能在 Handler 里直接調(diào)用 gorm
- 測試：表驅(qū)動測試風(fēng)格，mock 放在 `_test.go` 文件的 `TestMain` 中

### React 前端
- 組件狀態(tài)：局部用 `useState`，跨組件用 `useStore`（Zustand），禁止用 Redux
- API 調(diào)用：統(tǒng)一使用 `src/api/` 目錄下的 API 客戶端，不能直接 `fetch`
- 樣式：Tailwind CSS only，不能寫內(nèi)聯(lián) style，不能新建 CSS 文件

### 通用規(guī)范
- 所有公共 API 函數(shù)必須有 JSDoc/GoDoc 注釋
- 禁止提交 `.env` 文件，使用 `.env.example` 作為模板
- 分支命名：`feat/`, `fix/`, `chore/` 前綴

## 常用命令
- 啟動開發(fā)：`make dev`
- 運(yùn)行測試：`make test`
- 數(shù)據(jù)庫遷移：`make migrate-up`
- 生成 API 文檔：`make docs`

.claude/rules/
+-- typescript.md       # TypeScript 特定規(guī)范
+-- testing.md          # 測試規(guī)范
+-- database.md         # 數(shù)據(jù)庫使用規(guī)范
+-- security.md         # 安全規(guī)范
+-- api-design.md       # API 設(shè)計(jì)規(guī)范

---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript 規(guī)范

- 優(yōu)先使用 `interface` 而不是 `type`（除非需要聯(lián)合類型）
- 不允許 `any` 類型，使用 `unknown` + 類型守衛(wèi)
- 所有 Promise 必須有錯誤處理（`.catch()` 或 `try/catch`）
- 使用 `satisfies` 運(yùn)算符代替 `as` 類型斷言

# 項(xiàng)目規(guī)范

## API 文檔
請參考以下 API 設(shè)計(jì)規(guī)范：
@docs/api-design-guide.md

## Git 工作流
@docs/git-workflow.md

## 當(dāng)前架構(gòu)
@ARCHITECTURE.md

# 常用的 @imports 模式

# 引用 README（讓 Claude 了解項(xiàng)目背景）
@README.md

# 引用包依賴（讓 Claude 知道可用的庫）
@package.json

# 引用全局個(gè)人配置
@~/.claude/personal-preferences.md

monorepo/CLAUDE.md（約50行）：
  - 通用代碼規(guī)范
  - 跨包的接口約定
  - CI/CD 流程
  
apps/frontend/CLAUDE.md（約40行）：
  - React/TypeScript 特定規(guī)范
  - 組件庫使用規(guī)范
  - 測試框架（Vitest + Testing Library）

apps/backend/CLAUDE.md（約40行）：
  - Go 編碼規(guī)范
  - 內(nèi)部包使用約定
  - 數(shù)據(jù)庫訪問模式

[ ] 每一行都能回答"沒有這行會出錯嗎？"（Litmus Test）
[ ] 總行數(shù)在 200 行以內(nèi)
[ ] 沒有解釋 Claude 已經(jīng)知道的通用最佳實(shí)踐
[ ] 有明確的技術(shù)棧聲明（語言版本、框架版本）
[ ] 有項(xiàng)目特定的約束（非通用規(guī)范）
[ ] 有常用命令（不需要 Claude 自己去猜）
[ ] 細(xì)分規(guī)范已遷移到 .claude/rules/ 目錄
[ ] 被 @imports 引用的文件都存在