系统级指令配置

系统级指令是 AI 辅助开发中"一次配置、持续生效"的最高效手段。通过合理配置 CLAUDE.md、.cursorrules、copilot-instructions.md，可以让 AI 工具始终遵循项目规范，无需在每次对话中重复说明。

CLAUDE.md 体系

Claude Code 通过读取多个层级的 CLAUDE.md 文件来构建项目上下文，形成覆盖全局、项目、本地的三级配置体系。

层级结构

~/.claude/CLAUDE.md          ← 用户全局级（所有项目通用）
  └── ./CLAUDE.md            ← 项目级（提交到 Git，团队共享）
        └── ./CLAUDE.local.md ← 本地级（.gitignore，个人偏好）

优先级：本地级 > 项目级 > 全局级（下层覆盖上层）

---

1. 用户全局级：~/.claude/CLAUDE.md

适合放个人偏好、通用规范、常用工具配置。

# 我的全局开发规范

## 代码风格
- 所有代码使用 2 空格缩进
- 优先使用函数式编程，避免副作用
- 变量命名：描述性名称，禁止单字母（循环变量除外）
- 注释语言：中文（团队规范）

## 技术偏好
- 前端：React + TypeScript，不使用 class 组件
- 测试：Vitest（非 Jest），覆盖率要求 >80%
- 包管理：pnpm（非 npm/yarn）
- Git：提交信息使用约定式提交（Conventional Commits）

## 输出规范
- 生成代码时不添加不必要的注释
- 错误处理必须明确（不使用空 catch）
- 异步代码优先使用 async/await

## 禁止行为
- 不使用 any 类型（TypeScript）
- 不使用 var（使用 const/let）
- 不在生产代码中留 console.log

---

2. 项目级：./CLAUDE.md

随代码一起提交，团队成员共享。重点描述项目架构、约定和关键决策。

# 项目名称：LXP 学习管理平台

## 项目概览
在线学习平台，支持课程管理、学员进度追踪、在线考试。
技术栈：Next.js 14 (App Router) + TypeScript + Prisma + PostgreSQL

## 目录结构
src/
├── app/          # Next.js App Router 页面
├── components/   # 共享 UI 组件
├── lib/          # 工具函数和服务层
│   ├── db/       # Prisma 数据库操作
│   └── api/      # API 客户端封装
├── hooks/        # 自定义 React Hooks
└── types/        # TypeScript 类型定义

## 关键约定
### API 路由
- 所有 API 在 src/app/api/ 下
- 使用 zod 验证请求体，schema 放 src/lib/validators/
- 错误响应格式：{ error: string, code: string }

### 数据库
- 所有数据库操作通过 src/lib/db/ 模块，禁止在组件中直接用 Prisma
- 事务操作使用 prisma.$transaction()

### 组件规范
- 服务端组件默认，客户端组件需 'use client' 并说明原因
- Props 类型用 interface（非 type），命名：ComponentNameProps

## 当前已知问题
- 课程详情页存在 N+1 查询问题（待优化）
- 上传功能暂不支持大于 100MB 的文件

## 不要修改的文件
- src/lib/auth/session.ts（正在重构中，由 @zhangsan 负责）
- prisma/migrations/（只通过 prisma migrate 命令修改）

---

3. 本地级：./CLAUDE.local.md

不提交到 Git，存放个人调试信息、临时配置、敏感数据路径。

# 本地开发配置（不提交）

## 本地环境
- 数据库：localhost:5432/lxp_dev
- Redis：localhost:6379
- 测试账号：admin@test.com / test123456

## 当前开发任务
正在开发：考试模块（feature/exam-system 分支）
关联需求文档：~/Documents/PRD-exam-v2.md

## 调试提示
- 遇到 Prisma 连接问题先检查 .env.local 的 DATABASE_URL
- 本地 seed 命令：pnpm db:seed:local

---

Cursor：.cursorrules

Cursor 使用项目根目录的 .cursorrules 文件配置 AI 行为规则。

# .cursorrules

## 角色定义
你是一名 React + TypeScript 高级工程师，熟悉 Next.js 14 App Router。
在回答问题时，优先给出可直接运行的代码，而非理论解释。

## 代码生成规则
1. TypeScript 严格模式，所有函数参数和返回值都要有类型
2. React 组件使用函数组件 + hooks，props 用 interface 定义
3. 异步操作使用 async/await，错误用 try/catch 处理
4. 样式：Tailwind CSS，不写内联 style
5. 状态管理：简单状态用 useState，跨组件用 Zustand

## 命名规范
- 组件文件：PascalCase（UserProfile.tsx）
- 工具函数：camelCase（formatDate.ts）
- 常量：UPPER_SNAKE_CASE
- 自定义 Hook：use 前缀（useUserData）

## 禁止使用
- class 组件
- any 类型
- // @ts-ignore
- 默认导出（除页面组件外）

## 测试
- 框架：Vitest + @testing-library/react
- 测试文件命名：ComponentName.test.tsx
- 每个组件至少测试：渲染不报错、核心交互、边界情况

## 提交信息格式
feat: 新功能
fix: 修复 bug
refactor: 重构（不影响功能）
test: 添加测试
docs: 文档更新

---

GitHub Copilot：copilot-instructions.md

在 .github/copilot-instructions.md 中配置 Copilot 的项目级指令。

<!-- .github/copilot-instructions.md -->

## 项目技术栈
- 语言：Python 3.11+
- Web 框架：FastAPI
- ORM：SQLAlchemy 2.0（使用 async）
- 数据库：PostgreSQL 15
- 测试：pytest + pytest-asyncio

## 代码规范
- 遵循 PEP 8，行宽 100 字符
- 类型注解：所有函数参数和返回值必须有类型提示
- 使用 Pydantic v2 做数据验证
- 日志：使用 structlog，不用 print

## API 设计规范
- RESTful 风格，资源名用复数（/users, /courses）
- 响应格式统一：{ data: T, message: str, success: bool }
- HTTP 状态码要语义正确（创建用 201，无内容用 204）
- 所有端点需要 OpenAPI 文档注释（summary + description）

## 数据库操作
- 使用 Repository 模式封装数据库操作
- 所有查询通过 async session，不使用同步操作
- 复杂查询写在 repository 层，不在路由层写 SQL

## 安全规范
- 敏感信息从环境变量读取，不硬编码
- 所有用户输入都要用 Pydantic 验证
- API 端点默认需要认证，公开端点需显式标注

---

规则优先级策略

在实际项目中，按以下层次设计规则，避免冗余和冲突：

框架层（最高优先级）
  ↓ Next.js 特定规范、FastAPI 惯例
语言层
  ↓ TypeScript/Python 语言规范
项目层
  ↓ 团队约定、架构决策
个人层（最低优先级）
  ↓ 个人习惯、本地调试

配置建议：

规则类型	推荐位置
个人编码风格	~/.claude/CLAUDE.md
项目架构约定	./CLAUDE.md 或 .cursorrules
框架最佳实践	./CLAUDE.md 的专项章节
临时/调试信息	./CLAUDE.local.md
禁止修改的区域	./CLAUDE.md 的醒目位置

---

常见配置错误

❌ 在系统指令中放大量代码示例（占用 context 空间）
✓ 只放规则和约定，具体示例放在单独的 examples/ 目录

❌ 规则过于宽泛（"写好代码"）
✓ 规则具体可检验（"函数超过 50 行必须拆分"）

❌ 全局级放项目专属规则
✓ 项目专属规则放项目级 CLAUDE.md

❌ 规则之间相互矛盾（"简洁" vs "完整注释"）
✓ 明确优先级，或给出具体场景区分