Skip to content

jj-flow ​

AI-Native 项目族研发编排工作流

通过自然语言对话,在多个关联仓库之间完成单仓需求闭环、同源跨仓迁移、多仓统筹派发与 Git 自动收工。所有进度以仓库内的计划文件、审查报告与 Git 提交为唯一凭据,随时可核对、随时可续接。

单仓闭环 · ralph

一句话提出需求,按“分析 → 计划 → 实施 → 验收 → 归档”五步落地,计划与过程记录完整保存在仓库中。

同源迁移 · same

把项目A 已经验证通过的能力,按项目B、项目C 各自的代码规范与目录结构适配过去,拒绝生搬硬套。

多仓调度 · dispatch

一次改动涉及多个项目时,先生成只读分支预览表,经你批准后再统一派发、独立跟踪验收状态。

证据门禁 · Evidence First

聊天口头声称“改完了”不算数;只有落盘的任务合同、只读审查记录与真实的 Git 提交才算通过。

支持的主流 AI 编程宿主

开箱支持 Codex(使用 $jj-… 前缀)、Claude Code、Grok、Qoder(使用 /jj-… 前缀),并同时提供 ~/.agents 兼容入口。无需记忆复杂命令行,在日常对话窗口里直接输入前缀即可调用。

三步快速上手 ​

  1. 安装对话入口:按 1 分钟安装与配置 在项目或全局执行一行 npx 命令,装好对话技能与子代理。
  2. 跑通第一个需求:跟随 第一次使用(完整实战),在当前业务仓库体验从提需求、自动实现到验收归档的全流程。
  3. 跨仓迁移与收工:对照下方选型表,用 same 将改好的功能同步到兄弟仓库,最后用 end 一键提交并合并到 dev 分支。

遇到分支拦截或收工报错时,可随时查阅 常见避坑与自检清单。拿不准该用哪个命令时,直接在对话里输入 $jj 或 /jj,由 jj 智能分流入口 帮你判断。

我该用哪个命令?(选型速查表) ​

日常研发只需要关注以下 6 个核心工作流入口:

你的目标场景推荐入口调用示例(Claude / Grok 将 $ 换为 /)核心行为与边界
登记新项目、补充跨仓知识库init$jj-init 当前仓加入全局地图,中文名「项目A」先生成预览提案,经你确认后写入 ~/.jj-flow/map.md
只在当前仓库开发或修复一个需求ralph$jj-ralph 登录后若密码过期,弹窗提醒用户改密执行五步任务闭环,归档后仍可随时接着改,不自动动 Git
对当前代码改动做一次独立审查review$jj-review 审一下刚才的密码过期弹窗改动派只读审查员检查代码并输出 [OK]、[WARN] 或 [BLOCK]
把项目A 做好的功能迁到项目B / 项目Csame$jj-same 交接到 项目B 项目C读取源仓提交与交接说明,按各目标仓原生写法适配并验证
多个项目需要统一预览、批准后再一起改dispatch$jj-dispatch 预览把依赖升级分发到项目A、项目B先给分支与模式预览表 → 你说“批准” → 分别派发与验收
把改好的代码提交、推送并合入集成分支end$jj-end 或 $jj-end integration=staging只操作 Git:提交本任务文件 → 推工作分支 → 合入 dev 并推送

一句话选型口诀

  • 改一个仓用 ralph;
  • 代码做完要检查用 review;
  • 搬到兄弟仓用 same;
  • 多仓先审批再统派用 dispatch;
  • 最后提交合分支用 end。

除了上述核心交付流,还提供 4 个可选辅助引擎(仅辅助本轮分析或方案探索,不直接替代 ralph 或 dispatch 的验收门禁):

  • team-coordinate:按当前问题动态拆分多个协作角色(如安全、性能、实现并行分析)。
  • team-lifecycle:按固定角色走“规格 → 计划 → 实现 → 测试 → 审查”标准化流水线。
  • team-swarm:针对复杂架构问题发起多假设探索与对抗评分,收敛出最优方案。
  • evaluated:基于真实交付记录做离线耗时与返工复盘。

核心工作流是如何串联的? ​

在实际的多端项目族(例如:项目A 为 PC 端、项目B 为 H5 端、项目C 为管理后台)中,各入口按照以下生命周期自然衔接:

text
[准备阶段]  $jj-init        将项目A / 项目B / 项目C 登记到本机项目地图 (~/.jj-flow/map.md)
               │
               ▼
[单仓交付]  $jj-ralph       在项目A 完成「分析 → 计划 → 编码 → 审查 → 验收 → 归档」
               │            (期间可随时调用 $jj-review 做只读审查,完成后用 $jj-end 提交)
               ▼
       ┌───────┴───────┐
       ▼               ▼
[同源迁移]          [多仓统筹调度]
$jj-same            $jj-dispatch
直接把项目A 的改动   先出多仓预览表 → 你批准后统一派发
适配到项目B / 项目C  并在调度账本中逐仓跟踪 VERIFIED 状态
       │               │
       └───────┬───────┘
               ▼
[收工合入]  $jj-end         在各仓库自动提交本任务文件、推送功能分支,并安全合入 dev 分支

全站文档导航 ​

章节分组适合读者包含内容与重点入口
开始首次接触 jj-flow 的开发者1 分钟安装、第一次使用(完整实战)、常见避坑与自检清单
工作流日常使用对话命令写代码的开发者命令总览与选型指南 及 11 个命令的详细步骤、对话实录与产物说明
概念想理解底层规则与目录结构的开发者核心术语表、证据门禁、目录布局、宿主与工作模式、知识库与记忆
维护者参与维护或调试 jj-flow 本身的人员系统架构、CLI 参考、维护指南、写作规范、站点部署、实验场规范
参考查阅架构演进与历史验收证据的深究者设计文档总览(含 Agent Harness 设计)、执行计划索引、ADR 索引,以及历史验收记录(真实 Host、M7 半真实 Host、H5 熵清理)

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