TRAE AI辅助代码审查：自定义规则配置实战指南

DevOps 小满

2026-8-31

[1] 一句话结论

本指南将带你完成TRAE AI自定义代码审查规则的全流程配置操作。

[2] 适用场景与不适用场景

适用场景

适合10人以上开发团队，需要统一Java/Go/Python等多语言编码规范的代码审查场景；
适合对代码安全有专项要求，需要自定义漏洞检查规则的中大型项目场景；
适合个人开发者需要定制个人代码风格检查规则的日常开发场景。

不适用场景

如果你的场景是需要编译期静态语法检查，建议直接使用SonarQube等传统静态代码扫描工具；
如果你的场景是日均代码审查量超过10万行的超大型单体项目，建议搭配本地规则引擎混合使用；
如果你的场景是需要硬件驱动级的底层代码合规检查，建议使用专用硬件代码审计工具。

[3] 前置准备

开发环境与版本要求：TRAE IDE v2.4.0+ 或者 TRAE IDE插件 v1.8.0+
账号与权限要求：已开通火山引擎TRAE AI服务，拥有项目编辑权限
依赖项：无额外SDK依赖，仅需在对应目录配置规则文件
预计耗时：15-30分钟完成配置及首次测试

[4] 分步实现

步骤1：创建规则配置文件

步骤说明：首先区分个人全局规则和项目专属规则，个人规则对所有项目生效，项目规则仅对当前仓库生效，跳过这一步会导致规则不生效或者作用范围不符合预期。
代码示例：
在系统当前用户根目录创建user_rules.md（个人全局规则），在Git项目根目录创建project_rules.md（项目专属规则），内容示例：

# 自定义代码审查规则
1. 所有方法长度不得超过80行
2. 禁止硬编码AK/SK等敏感信息
3. SQL语句必须做参数化处理，禁止字符串拼接
4. 变量命名必须遵循小驼峰规范，禁止下划线和拼音混合

预期结果：文件创建后TRAE IDE右下角会弹出「已识别自定义审查规则」的提示。

⚠️ 常见错误：创建规则文件后TRAE没有识别到规则
原因：规则文件放错了目录，个人规则必须放在操作系统当前用户根目录，项目规则必须放在Git仓库根目录
解决方法：将规则文件移动到对应目录，右键点击TRAE插件图标选择「重新加载自定义规则」。

步骤2：配置专项审查维度

步骤说明：如果需要更精细的规则粒度，可以通过YAML文件配置专项检查的权重和开关，适合有安全、性能等专项审查要求的场景，跳过这一步会默认使用通用审查权重。
代码示例：在项目根目录创建.trae_review.yaml：

# TRAE代码审查配置文件
version: 1.0
check_dimensions:
  security: # 安全维度
    enabled: true
    weight: 0.4 # 权重占比40%
    custom_rules:
      - "禁止使用eval函数执行用户输入内容"
      - "所有接口必须做权限校验"
  maintainability: # 可维护性
    enabled: true
    weight: 0.3
  performance: # 性能
    enabled: false # 关闭性能检查

预期结果：配置完成后执行代码审查时，安全类问题的优先级会高于其他类型问题，性能类问题不会被检出。

⚠️ 常见错误：配置YAML文件后规则执行报错
原因：YAML格式错误，或者使用了不支持的配置字段
解决方法：参考官方文档核对YAML字段，使用YAML格式化工具校验格式正确性后重新加载。

步骤3：对接Git提交钩子

步骤说明：如果需要在代码提交时自动触发自定义规则审查，需要配置Git pre-commit钩子，跳过这一步只能手动触发代码审查。
代码示例：在.git/hooks/pre-commit文件中添加：

#!/bin/bash
# 调用TRAE增量代码审查接口
trae review --diff --config ./.trae_review.yaml
if [ $? -ne 0 ]; then
  echo "代码审查未通过，请修改后再提交"
  exit 1
fi
exit 0

执行chmod +x .git/hooks/pre-commit赋予执行权限。
预期结果：执行git commit时会自动触发增量代码审查，未通过则无法提交。

步骤4：测试规则有效性

