SuperAPI AI 工具集

best-engineering-practice

编程与开发

查看项目

更新于 11-06 21:02

技能介绍

用途

best-engineering-practice 是一项跨领域的工程约束技能,适用于在规划、实现、调试、重构、测试或审查软件时使用。其目标是通过显式失败、简单归属、统一边界和可复现证据来产出正确的软件。技能要求在不与核心原则冲突的前提下,遵循仓库自身的约定。

主要能力

该技能的核心机制是按需加载参考资料,而不是一次性加载全部内容:

  • 每个任务都必须读取 references/core.md。
  • 架构指导仅在受影响的运行时下加载:涉及服务、处理器、worker、定时任务、CLI 进程、持久化、消息、外部集成或后端依赖方向时,读取 references/architecture/backend.md;涉及浏览器模块、UI、导航、表单、设计系统、客户端状态、无障碍、浏览器安全或客户端性能时,读取 references/architecture/frontend.md。
  • 仅当工作影响 HTTP 生命周期、浏览器-服务器交互、Web API、缓存、认证传输、上传、重定向、webhook 或 HTTP 中间件时,读取 references/protocols/http.md;设计或变更 REST/OpenAPI 契约时,还应使用 $best-openapi-design,由该技能负责资源建模和详细 REST 配置。
  • 验证指导按实际需要的证明加载:当生产行为、测试、契约、迁移、证明层选择或测试基础设施发生变化时,读取 references/verification/testing.md;当工作影响覆盖率策略、证明清单、原生报告、例外、架构强制、浏览器门禁或阻塞性 CI 策略时,读取 references/verification/quality-gates.md;当工作影响 HTTP 或 RPC 操作、仓库、外部适配器、缓存、队列消费者、迁移、认证、授权、服务生命周期、执行边界可观测性或后端依赖方向时,读取 references/verification/backend.md,并先加载测试和质量门禁;当工作影响浏览器路由、类型化传输、功能操作、表单、导航、浏览器状态、无障碍、安全、兼容性、性能、响应式行为、视觉质量或前端依赖方向时,读取 references/verification/frontend.md,并先加载测试和质量门禁。
  • 对于孤立的纯函数、文档、格式化或机械性变更,除非其边界或门禁确实受到影响,否则不加载运行时验证配置。对于垂直的全栈功能,加载两个架构配置、测试、适用的 HTTP 配置,以及仅由变更边界所需的运行时验证配置。

使用方式

技能要求保持用户请求的任务模式:

  • 对于规划、解释、诊断、检查或审查,保持只读,描述所需的变更、迁移、测试、门禁和未解决的决策。
  • 对于获得授权的构建、实现、修复或重构,在授权范围内执行以下工作流。可以在仓库中盘点等效的核心违规,但在变更该范围之外的实例之前,必须获得明确的仓库级迁移授权。

授权变更的执行流程分为四步:

  1. 建立结果与基线:阅读适用说明、受影响代码、测试、契约、发布历史和本地约定;识别可观察的结果、消费者、支持的发布基线、信任与数据边界,以及上述加载规则所需的参考资料;在变更接口或数据模型之前,解决难以逆转的歧义。
  2. 设计一个连贯的切片:选择最小的垂直行为切片;将每条规则放入其所属的领域模块,保持依赖和状态显式,并考虑受影响的契约、持久化数据、并发和兼容性;定义已纠正核心违规的结构签名,并在完整仓库中搜索等效实例;纠正授权范围并报告剩余清单;仅对明确授权的仓库级迁移要求零匹配结果。
  3. 以相称的证明实现:保持行为与证明在一起;对于 bug,首先创建能够变红的回归测试;使用能完整证明行为的最便宜的测试层,并在实际边界使用真实的集成语义;工作时运行聚焦检查,然后运行适用于变更范围的所有已配置门禁;绝不跳过或削弱门禁来制造成功。
  4. 审查并报告:使用核心原则对变更风险进行分类;对照请求和支持的契约审查结果,然后以风险相称的审查者独立性,对照已加载的参考资料和仓库标准审查工程实现;验证发现,分类其严重性和范围,解决范围内的阻塞性发现,并重新运行受影响的检查。

报告应包含:结果、重要决策、变更的契约、迁移、兼容性行为、验证命令与结果、发现的严重性与范围、未满足的门禁,以及未解决或已接受的风险。不得在没有证据的情况下声称成功。

适用场景

该技能适用于前端、后端等跨领域软件工程任务,包括规划、实现、调试、重构、测试和审查。它特别强调根据实际受影响的运行时和边界来加载对应的参考资料,因此既可用于单一领域的变更,也可用于垂直的全栈功能。

限制

技能本身未提供关于收费、价格、平台或具体效果的信息。其执行依赖于仓库中存在的 references/core.md 及各 references 子目录下的参考文件;若这些文件缺失,相关指导无法加载。技能要求不得跳过或削弱门禁,也不得在没有证据的情况下声称成功。对于授权范围之外的变更,需要明确的仓库级迁移授权。