一套精简的前端开发规范，专为 Cursor AI 编程助手设计。

本项目提供了一套核心开发规范，涵盖代码质量、命名约定、技术栈选型、性能优化、安全防护、设计系统、可视化绘图等方面。这些规则旨在提高代码质量和开发效率，确保项目的一致性和可维护性。

• 命名规范 - 统一的文件、变量、函数、组件命名约定
• 模块导出规范 - 导入导出的最佳实践和循环依赖避免
• AI 任务管理规范 - 引入 AI 驱动的任务拆解与进度管理规范

• 技术栈选型规范 - React 18+ + TypeScript 5+ + Vite + Tailwind + shadcn/ui
• React 开发规范 - 函数组件、Hooks 和最佳编程实践
• TypeScript 规范 - 类型定义和类型安全实践
• 样式规范 - Tailwind CSS 和 shadcn/ui 使用规范

• 性能优化规范 - Web Vitals 监控和核心优化技术
• 测试规范 - 测试金字塔和测试最佳实践
• 错误处理规范 - 统一错误处理和用户体验

• 安全规范 - 输入验证、XSS/CSRF 防护
• API 设计规范 - RESTful API 设计和错误处理

• npm 包安装规范 - 包管理规范
• 文档书写规范 - Markdown 格式和文档编写标准
• Git 提交消息规范 - 提交消息格式约定

• Context7 MCP 集成规范 - 第三方库文档获取流程
• LLM 严格模式规则 - AI 编程助手的工作模式约束
• 设计系统配置规范 - 从截图提取设计元素，生成标准化设计系统

• Excalidraw 绘图语法规范 - Excalidraw JSON 格式详解、元素类型、样式配置与 Mermaid 对比

1. 将此项目克隆到本地
2. 在 Cursor 中打开项目
3. 规则会自动被 Cursor AI 识别和应用
4. 在对话中使用 @规则名 引用特定规则

@naming-conventions 帮我优化变量命名
@react-standards 这个组件是否符合规范？
@security-standards 检查安全漏洞
@performance-optimization 优化页面性能
@api-design 设计 RESTful API
@design-system 根据截图生成设计系统
@excalidraw-grammar 生成 Excalidraw 绘图或优化图表结构

• 文件命名：kebab-case
• 变量函数：camelCase
• 类型组件：PascalCase
• 常量：UPPER_SNAKE_CASE
• 布尔值：使用 is/has/can/should 前缀
• Hooks：以 use 开头

• 核心：React 18+ + TypeScript 5+ + Vite 5+
• UI：Tailwind CSS + shadcn/ui
• 状态：Zustand（中大型项目）/ React Context（小型项目）
• 表单：React Hook Form + Zod
• 路由：React Router 6+

• 组件：函数组件 + Hooks
• 类型：TypeScript 严格模式 + 完整类型定义
• 导出：命名导出优于默认导出
• 性能：React.memo、useMemo、useCallback 合理使用

• 统一错误类型：type | code | message | timestamp
• 分层处理：组件级 → 页面级 → 应用级
• API 错误：统一 fetch 包装和错误处理
• 用户体验：友好错误提示

• Web Vitals：LCP、FID、CLS 监控
• 图片优化：响应式图片、懒加载
• 代码分割：React.lazy、动态导入
• 用户交互：防抖、节流

• 输入验证：Zod 验证所有用户输入
• XSS 防护：DOMPurify 清理 HTML
• CSRF 防护：Token 验证
• 敏感数据：安全存储和传输

• RESTful：标准 HTTP 方法和状态码
• 统一响应：{ success, data?, error?, message? }
• 错误处理：标准化错误码和消息
• 验证：Zod schema 验证请求

• JSON 配置：从界面截图提取设计元素，生成标准化配置
• 颜色系统：主色、辅助色、中性色、语义色完整定义
• 排版系统：字体族、字体大小、字重、行高层级规范
• 组件规范：按钮、输入框、卡片等组件的样式和状态定义
• 布局系统：响应式断点、栅格系统、间距规范
• AI 指导：作为设计指导文档，帮助 AI 生成一致风格的代码

💡 参考资源：设计系统开发方法论参考 3 Ways to Build Beautiful Websites Using Cursor AI

1. 遵循命名规范创建文件和目录
2. 使用 TypeScript 严格模式
3. 通过 Context7 MCP 获取第三方库文档
4. 从设计稿提取设计系统配置（如需要）
5. 实现统一错误处理
6. 编写必要的测试用例
7. 遵循 Git 提交消息规范

• 所有变量和函数都有明确类型
• 所有错误都有适当处理
• 所有组件都有合理的性能优化
• 所有 API 调用都有超时和重试
• 所有用户输入都有验证

• 统一的代码风格和规范
• 清晰的提交消息和分支管理
• 完整的文档和注释
• 标准化的错误处理和日志记录

本项目引入 AI 驱动的任务拆解与进度管理规范，详见 task-master.mdc。

• 智能任务拆解：支持自然语言需求自动分解为可执行任务，层次化、依赖清晰
• 实时进度跟踪：任务状态自动更新，进度可视化，所有变更实时同步到 task.md
• AI 辅助执行：为每个任务提供实现指导、代码建议、阻塞解决方案

• 标准 Markdown 结构，包含项目概览、任务分解、进度统计、里程碑、每日工作流等
• 任务分为 P0（核心）、P1（重要）、P2（一般）、PX（创新）四级，状态流转清晰
• 每个任务需有描述、验收标准、技术要点、工时、依赖、状态、最后更新时间

• 每日优先处理 P0 任务，实时更新状态，记录进展与阻塞
• 任务拆解需原子、可测试、时间可控、依赖明确
• 定期回顾任务优先级与进度，保持 task.md 文档准确
• 敏感信息不得写入任务描述，注意文档体积与安全

# 项目任务管理

> 📊 **项目进度**: !@进度条
> 🕒 **最后更新**: 2025-01-12 14:30:00
> 📈 **总体状态**: 进行中

## 📑 项目概览
### 需求描述
[项目的核心需求和目标描述]
### 技术栈
- 前端: [技术栈]
- 后端: [技术栈]
- 数据库: [技术栈]
- 其他: [相关技术]

---

## 🎯 任务分解
### P0 - 核心功能 (高优先级 - 立即执行)
#### 任务组 1: [功能模块名称]
- [ ] **T001** - [任务标题] `🔥 P0`
  - **描述**: [详细描述]
  - **验收标准**: [明确的验收标准]
  - **技术要点**: [关键技术点]
  - **预估工时**: [时间估计]
  - **依赖**: [前置任务ID]
  - **状态**: `📋 待开始` | `🔄 进行中` | `✅ 已完成` | `🚫 已阻塞`
  - **最后更新**: [时间戳]

  <details>
  <summary>📝 实现指导</summary>

  **步骤分解**:
  1. [具体步骤1]
  2. [具体步骤2]
  3. [具体步骤3]

  **代码示例**:
  ```javascript
  // 示例代码

注意事项:

• [重要提醒1]
• [重要提醒2]

本项目持续更新，确保规范与最新技术保持同步。