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. 实施指导: 提供逐步重构过程

质量指标

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

触发条件

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