audit-code-review

代码审查技能

自由度：混合 — 阶段 1–2 的判断 [高自由度]； 审查前必须执行的 Git/文档检查 [低自由度 — 严格按要求运行]。

审查此 PR 或指定的差异。仓库级反模式 → audit-code-quality。 批量转换语义 → audit-codemod-safety。

推理方式

1. 观察 — 引用代码块及其所在文件的上下文（不要只看单行）
2. 解读 — 如果合并，会导致什么故障、泄漏或重复？
3. 分类 — 阻塞项 / 建议 / 小问题 / 表扬
4. 严重程度 — 安全问题、数据丢失或破坏现有功能 = 阻塞项

示例

观察： 新增的 GET /api/invoices/:id 返回 Invoice.findById(id) ，但没有 userId 条件（此差异中的 app/api/invoices/[id]/route.ts）。 解读： 任何已通过身份验证的调用者都能读取其他用户的发票。 分类： 阻塞项（IDOR）。 严重程度： 严重 — 合并前必须修复。 发现： [id]/route.ts | 添加所有权检查 | 阻塞项

审查前检查 [低自由度 — 严格按要求运行]

审查代码前：

1. 阅读相关文档

README.md (project conventions)
src/[domain]/@_[domain]-README.md (domain-specific patterns)
CONTRIBUTING.md (code standards)

2. 了解完整变更

如果审查 PR 或提交：

git log --oneline -10 # recent context
git diff <base>..HEAD --stat # files changed
git diff <base>..HEAD # full diff

如果审查特定文件，请阅读完整文件以了解上下文，而不只是变更行。

3. 检查重复实现

使用 Grep 和 SemanticSearch 验证：

• 此代码是否重复了现有功能？
• 是否有应该扩展的现有组件/服务？
• 这是否遵循代码库中已有的模式？

4. 检查生产影响（Sentry）

如果变更涉及容易出错的代码，请检查是否存在相关的 Sentry 问题：

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "issues related to <component or function being changed>",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 10
}

这可以揭示：正在修改的代码是否存在已知的生产问题？此变更是在修复这些问题，还是有引入问题的风险？

5. 调研当前最佳实践（针对非简单模式）

如果代码使用了你想要验证的模式：

