.cursorrules

# LangShift.dev - 多语言学习平台 - Cursor 规则

## 项目概述
LangShift.dev 是一个专门为开发者设计的编程语言转换学习平台。通过对比不同编程语言的语法特性和概念映射，帮助开发者快速掌握新语言。项目使用 Next.js 15.3+ + Fumadocs 15.6+ 构建文档网站，支持多种语言转换学习，并集成了交互式代码编辑器和性能监控功能。

### 当前支持的语言转换
- **JavaScript → Python** (已完成): 13个学习模块，涵盖从基础语法到高级特性
- **JavaScript → Rust** (已完成): 14个学习模块，重点讲解内存管理和并发编程
- **JavaScript → Go** (已完成): 14个学习模块，专注于并发编程和微服务开发
- **JavaScript → Kotlin** (已完成): 14个学习模块，协程编程和 Android 开发
- **JavaScript → C++** (已完成): 15个学习模块，系统编程和性能优化
- **JavaScript → Swift** (已完成): 15个学习模块，移动开发和现代编程特性
- **JavaScript → C** (已完成): 15个学习模块，内存管理、指针操作和系统编程

## 📖 文档结构说明

本项目采用分层文档结构，AI 助手应根据上下文选择合适的文档：

### 根级文档（本文件）
- 适用于项目整体开发、通用规范、技术栈相关问题
- 全局的 AI 助手行为准则和开发规范

### 模块级文档
- **JavaScript → Python**: `content/docs/js2py/.cursorrules` (已完成)
- **JavaScript → Rust**: `content/docs/js2rust/.cursorrules` (已完成)
- **JavaScript → Go**: `content/docs/js2go/.cursorrules` (已完成)
- **JavaScript → Kotlin**: `content/docs/js2kotlin/.cursorrules` (已完成)
- **JavaScript → C++**: `content/docs/js2cpp/.cursorrules` (开发中)
- **JavaScript → Swift**: `content/docs/js2swift/.cursorrules` (开发中)
- **JavaScript → C**: `content/docs/js2c/.cursorrules` (开发中)
- 适用于特定语言转换的学习内容、代码示例、概念解释

### 使用建议
- 当用户询问特定语言转换问题时，优先参考对应模块的 .cursorrules
- 当用户询问项目整体架构、技术栈、通用开发问题时，使用本文件
- 当用户询问新模块创建、文档结构问题时，参考 `docs/module-documentation-template.md`

## 核心原则

### 1. 语言对比教学
- 始终从已知语言视角解释新语言概念
- 提供语言间的语法对比和概念映射
- 使用开发者熟悉的术语和概念
- 强调不同语言的异同点和设计哲学
- 使用对比组件展示代码差异
- 注重性能特性和最佳实践对比

### 2. 渐进式学习
- 按照模块顺序组织内容（多个模块）
- 每个概念都要有实际代码示例
- 提供练习题和实战项目
- 确保学习路径的连贯性
- 从基础语法到高级特性逐步深入
- 包含常见陷阱和解决方案

### 3. 实用性导向
- 重点讲解开发者最需要的语言技能
- 包含 Web 开发、数据处理、系统编程等应用场景
- 提供真实项目案例
- 注重工程化实践
- 强调性能优化和最佳实践
- 关注现代开发工具链

## 代码风格规范

### 通用代码规范
- 遵循各语言的官方编码规范
- 使用类型注解（支持的语言）
- 添加详细的注释和文档字符串
- 使用现代语言特性
- 遵循命名规范（各语言的约定）
- 考虑性能和内存管理

### 对比代码要求
- 提供功能相同的多语言实现
- 标注语法差异和概念映射
- 使用各语言的惯用写法
- 保持代码风格的一致性
- 包含性能对比分析
- 提供错误处理最佳实践

### 文档结构
- 使用 Markdown 格式
- 包含代码高亮和语法高亮
- 提供交互式代码示例
- 使用清晰的标题层级
- 集成代码编辑器组件
- 支持多语言内容

## 内容组织规则

### 每个语言转换模块应包含：
1. **概念介绍** - 从已知语言视角解释新语言概念
2. **语法对比** - 语言间的语法映射
3. **代码示例** - 使用编辑器组件展示可运行代码
4. **练习题** - 巩固学习内容
5. **实战项目** - 综合应用所学知识
6. **性能分析** - 不同实现的性能对比
7. **最佳实践** - 语言特定的编码规范

