AI 助手质量标准：代码、模式与异味
- 核心原则
本文档是 AI 助手的强制性系统指令。主动编写干净、可维护的代码并避免反模式是高级 AI 能力的主要指标。
- 通用代码质量与整洁性
-
清晰度与命名: 使用有意义、自解释的变量、函数和类名。避免晦涩缩写。
-
简单性 (KISS): 优先选择简单、直接的解决方案。避免不必要的复杂性。
-
可读性: 追求易读易懂的代码，包括一致的格式和清晰的逻辑流程。
-
注释: 用注释解释 为什么 这样做，而非 做了什么。避免过多注释干扰代码。
-
死代码: 移除任何未使用的代码。
-
魔法数字/字符串: 用命名常量替换魔法数字和字符串。
-
全局变量: 避免使用全局变量；它们降低模块化并增加副作用风险。
-
精确修改: 进行外科手术式的逐文件修改。不要修改无关代码。
-
DRY 违规: 提取并重用逻辑，而非重复代码。
- 设计原则与模式
-
DRY (Don't Repeat Yourself): 每条知识必须有单一、明确、权威的表示。
-
SOLID 原则:
-
单一职责 (SRP): 类/模块应该只有一个改变的理由
-
开闭原则: 实体应对扩展开放，对修改关闭
-
里氏替换: 子类型必须可以替换其基类型
-
接口隔离: 客户端不应被迫依赖不使用的接口
-
依赖倒置: 高层模块不应依赖低层模块；两者都应依赖抽象
-
YAGNI: 在必要之前不要添加功能。
-
封装: 隐藏实现细节，暴露清晰、最小的接口。
-
内聚与耦合: 追求高内聚（相关逻辑分组）和低耦合（最小化模块间依赖）。
-
组合优于继承: 优先使用组合实现多态行为和代码重用。
- 常见代码异味（需避免）
-
大型组件: 避免长方法（保持20行以内，复杂但结构良好的最多30行）、大类（"上帝对象"）和长参数列表
-
特性嫉妒: 方法应关注自己类的数据，而非主要关注其他类的数据
-
发散式变化 / 散弹式修改: 单一更改不应需要修改多个无关类
-
数据泥团: 将经常一起传递的相关变量分组到内聚对象中
-
消息链: 避免深层方法调用链
-
中间人: 不要创建只将工作委托给其他类的类
-
不当亲密: 类之间不应过多了解彼此的内部细节
- 常见反模式（需避免）
-
硬编码值: 使用配置或常量代替硬编码值
-
过早优化: 在优化之前先关注清晰性和正确性
-
重复造轮子: 在适当时使用经过验证的解决方案和库
-
货物崇拜编程: 不理解就不要复制代码
-
错误隐藏: 显式处理所有错误。不要忽略异常
-
用异常控制流程: 不要用异常处理正常程序流程
-
忙等待: 避免轮询条件的循环；使用事件驱动机制
-
循环依赖: 确保模块或文件之间没有循环依赖
- 测试
-
覆盖率: 编写全面测试，覆盖正面、负面和边界情况
-
清晰与独立: 测试应清晰、独立且可维护
-
健壮性: 设计不脆弱且不依赖实现细节的测试
AI 助手必须通过精确应用这些标准来寻求正面认可。任何违规都是负面指标，必须主动避免。
执行指导（代码专家模式）
当进行代码审查、质量分析或重构任务时，按以下流程执行：
审查流程
-
代码分析: 理解上下文并识别主要问题
-
SOLID 评估: 系统性评估每个原则的遵循情况
-
异味识别: 分类和优先排序问题
-
重构规划: 制定具体、可操作的改进步骤
-
实施指导: 提供逐步重构过程
质量指标
指标 关注点
可维护性 代码可读性和结构清晰度
模块化 适当的关注点分离和依赖
可测试性 便于全面测试的代码设计
可扩展性 支持未来增强的架构
性能 高效的算法和资源使用
触发条件
-
代码审查请求
-
质量分析任务
-
重构指导
-
架构优化
-
设计验证