Skip to content

07-RuleLibrary-Part4.md

Latest commit

 

History

History
828 lines (679 loc) · 22.5 KB

07-RuleLibrary-Part4.md

File metadata and controls

828 lines (679 loc) · 22.5 KB

规则库管理（第四部分）

规则维护高级策略

除了基本的版本控制外，还需要采用一些高级策略来确保规则库的长期可维护性和稳定性。

规则测试和验证

1. 创建规则测试系统

为了确保规则的可靠性，应该创建一个测试系统来验证规则的行为：

# Linux/macOS
# 创建规则测试目录
mkdir -p ~/cursor-rules-library/tests/fixtures
mkdir -p ~/cursor-rules-library/tests/results

# 创建测试脚本
cat > ~/cursor-rules-library/tests/test-rules.sh << 'EOL'
#!/bin/bash

# 规则测试脚本

LIBRARY_DIR="$HOME/cursor-rules-library"
TESTS_DIR="$LIBRARY_DIR/tests"
FIXTURES_DIR="$TESTS_DIR/fixtures"
RESULTS_DIR="$TESTS_DIR/results"

# 清理旧结果
rm -rf "$RESULTS_DIR"/*

# 对每个规则进行测试
find "$LIBRARY_DIR/categories" -name "*.mdc" -type f | while read rule_file; do
    rule_name=$(basename "$rule_file" .mdc)
    rule_fixture="$FIXTURES_DIR/$rule_name.fixture.js"
    
    echo "测试规则: $rule_name"
    
    # 如果存在对应的测试文件
    if [ -f "$rule_fixture" ]; then
        # 模拟规则应用
        rule_id=$(grep "^name:" "$rule_file" | head -n 1 | sed 's/name: //')
        
        # 创建测试结果目录
        rule_result_dir="$RESULTS_DIR/$rule_name"
        mkdir -p "$rule_result_dir"
        
        # 应用规则并收集结果
        {
            echo "规则ID: $rule_id"
            echo "规则文件: $rule_file"
            echo "测试时间: $(date)"
            echo "---------------------------------"
        } > "$rule_result_dir/result.txt"
        
        # 这里是规则应用的模拟逻辑
        line_num=1
        while IFS= read -r line; do
            if echo "$line" | grep -q "var"; then
                echo "触发规则: 行 $line_num - $line" >> "$rule_result_dir/result.txt"
            fi
            ((line_num++))
        done < "$rule_fixture"
        
        echo "测试完成: $rule_name"
    else
        echo "警告: 没有找到$rule_name的测试文件"
    fi
done

echo "所有规则测试完成！结果保存在 $RESULTS_DIR"
EOL

# 添加执行权限
chmod +x ~/cursor-rules-library/tests/test-rules.sh

# 创建示例测试文件
cat > ~/cursor-rules-library/tests/fixtures/js-best-practices.fixture.js << 'EOL'
// JS最佳实践规则测试文件

// 应该触发规则的代码
var x = 10;
var y = 20;

// 不应该触发规则的代码
let z = 30;
const w = 40;

function testFunction() {
    // 嵌套变量声明，也应该触发规则
    var innerVar = "test";
    
    // 不应该触发规则
    let innerLet = "test";
}
EOL
@echo off
REM Windows CMD
REM 创建规则测试目录
set libraryPath=%USERPROFILE%\cursor-rules-library
if not exist "%libraryPath%\tests\fixtures" mkdir "%libraryPath%\tests\fixtures"
if not exist "%libraryPath%\tests\results" mkdir "%libraryPath%\tests\results"

REM 创建测试批处理脚本
(
echo @echo off
echo REM 规则测试脚本
echo.
echo set libraryDir=%%USERPROFILE%%\cursor-rules-library
echo set testsDir=%%libraryDir%%\tests
echo set fixturesDir=%%testsDir%%\fixtures
echo set resultsDir=%%testsDir%%\results
echo.
echo REM 清理旧结果
echo if exist "%%resultsDir%%\*" del /q /s "%%resultsDir%%\*"
echo.
echo REM 执行基本测试
echo echo 开始执行规则测试...
echo.
echo for %%f in ("%%fixturesDir%%\*.js") do (
echo   echo 测试文件: %%f
echo   echo 测试结果 ^> "%%resultsDir%%\%%~nf.result"
echo   findstr /n "var" "%%f" ^>^> "%%resultsDir%%\%%~nf.result"
echo   echo --------------------------------------- ^>^> "%%resultsDir%%\%%~nf.result"
echo )
echo.
echo echo 测试完成，结果保存在 %%resultsDir%% 目录
) > "%libraryPath%\tests\test-rules.bat"

REM 创建示例测试文件
(
echo // JS最佳实践规则测试文件
echo.
echo // 应该触发规则的代码
echo var x = 10;
echo var y = 20;
echo.
echo // 不应该触发规则的代码
echo let z = 30;
echo const w = 40;
echo.
echo function testFunction() {
echo     // 嵌套变量声明，也应该触发规则
echo     var innerVar = "test";
echo     
echo     // 不应该触发规则
echo     let innerLet = "test";
echo }
) > "%libraryPath%\tests\fixtures\js-best-practices.fixture.js"

2. 规则验证标准

创建一个规则质量验证清单，确保所有规则满足一定的质量标准：

# Linux/macOS
# 创建规则质量清单
mkdir -p ~/cursor-rules-library/docs
cat > ~/cursor-rules-library/docs/rule-quality-checklist.md << 'EOL'
# 规则质量检查清单

每个规则在提交到规则库前，应该通过以下质量检查：

## 必要条件

- [ ] 规则有唯一的ID
- [ ] 规则有明确的版本号
- [ ] 规则有清晰的描述
- [ ] 过滤器使用了正确的语法
- [ ] 动作使用了正确的结构
- [ ] 规则通过了基本功能测试

## 文档要求

- [ ] 规则有详细的文档
- [ ] 文档包含使用示例
- [ ] 文档说明了规则的用途和适用场景
- [ ] 文档提供了相关规则的引用

## 性能考虑

- [ ] 规则的正则表达式优化（避免回溯）
- [ ] 规则的过滤器顺序合理（最具限制性的过滤器放在前面）
- [ ] 规则对大文件有性能考虑

## 兼容性考虑

- [ ] 规则与现有规则没有冲突
- [ ] 规则与不同版本的Cursor兼容
- [ ] 规则兼容不同操作系统（如Windows和Unix）

## 可维护性考虑

- [ ] 规则代码结构清晰
- [ ] 复杂逻辑有注释说明
- [ ] 规则有完整的变更日志
- [ ] 规则有测试用例
EOL
@echo off
REM Windows CMD
REM 创建规则质量清单
set libraryPath=%USERPROFILE%\cursor-rules-library
if not exist "%libraryPath%\docs" mkdir "%libraryPath%\docs"

(
echo # 规则质量检查清单
echo.
echo 每个规则在提交到规则库前，应该通过以下质量检查：
echo.
echo ## 必要条件
echo.
echo - [ ] 规则有唯一的ID
echo - [ ] 规则有明确的版本号
echo - [ ] 规则有清晰的描述
echo - [ ] 过滤器使用了正确的语法
echo - [ ] 动作使用了正确的结构
echo - [ ] 规则通过了基本功能测试
echo.
echo ## 文档要求
echo.
echo - [ ] 规则有详细的文档
echo - [ ] 文档包含使用示例
echo - [ ] 文档说明了规则的用途和适用场景
echo - [ ] 文档提供了相关规则的引用
echo.
echo ## 性能考虑
echo.
echo - [ ] 规则的正则表达式优化（避免回溯）
echo - [ ] 规则的过滤器顺序合理（最具限制性的过滤器放在前面）
echo - [ ] 规则对大文件有性能考虑
echo.
echo ## 兼容性考虑
echo.
echo - [ ] 规则与现有规则没有冲突
echo - [ ] 规则与不同版本的Cursor兼容
echo - [ ] 规则兼容不同操作系统（如Windows和Unix）
echo.
echo ## 可维护性考虑
echo.
echo - [ ] 规则代码结构清晰
echo - [ ] 复杂逻辑有注释说明
echo - [ ] 规则有完整的变更日志
echo - [ ] 规则有测试用例
) > "%libraryPath%\docs\rule-quality-checklist.md"

规则废弃和删除策略

随着时间的推移，一些规则可能会变得过时或不再需要，需要制定规则废弃和删除的策略。

1. 规则废弃流程

# Linux/macOS
# 创建规则废弃指南
mkdir -p ~/cursor-rules-library/docs
cat > ~/cursor-rules-library/docs/rule-deprecation-guide.md << 'EOL'
# 规则废弃指南

本文档描述了如何正确废弃和删除规则库中的规则。

## 规则废弃流程

1. **标记为废弃**：
   - 在规则的元数据中添加 `deprecated: true` 标记
   - 在规则的描述中说明废弃原因和替代方案
   - 更新规则的版本号

2. **废弃期**：
   - 规则标记为废弃后，保留至少3个月的废弃期
   - 在废弃期内，规则仍然可用，但会发出废弃警告
   - 在废弃期内，所有使用该规则的项目应迁移到替代方案

3. **删除规则**：
   - 废弃期结束后，可以从活动规则库中删除该规则
   - 删除前，将规则移动到 `archive` 目录
   - 在规则索引中移除该规则的引用

## 标记规则为废弃示例

```rule
metadata:
  deprecated: true
  deprecation_reason: "此规则已被新的'js_modern_syntax'规则取代，该规则提供了更全面的JavaScript语法检查。"
  alternative_rule: "js_modern_syntax"
  deprecation_date: "2023-03-14"
  removal_date: "2023-06-14"
</rule>

规则归档

被删除的规则应移动到归档目录，而不是直接删除：

rules-library/
├── archive/                  # 归档的规则
│   ├── 2023-03/              # 归档日期
│   │   ├── js-old-rule.mdc   # 归档的规则
│   │   └── ...

规则删除检查清单

  • 规则已标记为废弃至少3个月
  • 已通知所有使用该规则的项目
  • 提供了明确的迁移路径
  • 规则已移动到归档目录
  • 规则索引已更新
@echo off
REM Windows CMD
REM 创建规则废弃指南
set libraryPath=%USERPROFILE%\cursor-rules-library
if not exist "%libraryPath%\docs" mkdir "%libraryPath%\docs"

(
echo # 规则废弃指南
echo.
echo 本文档描述了如何正确废弃和删除规则库中的规则。
echo.
echo ## 规则废弃流程
echo.
echo 1. **标记为废弃**：
echo    - 在规则的元数据中添加 `deprecated: true` 标记
echo    - 在规则的描述中说明废弃原因和替代方案
echo    - 更新规则的版本号
echo.
echo 2. **废弃期**：
echo    - 规则标记为废弃后，保留至少3个月的废弃期
echo    - 在废弃期内，规则仍然可用，但会发出废弃警告
echo    - 在废弃期内，所有使用该规则的项目应迁移到替代方案
echo.
echo 3. **删除规则**：
echo    - 废弃期结束后，可以从活动规则库中删除该规则
echo    - 删除前，将规则移动到 `archive` 目录
echo    - 在规则索引中移除该规则的引用
echo.
echo ## 标记规则为废弃示例
echo.
echo ```rule
echo metadata:
echo   deprecated: true
echo   deprecation_reason: "此规则已被新的'js_modern_syntax'规则取代，该规则提供了更全面的JavaScript语法检查。"
echo   alternative_rule: "js_modern_syntax"
echo   deprecation_date: "2023-03-14"
echo   removal_date: "2023-06-14"
echo ^</rule^>
echo ```
echo.
echo ## 规则归档
echo.
echo 被删除的规则应移动到归档目录，而不是直接删除：
echo.
echo ```
echo rules-library/
echo ├── archive/                  # 归档的规则
echo │   ├── 2023-03/              # 归档日期
echo │   │   ├── js-old-rule.mdc   # 归档的规则
echo │   │   └── ...
echo ```
echo.
echo ## 规则删除检查清单
echo.
echo - [ ] 规则已标记为废弃至少3个月
echo - [ ] 已通知所有使用该规则的项目
echo - [ ] 提供了明确的迁移路径
echo - [ ] 规则已移动到归档目录
echo - [ ] 规则索引已更新
) > "%libraryPath%\docs\rule-deprecation-guide.md"

规则归档

被删除的规则应移动到归档目录，而不是直接删除：

rules-library/
├── archive/                  # 归档的规则
│   ├── 2023-03/              # 归档日期
│   │   ├── js-old-rule.mdc   # 归档的规则
│   │   └── ...

规则删除检查清单

  • 规则已标记为废弃至少3个月
  • 已通知所有使用该规则的项目
  • 提供了明确的迁移路径
  • 规则已移动到归档目录
  • 规则索引已更新

2. 创建规则归档目录

# Linux/macOS
# 创建规则归档目录
mkdir -p ~/cursor-rules-library/archive/$(date +"%Y-%m")
@echo off
REM Windows CMD
REM 创建规则归档目录
set libraryPath=%USERPROFILE%\cursor-rules-library
for /f "tokens=1,2 delims=/" %%a in ('echo %date%') do set month=%%a
for /f "tokens=3 delims=/" %%a in ('echo %date%') do set year=%%a
set archiveDir=%libraryPath%\archive\%year%-%month%
if not exist "%archiveDir%" mkdir "%archiveDir%"

团队协作管理

随着规则库的增长，团队协作变得越来越重要。以下是一些管理团队协作的策略：

1. 规则贡献指南

创建规则贡献指南，帮助团队成员正确贡献规则：

# Linux/macOS
# 创建贡献指南
cat > ~/cursor-rules-library/CONTRIBUTING.md << 'EOL'
# Cursor规则库贡献指南

感谢您对Cursor规则库的贡献！请遵循以下指南，确保您的贡献顺利集成到规则库中。

## 贡献流程

1. **新建分支**：从主分支创建新的功能分支
2. **编写规则**：按照规则模板创建和编辑规则
3. **测试规则**：确保规则按预期工作
4. **添加文档**：编写规则文档和使用示例
5. **提交更改**：提交更改并推送到远程仓库

## 命名约定

- **规则ID**：使用下划线命名法，如 `js_best_practices`
- **规则文件**：使用连字符命名法，如 `js-best-practices.mdc`
- **分支名称**：使用特性分支命名法，如 `feature/js-arrow-function-style`

## 提交信息格式

我们使用约定式提交信息格式：

"""
<类型>(<范围>): <描述>

<详细说明>

<脚注>
"""

类型包括：
- `feat`：新功能
- `fix`：修复
- `docs`：文档更改
- `style`：格式调整
- `refactor`：代码重构
- `test`：添加测试
- `chore`：其他更改

示例：
"""
feat(js-rules): 添加箭头函数风格检查

添加了箭头函数的风格检查规则，确保一致的风格和参数处理。
该规则检查包括：
- 单参数是否使用括号
- 函数体是否使用花括号
- 返回值是否使用return语句

Closes #123
""""

感谢您的贡献！
EOL
@echo off
REM Windows CMD
REM 创建贡献指南
set libraryPath=%USERPROFILE%\cursor-rules-library

(
echo # Cursor规则库贡献指南
echo.
echo 感谢您对Cursor规则库的贡献！请遵循以下指南，确保您的贡献顺利集成到规则库中。
echo.
echo ## 贡献流程
echo.
echo 1. **新建分支**：从主分支创建新的功能分支
echo 2. **编写规则**：按照规则模板创建和编辑规则
echo 3. **测试规则**：确保规则按预期工作
echo 4. **添加文档**：编写规则文档和使用示例
echo 5. **提交更改**：提交更改并推送到远程仓库
echo.
echo ## 命名约定
echo.
echo - **规则ID**：使用下划线命名法，如 `js_best_practices`
echo - **规则文件**：使用连字符命名法，如 `js-best-practices.mdc`
echo - **分支名称**：使用特性分支命名法，如 `feature/js-arrow-function-style`
echo.
echo ## 提交信息格式
echo.
echo 我们使用约定式提交信息格式：
echo.
echo ```
echo ^<类型^>^(^<范围^>^): ^<描述^>
echo.
echo ^<详细说明^>
echo.
echo ^<脚注^>
echo ```
echo.
echo 类型包括：
echo - `feat`：新功能
echo - `fix`：修复
echo - `docs`：文档更改
echo - `style`：格式调整
echo - `refactor`：代码重构
echo - `test`：添加测试
echo - `chore`：其他更改
echo.
echo 示例：
echo ```
echo feat^(js-rules^): 添加箭头函数风格检查
echo.
echo 添加了箭头函数的风格检查规则，确保一致的风格和参数处理。
echo 该规则检查包括：
echo - 单参数是否使用括号
echo - 函数体是否使用花括号
echo - 返回值是否使用return语句
echo.
echo Closes #123
echo ```
echo.
echo 感谢您的贡献！
) > "%libraryPath%\CONTRIBUTING.md"

2. 进行代码审查

# Linux/macOS
# 创建规则审查模板
mkdir -p ~/cursor-rules-library/docs
cat > ~/cursor-rules-library/docs/review-template.md << 'EOL'
# 规则审查模板

## 基本信息

- **规则ID**: [ID]
- **版本**: [版本号]
- **提交人**: [姓名/用户名]
- **审查人**: [姓名/用户名]
- **审查日期**: [日期]

## 功能审查

- [ ] 规则实现了预期功能
- [ ] 规则正确处理边缘情况
- [ ] 规则有充分的测试覆盖
- [ ] 过滤器逻辑准确
- [ ] 动作执行正确

## 代码质量审查

- [ ] 代码符合代码风格指南
- [ ] 命名清晰且一致
- [ ] 注释充分且有帮助
- [ ] 正则表达式优化且可读
- [ ] 没有不必要的复杂性

## 文档审查

- [ ] 文档描述了规则的用途
- [ ] 文档包含有用的示例
- [ ] 文档说明了规则的配置选项
- [ ] 文档提到了相关规则
- [ ] 文档格式正确

## 兼容性审查

- [ ] 与现有规则兼容
- [ ] 在不同操作系统上测试
- [ ] 考虑了向后兼容性

## 审查结果

- [ ] 批准
- [ ] 需要修改
- [ ] 拒绝

## 反馈和建议

[详细反馈]
EOL
@echo off
REM Windows CMD
REM 创建规则审查模板
set libraryPath=%USERPROFILE%\cursor-rules-library
if not exist "%libraryPath%\docs" mkdir "%libraryPath%\docs"

(
echo # 规则审查模板
echo.
echo ## 基本信息
echo.
echo - **规则ID**: [ID]
echo - **版本**: [版本号]
echo - **提交人**: [姓名/用户名]
echo - **审查人**: [姓名/用户名]
echo - **审查日期**: [日期]
echo.
echo ## 功能审查
echo.
echo - [ ] 规则实现了预期功能
echo - [ ] 规则正确处理边缘情况
echo - [ ] 规则有充分的测试覆盖
echo - [ ] 过滤器逻辑准确
echo - [ ] 动作执行正确
echo.
echo ## 代码质量审查
echo.
echo - [ ] 代码符合代码风格指南
echo - [ ] 命名清晰且一致
echo - [ ] 注释充分且有帮助
echo - [ ] 正则表达式优化且可读
echo - [ ] 没有不必要的复杂性
echo.
echo ## 文档审查
echo.
echo - [ ] 文档描述了规则的用途
echo - [ ] 文档包含有用的示例
echo - [ ] 文档说明了规则的配置选项
echo - [ ] 文档提到了相关规则
echo - [ ] 文档格式正确
echo.
echo ## 兼容性审查
echo.
echo - [ ] 与现有规则兼容
echo - [ ] 在不同操作系统上测试
echo - [ ] 考虑了向后兼容性
echo.
echo ## 审查结果
echo.
echo - [ ] 批准
echo - [ ] 需要修改
echo - [ ] 拒绝
echo.
echo ## 反馈和建议
echo.
echo [详细反馈]
) > "%libraryPath%\docs\review-template.md"

规则库共享和发布

规则库的真正价值在于分享和重用。本节将探讨如何发布和分享您的规则库。

发布规则库

1. 创建公共仓库

将规则库发布到公共Git仓库，如GitHub：

# 初始化仓库并添加远程源
cd ~/cursor-rules-library
git init
git add .
git commit -m "初始化规则库"
git remote add origin https://github.com/yourusername/cursor-rules-library.git
git push -u origin main

2. 创建规则库README

# Linux/macOS
# 创建README文件
cat > ~/cursor-rules-library/README.md << 'EOL'
# Cursor规则库

一个用于Cursor AI的规则集合，提高开发效率和代码质量。

## 简介

这个规则库包含了各种Cursor规则，涵盖代码质量、工作流自动化、文档生成等方面。这些规则旨在提高开发效率、保持代码质量和促进团队协作。

## 安装

### 方法1：克隆整个仓库

```bash
git clone https://github.com/yourusername/cursor-rules-library.git
cp -r cursor-rules-library/categories/code-quality/* ~/.cursor/rules/

方法2：单独下载规则

curl -o ~/.cursor/rules/js-best-practices.mdc https://raw.githubusercontent.com/yourusername/cursor-rules-library/main/categories/code-quality/js-best-practices.mdc

规则分类

  • 代码质量: 检查和提高代码质量的规则
  • 工作流: 自动化开发工作流的规则
  • 文档: 生成和验证文档的规则
  • 测试: 辅助测试的规则
  • 安全: 检查和提高代码安全性的规则

推荐规则

贡献

欢迎贡献您的规则！请查看贡献指南了解如何参与。

许可证

本规则库采用MIT许可证。详见LICENSE文件。

@echo off
REM Windows CMD
REM 创建README文件
set libraryPath=%USERPROFILE%\cursor-rules-library

(
echo # Cursor规则库
echo.
echo 一个用于Cursor AI的规则集合，提高开发效率和代码质量。
echo.
echo ## 简介
echo.
echo 这个规则库包含了各种Cursor规则，涵盖代码质量、工作流自动化、文档生成等方面。这些规则旨在提高开发效率、保持代码质量和促进团队协作。
echo.
echo ## 安装
echo.
echo ### 方法1：克隆整个仓库
echo.
echo ```bash
echo git clone https://github.com/yourusername/cursor-rules-library.git
echo cp -r cursor-rules-library/categories/code-quality/* ~/.cursor/rules/
echo ```
echo.
echo ### 方法2：单独下载规则
echo.
echo ```bash
echo curl -o ~/.cursor/rules/js-best-practices.mdc https://raw.githubusercontent.com/yourusername/cursor-rules-library/main/categories/code-quality/js-best-practices.mdc
echo ```
echo.
echo ## 规则分类
echo.
echo - **代码质量**: 检查和提高代码质量的规则
echo - **工作流**: 自动化开发工作流的规则
echo - **文档**: 生成和验证文档的规则
echo - **测试**: 辅助测试的规则
echo - **安全**: 检查和提高代码安全性的规则
echo.
echo ## 推荐规则
echo.
echo - [js_best_practices](categories/code-quality/js-best-practices.mdc): JavaScript最佳实践检查
echo - [react_component_standards](categories/code-quality/react-component-standards.mdc): React组件标准
echo - [git_commit_formatter](categories/workflow/git-commit-formatter.mdc): Git提交消息格式化
echo.
echo ## 贡献
echo.
echo 欢迎贡献您的规则！请查看[贡献指南](CONTRIBUTING.md)了解如何参与。
echo.
echo ## 许可证
echo.
echo 本规则库采用MIT许可证。详见[LICENSE](LICENSE)文件。
) > "%libraryPath%\README.md"

方法2：单独下载规则

curl -o ~/.cursor/rules/js-best-practices.mdc https://raw.githubusercontent.com/yourusername/cursor-rules-library/main/categories/code-quality/js-best-practices.mdc

规则分类

  • 代码质量: 检查和提高代码质量的规则
  • 工作流: 自动化开发工作流的规则
  • 文档: 生成和验证文档的规则
  • 测试: 辅助测试的规则
  • 安全: 检查和提高代码安全性的规则

推荐规则

贡献

欢迎贡献您的规则！请查看贡献指南了解如何参与。

许可证

本规则库采用MIT许可证。详见LICENSE文件。


在本章的最后部分，我们将总结规则库管理的关键点，并介绍一些实际应用和最佳实践案例。