refactor

重构 — 一项结构性实验

重构会改变结构，同时保留可观察到的行为。它执行一项由调用方选择的转换，并报告结果。“保留行为”是需要通过前后检查来证明的主张，绝不能仅凭断言。

什么算作行为

除非调用方明确排除某个方面，否则以下内容都必须保留：

• 消息和退出码。 错误和输出文本必须逐字节一致；退出码、错误类型以及哪个输入会引发哪个错误都必须保持不变。脚本和调用方会解析这些内容。保留不一致的消息并报告；将其规范化会改变行为。
• 近似重复项之间的差异。 合并重复分支时，将每项差异（常量、比较、消息、额外步骤）作为参数或分支保留。不要统一调用方未声明为偶然存在的差异。
• 接口。 公共签名、默认值、返回类型、持久化字段名称、协议值和 CLI 标志。除非获准的范围涵盖此项，否则重命名会构成兼容性变更。
• 顺序和覆盖范围。 分支优先级、默认处理、求值次数、副作用顺序，以及运行的测试集合。原先失败的测试不再失败，或某项测试不再运行，都属于行为变更。
• 保护性检查。 信任边界验证、防止数据丢失的保护措施、安全控制和无障碍功能都必须保留，即使其他层（上游或下游）也有重复检查，或没有测试覆盖到它。中立性检查无法发现这些检查被移除，因此看起来重复并不是删除它的理由。

流程

1. 使用调用方领域中的术语，说明要保留的行为、重点验收范围，以及给调用方带来的具体结构问题。
2. 运行重点检查，以及由变更范围决定的最小回归检查，并记录真实的基线，包括可复现的环境因素导致的失败。对于比较可执行行为的评估，固定起始源码，在修改前构建基线，并保留该二进制文件和比较输入。
3. 执行一项有界的转换：提取、重命名、内联、简化、封装、移动、替换为现有代码，或删除无用代码；重构目录列出了各模式的安全检查。应根据调用方需要理解的内容以及领域规则需要在哪处修改来评估，而不是根据文件大小。
4. 过程中发现的错误或可疑的不一致应单独报告（说明位置及其看起来不对的原因），并保持不修复。在重构中修复它会掩盖未经调用方授权的行为变更。
5. 使用相同输入（包括错误路径），重新运行相同的重点检查和最小的必要回归检查。
6. 报告结果，然后停止。失败结果是提供给调用方的证据；此技能不会回滚、缩小范围、重试、提交、验证或安排后续工作。

如果无法执行任何操作（没有运行时、没有测试，或代码是通过消息提供的），则无法证明行为中立：请给出调用方必须运行的准确前后命令和输入，包括错误路径，并列出行为未检查的每个方面。

transformation: <the one change>
preserved:      <behavior and surfaces from step 1>
checks:         <command>: before -> <result>; after -> <result>   (or "not run")
outputs:        <before/after hashes when the surface produces output>
diff:           <files touched>; only those the transformation names
suspected bugs: <file:line, why>; reported, not fixed
not checked:    <surfaces no check covered>; present even when empty

职责与接口成本

在添加接口或拆分模块之前，先检查有代表性的调用方。 统计它们必须协调的概念：必需的设置、顺序、状态、错误处理和重复的领域规则。好的边界会让一个内聚的规则由单一所有者负责，并让调用方请求结果，而不必复现该规则。 拒绝只增加另一个名称，或把相同的协调工作推给调用方的封装。如果没有具体的调用方问题值得改变，现有边界就已足够。

选择目标时，优先关注调用方所选区域中的阻力：同一规则被反复修改、调用方反复进行设置，或缺陷散布在协作文件中。如果调用方未明确指出，近期历史记录可以帮助定位这种阻力；但仅有代码变动频繁并不足以证明需要重构。具体说明预期节省的工作，例如只需在一个位置修改一条规则，并将其与调用方迁移和回归成本进行权衡。对于稳定且成本低廉的边界，不要改动。

通过设想移除提议的抽取来检查它：调用方是否必须重新构建一条内聚的规则，还是只会少一个转发步骤？如果调用方不需要替换能力，就将内部测试接缝保留为私有。通过调用方可见的边界验证保留的行为；在证明不同用例都得到等效覆盖之前，保留现有测试。移动测试不代表可以删除它所保护的行为。

抽取操作和类型时，使用调用方的词汇。如果命名歧义会改变行为，应在现有领域定义中解决；只有在确实需要处理这一区分时，才参考 领域。

如果转换需要一个接缝——抽取边界、接口或模块拆分——且存在多个候选接缝，请先试探再动手。在一次性隔离环境中试探（使用调用方策略允许的临时分支、工作树或副本）：初步搭建接缝，观察它带来的影响——签名变更、导入循环、测试重写——然后丢弃试探结果，只保留获得的经验。停止条件：最多试探两次；如果第二个候选接缝也难以适配，就将两次试探的发现报告给调用方，而不要尝试第三次。直接把第一个能想到的接缝切入工作树，是过早确定接缝这种失败模式：错误的边界会逐渐固化，因为此时回退它的成本已高于将就使用它。

中立性门槛

只有通过行为一致性的证明，才能继续转换：

• 定向检查和包级回归检查在变更前后都通过，且预先存在的失败项完全相同：不能新增失败项，也不能让已有失败项消失。
• 对于会生成输出的表面（生成器、序列化器、格式化器、报告），使用相同输入在变更前捕获输出哈希，并在变更后逐字节比较。任何不匹配都是需要呈现并解释的行为差异，不能置之不理；是否保留、缩小范围或撤销变更，由调用方决定。

事后跳过或缩小中立性门槛，是事后中立性这种失败模式——差异决定了实际测试的内容。将门槛未覆盖的任何表面标记为未检查行为。

参考资料

• 保持行为的简化 — 重构目录及各模式的安全检查
• 行为场景
• 上游能力参考 — Matt Pocock；原始 AgentOps 改编版本。