规则系统

{
  "rules": [
    "使用 TypeScript 严格模式",
    "所有函数必须包含 JSDoc 注释",
    "API 路由统一返回 { success, data, error } 格式",
    "数据库操作必须使用事务",
    "优先使用 async/await 而非回调"
  ]
}

{
  "rules": [
    "使用 2 空格缩进",
    "字符串使用单引号",
    "最大行长度 100 字符",
    "trailing comma: es5",
    "末尾不留空行"
  ]
}

{
  "rules": [
    "业务逻辑放在 services/ 目录",
    "不要在组件中直接调用 API",
    "使用 Repository 模式操作数据库",
    "所有 API 响应经过统一错误处理中间件",
    "前端状态管理使用 Zustand，不使用 Redux"
  ]
}

{
  "rules": [
    "所有用户输入必须经过 Zod 校验",
    "密码必须使用 bcrypt 哈希（cost ≥ 12）",
    "JWT 密钥存储在环境变量，不硬编码",
    "SQL 查询使用参数化防止注入",
    "敏感操作需要二次确认"
  ]
}

{
  "rules": [
    "新功能必须包含单元测试",
    "测试覆盖率不低于 80%",
    "使用 vitest 而非 jest",
    "测试文件与源码同目录，后缀 .test.ts"
  ]
}

# 项目根目录
.rules
# 或
.opencode/rules.md

# 项目规则
 
## TypeScript
 
- 启用 strict 模式
- 不使用 any 类型
- 接口名使用 I 前缀（如 IUser）
- 枚举使用 PascalCase
 
## React
 
- 使用函数组件 + Hooks
- Props 使用 interface 定义
- 事件处理函数以 handle 开头
- 自定义 Hook 以 use 开头
 
## API
 
- RESTful 风格
- 路由使用 kebab-case
- 响应格式: { success: boolean, data?: T, error?: string }
- HTTP 状态码语义正确（200/201/400/401/404/500）

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "rules": [
    // ===== 语言与类型 =====
    "使用 TypeScript 严格模式（strict: true）",
    "不使用 any 类型，必要时使用 unknown + 类型守卫",
    "所有函数参数和返回值必须显式标注类型",
 
    // ===== 代码风格 =====
    "使用 2 空格缩进",
    "字符串使用单引号",
    "最大行长度 100 字符",
    "使用 trailing comma（ES5 风格）",
 
    // ===== 项目结构 =====
    "控制器放在 src/controllers/",
    "路由放在 src/routes/",
    "业务逻辑放在 src/services/",
    "数据访问放在 src/repositories/",
    "类型定义放在 src/types/",
    "工具函数放在 src/utils/",
 
    // ===== API 规范 =====
    "所有 API 返回统一格式: { success: boolean, data?: T, error?: string }",
    "路由使用 kebab-case，如 /api/user-profiles",
    "HTTP 状态码语义正确",
 
    // ===== 数据库 =====
    "数据库操作使用 Prisma ORM",
    "所有写操作使用事务",
    "复杂查询使用 Prisma 的 include 和 select 优化",
 
    // ===== 安全 =====
    "使用 Zod 校验所有请求参数",
    "密码使用 bcrypt 哈希（rounds: 12）",
    "JWT 密钥从环境变量读取",
    "敏感信息不记录到日志",
 
    // ===== 错误处理 =====
    "使用自定义 AppError 类",
    "错误使用 winston 记录",
    "不向客户端暴露内部错误详情",
 
    // ===== 测试 =====
    "新功能必须包含单元测试",
    "使用 vitest + @vitest/coverage-v8",
    "测试覆盖率不低于 80%"
  ],
  "formatters": {
    "*.ts": "prettier --write",
    "*.json": "prettier --write"
  }
}

# 项目概述
 
这是基于 Next.js 14 + Prisma + PostgreSQL 的电商平台。
 
## 技术栈
 
- 前端：Next.js App Router + Tailwind CSS + shadcn/ui
- 后端：Next.js API Routes
- 数据库：PostgreSQL + Prisma
- 认证：NextAuth.js

{
  "rules": [
    "使用 Next.js App Router，不使用 Pages Router",
    "UI 组件使用 shadcn/ui",
    "数据库操作使用 Prisma",
    "认证使用 NextAuth.js 的 session 策略"
  ]
}

// AI 可能生成这样的代码
function getUser(id) {
  return db.query('SELECT * FROM users WHERE id = ' + id);
}

// AI 生成符合规则的代码
import { prisma } from '@/lib/prisma';
 
/**
 * 根据 ID 获取用户信息
 * @param id - 用户 ID
 * @returns 用户对象，不存在时返回 null
 */
async function getUser(id: string): Promise<User | null> {
  try {
    const user = await prisma.user.findUnique({
      where: { id },
      select: { id: true, email: true, name: true }
    });
    return user;
  } catch (error) {
    logger.error('Failed to get user', { id, error });
    throw new AppError('USER_FETCH_FAILED', '获取用户信息失败');
  }
}

{
  "rules": [
    "使用单引号",
    "字符串使用双引号"  // ❌ 冲突！
  ]
}

// ❌ 模糊
"写好代码"
 
// ✅ 具体
"所有公共函数添加 JSDoc 注释"
"函数长度不超过 50 行"
"嵌套深度不超过 3 层"

// ❌ 主观
"代码要优雅"
 
// ✅ 可验证
"所有 API 响应经过 Zod 校验"
"测试覆盖率不低于 80%"