# cursor_rules

**Repository Path**: wanwei8889/cursor_rules

## Basic Information

- **Project Name**: cursor_rules
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cursor AI 规则模板库

这是一个通用的 Cursor AI 规则模板库，采用 **skill（技能）** 的形式组织规则，可以在任何项目中复用。

## 项目说明

本模板库提供了模块化的 Cursor AI 规则，帮助团队在不同项目中保持一致的代码规范和开发约定。

## 主要特性

- 🎯 **模块化设计**：规则按 skill 分类，职责清晰
- 🔄 **可复用**：通用规则可在多个项目中直接使用
- 📝 **模板化**：项目特定规则提供模板，便于配置
- 🛠️ **易扩展**：可轻松添加自定义 skill

## 文件结构

```
.cursor/
├── skills/                    # Skill 目录（模块化规则）
│   ├── code-organization.md   # 代码组织原则
│   └── commit-convention.md   # Commit 消息规范
├── project.md.template        # 项目特定规则模板文件
├── project.md                 # 项目特定规则配置文件（从模板复制，被 .gitignore 忽略）
├── generate_cursorrules.py    # 生成脚本（Python版本）
├── generate_cursorrules.sh    # 生成脚本（Shell版本）
├── generate_cursorrules.ps1   # 生成脚本（PowerShell版本）
└── README.md                  # 本文件（项目说明和使用指南）

项目根目录/
└── .cursorrules               # 规则入口文件（由脚本自动生成）
```

## 规则入口

使用脚本生成 `.cursorrules` 文件后，该文件将作为规则入口。详见下方"生成 .cursorrules 文件"部分。

## 快速开始

### 步骤 1：复制项目模板文件

从模板文件复制创建项目专用配置文件：

```bash
# 在项目根目录执行
cp .cursor/project.md.template .cursor/project.md

# Windows PowerShell
Copy-Item .cursor/project.md.template .cursor/project.md

# Windows CMD
copy .cursor\project.md.template .cursor\project.md
```

### 步骤 2：配置项目信息

编辑 `.cursor/project.md`，将 `<占位符>` 替换为实际项目信息：

- 项目名称、描述
- 技术栈
- 开发环境配置
- 项目特定约定等

### 步骤 3：完成

配置完成后即可使用。`project.md` 已被 `.gitignore` 忽略，不会提交到仓库。

## 工作原理

- **通用 Skills**：保存在 `skills/` 目录中，可直接使用，无需修改
- **项目特定规则** (`project.md`)：包含项目特定的配置，被 `.gitignore` 忽略
- **规则入口** (`.cursorrules`)：通过脚本自动生成，采用元数据索引方式，列出所有可用的 skill 文件路径，让 agent 可以按需加载

这样既保证了通用规则模板的统一性，又允许每个项目有自己的特定配置，且不会产生冲突。采用索引方式可以最小化入口文件的大小，agent 可以根据需要按需加载对应的 skill 文件。

## Skill 的优势

- ✅ **模块化**：每个 skill 专注于一个特定方面，职责清晰
- ✅ **可复用**：通用 skills 可以在多个项目中直接使用
- ✅ **易扩展**：可以根据需要添加新的 skill 文件
- ✅ **易维护**：修改某个 skill 不影响其他规则

## 添加自定义 Skill

如果需要添加自定义的通用 skill，可以：

1. 在 `.cursor/skills/` 目录下创建新的 `.md` 文件
2. 编写对应的规则内容
3. 文件会被 Cursor 自动识别和使用

## 生成 .cursorrules 文件

本模板库提供了自动生成 `.cursorrules` 文件的脚本工具。脚本会扫描 `skills/` 目录下的所有 skill 文件，生成基于元数据的索引文件到项目根目录。

**重要**：生成的 `.cursorrules` 文件采用索引方式，只包含 skill 文件的路径和简要描述，不包含完整内容。Agent 可以根据需要按需加载对应的 skill 文件，这样可以最小化入口文件的大小。

**快速开始**：
```bash
cd .cursor
python generate_cursorrules.py --include-project
```

这将在项目根目录生成 `.cursorrules` 文件，该文件将作为 Cursor 的规则入口。

**详细说明**：请参考 [GENERATE_CURSORRULES.md](./GENERATE_CURSORRULES.md) 文档，其中包含：
- 三种平台脚本的使用方法（Python/Shell/PowerShell）
- 详细的使用场景和示例
- 故障排除指南


## 使用方式

> **两种方式的选择建议：**
> - **Git Submodule（推荐）**：适合需要版本跟踪、团队协作、定期更新的场景
> - **直接克隆**：适合一次性使用、不需要版本跟踪的场景
> 
> 详细区别见下方说明。

### 方式一：作为 Git Submodule（推荐）

将本模板库作为 git submodule 直接添加到项目的 `.cursor` 目录：

```bash
# 在项目根目录执行
git submodule add https://gitee.com/wanwei8889/cursor_rules.git .cursor

# 如果项目已有 .cursor 目录，需要先删除或重命名
# 然后执行上述命令
```

**Windows PowerShell:**
```powershell
git submodule add https://gitee.com/wanwei8889/cursor_rules.git .cursor
```

**Windows CMD:**
```cmd
git submodule add https://gitee.com/wanwei8889/cursor_rules.git .cursor
```

**克隆包含 submodule 的项目：**
```bash
# 克隆项目时同时初始化 submodule
git clone --recurse-submodules <project-url>

# 或者先克隆，再初始化 submodule
git clone <project-url>
cd <project-name>
git submodule update --init --recursive
```