firecrawl:firecrawl_search
{
 "query": "<framework> <pattern> best practice <current year>",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

---

审查流程 [高自由度]

阶段 1：高层评估

逐行审查前：

• 此变更的目的是什么？
• 从架构角度看，这种做法是否合理？
• 是否有更简单的替代方案？
• 是否引入了新的依赖？这些依赖是否合理？

阶段 2：详细审查清单

正确性

• 对所有预期输入，逻辑都正确
• 变更实现了 PR / 任务的要求 — 缺少要求、路径只实现了一半或范围被悄然缩小，都属于阻塞项
• 已处理边界情况（null、空值、溢出、并发访问）
• 没有明显的错误（差一错误、运算符错误、缺少 await）
• 错误处理完整且恰当
• 异步代码已处理竞态条件和清理工作（AbortController 等）

安全性

• 没有 SQL 注入风险（使用原始查询时带入用户输入）
• 没有 XSS 漏洞（dangerouslySetInnerHTML、innerHTML）
• 没有硬编码的密钥或凭据
• 所有面向用户的端点都进行了输入验证
• 已正确检查身份验证/授权（不只在 UI 层检查）
• 日志或错误消息中没有敏感数据

性能

• 没有 N+1 查询（批处理、预加载）
• 没有不必要的循环或重复计算
• 使用了合适的数据结构（Map 而非 Object、Set 而非 Array）
• 没有内存泄漏（清理事件监听器、取消订阅）
• React：没有不必要的重新渲染（在适当情况下使用 memo、useMemo、useCallback）
• 数据库：查询使用索引，避免全表扫描

可读性

• 名称清晰且具有描述性（函数、变量、类型）
• 函数大小合适（单一职责）
• 注释解释“为什么”而不是“做什么”（仅说明不明显的约束）
• 与项目现有风格一致

可维护性

• DRY —— 不应存在可共享的重复逻辑
• 单一职责 —— 每个函数/组件只做一件事
• 不使用魔法数字或字符串（使用常量或联合类型）
• 类型应具体（不使用 any，不使用过于宽泛的联合类型）
• 依赖应恰当且精简

测试

• 测试覆盖了此次变更（正常路径 + 边缘情况）
• 测试彼此独立且结果确定
• 未引入不稳定的测试（超时、竞态条件）
• 测试名称能描述预期行为

防止重复

• 没有重复组件（已检查 src/components/）
• 没有重复的服务或钩子
• 扩展现有模式，而非重复造轮子
• 逻辑被使用 2 次以上时，提取为共享工具函数/钩子

---

反馈格式

使用严重级别：

### Critical (must fix before merge)
**[File:Line]** — [Description]
Why: [Impact if not fixed]
Fix: [Specific suggestion]

### Suggestion (recommended improvement)
**[File:Line]** — [Description]
Why: [Benefit of the change]
Alternative: [How to improve]

### Nitpick (optional, non-blocking)
**[File:Line]** — [Description]

### Praise (good patterns to reinforce)
**[File:Line]** — [What's done well and why]

---

阻塞与非阻塞

阻塞（必须修复）

• 安全漏洞
• 数据损坏风险
• 破坏现有功能
• 缺少关键错误处理
• 性能回退（可测量）
• 类型安全违规（any、未经检查的类型断言）

非阻塞（建议）

• 更好的命名或组织方式
• 缺少针对边缘情况的测试
• 文档缺失
• 轻微的性能改进
• 未被代码检查工具覆盖的风格偏好

---

常见问题模式

TypeScript/JavaScript

// BLOCK: any types
const data: any = response;

// BLOCK: unhandled promises
fetchData(); // missing await or .catch()

// BLOCK: implicit type coercion in conditions
if (value) // when value could be 0 or ""

// SUGGEST: magic strings
if (status === 'active') // use a constant or union type

React

// BLOCK: missing key in lists
{items.map(item => <Item {...item} />)}

// BLOCK: stale closure in useEffect
useEffect(() => {
 setInterval(() => console.log(count), 1000); // captures stale count
}, []);

// SUGGEST: inline object creation in props
<Component style={{ margin: 10 }} /> // new object each render

数据库

-- BLOCK: SQL injection vector
WHERE name = '${userInput}'

-- SUGGEST: missing index
SELECT * FROM orders WHERE user_id = ? -- is user_id indexed?

-- SUGGEST: SELECT *
SELECT * FROM users -- select only needed columns

---

报告前自我批评 [LOW freedom — do not skip]

1. 有证据支撑 —— 引用差异中的 文件:行号，而不是“可以做得更好”
2. 可复现 —— 阅读完整文件，而不只是代码块
3. 严重级别合理 —— 阻塞问题 = 安全 / 数据丢失 / 功能破坏 / 缺少关键处理
4. 负责人正确 —— 整个仓库范围的问题 → audit-code-quality；批量转换 → audit-codemod-safety
5. 不制造虚假的安全感 —— 代码检查工具已覆盖的风格问题不属于阻塞问题

审查回复模板

## Code Review: [PR Title / File]

### Summary
[1-2 sentence overall assessment — is this ready to merge?]

### Critical (blocking)
[List any must-fix findings]

### Suggestions (recommended)
[List recommended improvements]

### Praise
[Highlight good practices — reinforces positive patterns]

### Questions
[Clarifying questions about intent or design decisions]

### Research Notes
[If patterns were verified via Firecrawl/Context7, note what was confirmed]

---

什么情况算作问题

阻塞问题包括正确性错误、安全漏洞、数据丢失路径，以及变更声明与实际行为之间的差距；建议和小问题按上述反馈格式处理。每个问题都要指出行号、后果和修复方法。代码检查工具或代码库自身约定已覆盖的风格问题，在任何级别都不算问题。评判代码块前应先阅读上下文代码；如果意图不清楚，应在“问题”部分询问，而不是擅自假设。