用途
Code Review 是一个代码审查技能,用于在完成实现工作后、提交代码前,对代码变更(diff)或指定文件进行系统性审查。它提供了一套明确的审查原则,帮助开发者发现命名、引用、复杂度、注释、测试、API 设计等方面的问题。
主要能力
该技能围绕以下审查原则展开:
-
命名反映当前现实:变量和函数名应描述它们“是什么”,而非“曾经是什么”。如果底层机制改变(如 FUSE 改为 NFS),所有相关名称必须更新。
-
无过时引用:重构后,搜索旧方法的引用——失效的检测逻辑、废弃的功能开关、提及已删除代码的注释。如果某个方案被尝试后回退,应移除所有痕迹。
-
简化检测与守卫逻辑:像“此功能能否运行”这样的门控应只检查真正重要的那一件事,不要串联多个回退检测。
-
注释记录“为什么”,而非“发生了什么”:保留非显而易见的技术发现、平台怪癖、“如果移除这个,X 会因为 Y 而崩溃”。移除关于尝试过什么、放弃了什么、重命名了什么的叙述,以及仅复述代码行为的注释。
-
分离安装期与运行期:安装脚本设置前置条件(工具链、系统依赖),运行期命令处理编译、缓存、二进制管理,不要混用。
-
无中间产物:迭代多种方案后,审计仅作为垫脚石存在的逻辑。如果为方案 A 添加了变通方法后切换到方案 B,应移除该变通方法。
-
变更后收紧保证:当变更使某事物成为保证(变量总是被设置、文件总是被创建、函数总是返回),审计下游仍针对旧“可能”状态进行守卫的代码。冗余的空值检查、回退默认值具有误导性。优先使用 const 而非 let。绝不抑制信号——修复根因。
-
变更纠缠时从干净状态开始:如果文件经历了 3 轮以上冲突编辑,用 git restore 恢复并只重新应用所需内容。
-
测试必须验证实际值,而非仅集合大小:测试去重、规范化或幂等操作时,断言存储的值,而不仅是 toHaveLength(1)。
-
无薄包装或仅重导出的模块:如果模块只转发另一个包的函数或类型,删除它并直接导入原始包。
-
只在真实职责边界处抽取:不要仅为减少行数而拆分文件。新文件应拥有读者能命名的连贯职责。
-
测试与实现解耦——端到端驱动系统:最有价值的测试套件是与所覆盖实现最解耦的。优先使用仍能提供快速、确定性信号的最外层入口点。测试行为,而非结构。
-
失败的检查可能是工具链缺陷,而非代码缺陷:在手工编写类型、添加类型转换、固定值或重构代码以使检查器通过之前,确认失败是代码缺陷而非工具链/环境产物。
-
身份来自认证,绝不来自调用方:从已认证请求(API 密钥、会话或已验证的内部密钥)解析行为身份,绝不从调用方提供的参数解析。
-
公共 API 操作是薄认证加派发,而非内联业务逻辑:公共路由进行认证、验证、派生身份,并派发到拥有工作的模型函数或内部操作。
-
公共端点以最小范围发布:一个路由,每个请求一个项目。不要预先添加 /batch 变体、分页列表或过滤参数。
-
复用既有类型——派生,而非重新声明:如果类型已在上游存在,直接使用它。对于变体,使用 Pick/Omit/Partial 等派生。
-
在索引处过滤,绝不 take() 加后置过滤:当列表查询返回表中子桶的行时,索引必须完成过滤。
-
绝不 .collect()——用 .take(N) 限制读取:Convex .collect() 读取所有匹配行且无上限。用 .take(N) 替换,N 是明显高于当前工作集的安全上限。
-
不要仅为重命名或默认字段而重映射行:复制每个字段以重命名两个字段或将 undefined 合并为 false 的对象字面量 .map() 是噪音。
-
内部 API 不携带版本或兼容机制:当我们同时拥有生产者和消费者时,不要添加 protocolVersion 字段、版本协商、能力标志。
-
必须一致的声明需要一个归属:当两个声明必须保持一致但各自可独立更改时,它们会漂移。给共享决策一个归属,让每个位置从中组合。
-
不要将单次使用的值提升为命名常量,除非它配得上这个名字:提取到模块作用域但仅引用一次的常量增加了间接性而无收益。
使用方式
该技能以原则清单形式提供审查指导。使用时,针对代码变更(diff)或指定文件,逐条对照上述原则进行检查。资料中未提供具体的安装命令或调用方式。
适用场景
- 完成实现工作后、提交代码前的自查
- 代码审查流程中的检查清单
- 重构后的清理与一致性检查
- 测试质量与 API 设计审查
限制
资料中未提供该技能的具体安装方式、运行环境要求、支持的编程语言或平台、收费信息等。该技能以原则清单形式呈现,具体执行方式暂未提供。