Skip to content

证据门禁:什么算真正「做完了」 ​

在 AI 辅助编程中,最常见的问题是:模型在聊天框里信誓旦旦地说“我已经改好并测试通过了”,但你打开仓库一看,要么漏改了文件,要么测试根本没跑,要么在跨仓迁移时只改了 A 漏了 B。

因此,jj-flow 的第一条核心原则就是:聊天口头承诺不算数,只有落盘的文件、测试输出、审查报告与 Git 提交才算数。

一、什么算数 vs 什么不算数? ​

验证维度算作有效凭据(可放行过门禁)不算有效凭据(会被拦截或保持 PENDING)
需求与步骤完成度.workflow/ralph/<task>/task_plan.md 中明确列出的目标、验收项与已完成步骤聊天记录里口头说“所有需求都满足了”
代码改动真实性工作区真实的 git diff 或已产生的 Git commit SHA对话里贴了一段代码片段,但未实际写入仓库文件
测试与验证结果progress.md 中记录的真实测试命令输出与验证结论口头声称“单测应该都能过”或跳过验证却未说明原因
代码审查结论只读审查员写入的 findings.md 与 .state/reviews/REV-*.json(结论为 [OK] 或 [WARN])审查结论仍为 [BLOCK](NEEDS_CHANGES),或存在未解决的高优缺陷
多仓调度完成度调度账本中记录的真实会话绑定、各仓 commit、审查记录与运行时沙箱证明(sandbox attestation)仅在聊天框里列了一张状态表格,但控制面账本无对应记录

证据不足时的默认行为:宁可停下问,绝不假装通过

当任何一项证据缺失、或者需求中的必做项(MUST)与边界无法确认时,jj-flow 会将状态保持在当前阶段(或标记为 PENDING / BLOCKED),并主动向你说明卡点,绝不会为了“看起来顺利”而帮你蒙混过关。

二、单仓、跨仓与收工的「完成标准」对照 ​

不同工作流入口负责不同的交付阶段,它们的“完成标准”有着严格的边界:

工作流入口什么状态下算该阶段完成?此时还没做什么?(下一步动作)
ralph(单仓闭环)代码已修改、测试与审查已通过、你在对话中确认验收,且任务目录已移入 .workflow/ralph/completed/尚未 git commit / push → 如需提交合入 dev,请调用 $jj-end;如需迁往其他仓库,请先提交再调用 $jj-same
same(跨仓迁移)每个目标仓库都按各自规范改好、跑过验证,并输出了独立小结(若项目B 完成、项目C 阻塞,则只算项目B 完成)尚未推送远端 → 请在验证通过的目标仓库调用 $jj-end
dispatch(多仓调度)统筹账本中所有目标项目均集齐“提交 + 审查 + 会话绑定 + 沙箱证明”并标为 VERIFIEDVERIFIED 不等于已推送远端或已合入 dev → 需在各目标仓执行 $jj-end 完成远端合入
end(Git 收工)本任务代码已提交,且工作分支与集成分支(如 dev)均已成功推送至远端,本地已切回工作分支Git 交付已全部闭环

三、三层状态架构:各层分别管什么? ​

为了既能跨项目统筹、又不污染各个业务仓库,jj-flow 将状态清晰地分为三层(日常使用无需手动维护,了解即可):

text
┌───────────────────────────────────────────────────────────────────┐
│ 第 1 层:本机全局配置层 (~/.jj-flow/naming.json & map.md)         │
│ 职责:记录本机有哪些业务仓库、路径在哪、属于哪个项目族            │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │ 按路径定位仓库
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│ 第 2 层:多仓统筹控制层 (~/.jj-flow/ 下的 DEL-* 调度账本)         │
│ 职责:对应 $jj-dispatch —— 管“派给谁、批没批、各仓是否 VERIFIED”   │
│ (只存指向各仓任务与 commit 的引用指针,绝不复制业务代码正文)    │
└─────────────────────────────────┬─────────────────────────────────┘
                                  │ 下发任务并回收证据
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│ 第 3 层:业务仓库执行层 (<项目根>/.workflow/ralph/task-…/)        │
│ 职责:对应 $jj-ralph / $jj-same —— 管真实的代码修改、测试与审查   │
└───────────────────────────────────────────────────────────────────┘

相关阅读 ​

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