Claude Code之CLAUDE.md与项目配置最佳实践

会话初始化流程：
    ↓
加载 Claude Code 系统提示（内置，约15-20K token）
    ↓
发现并加载 CLAUDE.md 文件（从当前目录向上查找，直到 git root）
    ↓
加载 .claude/rules/ 目录下的规则（按需或全量）
    ↓
会话就绪，等待用户输入

monorepo/
+-- CLAUDE.md               # 仓库级规范（总是加载）
+-- apps/
|   +-- frontend/
|   |   +-- CLAUDE.md       # 前端特定规范（在前端目录工作时加载）
|   +-- backend/
|       +-- CLAUDE.md       # 后端特定规范（在后端目录工作时加载）
+-- packages/
    +-- shared/
        +-- CLAUDE.md       # 共享包规范

# 删掉这行，会发生什么？

"使用 TypeScript 编写代码"
→ Claude 可能默认用 JavaScript，有价值 ✓

"代码要清晰可读"
→ Claude 本来就会写清晰代码，没有价值 ✗

"所有错误处理必须记录到 logger，不能用 console.log"
→ 不写，Claude 可能用 console.log，有价值 ✓

"请保持代码的高质量"
→ 废话，删除 ✗

# 不好（教程式，Claude 早就知道这些）
API端点应该处理错误并返回适当的HTTP状态码。
使用404表示资源不存在，400表示请求无效，500表示服务器错误。

# 好（约束式，告诉 Claude 项目特定规范）
所有API错误必须使用 ErrorResponse 结构体，不能直接返回字符串。
错误代码使用项目定义的 ErrorCode 枚举，参见 pkg/errors/codes.go。

# 项目：用户行为分析平台

## 技术栈
- 后端：Go 1.21，使用 Gin 框架，gorm + PostgreSQL
- 前端：React 18 + TypeScript，Vite，Zustand 状态管理
- 部署：Docker，k8s，使用 GitHub Actions CI/CD

## 关键约定

### Go 后端
- 错误处理：必须使用 `pkg/errors` 包的 `AppError`，不能用 `errors.New` 或 `fmt.Errorf`
- 日志：使用 `pkg/logger` 的结构化日志，不能用 `fmt.Println` 或 `log.Print`
- 数据库：所有查询必须通过 Repository 层，不能在 Handler 里直接调用 gorm
- 测试：表驱动测试风格，mock 放在 `_test.go` 文件的 `TestMain` 中

### React 前端
- 组件状态：局部用 `useState`，跨组件用 `useStore`（Zustand），禁止用 Redux
- API 调用：统一使用 `src/api/` 目录下的 API 客户端，不能直接 `fetch`
- 样式：Tailwind CSS only，不能写内联 style，不能新建 CSS 文件

### 通用规范
- 所有公共 API 函数必须有 JSDoc/GoDoc 注释
- 禁止提交 `.env` 文件，使用 `.env.example` 作为模板
- 分支命名：`feat/`, `fix/`, `chore/` 前缀

## 常用命令
- 启动开发：`make dev`
- 运行测试：`make test`
- 数据库迁移：`make migrate-up`
- 生成 API 文档：`make docs`

.claude/rules/
+-- typescript.md       # TypeScript 特定规范
+-- testing.md          # 测试规范
+-- database.md         # 数据库使用规范
+-- security.md         # 安全规范
+-- api-design.md       # API 设计规范

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

# TypeScript 规范

- 优先使用 `interface` 而不是 `type`（除非需要联合类型）
- 不允许 `any` 类型，使用 `unknown` + 类型守卫
- 所有 Promise 必须有错误处理（`.catch()` 或 `try/catch`）
- 使用 `satisfies` 运算符代替 `as` 类型断言

# 项目规范

## API 文档
请参考以下 API 设计规范：
@docs/api-design-guide.md

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

## 当前架构
@ARCHITECTURE.md

# 常用的 @imports 模式

# 引用 README（让 Claude 了解项目背景）
@README.md

# 引用包依赖（让 Claude 知道可用的库）
@package.json

# 引用全局个人配置
@~/.claude/personal-preferences.md

monorepo/CLAUDE.md（约50行）：
  - 通用代码规范
  - 跨包的接口约定
  - CI/CD 流程
  
apps/frontend/CLAUDE.md（约40行）：
  - React/TypeScript 特定规范
  - 组件库使用规范
  - 测试框架（Vitest + Testing Library）

apps/backend/CLAUDE.md（约40行）：
  - Go 编码规范
  - 内部包使用约定
  - 数据库访问模式

[ ] 每一行都能回答"没有这行会出错吗？"（Litmus Test）
[ ] 总行数在 200 行以内
[ ] 没有解释 Claude 已经知道的通用最佳实践
[ ] 有明确的技术栈声明（语言版本、框架版本）
[ ] 有项目特定的约束（非通用规范）
[ ] 有常用命令（不需要 Claude 自己去猜）
[ ] 细分规范已迁移到 .claude/rules/ 目录
[ ] 被 @imports 引用的文件都存在