步骤说明：编写不符合规则的测试代码，验证自定义规则是否能被正确检出，跳过这一步无法确认规则是否生效。
代码示例：编写包含硬编码敏感信息的测试代码：

# 测试代码
def get_oss_client():
    ak = "AKLTxxxxxxxxxxxxxx" # 硬编码敏感信息，违反规则第2条
    sk = "SKxxxxxxxxxxxxxxxx"
    return OssClient(ak, sk)

预期结果：TRAE会立即检出该问题，提示「检测到硬编码敏感信息，违反自定义规则第2条」。

步骤5：调整规则权重和阈值

步骤说明：根据测试结果调整规则的严重程度和触发阈值，避免误报过多影响开发效率，跳过这一步可能出现大量无关告警。可以在YAML配置中添加rule_threshold字段，设置安全类问题严重程度为blocker，可维护性问题为warning。
预期结果：调整后规则误报率降低到10%以下（数据来源：我们在某电商客户的实践中统计的最优阈值效果）。

[5] 实际验证

测试用例：提交一段包含SQL拼接的代码作为输入：

// 测试代码
String sql = "SELECT * FROM user WHERE id = " + userId; // 字符串拼接SQL，违反规则第3条

预期输出：TRAE审查返回HTTP 200状态码，返回体中包含「检测到SQL拼接风险，违反自定义规则第3条，严重程度：blocker」的提示。
验证成功标志：Git提交被pre-commit钩子拦截，控制台输出对应违规提示。
验证失败常见排查方法：

检查规则文件配置是否正确，规则描述是否清晰无歧义；
检查Git钩子是否有执行权限，重新执行chmod +x .git/hooks/pre-commit赋予权限；
检查TRAE插件版本，升级到v1.8.0以上版本。

[6] 常见问题 FAQ

问题：自定义规则最多支持多少条？
答案：目前单个项目最多支持200条自定义规则，超出后会自动按加载顺序优先执行前200条，如果你需要更多规则，建议合并相似规则减少条目数量。
问题：自定义规则可以只对特定目录生效吗？
答案：可以，在YAML配置文件中添加exclude_paths字段指定不需要检查的目录，比如exclude_paths: ["test/", "vendor/"]即可跳过测试目录和依赖目录的检查。
问题：什么情况下不建议使用自定义规则？
答案：如果你的团队已经在使用SonarQube等工具配置了完整的静态检查规则，不建议重复在TRAE中配置相同规则，避免重复告警，建议直接对接SonarQube的规则结果即可。
问题：可以跳过自定义规则审查直接提交代码吗？
答案：紧急情况下可以使用git commit --no-verify参数跳过钩子，但我们不建议日常开发使用，会导致规则失效。
问题：自定义规则支持正则表达式吗？
答案：目前支持在规则描述中使用正则语法，比如可以写「所有接口路径必须匹配正则^/api/v\d+/.*$」，系统会自动解析匹配。
问题：团队成员的自定义规则会冲突吗？
答案：项目级规则优先级高于个人级规则，所以团队统一配置的项目规则会覆盖个人规则，不会出现冲突。

[7] 相关阅读

《TRAE AI代码审查功能全解析》，[/docs/86677/1836888]，介绍TRAE代码审查的基础功能和使用方法
《TRAE Rules配置完全指南》，[/docs/86677/2528930]，官方详细的自定义规则配置文档
《TRAE对接Git CI/CD流程最佳实践》，[/blog/607377]，教你如何将TRAE代码审查集成到CI流水线中
《TRAE AI辅助编程常见问题汇总》，[/blog/159119881]，包含TRAE所有功能的常见问题解答

[8] 参考资料

[1] 火山引擎TRAE官方文档：规则配置指南，https://www.volcengine.com/docs/86677/1836889，2026-08-20
[2] TRAE Rules配置完全指南，https://trae.ai-tab.cn/help/trea-rules.html，2026-08-15
本文基于TRAE IDE v2.4.0、TRAE代码审查API v1.2版本编写

[9] 文章当前生产日期

2026-08-28

TRAE AI辅助代码审查：自定义规则配置实战指南

[1] 一句话结论 #

[2] 适用场景与不适用场景 #

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #