SuperAPI AI 工具集

legacy-code-protocol

编程与开发

查看项目

更新于 11-11 21:26

技能介绍

Legacy Code Protocol 用于在遗留代码中安全开展工作的操作协议。这里的遗留代码指几乎没有测试的现有代码,或团队中无人理解的代码;无论代码写得多整洁,只要缺少测试,就无法判断改动是改善还是恶化,无人能理解的代码同样如此。它借鉴 Michael Feathers《Working Effectively with Legacy Code》的方法:先理解代码,固定其当前行为,再有意识地修改。核心矛盾是:安全修改代码需要测试,而引入测试往往又需要先改动代码。协议的解法是:在测试存在之前所做的每个编辑都保持小、机械且不改变行为;一旦某区域被固定,就转入常规的测试驱动开发流程。

主要能力

  • 六种模式,由请求内容选择并按其步骤执行:survey(勘察不熟悉区域或需先了解整体情况);plan(工作规模大于一次改动,需补测试后再修改、重构或拆分);pin(在升级、迁移、重写或交接前锁定行为);change(对无测试代码做一项具体改动);replace(旧代码被重写、新库或新服务取代);review(PR 或 diff 触及遗留代码)。模式可串联:survey 为 plan 提供输入,plan 的每一步以 pin、change 或 replace 执行;用户指定模式时按指定模式执行。若改动请求落在尚未勘察的代码上且涉及多个文件,应先运行 survey 并说明。
  • 工作文件:survey 和 plan 会在仓库根目录的 .legacy/ 下写入 Markdown 文件,如 .legacy/<area>-map.md 与 .legacy/<area>-plan.md,供后续模式与会话读取;启动前先读已有文件并更新而非重来。除非用户要求提交,否则保持未提交状态,可将 .legacy/ 加入 .git/info/exclude 以免被后续提交带入。
  • 文档提升:工作文件只是草稿;下一个代理无论承接什么任务都需要的事实应写入仓库文档。每种模式结束时都会把已核实的内容提升到文档,使每个遗留任务都让其区域更易于代理接手。优先使用仓库已有的文档布局;没有时可采用建议布局,例如区域架构说明写入 docs/architecture/<area>.md 并从 ARCHITECTURE.md 链接,业务工作流写入 docs/DOMAIN.md,已确定的领域术语写入 CONTEXT.md,测试方法写入 docs/guides/testing.md,古怪代码的原因和已固定的意外行为写入区域文档的“Known quirks”,并在 AGENTS.md 中各加一行指针。只提升经测试运行、代码或 git 历史确认的事实,推断性事实需标注为推断;疑似缺陷应写入工单或报告而非文档;仅限当前区域,全仓库脚手架应引导用户使用 agent-ready;文档改动先提议、经用户同意后再写,并单独提交。
  • 基线:所有运行测试的模式都从此开始:阅读仓库说明并找到测试命令,运行覆盖该区域的最小子集并记录结果。通过则继续;失败则列出编辑前就失败的测试并保持原样报告,若失败测试覆盖改动点则停下询问;不稳定测试需重跑识别并视同无覆盖;无可运行测试框架时,检查语言标准运行器可否使用,若仅需一个开发依赖和一个配置文件即可搭建则先向用户提议,否则停止询问,或使用 Sprout/Wrap 并说明宿主代码仍无测试覆盖。基线以命令名加失败与不稳定测试列表(或“无”)记录。
  • 测试前编辑规则:每次编辑只采用一种技术,依据症状从 references/symptoms.md 中选择并按 references/dependency-breaking.md 应用;保留签名,参数列表原样复制,代码移动用剪切粘贴而非重打;借助编译器、类型检查器或 linter 找出所有受影响位置,动态语言先搜索名称再运行代码;生产路径保留当前默认值,真实协作者仍是默认,接缝只增加替换途径;接缝不美观可以接受,测试建立后再清理。
  • 护栏:差异范围限于当前目标或计划单元(改动点、使其可测试的接缝和测试),其他清理工作列为后续事项,如格式化、重命名、风格、死代码、过时模式;固定并报告疑似缺陷,仅在用户要求时修复,因为调用方可能依赖该行为;将接缝、表征测试、实际改动、重构和文档分开提交,便于审查者确认前者保持行为;只对实际运行的测试声称覆盖,推断内容标注为推断。

使用方式:根据请求选择模式并打开其文件按步骤执行;先建立测试基线;按规则进行测试前编辑;模式之间通过工作文件和文档衔接。

适用场景:接手无测试或无人理解的代码库;升级、迁移、重写或交接前需要锁定行为;对遗留代码做单项改动;审查触及遗留代码的拉取请求。

限制:协议依赖项目存在或可搭建测试运行器,无框架时需用户决定;文档与提交需用户同意;不提供自动修复疑似缺陷;收费、平台等信息暂未提供。