SuperAPI AI 工具集

speckit-review-types

编程与开发

查看项目

更新于 10-16 06:37

技能介绍

用途

speckit-review-types 是一个类型设计分析技能,扮演类型设计专家的角色,专注于分析和改进类型设计,使类型具备强健、表达清晰且封装良好的不变量。其核心理念是:设计良好的类型是易维护、抗缺陷软件系统的基础。

主要能力

该技能围绕四个维度对类型进行评估,并给出 1-10 的评分与理由:

  • 封装性(Encapsulation):内部实现细节是否被恰当隐藏、不变量能否从外部被破坏、访问修饰符是否合适、接口是否最小且完整。
  • 不变量表达(Invariant Expression):不变量是否通过类型结构清晰传达、能否尽可能在编译期强制、类型是否通过设计自文档化、边界情况与约束是否从类型定义中显而易见。
  • 不变量实用性(Invariant Usefulness):不变量是否能防止真实缺陷、是否与业务需求一致、是否让代码更易推理、是否既不过于严格也不过于宽松。
  • 不变量执行(Invariant Enforcement):不变量是否在构造时检查、所有变更点是否受保护、是否无法创建非法实例、运行期检查是否恰当且全面。

分析时首先识别类型中的隐式与显式不变量,包括数据一致性要求、有效状态转换、字段间关系约束、类型中编码的业务规则、前置与后置条件。

使用方式

技能会按固定结构输出分析结果:以 ## Type: [TypeName] 开头,依次列出识别到的不变量、四项评分及理由、优势、关注点、推荐改进。

在确定需要分析的变更文件时:

  • 若用户提供了文件列表或明确的文件获取指令(例如仅暂存、仅未暂存、特定文件夹等),直接遵循该指令。
  • 否则,必须执行 .specify/scripts/bash/detect-changed-files.sh 并带 --json 参数来检测变更文件。不得通过直接运行 git 命令、手动读取 git 状态或任何其他方式检测变更,始终委托给该脚本。

该脚本会自动选择最佳检测模式:

  • 模式 A(特性分支):从合并基点将当前分支与默认分支(main/master)进行差异比较,并加上任何暂存和未暂存的改动。
  • 模式 B(工作目录):当没有特性分支时(例如直接在默认分支上工作),回退到暂存 + 未暂存的改动。

JSON 输出格式为:{"branch", "default_branch", "mode", "changed_files": [...]}。

注意:包含该脚本的文件夹可能被排除在版本控制之外或被搜索索引隐藏,但仍必须定位并执行它,不得跳过或用自定义的文件检测逻辑替代。

适用场景

适用于对代码库中的类型设计进行审查与改进,尤其是需要评估不变量强度、封装质量与实用价值的场景,帮助构建健壮、清晰、可维护且不引入不必要复杂度的类型。

关键原则与限制

关键原则包括:在可行时优先使用编译期保证而非运行期检查;重视清晰与表达力而非取巧;考虑建议改进带来的维护负担;认识到完美是好的敌人,提出务实的改进;类型应让非法状态不可表示;构造器验证对维护不变量至关重要;不可变性通常简化不变量的维护。

会标记的常见反模式包括:没有行为的贫血领域模型、暴露可变内部状态的类型、仅通过文档强制的不变量、职责过多的类型、构造边界缺少验证、各变更方法之间执行不一致、依赖外部代码维护不变量的类型。

提出改进时需始终考虑:建议的复杂度成本、改进是否值得潜在的破坏性变更、现有代码库的技能水平与约定、额外验证的性能影响、安全性与可用性之间的平衡。

关于收费、价格、平台支持等具体信息,资料中暂未提供。