最佳实践

你：用 pnpm 安装依赖
Claude：好的，运行 npm install...
你：不是 npm，是 pnpm！
Claude：抱歉，运行 pnpm install...

# 我的项目名称

## 概述
这是一个基于 Next.js 15 的电商后台管理系统，使用 TypeScript 编写。

## 技术栈

- 运行时：Node.js 22 LTS
- 框架：Next.js 15 (App Router)
- 样式：Tailwind CSS v4
- 数据库：PostgreSQL 16 + Prisma ORM
- 包管理器：pnpm 9
- 测试框架：Vitest + Playwright

## 常用命令

- 安装依赖：`pnpm install`
- 开发服务器：`pnpm dev`（端口 3000）
- 运行测试：`pnpm test`
- 代码检查：`pnpm lint`
- 数据库迁移：`pnpm prisma migrate dev`
- 构建生产：`pnpm build`

## 编码规范

- 严格使用 TypeScript，禁止 `any`
- React 组件使用函数式写法 + hooks
- 样式只用 Tailwind，不写内联 style 和 CSS 文件
- 所有 API 路由统一返回 `{ success: boolean, data?: T, error?: string }`
- 数据库查询统一走 service 层，不在 route 中直接调用 Prisma
- 提交信息格式：`feat:` / `fix:` / `docs:` / `refactor:` 等前缀

## 项目结构

- `src/app/` — 页面和 API 路由（App Router）
- `src/components/` — 可复用 UI 组件
- `src/components/ui/` — 基础组件（Button、Input 等）
- `src/services/` — 业务逻辑层
- `src/lib/` — 工具函数和配置
- `prisma/` — 数据库 schema 和迁移文件

## 注意事项

- 不要手动修改 `prisma/migrations/` 下的文件
- 环境变量配置在 `.env.local`（不提交到 Git）
- API 鉴权中间件在 `src/middleware.ts`
- 图片资源放 `public/images/`，使用 next/image 组件加载

/init

# .claudeignore

# 依赖目录
node_modules/
vendor/
.venv/

# 构建产物
dist/
build/
.next/
out/

# 大型数据文件
*.sql
*.csv
*.sqlite
data/

# 二进制和媒体文件
*.jpg
*.png
*.mp4
*.zip

# 自动生成的代码
generated/
*.gen.ts
prisma/migrations/

# 日志
logs/
*.log

## 项目结构
src/
├── app/                 # Next.js App Router
│   ├── (auth)/          # 需要登录的页面
│   ├── (public)/        # 公开页面
│   └── api/             # API 路由
├── components/
│   ├── ui/              # 基础 UI 组件（shadcn/ui）
│   ├── forms/           # 表单组件
│   └── layouts/         # 布局组件
├── services/            # 业务逻辑（每个模块一个文件）
├── hooks/               # 自定义 React hooks
├── lib/                 # 工具函数
│   ├── auth.ts          # 认证相关
│   ├── db.ts            # 数据库连接
│   └── validators.ts    # Zod schema 定义
└── types/               # TypeScript 类型定义

看看 @src/services/order-service.ts 和 @src/types/order.ts，
然后在 order-service 中添加一个取消订单的方法，要检查订单状态是否允许取消。

@src/services/auth.ts       # 引用单个文件
@src/components/            # 引用整个目录
@package.json               # 引用配置文件
@https://nextjs.org/docs    # 引用在线文档（会抓取内容）

# 不推荐：一次性要求太多
"给用户模块添加头像上传功能，顺便把登录页的样式改一下，
还有那个搜索框的防抖也加上，对了密码重置的邮件模板也更新一下。"

# 推荐：分步进行
第 1 步："在 UserProfile 组件中添加头像上传功能，使用 S3 存储"
第 2 步："更新登录页样式，参考 @docs/design-spec.md 中的设计稿"
第 3 步："给搜索框添加 300ms 防抖，使用自定义 hook"
第 4 步："更新密码重置邮件模板，参考 @src/templates/welcome.html 的风格"

# 第一步：先理解
"阅读 @src/services/payment-service.ts，告诉我现在支付流程的处理逻辑，
特别是错误处理和重试机制。不要改任何代码。"

# 第二步：再规划
"基于你的理解，我想添加微信支付渠道。请制定修改方案，列出需要改动的地方。"

# 第三步：执行修改
"方案看起来没问题，开始执行吧。先改 payment-service.ts。"

[Plan Mode]
我需要给现有系统添加 RBAC（基于角色的访问控制）权限系统。
现在用户只有 admin 和 user 两种角色，我需要支持自定义角色和细粒度权限。
请先分析现有代码，制定详细的实施计划。

/compact    # 压缩当前对话历史，保留关键信息，释放上下文空间
/clear      # 彻底清空对话历史，从零开始

# 使用时机：
# - 切换到完全不同的任务 → /clear
# - 同一任务但对话太长 → /compact
# - 感觉 Claude 的回复变差了（上下文过载）→ /compact
# - 刚完成一个功能，要开始下一个 → /clear

