SuperAPI AI 工具集

code-guidelines

编程与开发

查看项目

更新于 10-23 16:45

技能介绍

用途

code-guidelines 是一套面向 AI 编码智能体的编码规范技能,目标是在生成、修改或评审代码时,统一应用可维护的编码标准,覆盖正确性、简洁性、一致性、设计、命名、抽象、控制流、复杂度与测试。所有规则均为强制性,需一起应用;当规则冲突时,按下列优先级顺序处理。

优先级

  1. 满足必需行为并保持正确性。
  2. 使用最少的概念与最少的间接层,同时保持清晰与正确。
  3. 最小化耦合,保持清晰的变更边界。
  4. 遵循代码库中既有的模式。

设计

  • 实现满足当前需求的最小完整设计。
  • 当重构能减少代码、简化设计或建立单一事实来源时,重构既有代码。
  • 移除过时代码、兼容层、不可达代码以及没有当前需求支撑的结构。
  • 使用直接、显式的代码。
  • 隔离副作用。
  • 始终使用单向数据流:数据向下,动作向上。
  • 派生值,而不是存储冗余状态。
  • 不要依赖隐藏的变更、隐式行为或调用顺序;通过参数与返回值表达依赖。
  • 让初始化、清理与取消显式化。
  • 只传递函数实际使用的值;不要传递宽泛的上下文对象。
  • 在系统边界将传输模型与持久化模型映射为内部类型;不要让可变 DTO 或 ORM 实体穿过内部逻辑。
  • 当既有辅助函数已实现所需行为时,复用它。
  • 按 API 的预期用途及其显式契约使用 API;不要利用内部时序、顺序或变更来让它适配其他目的。
  • 只实现当前需求;不要解决假设性问题。
  • 仅在需求、文档化行为、观察到的用法、生产证据或现实失败模式支持时,才处理某个边界情况。

命名与代码注释

  • 按业务或领域意图命名代码,而不是按操作命名。
  • 当条件组合多个条件或跨多行时,将其提取为具名布尔值。
  • 在将函数结果传给另一个函数之前,先赋值给具名变量。
  • 仅为代码无法表达的上下文、约束、假设或行为添加代码注释。
  • 当某个不变量无法从代码中明显看出时,添加代码注释说明它为何存在,以及若改变可能破坏什么行为。

抽象与重复

  • 不要创建投机性抽象、占位符或一次性提取。
  • 依据共享职责或行为来评估重复,而不仅仅是文本或结构上的相似。
  • 在两个实例出现之前不要创建共享抽象;两个实例触发评估,而不是自动抽象。
  • 仅当实例共享行为或职责且具有相同的变更原因时,才创建抽象。
  • 只抽象共享行为;不要耦合不相关的用例。

控制流与复杂度

  • 对无效或异常情况使用守卫子句;保持主路径扁平。
  • 不要使用依赖单独守卫的非空断言。在可空值自身的边界处校验并收窄它,使安全性在移动或移除其他代码后仍然成立。
  • 对非对称决策使用 if。
  • 对单一有限判别值上的对称情况使用 switch。
  • 当分支实现不同算法或具有独立变更原因时,使用多态或策略。
  • 当同一业务字段被反复分支判断时,先评估共享抽象,并在创建前应用重复规则。
  • 始终在系统边界校验并规范化外部数据。
  • 使用满足需求与预期数据规模的最简算法与控制流。
  • 没有具体需要时,不要添加抽象、间接层、状态或分支。
  • 当存在更低复杂度的方案满足需求时,不要对未明确界定规模的集合使用 O(n²) 操作。
  • 正则表达式处理使用 match() 或 matchAll()。
  • 不要使用依赖可变 lastIndex 的有状态正则迭代。

测试

  • 仅针对影响用户可见行为、公共契约、错误处理、诊断、必需边界情况或具有已知回归风险的逻辑的变更,添加或更新测试。
  • 使用聚焦的测试覆盖变更后的行为以及已记录或可达的失败模式。

适用场景

该技能适用于 AI 编码智能体在编写、修改或评审代码时统一执行编码标准,尤其适合需要控制复杂度、减少耦合、明确边界与变更原因、并保持测试聚焦的场景。

限制

资料未提供该技能的具体安装方式、支持平台、收费模式或价格信息,暂未提供。