用途
caveman-review 是一种用于编写代码审查评论的风格规范,目标是让 PR 反馈极度精简、可执行。它通过固定格式和严格规则,去除冗余表达,只保留位置、问题和修复建议,从而减少噪音,提高审查效率。
主要能力
- 单行格式:每条发现写成一行,格式为
L<line>: <problem>. <fix>.,多文件差异时使用<file>:L<line>: ...。 - 严重程度前缀(可选,混合时使用):
- 🔴 bug: 行为错误,会导致事故
- 🟡 risk: 能工作但脆弱(竞态、缺少空值检查、吞掉错误)
- 🔵 nit: 风格、命名、微优化,作者可忽略
- ❓ q: 真实疑问,不是建议
- 删除内容:
- “我注意到……”、“看起来……”、“你可能想考虑……”
- “这只是个建议但是……”——改用 nit:
- “干得好!”、“整体看起来不错但是……”——在顶部说一次,不要每条都写
- 复述该行代码的功能——审查者可以自己看 diff
- 模糊措辞(“也许”、“可能”、“我认为”)——如果不确定就用 q:
- 保留内容:
- 精确行号
- 反引号中的精确符号/函数/变量名
- 具体修复,而不是“考虑重构这个”
- 如果修复原因不明显,说明为什么
使用方式
直接按照上述规则编写评论,输出可直接粘贴到 PR 中的评论。示例:
-
❌ “我注意到在第 42 行,你在访问 email 属性之前没有检查 user 对象是否为 null。如果数据库中找不到用户,这可能会导致崩溃。你可能想在这里加一个空值检查。”
-
✅
L42: 🔴 bug: user can be null after .find(). Add guard before .email. -
❌ “看起来这个函数做了很多事情,为了可读性,拆分成更小的函数可能会更好。”
-
✅
L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist. -
❌ “你有没有考虑过如果 API 返回 429 会发生什么?我认为我们可能应该处理这种情况。”
-
✅
L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
自动清晰模式
在以下情况放弃精简模式:安全发现(CVE 级 bug 需要完整解释和引用)、架构分歧(需要理由,不能只写一行)、以及新人引导场景(作者是新手,需要知道“为什么”)。这些情况下写正常段落,然后对其余部分恢复精简模式。
边界
仅用于审查——不编写代码修复,不批准/请求更改,不运行 linter。输出可直接粘贴到 PR 的评论。输入“stop caveman-review”或“normal mode”可恢复详细审查风格。
适用场景
适用于需要快速、清晰、可操作反馈的代码审查,尤其是团队熟悉该风格、追求效率的场景。不适用于需要详细解释的安全问题、架构讨论或新人引导。
限制
该工具本身不执行代码修改、不运行检查、不管理 PR 状态,仅提供评论风格规范。具体效果取决于使用者的遵循程度。