# Epic feature branch 长期不 rebase develop → 按主题 cherry-pick 拆分不可行

**日期**：2026-05-18
**场景**：`feature/robot-manager-v3-full-refactor` 累积 66 commits / 305 files / +56k 行 LOC，
横跨 5+ 独立主题（v3 schema 终态 / docs/standards / FFAI Agent Phase 2 / 占位 SN / import M1）。
准备按主题拆 4-5 个 PR 分批合，cherry-pick **第一个 PR 就出 9 处 conflict**。

## 根因

epic feature branch 的演化路径跟 develop 的演化路径**严重 diverge**：

1. **feature branch**: 每个主题是 N 个 commit 累加（如 Agent 模块 4 个 commit 连续改 `tool-registry.service.ts / agent.module.ts / tool.types.ts` 相同 hunk）
2. **develop**: 同一时期同主题通过几次 PR squash merge 进来（如 `a3042cb9 "Phase 1 完整落地"`），文件最终状态跟 feature branch 上的**中间状态**不一致

cherry-pick 单 commit = 应用 patch context（hunk 上下几行），上下文在 develop 上对不上 → conflict。
多 commit cherry-pick = 依赖链 + 累积 conflict 雪崩。

## 数学模型

```
feature branch:  A → A' → A'' → A'''  (N 个 commit 串联)
develop:         A → squash(A → S)    (1 个 squash commit，S 是某种 reorganization)

cherry-pick A' onto develop = 试图把 (A → A') 的 patch apply 到 S 上
patch 上下文是 A，但 develop 上是 S → conflict
```

## 解决路径（按工程成本递增）

### 路径 1（推荐）：squash-diff per theme

不 cherry-pick 单 commit，而是按主题**取净 diff** 作为新 commit：

```bash
# 对每个主题
git checkout -b feature/theme-X develop
git checkout feature/epic-branch -- <theme-paths>
git add -A
git commit -m "feat(theme-X): ..."
git push -u origin feature/theme-X
# 创建 PR
```

**优点**：避免 cherry-pick conflict 链，每个 PR 干净。
**缺点**：失去 commit 历史（reviewer 看不到 incremental 演化过程）；如果主题之间文件交叉（一个文件被多主题改），路径切分困难。

### 路径 2：接受 epic 大 PR

承认 epic 不能拆，一次性 305 files / 56k 行 PR。

**风险**：违反 CLAUDE.md PR 拆分准则；review 灾难；auto-merge.yml ai-review 大概率 block。

### 路径 3：放弃 develop 路径

epic branch 不 PR，作为长期 work-in-progress 留着。但**这破坏了 v3 整体能进入测试 / 部署的可能**——v3 测试环境无法基于 develop 起来。

### 路径 4：强行 rebase epic → develop

`git rebase --onto develop <fork-point> epic-branch`，逐 commit 解 conflict。

**成本**：66 commits 每个潜在 conflict，工作量数小时-数天；高风险手工 resolve 可能损坏代码语义。

## 元根因 / 防御措施

CLAUDE.md 已有「一个分支只做一件事，PR merge 后立即删」原则，但缺**操作层面**约束：

- **epic feature branch 跨多主题** 是反模式（v3 重构这种跨模块大改造，应该拆成多个 stacked PR 增量合 develop，而不是单 branch 累积 N 周）
- **长 branch 必须定期 rebase develop**（建议 weekly），否则会进入"拆不开"陷阱
- 项目应在 `docs/standards/05-development-workflow.md` 加约束：feature branch ≥ 14 天未 rebase develop 触发警告

## 何时遇到

- 长期 work-in-progress epic feature branch（≥ 2 周）准备合 develop 时
- 多人在同一 branch 上累积不同主题工作
- v3 这种"整个模块重构"类型的 epic（schema 切换 + service 重写 + frontend 重写打包成一个 PR）

## 本次决策

参考 路径 1（squash-diff per theme）或 路径 2（接受 epic PR），user 重新决策。