**更新 submodule：**
```bash
# 在主项目中更新 submodule 到最新版本
cd .cursor
git pull origin main
cd ..

# 或者使用 submodule 命令
git submodule update --remote .cursor
```

**移除 submodule：**
如果不再需要 submodule，可以按以下步骤移除：

```bash
# 1. 取消注册 submodule（从 .gitmodules 和 .git/config 中删除）
git submodule deinit -f .cursor

# 2. 删除 .git/modules 中的 submodule 数据
rm -rf .git/modules/.cursor

# 3. 从工作目录和 git 索引中删除 submodule 目录
git rm -f .cursor

# 4. 提交更改
git commit -m "移除 .cursor submodule"
```

**Windows PowerShell:**
```powershell
git submodule deinit -f .cursor
Remove-Item -Recurse -Force .git\modules\.cursor
git rm -f .cursor
git commit -m "移除 .cursor submodule"
```

**Windows CMD:**
```cmd
git submodule deinit -f .cursor
rmdir /S /Q .git\modules\.cursor
git rm -f .cursor
git commit -m "移除 .cursor submodule"
```

### 方式二：直接克隆

直接将模板库克隆到项目的 `.cursor` 目录：

```bash
# 在项目根目录执行
git clone https://gitee.com/wanwei8889/cursor_rules.git .cursor
```

**重要提示：**
- 如果项目已有 `.cursor` 目录，需要先删除或重命名，然后再执行克隆命令
- **嵌套 Git 仓库问题**：直接 `git clone` 会在 `.cursor` 目录内创建 `.git` 目录，形成嵌套的 git 仓库
- 如果不想保留 git 历史，可以在克隆后删除 `.git` 目录：
  ```bash
  git clone https://gitee.com/wanwei8889/cursor_rules.git .cursor
  rm -rf .cursor/.git  # 删除 .git 目录，只保留文件内容
  ```
- **建议**：如果项目本身是 git 仓库，推荐使用 Git Submodule 方式（方式一），以避免嵌套仓库的潜在问题

### 方式三：作为参考模板

参考本模板库的结构和规则内容，在你的项目中创建自己的规则文件。

## Git Submodule 与直接克隆的区别

### Git Submodule 方式

**优点：**
- ✅ **版本跟踪**：主项目会记录 submodule 的特定版本，确保团队使用相同版本
- ✅ **易于更新**：可以统一更新到新版本，也可以锁定特定版本
- ✅ **团队协作**：所有团队成员自动使用相同版本的规则模板
- ✅ **版本控制**：规则模板的版本变化会反映在主项目的提交历史中
- ✅ **独立性**：规则模板保持独立的 git 仓库，便于维护和更新

**缺点：**
- ❌ 需要额外的 submodule 操作命令
- ❌ 克隆项目时需要额外的 `--recurse-submodules` 参数

**适用场景：**
- 团队协作项目
- 需要确保所有成员使用相同版本的规则
- 需要定期更新规则模板
- 需要追踪规则模板的版本变化

### 直接克隆方式

**优点：**
- ✅ **简单直接**：只需一条 `git clone` 命令
- ✅ **无依赖**：不依赖主项目的 git 配置
- ✅ **独立管理**：可以自由修改，不受版本约束

**缺点：**
- ❌ **嵌套 Git 仓库**：`.cursor` 目录会成为独立的 git 仓库（包含 `.git` 目录）
- ❌ **Git 冲突风险**：主项目的 git 通常不会跟踪子目录中的 `.git`，但可能造成混淆
- ❌ **无版本跟踪**：主项目无法追踪规则模板的版本
- ❌ **团队不一致**：不同成员可能使用不同版本的规则
- ❌ **更新困难**：需要手动拉取更新，可能产生冲突
- ❌ **修改风险**：直接修改可能影响后续更新

**注意事项：**
- 直接 `git clone` 会在 `.cursor` 目录内创建 `.git` 目录，形成嵌套的 git 仓库
- 主项目的 git 通常不会跟踪 `.cursor/.git`（会被自动忽略）
- 如果不想保留 `.cursor` 目录的 git 历史，可以在克隆后删除 `.git` 目录：
  ```bash
  git clone https://gitee.com/wanwei8889/cursor_rules.git .cursor
  rm -rf .cursor/.git  # 删除 .git 目录，只保留文件
  ```

**适用场景：**
- 个人项目
- 一次性使用，不需要版本跟踪和 git 历史
- 需要大量自定义修改
- 不需要团队统一规则版本
- **注意**：如果项目是 git 仓库，建议使用 Git Submodule 方式以避免冲突

## 配置步骤

使用本模板库后，需要完成以下配置：

1. **复制并编辑项目特定规则**：
   从模板文件复制：`.cursor/project.md.template` → `.cursor/project.md`
   然后编辑 `.cursor/project.md`，替换 `<占位符>` 为实际项目信息
   - 项目名称、描述
   - 技术栈
   - 开发环境配置
   - 项目特定约定等

2. **完成配置**：
   `project.md` 中的项目特定配置已被 `.gitignore` 忽略，不会提交到仓库

3. **可选：添加自定义 Skill**：
   根据项目需要在 `.cursor/skills/` 目录下添加自定义的 skill 文件

4. **可选：生成 .cursorrules 文件**：
   可以使用提供的脚本自动生成 `.cursorrules` 文件到项目根目录：
   ```bash
   cd .cursor
   python generate_cursorrules.py --include-project
   ```
   详细说明请参考：[GENERATE_CURSORRULES.md](./GENERATE_CURSORRULES.md)