“行为不变”要先说清楚哪些行为旧代码功能正常只是函数太长、命名难懂、重复判断越来越多。这时让 AI 帮忙整理很容易得到一份看起来更漂亮的代码。但代码变短了、分支变少了并不能说明重构成功。真正需要验收的是同样的输入在约定的运行条件下是否仍然产生同样的可观察结果。资料 S4《67个AI编程必会知识1.6w字一次讲透女友“你要考研啊”帮助开发者理解AI编程中的核心概念。文章详细解释了人 - 掘金》将重构解释为在不改变功能的前提下改进代码结构和质量。它列举了提取重复代码、改进命名、简化复杂逻辑、拆分过长文件等方式并建议让 AI 小步重构每次重构后都进行测试。这里最容易被省略的恰好是“不改变功能”这几个字。它需要被写成检查项而不能只作为提示词里的口号。对维护任务而言可以先把要求拆成三部分行为基线现有代码在选定输入下会产生什么结果。修改边界本次允许改变哪些内部结构。验证方式用什么检查证明这些行为仍然成立。三部分写清楚AI 才有具体的执行边界评审者也才有判断依据。先记录现状再讨论怎样整理重构前不妨先问一个具体问题调用方到底依赖了这段代码的什么答案通常不只有返回值还可能包括返回类型、字段是否存在、列表顺序、异常类型以及是否发生数据库写入或外部请求。对有副作用的代码而言“最后返回值一样”只是部分证据。可以建立一张简短的行为记录表检查对象需要记录的内容检查目的返回值数值、字符串、对象字段及类型避免计算结果或接口形状变化边界输入空集合、零值、缺省参数等现有处理结果避免整理分支时丢失特殊处理顺序返回列表顺序、必要的调用先后关系避免排序或执行顺序变化异常抛出条件、异常类型、调用方依赖的信息避免错误处理语义变化副作用写入内容、请求参数、调用次数避免重复执行或遗漏操作这张表应当服务于具体模块无须把所有项目都机械地套进去。纯计算函数可以重点检查输入输出涉及存储和网络的函数则需要补充相关交互记录。还要区分两个概念当前确实如此以及业务希望如此。如果旧代码的某种表现看起来奇怪先核对调用方、已有测试和业务约定。尚未确认的问题可以标注出来不要让 AI 根据“通常应该这样”自行改写。一个历史行为即使值得调整也应当成为明确的业务变更而不是藏在结构整理里面。正常分支必须进入回归范围资料 S5《AI-Coding-Guide-Zh/docs/claude-code/02-基础使用完整指南.md at main · KimYx0207/AI-Coding-Guide-Zh · GitHub》给出了一个具体检查要求当空列表问题处理后如果正常进度全部变成了0应指出2/4必须仍为50并要求修复正常分支后重新运行测试。资料还要求为“完成 3 项、共 8 项”补充检查明确预期结果为38。这些内容来自故障修复练习但其中的正常分支回归、明确预期结果、限制修改范围同样适用于功能正常时的重构。假设现在要整理一个进度计算函数。下面是一份教学示意具体基线仍应以实际项目为准输入应保留的结果关注点完成 2 项共 4 项50普通计算分支完成 3 项共 8 项38百分比取整规则完成 0 项共 4 项先读取旧实现并核实零完成量的处理完成 0 项共 0 项先读取旧实现并核实总量为零时的约定前两项的数值有 S5 的示例支持后两项不能靠猜测补齐。应先查看现有实现、已有测试和调用方式再把确认后的结果写入基线。尤其是3/8 → 38它提醒我们看起来不起眼的取整方式也属于可观察行为。如果 AI 在整理计算表达式时将取整方式换掉代码可能依然能运行结果却已经改变。预期结果应在改动前确定。如果源码改完之后再按照新实现的输出修改断言检查就失去了约束作用。把“允许整理”写成具体清单“帮我优化一下这个文件”包含太多可能性。AI 可能同时调整命名、合并条件、增加输入校验、修改默认值甚至顺手更换依赖。每一项单独看都可能有理由合在一起却很难判断行为是否保持一致。更清楚的任务描述应当直接列出允许调整的结构。例如任务整理进度计算模块保持已确认的外部行为。 本次允许 1. 重命名函数内部的局部变量。 2. 将重复的百分比计算提取为模块内私有函数。 3. 拆分过长函数保持对外导出和调用方式。 行为约束 1. 2/4 的结果保持为 50。 2. 3/8 的结果保持为 38。 3. 保留已确认的零值处理、返回类型和异常行为。 4. 保持现有的外部调用及其必要顺序。 执行要求 先阅读实现、调用方和现有检查列出拟修改点。 每次完成一类结构调整后运行相关检查并审阅差异。 发现疑似业务问题时记录位置与影响单独提出变更建议。这份约定的价值在于让修改可以被审查。评审者能够逐项追问新增的校验属于哪一项允许修改公开函数参数为什么改变了为什么一个命名整理任务出现了新的依赖实际使用时还可以写明允许修改的文件。若确实需要扩大范围应先更新任务约定再继续修改让范围变化留下清晰记录。怎样判断是在整理结构还是在修改业务判断标准可以落到调用方身上调用方能否观察到差异差异是否已被明确授权修改动作判断重点将局部变量a改成completedCount通常属于结构整理仍需检查引用是否完整将重复计算提取为私有函数检查参数求值、计算次数及副作用是否变化合并两个条件分支检查判断顺序、短路行为和异常触发条件调整取整方式会影响结果应作为明确的行为变更处理给原先允许的输入增加校验可能改变调用契约需要单独确认将返回字段缺省改为返回null改变接口形状需要核对调用方删除“看起来多余”的外部调用需要确认调用次数和顺序是否有实际意义“提取函数”也并非天然安全。例如原来只在某个分支里执行的计算被提前到函数开头可能让原本不会触发的异常提前出现。原来读取两次的数据被缓存后只读取一次也可能影响依赖可变状态的逻辑。因此不能只根据修改动作的名字判断风险还要检查它改变了什么执行过程以及这些变化是否能被外部观察到。小步修改让每一步都有可用的证据S4 建议的小步重构可以具体落实为以下流程建立起点。在修改前运行相关检查记录通过项和已有失败。已有失败需要说明原因避免后续将它误判为本次引入。选择单一目标。先改命名或先提取一段重复逻辑。每一步尽量只有一个主要目的。修改后立即验证。运行与当前模块相关的检查比较行为基线关注正常分支和边界分支。审阅代码差异。检查是否出现任务之外的默认值、校验、依赖或接口调整。保留可回退的版本。用小提交或其他版本记录保存已确认状态再进入下一步。如果某一步失败应围绕这一步定位原因。连续叠加更多修改会让“哪一步改变了行为”越来越难回答。验证也需要报告实际证据。S5 明确提出当 AI 声称改好了却没有测试输出时应要求执行检查命令报告退出结果和实际输出。对应到重构任务交付记录至少应说明运行了什么检查、结果如何以及哪些行为尚未覆盖。适用范围与局限这套方法适合功能基本稳定、需要持续维护的模块尤其适合整理重复逻辑、改善命名、拆分长函数等能够逐步推进的任务。已有测试和调用契约越清楚越容易建立有效的行为基线。它也有明确局限。有限的输入样例只能说明已检查场景保持一致无法证明所有可能输入下都完全等价。并发、时间、随机数、外部服务状态等因素也可能让简单的输入输出比较不足以描述真实行为。此外行为基线可能包含历史缺陷。保留基线可以帮助控制本次重构范围但不意味着这些缺陷永远不该修复。合理的做法是把发现记录下来另行定义新的预期结果、影响范围和验收条件。交付时最有价值的说明应当具体本次调整了哪些内部结构哪些行为经过了检查还有哪些路径未覆盖。例如可以在确实完成相应验证后写明“提取了内部计算函数已检查普通比例、取整及已确认的零值分支对外参数与返回结构保持一致外部服务交互尚未验证。”这样“行为不变”就有了可检查的内容也有了诚实的边界。参考资料以下链接为本文使用的公开资料。事实依据与检索摘录保存在本地记录中资料内容与适用范围以原始页面为准。67个AI编程必会知识1.6w字一次讲透女友“你要考研啊”帮助开发者理解AI编程中的核心概念。文章详细解释了人 - 掘金AI-Coding-Guide-Zh/docs/claude-code/02-基础使用完整指南.md at main · KimYx0207/AI-Coding-Guide-Zh · GitHub