ai-proj-helper/plugins/req-plugin/code-review-guide.md

代码评审指南 (Code Review Guide)

代码评审是测试阶段的前置条件，确保代码质量在测试前得到验证。

评审时机

开发完成 → 代码评审 → 测试
    ↑          ↓
    └── 发现问题，修复后重新评审

评审检查清单

1. 代码风格

• 符合项目编码规范（Go/TypeScript）
• 命名清晰有意义
• 代码格式统一（已运行 lint/format）

2. 安全性

• 无 SQL 注入风险
• 无 XSS 漏洞
• 无敏感信息硬编码（密码、密钥）
• 权限检查完善

3. 错误处理

• 异常捕获完善
• 错误信息友好（不暴露内部细节）
• 边界条件处理

4. 性能

• 无 N+1 查询
• 无不必要的循环/递归
• 大数据量有分页处理

5. 日志与监控

• 关键操作有日志
• 日志级别适当
• 无敏感信息输出到日志

6. 测试覆盖

• 关键逻辑有单元测试
• 测试用例有效

7. 文档

• 复杂逻辑有注释
• API 有文档说明

评审方式

方式	适用场景
自评 (Self Review)	AI 开发的代码，Claude 自动检查
他人评审 (Peer Review)	团队协作，提交 PR 等待评审
结对评审 (Pair Review)	复杂功能，实时讨论

执行流程

/req cr 命令执行步骤

1. 验证开发完成

   检查所有 implementation 任务状态 = completed
   

2. 生成变更摘要

   git diff --stat HEAD~N  # N = 开发期间的提交数
   git diff --name-only HEAD~N
   

3. 显示检查清单

   • 输出上述检查清单
   • 逐项确认或标记问题

4. 记录评审结果

   • 通过：创建 code_review 任务并标记 completed
   • 不通过：列出问题，等待修复后重新评审

常见问题

Go 后端

• 未检查 error 返回值
• 缺少 defer 关闭资源
• 并发访问未加锁

TypeScript 前端

• any 类型滥用
• 缺少空值检查
• 未处理异步错误

数据库

• 缺少索引
• 大事务未拆分
• 未考虑并发更新

评审不通过时

/req cr REQ-XXXX

→ 发现问题:
  ⚠️ handlers/task_handler.go:245 - 缺少错误处理
  ⚠️ pages/TaskList.tsx:88 - 存在 XSS 风险

→ 请修复后重新执行 /req cr

跳过评审（紧急情况）

/req test REQ-XXXX --skip-cr --reason="紧急生产修复"

跳过评审需记录原因，事后补充评审。