# GitHub Copilot Code Review 指导

## 基础规则

1. Code Review 评论内容请使用中文
2. 专注于提供有价值、可操作的建议，避免指出显而易见的问题

## CR 优先级框架

### 🔴 高优先级（必须评论）

- **安全问题**：输入验证、SQL 注入、XSS、权限控制等
- **性能问题**：算法复杂度过高、内存泄漏、不必要的循环等
- **关键逻辑错误**：业务逻辑缺陷、边界条件处理不当
- **架构一致性**：违反项目架构模式、模块职责不清
- **TypeScript 类型安全**：类型滥用、any 类型的不当使用

### 🟡 中优先级（建议评论）

- **API 设计**：接口一致性、参数设计、返回值结构
- **错误处理**：异常处理不完整、错误信息不清晰
- **代码可读性**：复杂的业务逻辑需要更好的注释或重构
- **测试质量**：测试覆盖率不足、测试用例设计不合理

### 🟢 低优先级（避免评论）

- **格式问题**：缩进、空格、换行等（应由自动化工具处理）
- **命名风格**：除非严重影响理解
- **个人编码偏好**：不影响功能实现的习惯性写法

## 项目特定指导

### MCP 协议实现

- 关注 MCP 消息处理的正确性和完整性
- 检查传输适配器的错误处理和重连机制
- 验证工具调用和资源管理的生命周期

### TypeScript 最佳实践

- 优先使用具体的类型而非 `any`
- 鼓励使用类型推导和泛型
- 检查接口设计的一致性和向后兼容性

### 模块化架构

- 验证模块间的依赖关系是否合理
- 检查单一职责原则的遵循
- 确保依赖注入容器的正确使用

### 测试策略

- 重点检查集成测试和端到端测试
- 验证异步代码的正确测试
- 关注测试的可维护性和可读性

## 评论质量标准

### ✅ 好的评论应该

1. **解释原因**：说明为什么需要这个改动
2. **提供方案**：给出具体的修改建议
3. **考虑影响**：说明改动可能对其他部分的影响
4. **示例代码**：在需要时提供代码示例

### ❌ 避免的评论类型

1. **仅指出问题**："这里有问题"、"这样不好"
2. **模糊建议**："建议重构"、"优化一下"
3. **过度建议**：针对边缘案例的过度设计
4. **风格偏好**：个人习惯相关的评论

## 评审结论指引

### ✅ 评审通过

如果代码没有明显问题，符合项目要求，在 PR 中显著地用中文评论：

```
## ✅ 代码评审通过，允许合并

代码改动符合项目要求，可以合并。
```

### 评审通过的标准

- 代码功能正确，无明显 bug
- 符合项目的代码风格和质量要求
- 无高优先级或中优先级的安全问题
- 错误处理完善
- 测试覆盖合理

## 技术债务关注点

### 可维护性

- 代码重复
- 过长的函数或类
- 深层嵌套的复杂逻辑

### 可扩展性

- 硬编码的配置和常量
- 缺乏抽象的重复代码
- 紧耦合的组件设计

### 可测试性

- 难以测试的代码结构
- 过多的外部依赖
- 缺乏依赖注入

## 具体示例

### 好的评论示例

````
🔴 **安全问题**：这个函数直接使用用户输入构建 SQL 查询，存在 SQL 注入风险。

建议：使用参数化查询或 ORM 的查询构建器来避免 SQL 注入。

```typescript
// 当前代码（不安全）
const query = `SELECT * FROM users WHERE name = '${userName}'`;

// 建议改为
const query = 'SELECT * FROM users WHERE name = ?';
db.query(query, [userName]);
````

```

### 应该避免的评论
```

❌ "这个函数太长了"（没有具体建议）
❌ "变量名应该用 camelCase"（自动化工具应处理）
❌ "建议用 async/await"（没有说明具体收益）

```

## 上下文理解

1. **理解改动目的**：在评论前先理解这个 PR 的目标
2. **考虑整体影响**：不要只关注局部代码片段
3. **平衡建议**：在完美主义和实用性之间找到平衡
4. **尊重设计决策**：除非有明确问题，否则尊重现有的架构选择

## CR 范围控制

### 聚焦 PR 本身改动

- **专注于 PR 改动范围**：只分析本次 PR 修改的代码，不要扩大审查范围到未改动的代码
- **只分析改动本身**：评估改动代码本身是否有需要改进的地方
- **关注必要的潜在问题**：识别真正影响功能和安全的问题，避免过度延伸
- **不审查历史代码**：不要借机审查 PR 范围之外的代码，即使发现问题也只提醒不强制要求修复

### 范围控制原则

- 如果发现 PR 之外的代码有问题，可以简单提及但不应作为评审重点
- 不要求 PR 作者在当前改动中解决所有历史技术债务
- 保持评审焦点在本次改动的质量和正确性上

## 务实开发原则

### 核心原则

- **如无必要勿增实体**：需要什么功能就实现什么功能
- **功能驱动**：优先解决实际问题，不过度设计
- **优雅实现**：代码清晰、可维护、结构合理
- **避免过度设计**：
  - 不要为了"未来可能需要"而增加复杂度
  - 不要为了理论完美而过度抽象
  - 不要在没有性能问题时优化性能
  - 不要为了使用设计模式而使用

### 何时考虑复杂设计

- 实际遇到问题时
- 功能明确需要时
- 代码确实难以维护时
- 团队协作需要统一接口时

### CR 中的务实原则

- 评估代码是否增加了不必要的复杂性
- 验证功能实现是否符合"如无必要勿增实体"
- 确保代码优雅但不过度设计
- 验证架构合理性但不冗余
- 避免要求添加"未来可能用到"的功能

通过遵循这些指导，Copilot 将提供更有价值、更符合人类标准的 Code Review。
```