code-review

name	code-review
description	单文件代码审查方法，6 个维度逐项检查（正确性、安全性、性能、可维护性、测试、无障碍）。方法语言无关，无障碍仅前端适用。

单文件代码审查

本技能聚焦单文件内部的质量检查。跨文件一致性、变更完整性等由 /review-all 负责。 方法语言无关：下方示例为 TS，Python/其他语言同理套用对应写法；具体语言规则见 .agents/rules/。

触发条件

• 用户要求审查某个文件
• /review-all 的逐文件阶段调用本技能
• Builder 完成单个文件后自查

6 个审查维度

1. 正确性

查什么：逻辑是否正确、边界是否处理、错误是否捕获

怎么查：

• 走读每个函数的执行路径，标记未覆盖的分支
• 检查空值/undefined：函数参数、对象属性访问、数组索引
• 检查异步：Promise 是否 await、是否有竞态条件、错误是否 catch
• 检查返回值：所有路径是否都有返回、类型是否一致
• 检查副作用：是否修改了入参、是否污染了外部状态

常见问题：

// ❌ 未处理 null
const name = user.profile.name;

// ❌ 异步错误未 catch
const data = await fetch(url).then(r => r.json());

// ❌ 条件分支不完整
function getRole(user) {
  if (user.isAdmin) return 'admin';
  // 忘了处理普通用户的情况，返回 undefined
}

2. 安全性

查什么：是否有注入、越权、密钥泄露等安全漏洞

怎么查：

• SQL 注入：搜索 $ 或 ` 模板字符串中拼接用户输入的位置
• XSS：搜索 innerHTML、dangerouslySetInnerHTML、JSX 中直接渲染用户输入
• 命令注入：搜索 exec、spawn、system 中拼接参数的位置
• 密钥泄露：搜索硬编码的 token、password、secret、key
• 越权：检查每个 API 端点是否有权限校验
• 输入验证：检查外部输入（API 参数、表单、文件）是否经过验证

OWASP Top 10 速查：

类别	检查项	搜索关键词
注入	SQL/XSS/命令注入	query(, innerHTML, exec(
认证	密码哈希、Token 安全	password, token, jwt
授权	水平/垂直越权	role, permission, userId
密钥	无硬编码	secret, key, password=
输入	验证所有外部输入	req.body, req.params, process.env

3. 性能

查什么：是否有不必要的计算、查询、渲染

怎么查：

• 循环中的数据库/API 调用：N+1 查询，搜索 for/map/forEach 内的 await/query/fetch
• 不必要的重渲染：React 组件内创建新对象/数组/函数（每次渲染都新建引用）
• 内存泄漏：事件监听器未移除、定时器未清除、大数组未释放
• 大数据处理：是否应该分页/流式处理，搜索 SELECT * 无 LIMIT
• 重复计算：昂贵计算是否应该缓存（useMemo、记忆化）

常见问题：

// ❌ N+1 查询
for (const id of userIds) {
  const user = await db.user.findUnique({ where: { id } });
}

// ❌ 每次渲染创建新对象
<Component style={{ color: 'red' }} />

// ❌ 无限制查询
const all = await db.logs.findMany(); // 百万行全查

4. 可维护性

查什么：代码是否清晰、是否易于修改

怎么查：

• 命名：变量/函数名是否自解释？缩写是否必要？
• 职责：一个函数是否只做一件事？超过 30 行考虑拆分
• 重复：搜索相似代码块，是否应该提取为函数/常量
• 复杂度：嵌套超过 3 层？条件超过 5 个？考虑早返回或策略模式
• 魔法数字：搜索硬编码的数字/字符串，是否应该提取为常量

5. 测试

查什么：是否有测试、测试是否有意义

怎么查：

• 核心业务逻辑是否有对应的 .test.ts 文件
• 测试是否覆盖了正常路径 + 异常路径
• Mock 是否合理（mock 外部依赖，不 mock 被测代码）
• 测试是否独立（不依赖执行顺序、不共享可变状态）

6. 无障碍（仅前端 UI 文件）

只对前端 UI 代码适用。后端 API、CLI、库、数据管道等跳过此维度（不算缺陷）。

查什么：UI 组件是否对辅助技术友好

怎么查：

• 交互元素（按钮、链接、输入框）是否有 aria-label 或可见文本
• 图片是否有 alt 属性
• 颜色对比度是否 >= 4.5:1（WCAG AA）
• 所有功能是否可通过键盘操作（Tab、Enter、Escape）
• 是否使用了语义化 HTML（<button> 而非 <div onClick>）

审查原则

• 解释 WHY，不只说 WHAT（"这里有 SQL 注入风险，因为用户输入直接拼接到查询字符串"）
• 提供修复代码，不只指出问题
• 区分"必须改"和"建议改"（安全问题 = 必须改，命名风格 = 建议改）
• 安全问题零容忍
• 小问题批量提，不逐行挑刺