CLAUDE.md 10 段黄金模板：让 Claude Code 每次启动都像资深开发者一样了解你的项目

# [项目名称]

## 1. 项目概述
[2-3 句话说明这是什么项目、谁在用、解决什么问题]

示例：这是一个面向工程团队的 B2B 项目管理工具。
包含项目、任务、Sprint 管理和 GitHub 集成。
用户分为团队成员和管理员，通过 Stripe 付费订阅。

## 2. 技术栈
- 运行时: Node.js 22 / Python 3.12 / [你的运行时]
- 框架: Next.js 16（App Router，不是 Pages Router）
- 数据库: PostgreSQL（通过 Prisma ORM，不用裸 SQL）
- 认证: Clerk / Auth.js / JWT
- 样式: Tailwind CSS v4（不是 v3，配置方式已变）
- 测试: Jest + Playwright / Vitest
- 包管理: bun / pnpm / npm

（版本很重要——API 会变，Claude Code 的训练数据包含旧版本）

## 3. 核心命令
- 启动开发服务器: `npm run dev`
- 运行测试: `npm run test`
- 类型检查: `npm run typecheck`
- 构建: `npm run build`
- 数据库迁移: `npx prisma db push`（开发）/ `npx prisma migrate deploy`（生产）
- Lint: `npm run lint`

（这部分写了，Claude Code 才会自动运行测试验证改动）

## 4. 项目结构
src/
  app/          # Next.js App Router 页面和 API 路由
  components/   # 可复用 UI 组件
  lib/          # 业务逻辑、工具函数、SDK 封装
  hooks/        # 自定义 React Hooks
  types/        # TypeScript 类型定义
prisma/
  schema.prisma # 数据库 Schema

（目录描述让 Claude Code 知道新文件放哪，不用读 50 个文件推断）

## 5. 代码规范
- TypeScript strict 模式已开启，禁止使用 `any`
- 使用命名导出，不用默认导出（页面组件除外）
- 所有 API 路由通过 `src/lib/auth.ts` 做认证，不要重复实现
- 数据库查询放在 `src/lib/db/`，不要内联在 API 路由里
- 输入验证统一使用 Zod
- 只用 Tailwind 工具类，除非绝对必要不写自定义 CSS
- 文件命名：全部使用 kebab-case

## 6. 禁止修改区域（最重要的安全措施）
- src/lib/auth/ —— 认证逻辑单独维护，不要改
- prisma/migrations/ —— 永远不要直接修改 migration 文件
- .env.local —— 不要在代码里读写密钥
- src/lib/stripe/ —— Stripe 集成由另一个团队负责

## 7. 测试规范
- 单元测试：src/lib/ 下的工具函数
- 集成测试：API 路由
- E2E 测试：仅核心用户流程（结账、认证、核心功能）
- 完成任务前必须运行 `npm run test`
- 修复 Bug 时不要跳过测试——测试也要修

## 8. 数据库规范
- 不要删除表或字段——先标记为 deprecated
- 新表必须包含：id（UUID）、created_at、updated_at
- 多表写入使用数据库事务
- Prisma schema 中必须显式声明外键

## 9. 代码风格
- 函数最长 20 行——超过则提取为辅助函数
- 文件最长 200 行——超过则拆分为模块
- 优先组合而非继承
- 注释解释"为什么"，而不是"是什么"

## 10. 当前工作（每次大任务前更新）
正在做：Stripe 订阅管理
下一步：邮件通知系统
最近完成：用户资料编辑

## 当前工作
正在做：实现用户通知功能（WebSocket + 站内信 + 邮件）
注意：notifications 表的 Schema 已经在 PR #234 里，等 merge
不要碰：src/lib/ws/ 正在被另一个同事修改
活跃分支：feature/notifications

## Stripe 集成
详细文档：参见 src/lib/stripe/STRIPE_DOCS.md
测试卡：https://stripe.com/docs/testing
重要：所有 Webhook 必须通过 src/lib/stripe/webhook-validator.ts 验证

## 废弃警告
src/lib/legacy-auth/ 正在被 src/lib/auth/ 替代
永远不要在 legacy-auth/ 里添加新代码
新的认证代码统一放在 src/lib/auth/