CLAUDE.md 进阶技巧

<!-- 不好的写法 -->
写好的代码，遵循最佳实践。

<!-- 好的写法 -->
- 所有异步函数必须使用 try-catch 包裹，错误统一通过 src/utils/logger.ts 的 logError() 记录
- React 组件 props 超过 3 个时，必须定义独立的 interface，命名格式为 {ComponentName}Props
- API 响应必须使用 src/types/api.ts 中定义的泛型 ApiResponse<T> 包装

## 命名规范

文件命名使用 kebab-case，组件命名使用 PascalCase。

正确示例:
- 文件: user-profile-card.tsx
- 组件: UserProfileCard

错误示例:
- 文件: UserProfileCard.tsx
- 文件: userProfileCard.tsx

## 代码质量优先级（从高到低）

1. 类型安全 - 绝对不允许使用 any 或 ts-ignore
2. 错误处理 - 所有可能失败的操作必须有错误处理
3. 可读性 - 变量名要有意义，函数不超过 30 行
4. 性能 - 避免不必要的重渲染和重复计算

my-monorepo/
  CLAUDE.md                    # 全局规范
  packages/
    web-app/
      CLAUDE.md                # Web 应用特定规范
      src/
    api-server/
      CLAUDE.md                # API 服务特定规范
      src/
    shared-utils/
      CLAUDE.md                # 工具库特定规范
      src/

# MyProject Monorepo

## 通用规范
- 使用 pnpm workspace 管理依赖
- 共享类型定义在 packages/shared-types 中
- 所有包使用统一的 TypeScript 配置 (继承根目录 tsconfig.base.json)
- Git commit message 遵循 Conventional Commits 格式

# Web App (packages/web-app)

## 框架特定规范
- 使用 Next.js App Router，不使用 Pages Router
- 页面组件放在 app/ 目录，可复用组件放在 components/ 目录
- 服务端组件优先，仅在需要交互时使用 'use client'
- 使用 next/image 替代原生 img 标签

## 架构参考

详细的架构设计见 docs/architecture.md 文件。

## API 规范

API 设计遵循 docs/api-guidelines.md 中的规范。

## 工作流程指引

- 添加新 API 端点前，先阅读 docs/api-guidelines.md
- 修改数据库 schema 前，先阅读 docs/database-conventions.md
- 创建新组件前，先阅读 src/components/README.md 了解组件规范

## 技术栈

- Runtime: Node.js 20 LTS
- 语言: TypeScript 5.3 (strict: true)
- 框架: Express.js 4.x
- ORM: Prisma 5.x
- 数据库: PostgreSQL 16
- 缓存: Redis 7
- 消息队列: BullMQ
- 测试: Jest + Supertest

## 项目约定

### 目录结构
- src/modules/{module-name}/ - 业务模块，每个模块包含 controller, service, repository, dto, entity
- src/common/ - 通用工具、中间件、装饰器
- src/config/ - 配置文件，使用 env-schema 验证环境变量

### 错误处理
- 业务错误继承 AppError 基类 (src/common/errors/app-error.ts)
- Controller 层不直接 catch 错误，统一由全局错误中间件处理
- 所有错误必须包含 errorCode 和 message

### 日志
- 使用 src/common/logger.ts 封装的 Winston logger
- 日志级别: error > warn > info > debug
- 生产环境只输出 info 及以上级别

## 测试规范

- 单元测试文件与源文件同目录，命名为 {filename}.test.ts
- Service 层必须有单元测试，覆盖率要求 > 80%
- API 端点必须有集成测试，放在 test/integration/ 目录
- 使用 factory 模式创建测试数据 (test/factories/)
- Mock 外部服务，不要在测试中调用真实 API

## 常用命令

- npm run dev          - 启动开发服务器 (热重载)
- npm run build        - TypeScript 编译
- npm run test         - 运行所有测试
- npm run test:watch   - 监听模式运行测试
- npm run test:cov     - 运行测试并生成覆盖率报告
- npm run lint         - ESLint 检查
- npm run lint:fix     - ESLint 自动修复
- npm run db:migrate   - 执行数据库迁移
- npm run db:seed      - 填充测试数据
- npm run db:studio    - 打开 Prisma Studio

## 部署

