Skip to content

常见避坑与自检清单 ​

本页汇总了真实多项目交付中最容易遇到的 12 个典型问题。为了方便你快速排查,我们按**“单仓开发 → 跨仓迁移与调度 → Git 收工合并 → 安装与环境”**四个阶段分类整理。

跨仓派发前 10 秒自检清单

在调用 $jj-same 或 $jj-dispatch 把改动同步到其他仓库前,先确认这 4 项:

  • [ ] 源仓库已提交:项目A 的改动已经 git commit(工作区干净)。
  • [ ] 目标分支正确:每个目标仓库(项目B、项目C)都已经切到了本次任务对应的功能分支。
  • [ ] 项目名称稳定:使用已在项目地图(~/.jj-flow/map.md)登记的固定名称(如“项目A / 项目B”),不要混用临时别名。
  • [ ] 明确收工边界:清楚区分“任务验收通过(本地完成)”与“Git 推送合并(需额外调用 $jj-end)”。

一、单仓开发与验收阶段(ralph / review) ​

1. 只看聊天回复说“改好了”,没核对仓库文件 ​

  • 发生阶段:ralph 验收归档或 dispatch 汇总结果时。
  • 问题表现:对话里说功能已经完成,但实际上单测没跑过、审查还留着 [BLOCK] 阻塞项,或者代码根本没保存。
  • 正确做法:
    1. 验收时看三样真实凭据:git diff(代码改动)、task_plan.md(验收项勾选状态)、progress.md / findings.md(测试输出与审查结论)。
    2. 只要还有未解决的阻塞项或中高风险缺陷,就回复“验收不算,按审查改”,不要放行归档。
    3. 详见 证据门禁:什么算做完。

2. 把可选的 team-* 协作完成当成了正式验收通过 ​

  • 发生阶段:使用 team-coordinate、team-lifecycle 或 team-swarm 跑完一轮多角色协作后。
  • 问题表现:看到 team 会话提示 complete 并产出了报告,就以为当前需求已经通过了 ralph 验收或 dispatch 门禁。
  • 正确做法:
协作引擎产出的内容能否直接算作交付验收通过?
team-coordinate动态多角色分析与实现产物(.workflow/.team/TC-*/)不算
team-lifecycle固定 SDLC 规格、计划与实现产物(.workflow/.team/TLV4-*/)不算
team-swarm多假设评分与推荐方案(.workflow/.team/TAS-*/)不算

这些引擎只负责“这一轮怎么组织分析或搜索方案”,它们的产物可以作为证据被引用,但正式验收仍然以 ralph 或 dispatch 的任务账本为准。

3. 以为每次开发都必须新建独立目录(worktree) ​

  • 发生阶段:启动 ralph 或 dispatch 选择工作区模式时。
  • 问题表现:每次改一个小需求都去建一套独立的 Git worktree,或者反过来在满是未提交脏文件的 main 分支上直接硬改。
  • 正确做法:日常默认就在当前仓库切好的功能分支上直接修改(即 Mode S);只有当前工作区有无法清理的无关脏改动、或你明确要求物理隔离时,才使用独立 worktree(Mode W)。

二、跨仓迁移与多仓调度阶段(same / dispatch) ​

4. 源仓库还没 git commit 就发起多仓派发或迁移 ​

  • 发生阶段:从 ralph 转入 same,或 dispatch 从预览进入正式派发时。
  • 问题表现:预览能看,但一点正式派发或开始迁移就被系统拦截,提示源仓库交接未就绪。
  • 正确做法:
    1. 跨仓迁移必须绑定源仓库的稳定 commit 哈希。
    2. 先在源仓库提交代码(或先跑一次 $jj-end),然后再调用 $jj-same 或 $jj-dispatch。

5. 目标仓库停在错误分支上就开始迁移 ​

  • 发生阶段:same 确认目标仓库状态时。
  • 问题表现:直接说“交接到项目C”,如果项目C 当时正停留在发布分支(如 master 或 release)且未检查,就会改错分支。
  • 正确做法:
    1. 迁移前先确认每个目标仓库当前所在的分支是否干净、是否是本次任务的功能分支。
    2. 如果分支不对,先切到正确的功能分支再继续;same 检测到分支异常停下询问时,明确告诉它目标分支名。

6. 把 dispatch 的“验收通过(VERIFIED)”当成“已经推送上线” ​

  • 发生阶段:dispatch 报告所有目标项目均已 VERIFIED 之后。
  • 问题表现:以为调度状态变成 VERIFIED 就万事大吉,结果去远端仓库一看,代码既没 push 也没合入 dev。
  • 正确做法:
