Git 大分支迁移方法论

第一步：诊断现状

# 找到分叉点
git merge-base <target> <source>

# 源分支独有的提交数
git log --oneline <source> ^<target> | wc -l

# 分叉时间
git log --format="%ai" <merge-base-hash> -1

# 文件差异统计
git diff --stat <target> <source> | tail -3

根据结果判断整体策略，参见 references/complexity-guide.md。

第二步：建立安全网 + 初始化进度文件

git tag backup/<source>-before-merge <source>
git tag backup/<target>-before-merge <target>

在 .claude/tmp/merge-progress.md 创建进度文件：

# 分支迁移进度

来源：<source> → 目标：<target>
开始：<date>

## 进度概览
✅ 0 完成 / 🔄 0 进行中 / ⏭ 0 跳过 / ⬜ 待归纳

## 待处理提交
（将 git log 输出粘贴在此，逐步消耗）

## Spec 列表
（每完成一个在此追加）

第三步：归纳下一个 spec（循环起点）

从进度文件的"待处理提交"中取下一批，按功能意图归纳出一个 spec，提交用户审核。

归纳方法见 references/commit-grouping.md。

输出格式：

📋 Spec N：<功能意图标题>

包含提交：<hash1> <message>
          <hash2> <message>
涉及文件：src/xxx, src/yyy
意图描述：<一两句话说清楚这组提交要实现什么、解决什么问题>
建议方式：[ ] opsx:new  [ ] 直接迁移

等待用户：批准 / 修改描述 / 跳过（记入进度文件跳过区域）

第四步：执行迁移

每个 spec 必须启动一个新的 sub-agent 来完成，不在主线上下文中直接操作。这样可以防止主线上下文被实现细节撑爆，保证整个迁移任务的进度管理始终清晰。

Sub-agent 的 prompt 应包含：

• spec 的意图描述
• 涉及的提交 hash（供 sub-agent 读 diff）
• 进度文件路径（.claude/tmp/merge-progress.md）
• 当前目标分支名
• 实现方式（直接迁移 / opsx:new）

Sub-agent 完成后返回：实现结果 + 构建是否通过。

实现方式参考：

• 直接迁移（简单明确）→ 参见 references/direct-apply.md
• opsx:new（复杂/需要重新设计）→ 参见 references/spec-format.md

第五步：验证 + 更新进度 → 回到第三步

dotnet build

构建通过后，更新 .claude/tmp/merge-progress.md：

• 将该 spec 状态改为 ✅，填入实现方式
• 更新概览计数

回到第三步，处理下一批提交。所有提交处理完毕后，迁移结束。

关键原则

• 一次只处理一个 spec：归纳一个，审核一个，迁移一个
• 每个 spec 用独立 sub-agent 实现：主线上下文只负责进度管理和 spec 归纳，实现细节交给 sub-agent
• 进度文件是唯一的任务指引：随时打开 .claude/tmp/merge-progress.md 查看当前状态
• 跳过不等于丢失：跳过的提交记录在进度文件，便于事后 review