/review

我刚才修改了 @src/services/order-service.ts 中的取消订单逻辑。
请为这个方法编写单元测试，覆盖以下场景：
1. 正常取消待发货订单
2. 尝试取消已发货订单（应该失败）
3. 取消不存在的订单
4. 并发取消同一订单

# 第一轮：整体审查
"审查 @src/services/payment-service.ts 的最新改动，
重点关注安全性和错误处理。"

# 根据反馈修改后，第二轮：
"请重新审查修改后的代码，这次重点关注性能和边界情况。"

# 第三轮（可选）：对比审查
"对比修改前后的代码，确认所有问题都已修复，没有引入新问题。"

运行 pnpm build 时报错了，完整错误日志如下：

这个错误发生在 @src/app/api/user/route.ts 中。
我怀疑是 session 类型定义的问题，请帮我检查。

# 第一步：诊断
"用户报告登录后偶尔会跳转到 404 页面。
请检查 @src/middleware.ts 和 @src/app/(auth)/layout.tsx，
分析可能导致这个问题的原因。先不要修改代码。"

# 第二步：确认原因后再修复
"你的分析很有道理，确实是 session 过期时重定向逻辑有问题。
请修复这个问题，同时添加适当的错误日志方便后续排查。"

看看这张截图 @screenshot.png，表格的最后一列文字被截断了。
请检查 @src/components/DataTable.tsx 中的样式，修复这个问题。

/commit

/commit
# Claude 生成的消息不够好？
"提交消息请更详细一些，说明为什么要改这个逻辑"

# 1. 创建功能分支
git checkout -b feature/order-cancel

# 2. 启动 Claude Code 开发
claude

# 3. 开发过程中多次小步提交
> "实现取消订单的基本逻辑"
> /commit

> "添加取消原因字段和验证"
> /commit

> "添加取消订单的单元测试"
> /commit

# 4. 完成开发，创建 PR
> 为当前分支创建 Pull Request，总结所有提交的变更，生成规范的 PR 描述

# 在 CLAUDE.md 中添加这条规则：
## Git 规范

- 所有修改必须在功能分支上进行，不要直接修改 main 分支
- 分支命名：feature/xxx、fix/xxx、refactor/xxx
- 提交前运行 `pnpm lint && pnpm test` 确保没有问题

# 项目根目录的 CLAUDE.md → 提交到 Git
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md project configuration"

# 个人偏好的配置 → 放在 .claude/CLAUDE.md，加入 .gitignore
echo ".claude/CLAUDE.md" >> .gitignore

## PR Review 标准
审查代码时请检查以下方面：
1. **功能正确性**：是否完整实现了需求
2. **错误处理**：是否覆盖了异常情况
3. **安全性**：是否有 SQL 注入、XSS、权限绕过等风险
4. **性能**：是否有不必要的数据库查询、内存泄漏
5. **测试覆盖**：新增代码是否有对应测试
6. **代码风格**：是否符合项目规范
7. **文档**：公共 API 是否有 JSDoc 注释

## 代码风格

- 命名：组件用 PascalCase，函数/变量用 camelCase，常量用 UPPER_SNAKE_CASE
- 文件名：组件文件用 PascalCase（如 UserAvatar.tsx），其余用 kebab-case
- import 顺序：React → 第三方库 → 内部模块 → 类型 → 样式
- 函数最大行数：50 行，超过请拆分
- 组件 props 超过 3 个时用 interface 定义

# .claude/commands/review-security.md
请对以下代码进行安全审查，重点检查：
1. SQL 注入风险
2. XSS 攻击面
3. CSRF 防护
4. 权限校验是否完整
5. 敏感数据是否加密
6. 日志中是否泄露敏感信息

检查范围：$ARGUMENTS

/review-security @src/app/api/

我需要给订单系统添加优惠券功能，涉及以下文件：

- @src/types/coupon.ts — 新建，定义优惠券类型
- @src/services/coupon-service.ts — 新建，优惠券业务逻辑
- @src/services/order-service.ts — 修改，在结算时应用优惠券
- @src/app/api/coupons/route.ts — 新建，优惠券 API
- @prisma/schema.prisma — 修改，添加 Coupon 模型

请按照上面的顺序依次处理，每完成一个文件告诉我。

[使用 Opus 模型]
我在考虑把现在的 REST API 迁移到 GraphQL。
请深入分析利弊，考虑以下因素：
1. 现有 50+ 个 API 端点的迁移成本
2. 前端查询优化的收益
3. 缓存策略变化
4. 团队学习曲线
5. 与现有 React Query 的集成方案

不需要写代码，给我一份详细的技术分析报告。

修改完成后，请：
1. 运行 pnpm lint 检查是否有格式问题
2. 运行 pnpm test 确认没有破坏现有测试
3. 如果有类型错误，自己修复