- 分支策略: main (生产), develop (开发), feature/* (功能分支)
- CI/CD: GitHub Actions，配置文件在 .github/workflows/
- 部署目标: AWS ECS (Fargate)
- 环境变量通过 AWS Parameter Store 管理，不要硬编码

<!-- 不要这样写 -->
写干净的代码。
遵循最佳实践。
确保代码质量。

<!-- 不要这样写 -->
- 所有函数使用 async/await 风格
- （后面某处又写）回调风格更高效，优先使用回调

<!-- 不要这样写 -->
注意：我们正在从 Webpack 迁移到 Vite（已于三个月前完成）

<!-- 不要这样写 -->
项目文件列表：
- src/index.ts
- src/app.ts
- src/routes/user.ts
- src/routes/product.ts
- ... (列出几百个文件)

# ShopFront - 电商前端

## 技术栈
- React 18 + TypeScript
- Vite 构建
- TanStack Router (文件路由)
- TanStack Query (数据请求)
- Tailwind CSS + shadcn/ui
- Zustand (全局状态)

## 组件规范
- 组件按功能模块放在 src/features/{feature}/components/
- 通用 UI 组件放在 src/components/ui/ (基于 shadcn/ui)
- 页面组件放在 src/routes/
- 每个组件必须导出 TypeScript 类型的 Props interface
- 使用 forwardRef 包装需要暴露 ref 的组件

## 状态管理
- 服务端状态: TanStack Query (不要用 Zustand 管理 API 数据)
- 全局 UI 状态: Zustand (主题、侧边栏开关等)
- 表单状态: React Hook Form + Zod 验证
- 本地状态: useState/useReducer

## 样式规范
- 使用 Tailwind CSS utility classes，不写自定义 CSS
- 响应式断点: sm(640px), md(768px), lg(1024px), xl(1280px)
- 颜色使用 CSS 变量 (定义在 src/styles/globals.css)

# DataPipe - 数据处理服务

## 技术栈
- Python 3.12
- 框架: FastAPI
- ORM: SQLAlchemy 2.0 (async)
- 数据库: PostgreSQL
- 任务队列: Celery + Redis
- 包管理: Poetry

## 代码规范
- 类型标注: 所有函数参数和返回值必须有类型标注
- 使用 Pydantic v2 模型做数据验证
- 异步优先: 数据库操作和外部调用使用 async/await
- 依赖注入: 使用 FastAPI 的 Depends 机制

## 目录结构
- app/api/v1/ - API 路由
- app/models/ - SQLAlchemy 模型
- app/schemas/ - Pydantic 模型
- app/services/ - 业务逻辑
- app/repositories/ - 数据访问层
- app/core/ - 配置、安全、依赖注入

## 测试
- pytest + pytest-asyncio
- 测试文件在 tests/ 目录，镜像 app/ 目录结构
- 使用 factory-boy 创建测试数据
- 运行测试: poetry run pytest
- 运行带覆盖率: poetry run pytest --cov=app

# OrderService - 订单微服务

## 技术栈
- Go 1.22
- Web 框架: Gin
- ORM: GORM
- 数据库: MySQL 8
- 消息队列: Kafka (segmentio/kafka-go)
- gRPC: 服务间通信

## 代码规范
- 遵循 Effective Go 和 uber-go/guide
- 错误处理: 使用 fmt.Errorf 包装错误，包含上下文信息
- 日志: 使用 slog 结构化日志
- 不使用 init() 函数，依赖在 main 中显式初始化
- 接口定义在使用方，不在实现方

## 目录结构 (遵循 Standard Go Project Layout)
- cmd/server/ - 主程序入口
- internal/handler/ - HTTP/gRPC 处理器
- internal/service/ - 业务逻辑
- internal/repository/ - 数据访问
- internal/model/ - 数据模型
- pkg/ - 可被外部引用的公共包

## 常用命令
- go run cmd/server/main.go - 启动服务
- go test ./... - 运行所有测试
- go test -race ./... - 竞态检测
- make proto - 编译 protobuf 文件
- make migrate-up - 执行数据库迁移

## 编码标准

### 必须遵守 (Do)
- 新增 API 端点必须同时编写 OpenAPI 文档注释
- 数据库查询必须使用参数化查询，防止 SQL 注入
- 所有用户输入必须经过验证和清洗
- 敏感操作必须记录审计日志

### 禁止事项 (Don't)
- 不要在代码中硬编码密钥、密码或连接字符串
- 不要使用 console.log 调试，使用项目的 Logger 工具
- 不要直接操作 DOM，使用 React 的方式管理 UI
- 不要在组件中直接调用 fetch，使用 API service 层

## 代码生成检查清单

Claude 在生成代码后，请自行检查以下内容：
1. 所有新函数是否有错误处理？
2. 是否有类型标注缺失？
3. 是否需要添加单元测试？
4. 是否有潜在的安全问题？
5. 命名是否符合项目约定？