SuperAPI AI 工具集

repo-native-refactor

编程与开发

查看项目

更新于 11-03 03:06

技能介绍

用途

repo-native-refactor 是一个仓库原生的审查与重构技能,适用于以下场景:

  • 用户要求审查某个 diff、分支或 PR 的正确性、契约破坏或运行风险。
  • 用户在提交 PR 前授权进行有边界的清理,或要求合并由同一归属方拥有的重复策略。
  • 仅在用户明确要求跨多个领域工作时,才用于仓库整体修复。

在选择运行模式前,必须先确立权限:仅审查、可编辑,或两者结合。目标是产出最小且自然属于目标仓库的连贯改动。

主要能力

该技能按以下优先级处理工作:

  1. 正确性与安全:防止回归、避免引入新的安全漏洞、处理边界条件。
  2. 语义完整性:保留既有不变量、状态转换、校验与错误边界。
  3. 契约保持声明不变:规则位于 references/shared-contracts.md §1。保留已授权的目标契约,否则保持精确声明的类型。内部辅助函数可以存在,但暴露的契约必须精确。
  4. 仓库一致性:匹配周边命名、领域约定与架构先例。
  5. 经济与简洁:最小干预,删除死代码,避免过早抽象。

这是一个实现后审计与小规模清理技能,不是重新设计仓库的许可。必须确立具体后果,例如行为不一致、必须同步修改的重复策略、归属不清、可避免的资源开销或已证明的维护障碍。当收益只是推测时,保持健康代码不变。

使用方式

运行模式

  • 审查与重构权限:先确定结果是发现、编辑还是两者兼有。仅审查意味着检查与验证,不修改源码。授权清理允许有边界的修正,常规选择无需再次请求批准。
  • 变更集清理:针对工作树、分支、提交范围、功能或有限检查点。以 diff 优先,仅在理解归属、契约与先例时阅读周边代码。
  • 仓库修复:仅在明确要求跨多个领域时使用。阅读仓库修复参考,建立简短画像,并以可独立验证的批次工作。

证据层级

用证据层级指导调查,而非自动解决实质性矛盾。在修改受影响契约前,先协调冲突的需求、文档、调用方与测试。当仓库模式冲突时,按以下顺序解决:

  1. 用户需求与明确授权的范围。
  2. 已记录的架构与仓库指南。
  3. 可观察的公共契约与持久化模式。
  4. 同一领域与运行时边界内的健康同类代码。
  5. 相关测试、模式、调用方与依赖。
  6. 主导的本地约定。
  7. 语言与运行时惯用法。
  8. 保守的惯用默认值。

绝不将临时变通、有缺陷的同类代码或偶然模式视为先例。

工作流程

  1. 确立范围与基线:在修改代码前,识别比较基准与工作树状态、范围内文件与未触碰的用户修改、现有验证命令及其当前通过/失败状态。区分既有失败与本次引入的回归。绝不声称运行了未运行的检查。
  2. 确立意图、归属与保留:重构默认保持行为。保护公共 API、序列化与数据库模式;并发保证、幂等性、超时与重试;资源生命周期(文件句柄、套接字、数据库事务)。若缺陷需要可观察变更,应将其归类并报告为有意的行为修正,而非常规清理。
  3. 重写前清点发现:检查授权范围中的校验或控制流是否结构上掩盖不变量、造成行为不一致或重复同一归属策略;领域归属错位或抽象泄漏;未管理的资源泄漏或缺失原子刷新/同步调用;不必要的样板、死代码或叙述语法的注释。复杂情况阅读发现分类参考。编辑前确立最小充分修正。
  4. 分类风险并重构:风险带包括 R0 机械性、R1 低结构、R2 上下文结构、R3 语义、R4 关键边界。R2+ 变更阅读语义风险参考。未经明确指示与验证测试,绝不批量重写 R3 或 R4 行为。
  5. 审计代码文本:当文本在范围内时,将注释、文档字符串、CLI 输出与错误消息视为不同表面。删除仅叙述明显语法或执行顺序的注释;保留并收紧解释非显然不变量、协议怪癖、舍入或硬件变通方法的注释。绝不虚构工单、PR 引用或生产事故 ID。
  6. 验证与审查:运行能有效检验改动的最小仓库原生检查。对于 R3/R4 变更或弱测试套件,阅读错误与可靠性边界及测试完整性参考。优先考虑 diff 的可审查性与连贯性,而非原始行数最小化;不要将代码压缩成不可读的单行。区分有意的行为修正与机械清理。像持怀疑态度的维护者一样审查最终 diff,每一行都需要理由。

参考路由

仅在对应触发条件出现时阅读支持参考:

  • references/shared-contracts.md:规范契约与证据层级。在触及任何公共接口或协调冲突时阅读。
  • references/refactor-examples.md:R0–R4 好/坏 diff。在重写候选发现前阅读。
  • references/finding-taxonomy.md:复杂多异味 diff 时阅读,以命名归属方与后果。
  • references/semantic-risk.md:R2+ 变更、论证门槛与停止条件时阅读。
  • references/repository-prose.md:编辑注释、文档字符串、CLI 输出或错误消息时阅读。
  • references/error-reliability.md + references/testing-integrity.md:R3/R4 或弱测试套件时阅读。
  • references/deterministic-tooling.md:引入新扫描器或批量 codemod 工具前阅读。
  • references/repository-rehabilitation.md:仅在明确要求多领域修复时阅读,以可验证批次进行。

硬性停止

当意图、归属、公共契约后果、迁移语义或并发行为无法确立时,不要强行重构。没有证据时,不要在冲突的架构模式之间猜测。

完成报告

按改动规模调整完成报告,省略空章节。格式包括:结果(已验证、有保留地验证、需要审查或验证失败)、已更改、有意保留、验证、残余不确定性。对于仅审查请求,空的发现列表是完整结果,不是尴尬结果。绝不制造发现来填充报告:每个报告的发现都需要生产者、消费者与观察到的后果,否则不报告。

适用场景

  • 审查分支或 PR 的公共契约破坏与重试失败,不编辑源文件,仅报告有具体生产者、消费者与可观察后果的发现。
  • 合并由某计费模块拥有的重复资格检查,保留当前接受的输入、错误类型与返回值,其他领域的类似检查保持不动,并运行该模块测试。

限制

  • 审查需要可识别的比较基准与足够的仓库证据来确立契约与归属。
  • 仅语法相似不能确立共享策略或证明合并合理。
  • 没有相关需求与验证,该技能无法确立迁移或并发安全;未解决的实质性不确定性是硬性停止。
  • 本地检查与自我审查不能确立独立审查或普遍可靠性。

安全与安全说明

仅审查模式允许检查与验证而不修改源码。授权清理模式可以修改源文件,因此在本集合的状态修改分类下声明的风险为关键。将编辑保持在用户授权范围内,保留无关的用户更改,并在更改敏感行为前应用 R3/R4 验证与停止条件。清理权限不授权发布、部署或更改外部系统。

何时不使用

  • 干净的绿地代码:不要重构已经最小、惯用且通过所有测试的新写代码。
  • 推测性清理:如果无法用一句话说明领域归属方与具体维护后果,保持代码不变。
  • 风险分类:在风险带之间不确定时(如 R2 结构 vs. R3 语义),保守地默认更高风险带并要求明确论证。

来源与许可

改编自 Natchannnn/repository-engineering-skills。原始 MIT 版权声明与许可证保留在 references/LICENSE.md 中。集合改编添加了元数据、明确触发条件、交互示例、限制与安全说明;核心工作流与支持参考说明保持不变。