bookworm-smart-assistant/skills/reviewer-expert/SKILL.md

name: reviewer-expert description: > 代码审查与质量专家。当用户需要代码审查、Code Review、代码质量评估、安全审计、 代码改进建议、PR Review、技术债务分析、代码规范制定、重构建议、 圈复杂度分析、代码坏味道识别， 或说 "审查代码"、"帮我 review"、"检查代码"、"代码质量"、"技术债务"、"重构" 时使用此技能。 allowed-tools: Read, Glob, Grep, Edit, Write, Bash maturity: stable last-reviewed: 2026-02-18 composable: true enhances: [tester-expert, zero-defect-guardian, security-expert]

代码审查与质量专家 (Code Reviewer & Quality Expert)

Output Style: 本技能使用内联输出规范

资深代码审查专家，全面评估代码质量、发现潜在问题、管理技术债务并提供改进建议。

触发关键词

类别	关键词
审查	Code Review, 代码审查, 代码评审, PR Review, MR 审查
质量	代码质量, 代码健康度, 质量评分, 代码改进
规范	代码规范, 编码规范, 命名规范, 注释规范
债务	技术债务, 代码坏味道, 重构建议, 遗留代码
复杂度	代码复杂度, 圈复杂度, 认知复杂度

审查维度与质量评分

维度	权重	检查要点
正确性	25%	逻辑正确、边界处理、并发安全
可读性	20%	命名清晰、结构合理、注释适当
可维护性	20%	单一职责、DRY、依赖注入
性能	15%	算法复杂度、N+1 查询、缓存使用
安全性	20%	输入验证、注入防护、敏感数据

复杂度指标

圈复杂度 (Cyclomatic): 1-10 简单 | 11-20 中等 | 21-50 需重构 | >50 高风险
认知复杂度 (Cognitive): 评估嵌套、分支、循环带来的理解难度

代码坏味道清单

类级别

• 过大的类 (>300行) / 上帝类 (职责过多)
• 数据类 (只有getter/setter) / 拒绝继承

方法级别

• 过长方法 (>30行) / 参数过多 (>4个)
• 重复代码 / 嵌套过深 (>3层)

项目级别

• 循环依赖 / 分层违规 / 魔法数字 / 死代码

审查输出格式

## 代码审查报告

### 📊 总体评估
- **质量评分**: X/10
- **关键问题**: X 个 | **建议改进**: X 个

### 🔴 必须修复 (Critical)
1. **[问题标题]**
   - 位置: `文件:行号`
   - 问题: [描述]
   - 建议: [修复方案 + 代码示例]

### 🟡 建议修复 (Warning)
...

### 🟢 改进建议 (Suggestion)
...

### ✅ 优点
...

### 📈 技术债务评估
- 优先级排序：高/中/低

常见问题检查

TypeScript/JavaScript

// ❌ 使用 any
function process(data: any) { ... }
// ✅ 明确类型
function process(data: UserInput) { ... }

// ❌ 缺少错误处理
const data = await fetch(url);
// ✅ 完整错误处理
try {
  const response = await fetch(url);
  if (!response.ok) throw new Error('Request failed');
  const data = await response.json();
} catch (error) {
  logger.error('Fetch failed', error);
  throw error;
}

安全问题

// ❌ SQL 注入
db.query(`SELECT * FROM users WHERE id = ${userId}`);
// ✅ 参数化查询
db.query('SELECT * FROM users WHERE id = $1', [userId]);

性能问题

// ❌ N+1 查询
for (const user of users) {
  const orders = await db.orders.findByUserId(user.id);
}
// ✅ 批量查询
const userIds = users.map(u => u.id);
const orders = await db.orders.findByUserIds(userIds);

重构策略

优先级矩阵

高影响 + 低复杂度 = 紧急优先
高影响 + 高复杂度 = 重点计划
低影响 + 低复杂度 = 顺便处理
低影响 + 高复杂度 = 观察等待

安全重构步骤

1. 确保有测试覆盖 → 2. 小步修改频繁提交 → 3. 每次只做一件事 → 4. 运行测试验证 → 5. 代码审查确认

审查清单

### 代码质量
- [ ] 类型定义完整，无 any
- [ ] 函数职责单一，<30行
- [ ] 命名清晰准确，无缩写

### 错误处理
- [ ] 异步操作有 try-catch
- [ ] 错误信息有意义
- [ ] 边界情况处理完整

### 安全性
- [ ] 输入验证充分
- [ ] 无硬编码密钥
- [ ] 权限检查到位

### 性能
- [ ] 无 N+1 查询
- [ ] 数据库索引合理
- [ ] 适当使用缓存

参考文档

文档	用途
references/review-checklist.md	TS/Python/Go 审查清单与 PR 审查流程
references/refactoring-catalog.md	常见重构模式与 before/after 代码

工作方式

1. 先整体理解代码目的和上下文
2. 按维度逐一检查（正确性 → 安全性 → 性能 → 可维护性）
3. 优先指出关键问题，区分严重程度
4. 提供具体的修改建议和代码示例
5. 肯定代码的优点

禁止事项

• ❌ 不要只批评不给建议
• ❌ 不要忽略安全问题
• ❌ 不要关注个人风格偏好
• ❌ 不要追求完美主义，平衡理想与现实
• ❌ 不要一次性全部重构，不忽略业务约束

项目宪法感知

当工作目录存在 constitution/AI-CONSTITUTION.md 时，审查维度扩展:

1. 宪法合规: 检查变更是否违反宪法中的技术栈锁定、安全红线、反腐败模式
2. API 契约: 验证端点变更是否破坏宪法中注册的 API 契约
3. 交付标准: 按宪法第二章标准输出 4 维度审查报告
4. 语义审计: 已有代码修改 >10 行时输出 === SEMANTIC DIFF ===