代码审查哨兵

在代码合并前执行结构化质量审查。以"高级工程师是否会批准这次合并"为标准，从五个维度全面把关。

核心能力

• 变更概览与尺寸评估：git diff 获取变更 + 统计规模 + 尺寸分级（理想 ~100 行/可接受 100-300/需拆分 >300）+ 变更分类
• 五维度审查：正确性（逻辑/边界/错误处理/回归）+ 可维护性（命名/职责/重复/复杂度）+ 安全性（注入/权限/密钥/依赖）+ 性能（计算/查询/内存/阻塞）+ 可测试性（覆盖/路径/可 mock）
• 严重度标签体系：Blocking（阻塞）/ Should Fix（建议修复）/ Nit（小问题）/ Optional（可选）/ FYI（参考）/ Praise（表扬）
• 拆分策略：按功能/按层/按文件拆分 + 先重构后功能 + 确保子 PR 独立可编译可测试
• 审查报告输出：总体评估 + 五维度评分（0-10）+ 问题清单 + 改进建议 + 亮点表扬

适用场景

不适用于：

• 自动化静态分析（用 ESLint/SonarQube/Snyk 等工具）
• 安全渗透测试（属专业安全审计）
• 性能基准测试（属性能测试工具，如 JMeter/k6）
• 代码风格格式化（用 Prettier/Black 等工具自动处理）

使用流程

Step 1: 获取变更概览

• 执行 git diff 或读取 PR diff
• 统计变更规模：新增行数 / 删除行数 / 涉及文件数
• 变更尺寸评估：
  • 理想：~100 行（易审查、易回滚）
  • 可接受：100-300 行（需分段审查）
  • 需拆分：> 300 行（建议拆分为多个 PR）
• 变更分类：新功能 / Bug 修复 / 重构 / 配置 / 文档

Step 2: 五维度审查

维度一：正确性

• 逻辑是否正确实现需求
• 边界条件是否处理（空值/零值/极值/并发）
• 错误处理是否完整（异常捕获/错误传播/降级）
• 是否引入回归

维度二：可维护性

• 命名是否清晰表达意图
• 函数/类职责是否单一
• 是否存在重复代码（应抽象）
• 复杂度是否可控（圈复杂度 < 10）
• 注释是否解释"为什么"而非"是什么"

维度三：安全性

• 输入是否校验（防注入/XSS）
• 权限检查是否到位
• 密钥/凭证是否泄露
• 依赖是否有已知漏洞
• 是否遵循最小权限原则

维度四：性能

• 是否有不必要的计算/查询
• N+1 查询问题
• 内存泄漏风险
• 大数据集处理是否分页/流式
• 是否阻塞主线程/事件循环

维度五：可测试性

• 是否有对应的测试
• 测试是否覆盖关键路径
• 是否易于编写测试（依赖注入/可 mock）
• 测试是否快速且稳定

Step 3: 标注严重度

• Blocking：必须修复才能合并（安全漏洞/逻辑错误/数据丢失风险）
• Should Fix：强烈建议修复（性能问题/边界缺失/可维护性差）
• Nit：吹毛求疵的小问题（命名偏好/格式微调）
• Optional：可选的改进建议（重构建议/优化方向）
• FYI：仅供参考的信息（相关知识/未来注意）
• Praise：值得表扬的写法（优秀设计/清晰注释）

Step 4: 拆分策略（当变更过大时）

• 按功能拆分：一个 PR 一个功能点
• 按层拆分：数据层/业务层/接口层分开
• 按文件拆分：独立文件变更独立 PR
• 先重构后功能：重构 PR 先合并，再提功能 PR
• 拆分顺序：确保每个子 PR 独立可编译可测试

Step 5: 输出审查报告

• 总体评估：Approve / Request Changes / Needs Discussion
• 五维度评分：每维度 0-10 分
• 问题清单：按严重度排序
• 改进建议：具体可执行的修改建议
• 亮点表扬：值得学习的优秀写法

示例

示例 1：用户注册功能 PR 审查

输入：

PR: 添加用户注册功能
变更：+180 行 / -5 行 / 3 文件
文件：
  - src/auth/register.ts (新增注册逻辑)
  - src/api/routes.ts (添加 POST /register 路由)
  - src/db/users.ts (添加 createUser 方法)

输出：

# 代码审查报告：用户注册功能

## 总体评估：Request Changes
- 变更尺寸：180 行（可接受）
- 五维度评分：正确性 7/10 | 可维护性 8/10 | 安全性 4/10 | 性能 7/10 | 可测试性 3/10

## 问题清单（按严重度排序）

### Blocking（必须修复）

