Trae 省积分批量注释生成法 —— SonarQube 注释率专项（不改代码 + 预统计 + 自审核）

Agent模式专区
1

一次踩坑复盘：为了把项目注释率从 13.8% 拉到 SonarQube 要求的 20%，绕来绕去花了 1 万多积分才摸索出这套稳定方案。整理出来给同样被 SonarQube 注释率卡住的同学，直接抄作业，少走弯路。

为什么诞生这个想法请看图片 干了我1w积分 最后发现几百积分就能完成的事 现时代大冤种 最主要的是之前1w积分搞出来的只是吧13.8%升到了16.4% 我也是被气到了 话不多说看图

先看我节省积分后的使用情况

image
image828×594 38.9 KB

image
image828×491 36.7 KB

再看使用长任务消耗的积分情况

image
image828×546 42.9 KB

image
image822×989 64.7 KB

痛点：为什么需要这个技巧

  • SonarQube 注释率是硬性质量门禁（通常要求 20%）
  • .vue 文件中 <script> 标签外的 HTML 注释不被 SonarQube 统计
  • 逐文件手动让 AI 加注释，token 消耗大、容易跑偏改业务代码、反复返工
  • 没有自检环节，提交后才发现注释率没涨、代码还被改动
  • 绕来绕去试错，一晚上烧掉 1 万多积分

一句话方案

三阶段 Prompt：预统计 → 只新增注释 → 自审核，全程禁止修改业务代码，按需精准补充注释，省积分、不返工。

核心约束（5 条铁律）

  1. 省积分模式：优先精简上下文，分文件分批处理，不读取无关依赖，不重构代码，只新增注释，绝对不修改任何业务代码逻辑、变量、表达式、导入导出
  2. 仅新增注释：原有代码一字不动；禁止删除、调整现有代码
  3. 前置统计：先统计目标文件总代码行数、当前有效注释行数、当前注释密度；根据目标注释率，计算需要新增的注释行数
  4. 自审核：完成后校验代码是否改动、注释是否为 Sonar 有效注释、剔除无效空注释
  5. 范围限定：只处理后缀 .js .ts .vue；排除 node_modules、dist、build

Trae Prompt（直接复制使用，搭配 #Folder）

【省积分模式，Sonar注释率专项】
选中#Folder目录下*.js,*.ts,*.vue文件，排除node_modules/dist/build。
阶段1【预统计】：不生成注释，仅统计：有效代码总行数、现有Sonar可识别有效注释行数、当前注释率；输入目标注释率，自动计算需要新增多少行有效注释。只输出统计结果，不改动文件。
阶段2【批量加注释】：严格只新增注释，原有代码完全不动，不修改任何逻辑、变量、语句。使用JSDoc/** */给函数/类，简单逻辑用//单行注释；禁止纯空注释、只有*的无效注释，注释贴合代码，禁止编造逻辑。按刚才计算的目标行数添加注释。
阶段3【自审核】：完成注释添加后自动自检：
1. 校验所有原始代码是否无任何改动；
2. 检查注释是否都是Sonar有效注释，剔除无效空注释；
3. 重新统计新的代码行数、注释行数、新注释率；
4. 输出审核报告：代码是否被改动、新增注释行数、最终注释率。
全程禁止修改业务代码，只新增注释，省积分：精简上下文，不解析第三方依赖，分批处理。

执行步骤

  1. #Folder 选中 src 目标目录，发送上面 Prompt，先执行阶段 1 预统计：输入目标注释率，拿到需新增注释行数
  2. 确认数字后，继续执行阶段 2 批量加注释：只新增注释，代码保持原样
  3. 自动执行阶段 3 自审核：输出审核结果与最终注释率
  4. 审核不达标 → 定向补充注释；代码有改动 → 直接放弃本次变更，git 回滚

规则限制

  • 不重构、不优化代码，不调整格式（除非仅注释换行）
  • 不读取项目完整依赖树，减少 token 消耗，省积分
  • 自审核只要检测到原始代码发生修改，立刻终止并告警

精简快速指令（省积分短版）

#Folder src 省积分模式，先统计代码行数当前注释率，输入目标注释率算出需新增注释行数；只新增注释不改任何代码；加完后自审核：检查代码是否改动，重新统计注释率，Sonar有效注释，禁止空注释

实战踩坑提醒（Vue 项目必看）

结合 Vue 2.7 项目实战经验，这些坑我替你踩过了：

  • .vue 文件的注释必须放在 <script> 标签内部第一行，使用 JSDoc 格式 /** ... */ 才能被 SonarQube 统计
  • 文件开头的 HTML 注释（<!-- 文件名 - 描述 -->）不计入注释率
  • SonarQube 社区版不支持分支分析，注释修改只在 push 到 dev 或 MR 目标为 dev 时才触发扫描
  • 不要让 AI 顺手改格式、调导入顺序、重命名变量，"只动注释"是底线
  • git 回滚用 git checkout -- <file> 或 git restore <file>，不要用 reset --hard，保留可复盘的现场
  • 加注释前先 git status 确认工作区干净，方便自审核阶段对比

为什么这套方案能省积分

传统做法 本方案
逐文件让 AI 读全文、分析、写注释 预统计 → 批量加 → 自审核，阶段化
AI 容易顺手重构、改格式，返工 铁律：只新增注释，代码一字不动
提交后才发现注释率没达标 前置统计先算目标行数，按需补充
注释格式不被 SonarQube 识别 强制 JSDoc / 单行 //，贴合 Vue 项目规范
反复试错，单次任务烧 1 万+ 积分 三阶段闭环，一次到位

适用场景

  • Vue 2 / Vue 3 项目、JS / TS 项目
  • SonarQube 注释率硬性门禁（20% 或更高）
  • 历史代码注释稀疏，需要批量补注释
  • 需要在不改动业务代码的前提下提升注释率

技巧便利店特价：一次 Prompt 闭环，省下 1 万积分。用过的同学回来点个赞。

4 个赞