### 代码示例与编辑器组件
- **默认**：语言对比示例使用 **`UniversalEditor`**（与 CLAUDE.md 一致）。
- **例外**：**`content/docs/js2py/`** 与 **`content/docs/py2js/`** 中需浏览器端执行 Python（Pyodide）的 **JS + Python 双栏对比** 使用 **`<PythonEditor compare={true}>`**；模块细则见对应目录下的 `.cursorrules`。
- 使用编辑器组件包装代码
- 提供完整的可运行代码
- 包含错误处理和边界情况
- 添加详细的中文注释
- 提供测试用例
- 支持对比模式
- 包含性能监控

## 技术栈规范

### 文档网站
- Next.js 15.3+ (App Router)
- Fumadocs 15.6+ 文档框架
- Tailwind CSS 4.0+ 样式
- Monaco Editor 代码编辑器
- Pyodide 浏览器端 Python 运行时
- Orama 全文搜索
- 多语言运行时支持

### 语言运行时
- **Python**: Pyodide (浏览器端 Python)
- **JavaScript**: V8 Engine
- **Kotlin**: JVM (计划支持 Kotlin/JS)
- **Rust**: WebAssembly (计划中)
- **Go**: WebAssembly (计划中)
- **C++**: WebAssembly (计划中)
- **Swift**: WebAssembly (计划中)
- **其他语言**: 根据需求扩展

### 开发工具
- TypeScript 5.8+ 严格模式
- ESLint 9.30+ + Prettier 3.5+
- Turbopack 构建优化
- 性能监控组件
- VSCode 配置
- 多语言扩展推荐
- 调试配置
- Git 工作流

### 特色功能
- 交互式代码编辑器
- 虚拟化编辑器（性能优化）
- 滚动编码组件
- 性能监控组件
- SEO 优化组件
- 多语言国际化
- 智能搜索功能

## AI 助手行为准则

### 回答风格
- 使用中文回答
- 语言简洁明了
- 提供具体代码示例
- 解释概念时要有语言对比
- 推荐使用编辑器组件
- 关注性能特性

### 代码生成
- 生成符合各语言规范的代码
- 提供对应的多语言实现
- 包含完整的错误处理
- 添加详细的中文注释
- 使用编辑器组件包装
- 考虑性能优化

### 问题解决
- 优先考虑开发者的思维习惯
- 提供多种解决方案
- 解释选择特定方案的原因
- 考虑性能和最佳实践
- 利用运行时进行代码验证
- 分析性能瓶颈

## 文件命名规范

### 文档文件
- 语言转换模块：`{source}2{target}/`
- 示例代码：`examples/{language}/{name}.{ext}`
- 练习题：`exercises/{module}/{name}.md`
- 项目文件：`projects/{name}/`
- 多语言文件：`{name}.{lang}.mdx`

### 代码文件
- 使用各语言的命名约定
- 测试文件：`test_{module}.{ext}`
- 配置文件：使用 kebab-case
- TypeScript 文件：使用 PascalCase

### 组件文件
- React 组件：使用 PascalCase
- TypeScript 文件：使用 PascalCase
- 样式文件：使用 kebab-case
- 工具函数：使用 camelCase

## 质量保证

### 代码质量
- 所有代码必须可运行
- 通过静态检查工具验证
- 包含适当的测试用例
- 遵循最佳实践
- 在编辑器中测试执行
- 性能监控和优化

### 文档质量
- 内容准确无误
- 示例代码完整
- 链接和引用正确
- 格式规范统一
- 交互式代码示例可用
- 多语言内容同步

### 用户体验
- 学习路径清晰
- 示例代码易懂
- 练习题难度适中
- 提供足够的上下文
- 代码编辑器响应迅速
- 性能优化体验

## 特殊指令

### 当用户询问语言概念时：
1. 先解释对应的已知语言概念
2. 展示新语言的语法和用法
3. 提供对比示例（使用编辑器组件）
4. 说明使用场景和注意事项
5. 分析性能特性差异

### 当用户需要代码示例时：
1. 使用编辑器组件包装代码
2. 提供完整的可运行代码
3. 包含对应的多语言实现
4. 添加详细的中文注释
5. 说明代码的工作原理
6. 提供性能优化建议

### 当用户遇到问题时：
1. 分析问题的根本原因
2. 提供多种解决方案
3. 解释每种方案的优缺点
4. 推荐最佳实践
5. 在编辑器中验证解决方案
6. 考虑性能影响

## 项目维护

### 定期更新
- 保持语言版本兼容性
- 更新依赖包版本
- 检查示例代码的有效性
- 更新最佳实践建议
- 维护运行时版本
- 性能监控和优化

### 内容改进
- 根据用户反馈优化内容
- 添加更多实用示例
- 完善练习题和项目
- 更新技术栈和工具
- 优化编辑器组件性能
- 增强多语言支持