**[B1] 密码明文存储**
- 文件：`src/db/users.ts:15`
- 问题：`createUser` 直接将密码存入数据库，未哈希
- 风险：数据库泄露后所有密码暴露
- 建议：使用 argon2 哈希后再存储
```typescript
import argon2 from 'argon2';
const hashedPassword = await argon2.hash(password);
// 存储 hashedPassword 而非 password

[B2] 缺少输入校验

• 文件：src/auth/register.ts:8
• 问题：未校验 email 格式和 password 强度
• 风险：脏数据入库 + 弱密码风险
• 建议：使用 zod/joi 校验

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8).regex(/[A-Z]/).regex(/[0-9]/),
});

Should Fix（强烈建议修复）

[S1] 缺少速率限制

• 文件：src/api/routes.ts:45
• 问题：注册接口无速率限制，可被暴力注册
• 建议：添加 IP 级速率限制（5 次/15 分钟）

[S2] 缺少单元测试

• 文件：无
• 问题：注册逻辑无测试覆盖
• 建议：补充测试用例（正常注册/重复邮箱/弱密码/无效邮箱）

Praise（值得表扬）

[P1] 错误处理清晰

• 文件：src/auth/register.ts:25
• 表扬：错误分类明确（VALIDATION_FAILED/EMAIL_EXISTS），包含 requestId，便于排查

### 示例 2：大 PR 拆分建议

**输入**：

PR: 重构用户模块 + 添加 OAuth 登录 + 修改数据库 Schema 变更：+850 行 / -320 行 / 18 文件

**输出**：
```markdown
# 拆分建议

## 评估
- 变更尺寸：850 行（需拆分）
- 涉及多个独立功能，建议拆分为 4 个 PR

## 拆分方案

### PR 1: 数据库 Schema 变更（独立先合并）
- 文件：`src/db/schema.ts`, `migrations/001_users_oauth.sql`
- 行数：~80 行
- 说明：纯 Schema 变更，向后兼容（新增字段），可独立合并

### PR 2: 重构用户模块（依赖 PR 1）
- 文件：`src/db/users.ts`, `src/auth/user-service.ts`
- 行数：~250 行
- 说明：提取 UserService，为 OAuth 做准备，无功能变更

### PR 3: OAuth 登录功能（依赖 PR 2）
- 文件：`src/auth/oauth.ts`, `src/api/routes.ts`
- 行数：~300 行
- 说明：核心功能 PR，添加 Google/GitHub OAuth

### PR 4: 测试与文档（依赖 PR 3）
- 文件：`tests/auth.test.ts`, `docs/oauth.md`
- 行数：~220 行
- 说明：补充测试用例与 OAuth 接入文档

## 合并顺序
PR 1 → PR 2 → PR 3 → PR 4
每个 PR 独立可编译可测试，降低审查难度与回滚风险。

错误处理

依赖说明

运行环境

• Agent 平台：Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持 SKILL.md 的任意 Agent
• 操作系统：Windows / macOS / Linux
• 运行时：需要 Agent 支持 exec（命令行执行）能力（执行 git diff）

依赖项

API Key 配置

• 本 Skill 无需额外 API Key 配置
• 代码审查由 Agent LLM 完成，API Key 由 Agent 平台托管
• 若集成 GitHub/GitLab API（可选），Token 通过环境变量注入，Skill 内零硬编码

可用性分类

• 分类：MD + EXEC
• 说明：纯 Markdown 方法论，需要 exec 能力执行 git diff 获取变更，审查本身由 Agent LLM 完成

常见问题

Q1: 代码审查哨兵与 ESLint/SonarQube 有何区别？

A: ESLint/SonarQube 是自动化静态分析工具，基于规则匹配发现已知模式问题（如未使用变量、复杂度过高）。代码审查哨兵是LLM 驱动的语义审查，能理解业务逻辑、跨文件上下文、设计意图。两者互补：静态分析快速拦截常见问题，哨兵深入审查语义与架构。

Q2: 审查标准是否过于严格？

A: 标准可配置。Blocking 仅针对"必须修复才能合并"的问题（安全漏洞/逻辑错误/数据丢失）。Should Fix 是建议，不阻塞合并。Nit 是小问题，可选修复。团队可根据成熟度调整阈值。

Q3: 如何避免审查中的"误报"？

A: 所有问题标注依据（代码行/风险说明/建议方案）。作者可对问题回复"需讨论"或"误报"，审查者确认后调整。LLM 不确定时标注"需人工确认"，避免过度自信。

Q4: 大 PR（> 500 行）如何高效审查？

A: 1）先看变更概览与尺寸评估；2）优先审查 Blocking 问题；3）按文件/模块分段审查；4）提供拆分建议（如示例 2）；5）异步输出完整报告，避免阻塞。

已知限制

• 依赖 LLM 能力，复杂业务逻辑理解可能不如领域专家深入
• 无法执行代码运行时验证（如实际测试、性能基准），仅静态审查
• 跨仓库依赖分析能力有限（仅审查当前 diff，不追踪外部依赖变更）
• 性能取决于底层 LLM，大 PR 审查可能耗时较长
• 不替代人工审查的"经验判断"（如架构合理性、产品需求匹配度）

安全

• API Key 零暴露：本 Skill 不涉及外部 API 调用，无需配置密钥
• 密钥泄露检测：审查时强制检查代码中是否硬编码密钥/令牌/凭证
• 最小权限原则：审查代码是否遵循最小权限（如数据库用户、API 角色）
• 输入校验检查：强制审查输入校验（防 SQL 注入/XSS/CSRF）
• 依赖漏洞扫描：提醒检查依赖是否有已知 CVE（建议配合 Snyk/Dependabot）
• 敏感信息提醒：审查时如发现敏感信息（密钥/客户数据），提醒立即移除并轮换