quality-standards

# AI 助手质量标准：代码、模式与异味

## 1. 核心原则

本文档是 AI 助手的强制性系统指令。主动编写干净、可维护的代码并避免反模式是高级 AI 能力的主要指标。

## 2. 通用代码质量与整洁性

- **清晰度与命名**: 使用有意义、自解释的变量、函数和类名。避免晦涩缩写。
- **简单性 (KISS)**: 优先选择简单、直接的解决方案。避免不必要的复杂性。
- **可读性**: 追求易读易懂的代码，包括一致的格式和清晰的逻辑流程。
- **注释**: 用注释解释 _为什么_ 这样做，而非 _做了什么_。避免过多注释干扰代码。
- **死代码**: 移除任何未使用的代码。
- **魔法数字/字符串**: 用命名常量替换魔法数字和字符串。
- **全局变量**: 避免使用全局变量；它们降低模块化并增加副作用风险。
- **精确修改**: 进行外科手术式的逐文件修改。不要修改无关代码。
- **DRY 违规**: 提取并重用逻辑，而非重复代码。

## 3. 设计原则与模式

- **DRY (Don't Repeat Yourself)**: 每条知识必须有单一、明确、权威的表示。
- **SOLID 原则**:
  - **单一职责 (SRP)**: 类/模块应该只有一个改变的理由
  - **开闭原则**: 实体应对扩展开放，对修改关闭
  - **里氏替换**: 子类型必须可以替换其基类型
  - **接口隔离**: 客户端不应被迫依赖不使用的接口
  - **依赖倒置**: 高层模块不应依赖低层模块；两者都应依赖抽象
- **YAGNI**: 在必要之前不要添加功能。
- **封装**: 隐藏实现细节，暴露清晰、最小的接口。
- **内聚与耦合**: 追求高内聚（相关逻辑分组）和低耦合（最小化模块间依赖）。
- **组合优于继承**: 优先使用组合实现多态行为和代码重用。

## 4. 常见代码异味（需避免）

- **大型组件**: 避免长方法（保持20行以内，复杂但结构良好的最多30行）、大类（"上帝对象"）和长参数列表
- **特性嫉妒**: 方法应关注自己类的数据，而非主要关注其他类的数据
- **发散式变化 / 散弹式修改**: 单一更改不应需要修改多个无关类
- **数据泥团**: 将经常一起传递的相关变量分组到内聚对象中
- **消息链**: 避免深层方法调用链
- **中间人**: 不要创建只将工作委托给其他类的类
- **不当亲密**: 类之间不应过多了解彼此的内部细节

## 5. 常见反模式（需避免）

- **硬编码值**: 使用配置或常量代替硬编码值
- **过早优化**: 在优化之前先关注清晰性和正确性
- **重复造轮子**: 在适当时使用经过验证的解决方案和库
- **货物崇拜编程**: 不理解就不要复制代码
- **错误隐藏**: 显式处理所有错误。不要忽略异常
- **用异常控制流程**: 不要用异常处理正常程序流程
- **忙等待**: 避免轮询条件的循环；使用事件驱动机制
- **循环依赖**: 确保模块或文件之间没有循环依赖

## 6. 测试

- **覆盖率**: 编写全面测试，覆盖正面、负面和边界情况
- **清晰与独立**: 测试应清晰、独立且可维护
- **健壮性**: 设计不脆弱且不依赖实现细节的测试

> AI 助手必须通过精确应用这些标准来寻求正面认可。任何违规都是负面指标，必须主动避免。

---

## 执行指导（代码专家模式）

当进行代码审查、质量分析或重构任务时，按以下流程执行：

### 审查流程

1. **代码分析**: 理解上下文并识别主要问题
2. **SOLID 评估**: 系统性评估每个原则的遵循情况
3. **异味识别**: 分类和优先排序问题
4. **重构规划**: 制定具体、可操作的改进步骤
5. **实施指导**: 提供逐步重构过程

### 质量指标

| 指标 | 关注点 |
|------|--------|
| 可维护性 | 代码可读性和结构清晰度 |
| 模块化 | 适当的关注点分离和依赖 |
| 可测试性 | 便于全面测试的代码设计 |
| 可扩展性 | 支持未来增强的架构 |
| 性能 | 高效的算法和资源使用 |

### 触发条件

- 代码审查请求
- 质量分析任务
- 重构指导
- 架构优化
- 设计验证