分支管理策略：双轨（长/短上下文）+ Tag 回溯¶

状态：待执行 关联：naming-convention-cleanup.md（分支命名规范）、PENDING-short-context-eng-phase2.md（短上下文工程化第 2 期）

决策概览（分支树）¶

master（发布）
   │
   develop              ← 长上下文主轨（保留，继续演进）
   │   ├── PR #8 (evidence-projection)
   │   ├── PR #7 (memory)
   │   ├── PR #6 (trace)
   │   │
   │   ● tag: baseline-long-context-v1   ← 短轨起点
   │   │
   │   └─ 后续垂直模块继续合入此分支
   │
   develop-short        ← 短上下文主轨（新建，所有短上下文工作在此）
       ├── 从 baseline-long-context-v1 切出
       ├── 短上下文工程化第 2 期（瘦身 + 预筛）
       ├── 后续所有短上下文改造
       └── 周期性 merge develop（单向吸收垂直模块）

一、问题背景¶

当前仓库面临三个维度的代码演进：

垂直新模块（互不冲突）
PR #7 (memory)：新增 skills/memory/
PR #6 (trace)：新增 eval_mvp/
横切改造（改公共文件，互相冲突）
PR #8 (evidence-projection)：改 _lib.py + 5 个 SKILL.md
第 2 期：SKILL 瘦身、规则预筛（同样改 SKILL.md）
未来：comparison_mode 修复、子技能合并等
环境差异（部署目标不同）
OpenCode + DeepSeek：上下文 50K 限制，需要短上下文工程化
Claude Code：200K 上下文，工程化非必需但有益
未来 GLM 升级：可能扩到 200K+

核心问题：

短上下文工程化是"实验性改造"，触及 agent 行为语义，风险高于一般改进
长上下文主轨需要保持稳定可用，不能被实验拖累
垂直模块（memory/trace）在长轨上推进，但短轨也需要它们
横切改造只该在短轨上做，避免污染长轨

二、决策：双轨——长/短上下文各一条主线¶

选定：develop（长）+ develop-short（短）¶

主轨	用途	接收内容
`develop`	长上下文稳定主轨	所有垂直模块（memory/trace 等）；不接短上下文实验改造
`develop-short`	短上下文实验主轨	所有短上下文工程化改造（SKILL 瘦身、规则预筛等）；周期性吸收 develop 的垂直模块

选定理由：

风险隔离：短上下文工程化触及 SKILL.md 的执行语义（拆分、按需加载、规则预筛），改造期间可能引入回归。隔离到短轨后，长轨用户始终有稳定版本可用。
职责清晰：长轨 = 业务功能演进（垂直模块为主）；短轨 = 工程化改造（横切改造为主）。两侧 review 重点不同。
回退成本低：短轨出问题，删掉重切即可，长轨不受影响。

三、回溯节点：Tag = 短轨起点¶

Tag 的双重身份¶

baseline-long-context-v1 这个 tag 同时承担两个职责：

回溯点：万一短轨改造全盘失败，可以回到这个点重新决策
短轨起点：develop-short 从这个 tag 处切出，确保短轨起步时包含 PR #8/#7/#6 的完整成果

用 Tag 不用分支的理由¶

维度	长上下文分支	Tag
不可变	❌ 会随 develop 同步	✅ 快照固定
维护成本	高（每次同步）	零
回退操作	checkout 分支	checkout tag
占用资源	远端分支	tag 引用

Tag 规划¶

# PR #8 / #7 / #6 全部合入 develop 后
git tag -a baseline-long-context-v1 -m "短轨起点：投影 + memory + trace 合入后的长轨快照"
git push origin baseline-long-context-v1

# 第 2 期（瘦身 + 预筛）合入 develop-short 后
git tag -a short-context-eng-v1 -m "短上下文工程化第 1 个完整版本"

# 未来每个里程碑
git tag -a <milestone-id> -m "..."

任何时候想跑历史版本：git checkout <tag-name>。

四、短轨与长轨的同步机制¶

单向同步：develop → develop-short¶

垂直模块（memory/trace 等）只 merge 到 develop，develop-short 周期性 merge develop 把它们拉过来。反向同步（develop-short → develop）不做。

# 在 develop-short 上
git fetch origin
git merge origin/develop
git push origin develop-short

为什么单向¶

方向	是否做	理由
develop → develop-short	✅ 周期性	让短轨用上新的垂直模块
develop-short → develop	❌ 永不做	短轨的实验改造不应回污长轨；如确有成熟改造需 backport，开独立 issue 单独挑

同步频率¶

强制节点：每个短上下文里程碑（如 phase2 合入前）必须先 merge develop
按需节点：develop 有新垂直模块合入后，短轨开发者按需同步

同步纪律（避免冲突的根本保障）¶

垂直模块必须保持"不碰公共文件"（只新增 skills/memory/、eval_mvp/ 等独立目录）。如果某个垂直模块改了 _lib.py / SKILL.md，merge 时就会冲突——这种 PR 在 review 时拦住，不在 merge 时补救。

例外共享文件：.gitignore / README.md 等追加式共享文件，merge 时 git 通常自动合并，无需手动干预。

五、垂直模块 vs 横切改造：不同处理¶

垂直模块（PR #6 / #7 等）¶

特征：自包含在独立目录，几乎不碰公共代码。

处理方式：可并行合入 develop，顺序无关。develop-short 周期性吸收。

develop
   │
   ├── PR #7 (memory)   ─┐
   │                     ├── 任意顺序，互不冲突
   ├── PR #6 (trace)    ─┘
   │
   └─ → develop-short（通过 merge develop 吸收）

