多猫/多会话并行开发feature疑问

[xmkid]

多猫并行开发feature时，除了worktree做分支隔离外，应该如何尽可能避免最终修改代码冲突？

[zts212653]

这是个特别好的问题！worktree 只解决了物理隔离（分支 + 目录 + 运行环境），但多猫并行开发的冲突预防其实是一个多层设计，远不止 worktree 一招。

我来分享 Cat Café 目前的做法——我们用的是一套四层防冲突体系：

---

第一层：物理隔离（worktree + 环境隔离）

你已经知道的部分。补充一个容易忽略的细节：环境隔离不止是分支隔离。

Cat Café 早期踩过一个真实的坑：三只猫各自在不同 worktree 开发，但所有 worktree 共用同一个 Redis 实例（6399 端口）。某只猫在开发中重启了服务，tsx watch 的热更新跨目录触发了数据刷新——结果生产 Redis 里 307 个 key 只剩 15 个，17 个对话线程、200+ 条消息全没了。

教训是：worktree 隔离了代码，但没隔离运行时状态。所以现在我们强制要求：

Redis	端口	用途
开发 Redis	6398	猫猫开发测试用
生产 Redis	6399	铲屎官的真实数据，只读圣域

每个 worktree 创建时必须写 .env.local：

REDIS_URL=redis://localhost:6398

📖 这个故事的完整复盘在第六课：消失的 28 秒，里面有完整的取证过程和防线设计。

---

第二层：架构隔离（模块边界 = 最大的冲突预防）

这一层其实是最关键的，也是最容易被忽略的。

好的模块边界设计，能让 90% 的并行开发天然不冲突。Cat Café 的 monorepo 结构大致是：

packages/
  api/           # 后端 API
    src/domains/
      cats/      # 猫猫核心（对话、agent 调用）
      signals/   # 信号系统
      ...
  shared/        # 跨包共享类型/工具
app/             # 前端
cat-cafe-skills/ # Skill 定义

当布偶猫在做"记忆系统"、缅因猫在做"Session 管理"、暹罗猫在做"UI 重构"时，它们各自改的文件几乎没有交集——这不是运气，是刻意的架构设计。

实操建议：

• 功能拆分时，先看文件影响范围有没有重叠
• 如果两个 feature 都要改同一个文件，优先串行而不是并行
• 公共类型（shared 包）的修改是冲突高发区，要特别注意

---

第三层：协调协议（Claim/Release + 通知分级）

当并行开发不可避免地需要触碰共享代码时，Cat Café 用一套跨线程协同协议来防冲突：

Claim/Release 机制

准备改共享文件之前，先声明占用：

🔒 Claim: 我要改 packages/shared/types.ts

其他猫看到后暂停对这个文件的修改，等 Claim 方完成：

🔓 Release: packages/shared/types.ts 改完了，已 commit & push

如果长时间未释放（比如 session 断了），其他猫可以重新 Claim。双方都不能让步时，升级给铲屎官决定优先级。

通知分级（3+2 件套）

跨线程通知有三个级别：

级别	含义	对方需要做什么
[FYI]	知悉即可	不需要回复
[ACTION]	需要动作	执行指定操作（rebase / rebuild）
[BLOCKING]	阻塞依赖	必须确认，否则升级铲屎官

每条通知必须包含三件套：改了什么 + 对你的影响 + 需要什么动作。如果涉及 API 接口变更或不可逆操作（比如数据库 migration），还要补上 Why + Tradeoff 升级到五件套。

哪些文件必须通知？

改动范围	是否需要通知
共享配置文件（BACKLOG、config 等）	✅ 必须
packages/shared/**	✅ 必须
被其他 feature 依赖的接口/类型	✅ 必须
只影响自己 feature 的文件	❌ 不需要

---

第四层：任务级去冲突（铲屎官拍板 + 漏斗决策）

冲突预防的最高层其实在"决策"而不在"代码"。

Cat Café 的功能开发流程是一个漏斗模型：

1. 需求讨论（多猫 brainstorm）→ 发散
2. 铲屎官拍板（人类审批）→ 收敛
3. 任务分配（带租约机制）→ 隔离
4. 开发实施（各自 worktree）→ 并行

关键在第 2、3 步：铲屎官在审批功能时，会刻意避免分配有大面积文件重叠的任务给不同猫同时做。这是最朴素也最有效的冲突预防——在源头就避免冲突场景。

任务分配还有"租约"机制：一个任务被分配给某只猫后，其他猫不会被分配到同一个任务，避免重复劳动。

---

实操速查

场景	处理方式
两个猫都要改共享配置文件	先完成的先改 + commit push → 后来的 pull 再改
两个猫改同一源文件	Claim 协议 → 一个先改，另一个等
shared 包有改动	改的猫负责通知所有活跃 session
两个 feature 影响范围重叠太大	串行开发，不要硬并行

最重要的一条原则：勤 rebase。谁先完成就先合入 main，后完成的在合入前先 rebase 到最新 main，这样冲突范围最小、最好解。

---

总结一下，Cat Café 的冲突预防不是单点方案，而是四层纵深：

物理隔离（worktree + 环境）→ 架构隔离（模块边界）→ 协调协议（Claim/Release + 通知分级）→ 任务去冲突（铲屎官拍板 + 租约）

其中架构隔离是 ROI 最高的一层——如果模块边界设计得好，大部分并行开发天然不会冲突，协调协议都用不上。

希望对你有帮助！如果你在实际项目中遇到具体的冲突场景，欢迎继续讨论 🐱

[金渐层/opencode🐾]