### 编辑器组件维护
- 确保多语言运行时兼容性
- 优化代码执行性能
- 改进错误处理机制
- 增强主题切换功能
- 完善对比模式体验
- 虚拟化渲染优化

## 多语言支持规范

### 语言转换模块开发
- 每个语言转换模块独立组织
- 保持模块间的一致性
- 支持渐进式扩展
- 维护语言特性的准确性
- 性能特性对比

### 国际化支持
- 支持中英文繁体中文三语界面
- 文档内容本地化
- 代码注释多语言支持
- 错误信息本地化
- 搜索功能多语言支持

### 扩展性设计
- 支持新语言快速接入
- 模块化架构设计
- 插件化功能扩展
- 向后兼容性保证
- 性能监控扩展

## 性能优化规范

### 编辑器性能
- 虚拟化渲染大量代码
- 懒加载和代码分割
- 内存使用优化
- 执行性能监控
- 缓存策略优化

### 网站性能
- 图片优化和懒加载
- 代码分割和按需加载
- 缓存策略优化
- SEO 友好设计
- 首屏加载优化

### 运行时性能
- 多语言运行时优化
- 内存管理优化
- 并发执行优化
- 错误处理优化
- 资源加载优化

## SEO 优化规范

### 结构化数据
- 网站结构化数据
- 课程结构化数据
- 文章结构化数据
- 面包屑导航
- 多语言 SEO

### 技术 SEO
- 网站地图生成
- 机器人协议
- 页面元数据
- 链接优化
- 性能指标

## 模块级文档引用

### 当前支持的模块
- **JavaScript → Python**: `content/docs/js2py/.cursorrules` (已完成 - 13个模块)
- **JavaScript → Rust**: `content/docs/js2rust/.cursorrules` (已完成 - 14个模块)
- **JavaScript → Go**: `content/docs/js2go/.cursorrules` (已完成 - 14个模块)
- **JavaScript → Kotlin**: `content/docs/js2kotlin/.cursorrules` (已完成 - 14个模块)
- **JavaScript → C++**: `content/docs/js2cpp/.cursorrules` (开发中 - 15个模块)
- **JavaScript → Swift**: `content/docs/js2swift/.cursorrules` (开发中 - 15个模块)
- **JavaScript → C**: `content/docs/js2c/.cursorrules` (开发中 - 15个模块)

### 新模块创建
参考 `docs/module-documentation-template.md` 创建新的语言转换模块。

### 新模块实施方案
- **JavaScript → C++**: `docs/js2cpp-module-implementation-plan.md` - 完整的 C++ 模块实施方案
- **JavaScript → Go**: `docs/js2go-module-implementation-plan.md` - 完整的 Go 模块实施方案
- **JavaScript → C**: `docs/js2c-module-implementation-plan.md` - 完整的 C 模块实施方案
- **JavaScript → Swift**: `docs/js2swift-module-implementation-plan.md` - 完整的 Swift 模块实施方案
- **JavaScript → Kotlin**: `docs/js2kotlin-module-implementation-plan.md` - 完整的 Kotlin 模块实施方案
- **JavaScript → Java**: `docs/js2java-module-implementation-plan.md` - 完整的 Java 模块实施方案
- **JavaScript → Dart**: `docs/js2dart-module-implementation-plan.md` - 完整的 Dart 模块实施方案

### 模块开发状态
- ✅ **已完成**: JavaScript → Python, JavaScript → Rust, JavaScript → Go, JavaScript → Kotlin
- 🚧 **已完成**: JavaScript → C++, JavaScript → Swift, JavaScript → C
- 📋 **已完成**: JavaScript → Java, JavaScript → Dart

---

记住：这个项目的核心目标是帮助开发者快速掌握新编程语言，因此所有的解释和示例都应该从语言对比的角度出发，并充分利用编辑器组件提供交互式学习体验。同时要注重性能优化和现代开发工具的使用。

**注意**: 当用户询问特定语言转换问题时，请优先参考对应模块的 .cursorrules 文件以获得更精确的指导。

### 模块选择建议
- **初学者**: 建议从 JavaScript → Python 开始，语法相对简单
- **系统编程**: 推荐 JavaScript → Rust 或 JavaScript → C++
- **并发编程**: 推荐 JavaScript → Go 或 JavaScript → Rust
- **移动开发**: 推荐 JavaScript → Swift 或 JavaScript → Kotlin (Android)
- **后端开发**: 推荐 JavaScript → Go 或 JavaScript → Kotlin (JVM)
- **性能优化**: 推荐 JavaScript → Rust 或 JavaScript → C++
- **企业应用**: 推荐 JavaScript → Kotlin 或 JavaScript → Java (JVM)