副标题 / 摘要

当你在 AI 辅助开发中做迁移时，最容易踩的坑不是“写不出代码”，而是“把对齐和优化混在同一轮里”。本文给出一套可执行流程：先冻结参考基线，先完成行为等价迁移，再在独立波次做行为改造。中途新想法只记账，不插队。

目标读者

  • 正在做历史分支迁移、模块重构、流程管线化的后端工程师
  • 频繁与 AI 协作，想降低返工率与评审噪音的团队
  • 负责主线稳定性，需要高可回滚交付节奏的技术负责人

背景 / 动机

很多团队在迁移时会同时做三件事：

  1. 对齐参考分支。
  2. 顺手优化流程设计。
  3. 修复中途发现的问题。

结果通常是：提交语义混乱、评审困难、出问题时无法快速定位根因。

问题不在“能力不够”，而在“工作流没有控制变量”。

核心概念

1. 双阶段改造模型

  • 阶段 A：行为等价迁移（Move）
    • 目标是“和参考基线行为一致”，不是“更优雅”。
  • 阶段 B：行为改造优化（Change）
    • 目标是“在可用基线之上提升设计质量”。

2. 任务记账机制

中途发现额外改动点，不打断当前主任务：

  • 记录到 task ledger（任务清单）。
  • 标注优先级、影响面、建议分支。
  • 当前波次只做与目标直接相关的改动。

3. 工作区隔离机制

  • 主任务在当前分支推进。
  • 插件优化、实验性改造在独立 worktree/分支完成。
  • 避免“一个工作区混杂多类语义变更”。

实践指南 / 步骤

Step 1：冻结参考分支

记录参考分支 commit hash，作为迁移锚点。

git rev-parse task/feat/20260305-upload-entity-extract-pipeline
# 输出示例：a1b2c3d4...

规则：后续不再直接改这个参考分支，任何新想法开新分支。

Step 2：只做行为等价迁移

定义本轮完成标准：

  • 接口契约不变。
  • 关键行为不变。
  • 可编译、可启动、最小 smoke 通过。

禁止事项：流程重排、命名体系重构、附带性能优化。

Step 3：打“基线锚点提交”

迁移完成后立即提交，提交信息只描述“等价迁移完成”。

git add -A
git commit -m "refactor: 完成上传实体抽取链路的行为等价迁移基线"

这个提交是后续所有改造的回滚点与对照点。

Step 4：把中途发现的问题记账

使用简单模板记录，不在本轮插队：

[Backlog]
- topic: document_processing 独立 workflow
- reason: 当前埋在 document_prepare 内，观测粒度不足
- risk: 中等
- next_branch: feat/workflow-step-split

Step 5：在独立分支做行为改造

git switch -c feat/workflow-step-split
git worktree add ../repo-workflow-split feat/workflow-step-split

在这轮里单独处理：document_prepare / document_processing / asset_extract 等步骤语义拆分。

Step 6：独立验证改造波次

验证维度与迁移波次分离：

  • 新增行为是否符合设计目标
  • 兼容性是否保持
  • 观测与状态是否更清晰

Step 7：按语义分批提交

  • 提交 1：结构拆分（无行为改动）
  • 提交 2：行为改造（有契约变化）
  • 提交 3：文档与运维说明

可运行示例：最小流程脚本

# 1) 冻结参考锚点
ANCHOR=$(git rev-parse task/feat/20260305-upload-entity-extract-pipeline)
echo "anchor=$ANCHOR"

# 2) 当前分支只做等价迁移
# ...修改代码...

# 3) 形成基线锚点提交
git add -A
git commit -m "refactor: 行为等价迁移基线"

# 4) 开下一波改造分支
git switch -c feat/workflow-behavior-change

解释与原理

这套方法本质是三条工程原则：

  1. Make it work, then make it right, then make it better.
  2. Separate move from change.
  3. Small, reversible commits.

它不是保守，而是更快的高质量交付：

  • 评审方能快速理解每个提交在改什么。
  • 出问题时能在“迁移问题 vs 改造问题”之间秒级分层。
  • 回滚不需要牵连整条链路。

常见问题与注意事项

Q1：中途发现明显坏味道，为什么不顺手改？

因为这会污染当前波次语义。正确做法是记账，进入下一波改造。

Q2：这样会不会变慢？

单轮看似慢，整体更快。你减少了返工、沟通和回滚成本。

Q3：什么时候可以合并两波？

只有在影响面极小、可验证性极高、并且团队明确同意时才考虑合并。

最佳实践清单

  • 每一轮只允许一种变更语义。
  • 每轮结束必须有可验证“done_when”。
  • 中途发现的问题只记账不插队。
  • 所有架构改造放到独立分支/worktree。
  • 提交信息写“变更类型 + 影响对象 + 结果状态”。

小结 / 结论

面对 AI 协作开发，真正的效率不是“改得多快”，而是“每一轮改动是否可解释、可验证、可回滚”。

先等价迁移，再行为改造，是复杂系统持续演进时最稳、也最可复制的工作流。

行动号召（CTA）

下一个迁移任务，直接套用这三个动作开始：

  1. 先记参考锚点 hash。
  2. 本轮只做行为等价对齐。
  3. 新想法全部记账，下一波独立改造。