SuperAPI AI 工具集

chinese-code-review

编程与开发

查看项目

更新于 10-16 09:26

技能介绍

用途

本技能面向国内团队的 Code Review 场景,解决两个常见极端:过度客气导致关键问题被放过,或照搬西方直白风格让同事下不来台。目标是在不回避问题的前提下,让反馈更容易被接受。

核心原则:用「建议」代替「命令」,用「提问」代替「否定」,但绝不因为面子而放过 bug。

主要能力

审查反馈的表达方式

用建议代替命令,例如把「你必须改成 X」改为「建议考虑用 X,因为 Y」;把「这里写错了」改为「这里可能存在一个问题,是否考虑过 Z 的情况?」。

用提问代替否定,当不确定对方意图时先问再评。例如:「这里用 sync 方式读文件是出于什么考虑?如果并发量上来,可能会阻塞事件循环。」

分级标注

统一使用优先级标记,让作者快速判断轻重缓急:

  • [必须修复] — 安全漏洞、数据丢失风险、逻辑错误(不修不能合)
  • [建议修改] — 性能问题、可维护性、缺少校验(本次或下次迭代修复)
  • [仅供参考] — 命名优化、风格建议、替代方案(不改也行)
  • [问题] — 不确定的地方,需要作者解释意图

审查评论模板

以 SQL 注入风险为例,模板包含:问题定位(第 42 行)、原因说明(攻击者可注入 '; DROP TABLE users; --)、修复建议(使用参数化查询 db.query('SELECT * FROM users WHERE name = $1', [name]))以及参考链接。

中英混排代码注释规范

何时用中文:业务逻辑说明、复杂算法注释、TODO / FIXME、内部项目的文档注释(JSDoc / Javadoc 描述文字)。

何时用英文:变量名、函数名、类名;Git commit message;开源项目注释;生产环境错误信息和日志;对外 API 接口文档。

混排格式要求:中英文之间加空格;技术术语保留英文,不强行翻译。

Commit Message 中英双语格式

团队内部项目推荐使用约定式提交(Conventional Commits)的中文版,格式为 <类型>(<范围>): <简要描述>,并附详细说明与关联信息。类型对照表包括 feat、fix、docs、style、refactor、perf、test、chore。面向国际社区的项目使用英文 commit message,PR 描述中可附加中文说明。

常见反模式与对策

  • 过度客气:关键 bug 被委婉语掩盖。对策是使用分级标注,语气可温和但级别必须准确。
  • 不敢给高级开发者提意见:导致代码质量双标。对策是对事不对人,可用提问式或学习式表达。
  • 审查变成风格之争:浪费时间。对策是风格问题交给 ESLint / Prettier / gofmt 等工具自动处理。
  • 只写「LGTM」:审查形同虚设。对策是即使代码质量好,也要写出关注了哪些方面。

审查流程建议

开始审查前先看 PR 描述和关联 Issue,先整体浏览再逐文件细看。审查顺序为:架构层面、正确性、安全性、性能、可维护性、风格。审查结束后给出总结,包括整体评价、值得学习的地方、主要问题列表(按优先级)和建议的修改方向。

检查清单

提交审查意见前确认:每条评论都标注了优先级;[必须修复] 的问题都给出了具体修复建议;没有因面子跳过关键问题;没有纠结于工具能自动处理的风格问题;对好的代码给予了肯定;给出了整体总结。

使用方式

本技能以规范文档形式提供,可在进行 Code Review 时参照其中的表达方式、分级标注、评论模板、注释规范、Commit 格式、反模式对策、流程建议和检查清单执行。具体安装命令与集成方式暂未提供。

适用场景

适用于国内开发团队的代码审查、Pull Request 评审、代码注释与 Commit Message 规范制定等场景,尤其适合需要兼顾专业严谨与团队沟通文化的团队。

限制

本技能为规范与话术指南,不包含自动化审查工具或代码检查功能。具体工具集成方式、平台支持范围暂未提供。