摘要

本地 AI 代码审查系统已规模化落地且应用效果良好，但通用审查规则难以适配多业务、多技术栈及团队编码规范的差异化场景。
本文围绕自定义审查规则展开系统性阐述，涵盖规则定义分类、分层架构设计，给出基于 Cursor Rules 的接入规范与编写标准，同时构建完整的效果保障、指标监控及闭环迭代机制。通过整套落地方案，解决通用代码审查适配性不足的痛点，为团队 AI 代码审查规范化、精准化建设提供可直接参考的实践指南。

一、背景与核心痛点

1.1 本地 CR 系统现状与成效

本地 CR 系统上线运行后，已在内部大范围推广落地，整体用户覆盖率处于较高水平。依托完备的本地项目上下文能力，可精准识别代码潜在隐患，审查落地效果与实际使用认可度表现良好。

1.2 现存适配局限

本地 CR 效果良好，但通用上下文无法适配差异化需求，核心局限如下：

问题类型	描述	典型案例
业务形态差异	各业务系统开发规范、接口逻辑未对齐	跨系统 POST 请求未过滤 undefined 字段，导致后端校验报错
技术细节差异	同一功能实现方式不统一，维护成本上升	翻译函数 $gt 写法不一，代码可读性差
技术栈选型差异	团队内部多前端框架共存，规则无法通用	同时存在 Vue、React 项目，组件规范差异大
规范标准差异	各团队代码风格、架构要求不同，规则需灵活调整	团队规范松紧不一，通用规则无法适配

1.3 解决方案与目标

核心解决方案：提供自定义审查规则能力，支持项目组录入团队、项目、个人级上下文，助力大模型精准定位问题，提升 CR 建议质量与采纳率。

核心目标：各团队试点落地自定义规则，验证效果后逐步推广，适配不同场景审查标准。

二、自定义审查规则核心定义

2.1 规则本质与价值

2.1 规则本质与价值

审查规则是告知 AI “代码问题、严重程度及修复方案” 的标准化指令。

单条规则的核心组成包含：规则分类 + 危险度 + 问题描述 + 处理策略；而从规则整体落地管理维度，还可通过分层架构实现规则复用与优先级管控。

核心价值是赋予 AI “专业审查思维”，可贴合团队需求精准检查代码、发现潜在问题、提供可落地修复建议，降低修复成本。

2.2 规则分类体系

基于审查场景，规则划分为六大类别，覆盖核心审查需求，具体如下：

问题类别	主要检查项	典型规则示例
安全问题	数据安全、权限控制、敏感信息防护等	禁止前端硬编码敏感信息；localStorage 存敏感信息需加密等
规范问题	编码、命名、架构、类型定义规范等	变量名语义化；React 组件设 key；避免魔法数字等
可维护性问题	代码结构、耦合度、嵌套深度等	组件职责单一；避免重复代码；复杂逻辑加注释等
可扩展性问题	设计模式、接口设计、模块化程度等	CSS 遵循 BEM 规范；Props 过多传配置对象等
性能问题	算法效率、内存泄漏、渲染性能等	避免不必要重渲染；频繁事件用节流等
健壮性问题	异常处理、边界条件、类型安全等	清理事件监听器；处理空值；避免 any 滥用等

2.3 危险度评分体系

建立 2-5 级危险度评分体系（分数越高危险越高），对应不同处理策略，具体如下：

评分	危险程度	问题描述	处理策略	典型示例
5 分	极高危险	不修复必出错，多为致命缺陷	立即修复，系统自动应用修复建议	空指针、死循环、敏感数据泄露等
4 分	高危险	不修复可能触发错误，有潜在风险	优先修复，可自动应用（需提醒用户确认）	hooks 依赖缺失、内存泄漏风险等
3 分	中等危险	影响代码质量，不立即出错	建议修复，需用户确认后应用	组件性能优化、可读性提升等
2 分	低危险	规范性问题，不影响功能	仅提醒，不自动修改	命名不规范、注释不完善等

2.4 规则分层架构

基于复用性，规则分为三个层级（优先级从低到高），适配不同复用需求：

规则层级	复用范围	规则示例	优先级
通用级别规则层	所有项目基础规则	禁止硬编码敏感信息、React 异步状态规范等	低
项目级别规则层	特定项目/项目类型	项目接口参数命名规范等	中
用户级别规则层	个人/团队定制	团队组件命名规范等	高