冲突点：仅 .gitignore / README.md 等共享配置文件，且都是追加行，merge 时自动合并。

横切改造（PR #8 / 第 2 期等）¶

特征：改公共代码（_lib.py / SKILL.md），改造之间互相冲突。

处理方式：串行合入对应主轨，每个改造基于"上一个已合入"的主轨切出。

短上下文相关的横切改造（SKILL 瘦身、规则预筛等）→ 合入 develop-short
与短上下文无关的横切改造（如 comparison_mode 修复）→ 合入 develop

develop-short                         develop
   │                                     │
   ├── PR #8 (evidence-projection)       └── [未来] comparison_mode 修复等
   │       合入后 → 切 phase2 分支              （与短上下文无关的横切）
   │
   ├── [新] short-context-eng-phase2     ← 第 2 波（瘦身 + 预筛，单 PR 多 commit）
   │       合入后 → 切后续改造分支
   │
   └── [未来] ...短上下文相关改造

关键纪律：

横切改造之间不要并行（物理冲突）
但每个改造内部可以多 commit（commit 级可独立 revert）
详细方案见 PENDING-short-context-eng-phase2.md

横切改造内部：多个子改造如何承载¶

当一波横切改造包含多个互相冲突的子改造（例如短上下文第 2 期 = SKILL 瘦身 + 规则预筛 + 工作流集成，三者都改 SKILL.md），有三种承载方式：

方式 A：三个独立 PR 串行

develop-short ── PR-A(瘦身) ── PR-B(预筛) ── PR-C(集成) ──►

❌ 等待链长（B 等 A、C 等 B）
❌ 中间状态无效（只做瘦身不做预筛仍然不够用，每次端到端验证是浪费）

方式 B：三个独立 PR 并行

❌ 都改 SKILL.md → merge 冲突连环，比串行更慢

方式 C（选定）：一个分支多 commit

feat/IK?-short-context-eng-phase2
  ├─ commit 1: SKILL 拆分章节
  ├─ commit 2: 规则预筛
  ├─ commit 3: 工作流集成
  └─ commit 4: 端到端回归

✅ 物理 zero 冲突（都在一个分支）
✅ commit 级可独立 revert（git revert <sha>）
✅ 一次 PR review，描述里分阶段写清
✅ 一次端到端验证，证明多改造叠加后真进 50K

判定原则：当多个子改造有共同目标（"跑进 50K"）、改共同文件（SKILL.md）、需要叠加才能验证效果时，用方式 C；否则按独立 PR 串行处理。

六、合并顺序建议¶

近期建议顺序：

PR #8 (evidence-projection) 先合入 develop
已 review 中，独立成立
这是短轨切出前的最后一笔横切改造
PR #7 (memory) + PR #6 (trace) 并行合入 develop
垂直模块，无冲突
顺序无关，看哪个先 review 通过
打 tag：baseline-long-context-v1（在 develop 上）
切短轨：从 baseline-long-context-v1 创建 develop-short 分支并推到远端
第 2 期分支（基于 develop-short 切出）：
短上下文工程化第 2 期（瘦身 + 预筛）
合入后打 short-context-eng-v1 tag
未来横切改造：
短上下文相关 → 串行合入 develop-short
与短上下文无关 → 串行合入 develop

七、分支命名与规范衔接¶

本策略与 naming-convention-cleanup.md 配合：

分支命名：<type>/<issue-id>-<short-slug>
垂直模块：feat/IK?-memory-pipeline、feat/IK?-offline-eval
短上下文横切改造：feat/IK?-short-context-eng-phase2
长轨横切改造：feat/IK?-comparison-mode-fix（无短上下文关系的）
PR 标题：<type>(<scope>): <简述> (#<issue-id>)
合入目标：
垂直模块 / 长轨横切 → develop
短上下文相关横切 → develop-short
Tag：里程碑节点（不参与日常合并）

八、风险¶

风险	缓解
长轨用户拿不到短轨的工程化收益	短轨稳定后，如判断"对长轨也有益"，开独立 backport issue 把成熟改造挑回 develop。但本期内不做。
双轨同步被遗忘（短轨长时间不 merge develop）	在每个短轨里程碑（如 phase2 合入前）设强制同步节点；review 时检查短轨是否落后 develop 太多
垂直模块误改公共文件导致 merge 冲突	review 时强制拦住；maintainer 在 merge develop→develop-short 时如遇冲突，回头给垂直模块 PR 提 issue
develop-short 长期偏离 develop，最终不可收敛	强制同步节点 + 风险监控；如已严重偏离，评估是否结束双轨、收敛回单主干

九、待执行动作¶

#	动作	责任	状态
1	PR #8 合入 develop	reviewer	待 review
2	PR #7 / PR #6 合入 develop	reviewer	待 review
3	打 tag `baseline-long-context-v1`	Claude（合入后）	待
4	从 tag 切 `develop-short` 分支并推远端	Claude	待
5	文档：把本策略写入 CLAUDE.md / CONTRIBUTING.md	Claude	待
6	未来垂直模块：合 develop 后提醒短轨同步	所有 contributor	持续
7	未来横切改造：按"短上下文相关 / 无关"分流到对应主轨	所有 contributor	持续

十、验收¶

develop 作为长上下文主轨，无短上下文实验改造污染
develop-short 从 baseline-long-context-v1 切出，与 develop 在该点对齐
baseline-long-context-v1 tag 存在且不可变
垂直模块 PR 合入 develop 后，develop-short 能 merge develop 无冲突吸收
横切改造按"短上下文相关 / 无关"分流到 develop-short / develop
CLAUDE.md 写明本策略