常见避坑与自检清单
本页汇总了真实多项目交付中最容易遇到的 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]阻塞项,或者代码根本没保存。 - 正确做法:
- 验收时看三样真实凭据:
git diff(代码改动)、task_plan.md(验收项勾选状态)、progress.md/findings.md(测试输出与审查结论)。 - 只要还有未解决的阻塞项或中高风险缺陷,就回复“验收不算,按审查改”,不要放行归档。
- 详见 证据门禁:什么算做完。
- 验收时看三样真实凭据:
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从预览进入正式派发时。 - 问题表现:预览能看,但一点正式派发或开始迁移就被系统拦截,提示源仓库交接未就绪。
- 正确做法:
- 跨仓迁移必须绑定源仓库的稳定 commit 哈希。
- 先在源仓库提交代码(或先跑一次
$jj-end),然后再调用$jj-same或$jj-dispatch。
5. 目标仓库停在错误分支上就开始迁移
- 发生阶段:
same确认目标仓库状态时。 - 问题表现:直接说“交接到项目C”,如果项目C 当时正停留在发布分支(如
master或release)且未检查,就会改错分支。 - 正确做法:
- 迁移前先确认每个目标仓库当前所在的分支是否干净、是否是本次任务的功能分支。
- 如果分支不对,先切到正确的功能分支再继续;
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脚本,导致误合入预发分支。 - 正确做法:
jj-end的默认合入规则非常严格:只要你没显式指定integration=staging,且项目文档 /naming.json没有明文规定收工合入预发,只要存在dev分支就只合入dev(依次回退顺序为dev→develop→main)。git log历史、MR 标题、构建脚本名均不算分支约定。- 每次执行前,Agent 都会先打印一行
工作分支 → 合入分支(依据:…),一眼即可核对。 - 详见历史复盘记录:
docs/evaluations/EP-20260828-jj-end-staging-not-dev.md(仓库内归档)。
10. 合并遇到代码冲突就整段放弃,或者只解一半留半成品
- 发生阶段:
$jj-end将工作分支合入dev遇到冲突时。 - 问题表现:一看到 Vue 组件或文档有冲突就立刻
merge --abort停手;或者只解了import冲突、丢掉半截业务逻辑。 - 正确做法:
- Agent 会先对所有冲突文件打出一张分类表,区分为可自动合并(
self-merge)与需人工裁决(unhandleable)。 - 默认自行合并:只要能一句话说清两边意图、无需替产品拍板业务开关(如两边各自新增独立字段、样式或文档段落),Agent 会保留双方改动、清除冲突标记并继续完成收工。
- 真正冲突才中止:只有遇到两边对同一产品逻辑改成相反行为、或涉及二进制文件与密钥时,才会执行
merge --abort干净退回工作分支,并把冲突表交给你拍板,绝不留半成品合并。
- Agent 会先对所有冲突文件打出一张分类表,区分为可自动合并(
四、宿主环境与版本升级
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