reviewable-change

易于审查的变更

编写变更时，应确保未来的审查者能从差异中还原变更意图。

每个差异只做一件事

将不同类型的工作分开：

• 行为变更。
• 重构。
• 重命名。
• 格式调整。
• 生成的输出。
• 仅测试变更。
• 文档变更。

不要将大范围清理与功能开发混在一起。如果清理确有必要，请将其限制在已编辑的路径内，并说明原因。

明确表达意图

每项有意义的编辑都应至少回答以下一个问题：

• 它实现了哪项请求的行为？
• 它消除了哪个现有错误或风险？
• 它遵循了哪种现有模式？
• 哪项验证证明了它是正确的？

如果某项编辑无法与意图关联，就将其移除，或拆分为单独的请求变更。

控制差异规模

优先采用能够证明行为正确的最小差异。避免：

• 为了改变一小项行为而重写文件。
• 在功能开发期间跨整个代码仓库重命名符号。
• 重新格式化未触及的代码。
• 在证明确实需要移动代码之前就移动代码。
• 在出现第二个实际调用方之前引入抽象。

如果无法避免较大的差异，请将其分成便于审查的阶段，并说明各阶段之间的依赖关系。

保持审查者的独立判断

不要依赖 Agent 的内部推理作为证据。差异、测试、计划和最终报告必须提供足够的证据，让审查者能够核实工作。

在最终报告中包括：

• 变更的行为。
• 涉及的文件或模块。
• 运行过的验证。
• 任何有意造成的非局部影响。
• 仍需人工审查的风险。

完成标准

当差异只有一个明确目的，行为变更未与大范围重构或格式调整混杂，每项有意义的编辑都对应明确意图，验证证据齐备，且审查者无需相信 Agent 隐藏的推理过程就能理解变更时，这份差异便易于审查。