Claude Code: CLAUDE.md 使用指南

# CLAUDE.md

## 项目概述
[一句话描述项目是什么、做什么]

## 技术栈
[语言、框架、数据库、工具链]

## 常用命令
[构建、测试、部署、开发命令]

## 代码约定
[命名规范、文件组织、风格要求]

## 约束与限制
[不能做什么、必须做什么]

## 已知问题
[需要特别注意的技术债和坑]

# CLAUDE.md

## 项目概述
SaaS 计费平台后端，处理订阅管理、发票生成和支付集成。

## 技术栈
- Node.js 20 + TypeScript 5.3
- Express 4.18 + middleware chain
- Prisma 5.x (PostgreSQL)
- Redis (缓存 + 队列)
- Jest + Supertest (测试)

## 常用命令
- `npm run dev` — 启动开发服务器 (port 3000)
- `npm test` — 运行全量测试
- `npm test -- --watch` — 监视模式
- `npm run lint` — ESLint 检查
- `npx prisma migrate dev` — 数据库迁移

## 代码约定
- Service 层只处理业务逻辑，不直接访问 HTTP 对象
- Controller 层负责请求/响应转换
- 所有数据库操作通过 Repository 模式
- 错误使用 AppError 类，包含 statusCode 和 code
- API 响应格式：`{ success: boolean, data: T, error?: string }`

## 约束
- ❌ 禁止直接使用 pg 客户端，必须用 Prisma
- ❌ 禁止在 Service 层访问 req/res
- ❌ 禁止硬编码密钥和凭证
- ✅ 每个 API endpoint 必须有集成测试
- ✅ 所有金额使用 cents（整数），避免浮点误差

## 已知问题
- PaymentService.processRefund 有并发问题（见 ISSUE-342）
- InvoiceService.generatePDF 在大量项目时性能差（见 ISSUE-156）

~/.claude/CLAUDE.md          # 全局：个人偏好
项目根/CLAUDE.md             # 项目：团队约定
项目根/src/api/CLAUDE.md     # 目录：局部指令

<!-- ~/.claude/CLAUDE.md -->
# 全局偏好

## 代码风格
- 使用 TypeScript 严格模式
- 优先 const，避免 let
- 函数不超过 20 行
- 添加 JSDoc 注释

## 测试偏好
- 使用 describe/it 风格
- 每个 test 独立，不依赖执行顺序
- mock 外部依赖，不 mock 内部模块

<!-- src/api/CLAUDE.md -->
# API 模块约定

## 路由注册
- 所有路由在 index.ts 统一注册
- 中间件顺序：auth → rateLimit → validate → handler

## 响应格式
- 成功：{ success: true, data: T }
- 失败：{ success: false, error: { code, message } }

## 禁止
- ❌ 不要在 handler 中直接写业务逻辑
- ❌ 不要跳过参数验证

my-monorepo/
├── CLAUDE.md                 # 全局：Monorepo 结构和公共命令
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # 前端：React 约定
│   ├── api/
│   │   └── CLAUDE.md         # 后端：API 约定
│   └── shared/
│       └── CLAUDE.md         # 共享：纯逻辑，无 I/O

> 根据最近的代码变更，更新 CLAUDE.md

Claude Code:
  → Reading recent commits (last 2 weeks)
  → Reading current CLAUDE.md
  → Changes detected:
    1. Migrated from Express to Fastify
    2. Added Redis caching layer
    3. Changed test framework from Jest to Vitest

  → Updating CLAUDE.md:
    - Tech stack: Express → Fastify
    - Commands: npm test → npm run test (vitest)
    - Added: Redis caching conventions
    - Updated: API response format (Fastify style)

  CLAUDE.md updated ✓

# Alice 为新项目编写 CLAUDE.md

> 分析项目并生成 CLAUDE.md

Claude Code:
  → Reading package.json, tsconfig.json
  → Scanning src/ directory structure
  → Reading ESLint and Prettier config
  → Reading existing test files for patterns
  → Generating CLAUDE.md...

# Alice 手动补充业务约定：

## 业务规则
- 订阅状态：active/past_due/canceled/expired
- 订阅降级：立即生效，不退差价
- 计费周期：monthly/yearly，按自然月/年
- 退款策略：7 天内全额退款，超过 7 天按比例退款

## 数据约束
- 金额使用 cents (integer)
- 日期使用 ISO 8601
- 货币使用 ISO 4217 (USD, EUR, CNY)