三、业务组接入指南（Cursor Rules 集成）

3.1 Cursor Rules 集成规范

3.1.1 目录结构规范

为确保规则被正确识别，需遵循以下规范：

• 文件夹格式：code-review
• 文件名格式：cr-*.mdc

标准目录结构：

.cursor/rules
├── xxx
└── local                    # 用户级别规则层
    └── code-review
        ├── cr-component.mdc  # 组件相关规则
        └── cr-request.mdc    # 请求相关规则

3.2 规则编写规范

3.2.1 编写原则

原则	说明
明确性	描述清晰无歧义，便于 AI 与开发者理解
可执行	可被 AI 解析执行，避免模糊表述
分层	按复用范围归入对应层级
分类	归属六大类别，避免分类混乱

3.2.2 编写示例（项目级）

---
description: 自定义 CR 规范，适配项目级审查需求
alwaysApply: true
---

## 敏感数据脱敏处理
分类：安全问题 | 危险度：5 分
正例：const maskedTel = userTel.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2');
反例：const userData = { userTel: '18647564936' }; // 未脱敏，直接暴露敏感信息

## Vue 组件命名规范
分类：规范问题 | 危险度：2 分
正例：UserInfoProfile.vue（大驼峰命名）
反例：user-info-profile.vue（连字符，不规范）

## 样式文件规范
分类：可维护性问题 | 危险度：3 分
正例：import styles from './UserCard.module.less'; <div className={styles.cardContainer}>
反例：<div style={{ margin: '10px' }}> // 禁止内联样式，不利于维护

## 组件 Props 数量控制
分类：可扩展性问题 | 危险度：3 分
正例：通过配置对象传参，简洁易维护
interface TablePropsConfig { tableColumns: Column[]; pageCount: number; }
<MyTable propsConfig={tablePropsConfig} />
反例：<MyTable colA={} colB={} colC={} ... /> // Props 过多，维护困难

3.3 最佳实践与验证

3.3.1 快速调用方式

在 Cursor Chat 输入以下指令，即可调用自定义规则审查：

@cr-component.mdc 帮我审查这段代码

注：现阶段需手动 @ 规则目录，后续将实现规则目录自动化分析。

3.3.2 规则生效验证

规则编写完成后，需先验证加载与应用效果，避免配置错误导致审查失效。

四、审查效果保障机制

4.1 核心理念

核心是通过 Prompt 提示词工程、上下文工程、数据驱动 三大方式，保障自定义审查规则的执行效果，核心逻辑为“尝试→验证→优化”的循环迭代。

注：AI 大模型回复无标准答案，需通过持续迭代优化审查精度。

4.2 效果影响因素

自定义审查规则的效果，主要受四大关键因素影响，具体如下：

影响因素	效果表现	典型场景
规则质量	高质量→精准识别；低质量→误报/漏报	规则描述模糊误判、覆盖不全漏检等
AI 理解能力	理解准确→正常执行；偏差→效果不佳	复杂规则难执行、上下文相关规则误判等
代码上下文	上下文充分→判断准确；不足→失误	diff 片段信息有限、跨文件依赖难识别等
规则适配性	匹配场景→有效检测；不匹配→失效	Vue 规则用于 React 项目、旧规则适配新技术栈等

综上，四大影响因素相互关联、层层递进，其中规则质量是基础，AI 理解能力与代码上下文是关键支撑，规则适配性决定场景落地效果，共同影响自定义审查规则的最终执行质量。

4.3 效果保障策略

保证维度	策略分类	核心措施	实施要点	目标效果
规则质量保证	编写质量控制	明确性要求	采用标准化模板，明确规则触发条件	减少理解歧义
		示例验证	配置正反例代码，校验规则判定逻辑	精准识别代码问题
		边界测试	设计边界用例，验证规则鲁棒性	规避特殊场景失效
	质量验证	同行评审	建立评审流程，多人交叉校验	整体提升规则质量
		验证清单	从描述、正反例、边界等项标准化校验	统一质量验收标准
AI 理解能力提升	规则表达优化	结构化描述	统一规则模板与格式规范	提升 AI 理解准确度
		关键词标识	高亮核心检查点，定义优先级	辅助 AI 抓取重点
		上下文补充	补充技术背景与业务场景说明	强化场景适配理解
	动态学习机制	反馈循环	收集使用反馈，迭代优化规则	基于实际效果持续改进
		案例积累	沉淀正反例样本库，定期更新	提升问题识别精度
		模式识别	分析历史数据，优化识别逻辑	精准定位特定类型问题