状态阶段真实含义后续动作
调度验收通过(VERIFIED)各目标仓库本地改动、测试、只读审查与沙箱证明均已齐备代码仍在本地功能分支
远端分支合入与发布工作分支与集成分支(如 dev)均已推送至远端需在对应仓库调用 $jj-end 完成 Git 收尾

7. 把项目族里的仓库名称临时改叫 source / target ​

  • 发生阶段:在 same 或 dispatch 对话中指代各个项目时。
  • 问题表现:一会儿叫“源仓/目标仓”,一会儿叫“老项目/新项目”,导致调度记录或跨仓定位指错目录。
  • 正确做法:始终使用项目地图(~/.jj-flow/map.md)中登记的稳定名称(如文档示例中的 项目A / 项目B / 项目C),让 Agent 严格按地图里的 path 对照,不要靠临时起别名猜测。

8. 回退多项目交付时,担心 Agent 擅自重置 Git 历史 ​

  • 发生阶段:使用 dispatch 回退某次交付或重开某个目标仓库任务时。
  • 问题表现:担心说一句“回退刚才的交付”,Agent 就直接执行 git reset --hard 把已推送的历史冲掉。
  • 正确做法:放心调用回退。dispatch 的回退流程会先更新调度账本,然后只读探测各仓库“是否已推送、是否已合并”,列出安全的回退选项(未推送用 reset,已推送/已合入用 revert)交给你点选确认,绝不会背着你强推或改写 Git 历史。

三、Git 收工与合并阶段(end) ​

9. 收工时因为历史提交里有 staging,误把代码合进预发分支 ​

  • 发生阶段:调用 $jj-end 选择合入目标分支时。
  • 问题表现:仓库里同时存在 dev 和 staging 分支,以前有人在 git log 里留过 Merge into staging,或者 package.json 里有 build:staging 脚本,导致误合入预发分支。
  • 正确做法:
    1. jj-end 的默认合入规则非常严格:只要你没显式指定 integration=staging,且项目文档 / naming.json 没有明文规定收工合入预发,只要存在 dev 分支就只合入 dev(依次回退顺序为 dev → develop → main)。
    2. git log 历史、MR 标题、构建脚本名均不算分支约定。
    3. 每次执行前,Agent 都会先打印一行 工作分支 → 合入分支(依据:…),一眼即可核对。
    4. 详见历史复盘记录:docs/evaluations/EP-20260828-jj-end-staging-not-dev.md(仓库内归档)。

10. 合并遇到代码冲突就整段放弃,或者只解一半留半成品 ​

  • 发生阶段:$jj-end 将工作分支合入 dev 遇到冲突时。
  • 问题表现:一看到 Vue 组件或文档有冲突就立刻 merge --abort 停手;或者只解了 import 冲突、丢掉半截业务逻辑。
  • 正确做法:
    1. Agent 会先对所有冲突文件打出一张分类表,区分为可自动合并(self-merge)与需人工裁决(unhandleable)。
    2. 默认自行合并:只要能一句话说清两边意图、无需替产品拍板业务开关(如两边各自新增独立字段、样式或文档段落),Agent 会保留双方改动、清除冲突标记并继续完成收工。
    3. 真正冲突才中止:只有遇到两边对同一产品逻辑改成相反行为、或涉及二进制文件与密钥时,才会执行 merge --abort 干净退回工作分支,并把冲突表交给你拍板,绝不留半成品合并。

四、宿主环境与版本升级 ​

11. 混淆了 Grok / Claude 与 Codex 的多项目会话习惯 ​

  • 发生阶段:在 dispatch 中跨多个仓库派发任务时。
  • 问题表现:在 Claude 或 Grok 里以为必须手动开四五个聊天窗口才能同时改多个项目。
  • 正确做法:
宿主工具默认工作方式说明
Claude Code / Grok单会话多子代理(Mode S)默认就在当前这一个聊天窗口里完成;不同仓库可同时派发执行人并行修改,同一仓库内部保持串行
Codex支持多会话 / 多线程绑定可按宿主能力绑定独立线程或使用当前会话

详见 宿主平台与工作模式。

12. 升级 @brewer/jj-flow 后,对话菜单里找不到新命令(如 /jj-init) ​

  • 发生阶段:早期安装过旧版 jj-flow,升级后想用新增命令时。
  • 问题表现:能看到 /jj-ralph、/jj-same,但输入 /jj-init 没有反应。
  • 正确做法:重新运行一次安装命令补齐缺失技能,然后关闭当前会话、新开一轮对话即可:
bash
npx @brewer/jj-flow@latest install-skill --platform all --force

基于 MIT 协议发布 · 以持久文件与 Git 证据驱动的多项目研发工作流