SuperAPI AI 工具集

codebase-design

编程与开发

查看项目

更新于 10-16 04:58

技能介绍

用途:提供设计深模块(deep modules)的共享术语与原则。当用户想设计或改进模块接口、寻找深化机会、决定 seam 位置、让代码更可测试或更利于 AI 导航,或其它技能需要深模块词汇时使用。该技能从 mattpocock/skills(MIT)导入,上游为模型调用。

主要能力:用统一词汇描述模块设计。核心术语包括 Module(任何具有接口与实现的事物,刻意与规模无关)、Interface(调用者正确使用模块所需知道的一切,含类型签名、不变量、顺序约束、错误模式、必需配置与性能特征)、Implementation(模块内部代码)、Depth(接口处的杠杆,即调用者或测试每学习一单位接口可驱动的行为量)、Seam(可在不编辑该处的情况下改变行为的位置,即接口所在处)、Adapter(在 seam 处满足接口的具体事物)、Leverage(调用者从深度获得的收益)与 Locality(维护者从深度获得的收益)。深模块等于小接口加大实现,浅模块等于大接口加薄实现,应避免。设计接口时可自问:能否减少方法数量、简化参数、隐藏更多复杂度。

必要用法:原则包括——深度是接口属性而非实现属性;删除测试,若删除模块后复杂度消失则是直通,若复杂度在多个调用者中重现则模块有价值;接口即测试表面,调用者与测试跨越同一 seam;一个适配器只意味着假设的 seam,两个适配器才意味着真实的 seam,除非确实有变化否则不要引入 seam。可测试性方面:接受依赖而非创建依赖,例如 function processOrder(order, paymentGateway) {} 可测试,而内部 new StripeGateway() 难以测试;返回结果而非产生副作用,例如 function calculateDiscount(cart): Discount {} 可测试;保持小表面区域,方法越少测试越少,参数越少测试设置越简单。

适用场景与限制:适用于代码设计与重构时使用这套语言和原则。更深入内容参见 DEEPENING.md(依赖类别、seam 纪律、替换而非分层测试)与 DESIGN-IT-TWICE.md(用并行子代理从多个截然不同方向设计接口,再比较深度、局部性与 seam 位置)。建议先在一个狭窄范围应用本技能,确认输出符合所述形态后再扩大到完整任务。需要来自仓库或环境的事实时应自行查找而非询问用户。保持上游流程完整,明确记录偏离而非静默即兴;在技能标记为用户决策的每个点停下并交还控制权;偏好小型可逆变更,说明假设而非隐藏。限制:本文档未提供收费、价格、平台或具体安装命令等信息。