上下文信息增强	信息收集策略	扩展 diff 范围	扩充代码上下文，关联依赖定义	提供完整判定依据
		依赖关系分析	解析模块依赖，梳理代码调用链	厘清代码关联逻辑
		项目元信息	读取项目配置，识别技术栈特征	适配项目个性化特点
	智能推理补充	类型推断	依托 TS 类型辅助逻辑判断	提升类型问题识别精度
		框架识别	自动识别项目框架及版本	匹配框架专属审查规则
		模式匹配	识别通用代码与设计模式	挖掘潜在设计层面问题
规则适配性保证	自动适配机制	技术栈检测	解析项目依赖，动态加载匹配规则	适配当前技术栈
		版本兼容性	适配依赖版本差异，动态调整规则	兼容多版本技术环境
		环境感知	识别运行环境，动态调整检查严格度	适配不同环境审查标准
	规则冲突处理	优先级机制	设定规则优先级，自动消解冲突	保障审查执行一致性
		规则合并	聚合相似规则，精简执行链路	提升整体审查效率
		动态调整	结合项目特征，组合最优规则集	匹配项目实际业务场景

综上，四大保证维度与前文四大影响因素一一对应，通过分层分类的策略设计、明确的实施要点和清晰的目标导向，形成完整的效果保障体系，确保自定义审查规则落地见效、精准可控。

4.4 效果监控与持续改进

4.4.1 效果指标体系

建立三类核心指标，量化审查效果，具体如下：

指标类型	具体指标	计算方法
准确性指标	准确率	正确识别问题数 / 总识别问题数
	召回率	正确识别问题数 / 实际存在问题数
用户体验指标	采纳率	用户接受建议数 / 总建议数
	误报率	错误建议数 / 总建议数
效率指标	自动修复率	自动修复问题数 / 总发现问题数
	审查覆盖率	被审查代码行数 / 总变更代码行数

4.4.2 持续改进机制

建立“数据驱动 + 用户反馈”双闭环改进机制，持续优化审查效果：

改进类型	改进措施	具体操作	预期成果
数据驱动优化	问题分析	收集误报漏报案例、分析根因、制定方案	降低误报率
	趋势监控	建立监控面板、设置告警、生成报告	及时发现异常
	A/B 测试	设计对照实验、并行测试、统计差异	验证优化效果
用户反馈闭环	反馈收集	嵌入反馈按钮、建立表单、定期调研	贴合用户需求
	快速响应	建立工作流、设定响应标准、跟踪结果	提升满意度
	社区驱动	建立贡献平台、设立激励、组织分享	丰富规则库

五、总结与展望

5.1 核心价值总结

本文针对本地 AI CR 系统难以适配多业务、多技术栈的核心痛点，系统梳理自定义审查规则的定义、分类、分层架构、接入规范及效果保障方案，通过标准化体系与全维度管控，补齐通用审查短板，实现代码审查精准化、规范化、场景化落地。

价值维度	核心作用
精准审查	补充项目专属上下文，提升 AI CR 问题识别准确率与召回率
场景适配	三层规则架构，灵活兼容不同业务形态、技术栈与团队编码规范
落地高效	统一规则编写与 Cursor Rules 接入标准，降低业务组落地门槛
质量可控	建立指标监控与闭环迭代机制，长期稳定代码审查质量

5.2 落地实施建议

建议项	具体说明
试点先行	选取少量技术栈统一的标杆项目试点，验证规则效果后再批量推广
规范共建	统一团队规则编写范式，按六大类别、危险度标准规范产出规则
反馈迭代	常态化收集开发者使用反馈，结合监控数据持续优化规则表述与判定逻辑
复用沉淀	将验证成熟的规则沉淀至通用规则层，实现多项目共享复用

5.3 未来演进方向

演进方向	建设目标
流程自动化	自动识别项目 Cursor Rules 配置，省去手动调用操作，简化人工审查流程（可参考3.3.1）
规则智能化	基于项目技术栈与业务特征，智能匹配并推荐适配的审查规则体系
效果数据化	完善全维度监控指标，搭建可视化看板，实现审查效果可量化、可追溯
规则生态化	搭建内部规则共享库，沉淀最佳实践，形成团队规范共建共享生态