SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场jj-todo-workflow

jj-todo-workflow

编程与开发

查看项目

更新于 10-16 02:06

技能介绍

用途

JJ TODO Workflow 的核心思想是使用空修订（empty revisions）组成的有向无环图（DAG）作为 TODO 标记，表示待完成的任务，之后再回到这些修订中编辑，实际执行任务。这样就能实现带有清晰里程碑的结构化开发。修订描述（即提交信息）充当要实现内容的规格说明。JJ 让创建这种结构、随后填充每个修订变得容易。

该技能涉及两种角色：规划者（Planner，负责布置空修订及其规格）和执行者（Worker，负责实现它们）。根据情况，你可能只担任规划者、只担任执行者，或两者兼任。

主要能力

状态标志

使用描述前缀来跟踪状态，[task:*] 命名空间便于 grep 搜索并避免与其他约定冲突。允许的状态标志包括：

  • [task:draft]：已创建占位符，需要完整规格说明
  • [task:todo]：未开始，空修订且规格完整
  • [task:wip]：进行中
  • [task:blocked]：等待外部依赖
  • [task:standby]：等待某些决策（难以修复、实用性存疑等）
  • [task:untested]：实现完成，但测试不足，无法验证
  • [task:review]：需要审查（复杂代码、设计选择）
  • [task:done]：完成，所有验收标准均已满足

此顺序仅供参考：并非每个任务都必须经过所有这些步骤，也不一定按上述顺序。

辅助脚本

scripts/ 目录中的辅助脚本（需使用完整路径调用以避免 PATH 设置）：

  • jj-todo-create [--draft] <PARENT> <TITLE> [DESC]：创建 TODO（停留在 @）。使用 --draft 创建占位任务
  • jj-parallel-todos [--draft] <PARENT> <T1> <T2>...：创建并行 TODO。使用 --draft 创建占位任务
  • jj-todo-next [--mark-as STATUS] [REV]：审查规格、检查依赖、标记并可选移动
  • jj-flag-update <REV> <TO_FLAG>：更新状态标志（自动检测当前状态）
  • jj-find-flagged [FLAG]：查找带标志的修订

来自 working-with-jj 技能的额外有用脚本：

  • jj-show-desc [REV]：打印修订的描述

使用方式

快速开始

完整周期示例：

# 1. 规划：创建简单的 TODO 链
jj-todo-create @ "Add user validation" "Check email format and password strength"
# Created: abc123 (stays on current @)

jj-todo-create abc123 "Add validation tests" "Test valid/invalid emails and passwords"
# Created: def456 (@ still hasn't moved)

# 2. 开始处理第一个 TODO
jj edit abc123
jj-flag-update @ wip   # Now [task:wip]

# ... implement validation ...

# 3. 验证所有验收标准均已满足
make test  # Or equivalent in your project

# 4. 请求移动到下一个任务
jj-todo-next

# 5. 确认一切正确完成后，移动到下一个 TODO
jj-todo-next --mark-as done def456   # Marks abc123 as [task:done], starts def456 as [task:wip]

基本工作流

  1. 规划：创建 TODO 链（规划者）
jj-todo-create @ "Task 1: Setup data model" "...details..."
jj-todo-create <T1-id> "Task 2: Implement core logic" "..."
jj-todo-create <T2-id> "Task 3: Add API endpoints" "..."
jj-todo-create <T3-id> "Task 4: Write tests" "..."
  1. 工作：编辑每个 TODO（执行者）
jj-show-desc <task-id>
jj edit <task-id>
jj-flag-update @ wip
# ... implement ...
jj-flag-update @ untested
  1. 完成并移动到下一个（执行者）

jj-todo-next 脚本用于平滑“过渡到下一个任务”的过程。

无参数时：打印当前任务描述以供审查，打印下一个可能任务。

有参数时：更新当前任务标志，移动（jj edit）到下一个任务，将新任务标志更新为 [task:wip]。

jj-todo-next --mark-as done abc123

规划并行任务（DAG）

创建可独立工作的分支：

jj-todo-create @ "Task 1: Core infrastructure"
jj-todo-create <T1-id> "Task 2: Base components"
jj-parallel-todos <T2-id> "Widget A" "Widget B" "Widget C"
jj new --no-edit <A-id> <B-id> <C-id> -m "[task:todo] Integration of widgets\n\n..."

结果形成 DAG 结构，无需 rebase——直接指定父修订。

编写良好的 TODO 描述

结构包括：短标题（< 50 字符）、## Context（为什么存在此任务）、## Requirements（具体要求）、## Implementation notes（提示、约束或方法）、## Acceptance criteria（如何知道完全完成）。

描述应尽可能自给自足，让上下文很少的代理也能获得开始工作所需的所有信息。避免冗余，尽可能链接到已有规格文档或代码库中的相关示例。链接时避免使用行号等不稳定引用，优先使用章节名、标签引用或函数/类名。

AI 辅助 TODO 工作流

  • 监督代理（Supervisor Agent）进行初始规划并创建 TODO 修订图
  • 监督代理确保所有 [task:draft] 任务在工作者开始前被填充并标记为 [task:todo]
  • 子代理按顺序“运行”通过图，实现每个修订
  • 子代理只应处理 [task:todo] 任务（规格完整），绝不处理 [task:draft] 任务
  • 监督代理可以审查差异和笔记，必要时将任务切回 [task:wip] 或 [task:draft]

重要：子代理必须按顺序处理任务，不能并行。在同一仓库上并发运行多个代理会因争夺工作副本（@）而产生冲突。如果确实需要并行工作，必须使用 JJ 工作区（相当于 git worktree）隔离每个代理。但除非人类用户明确同意，否则不要创建工作区，因为这会显著增加复杂性，且该部分仍处于 beta 阶段。

何时停止并报告（执行者）

仅遵循规定的工作流。如果遇到任何问题，停止并向用户报告，尤其是：在错误的修订中做了更改、注意到之前的工作需要修复、不确定如何继续、依赖或需求不明确。不要尝试使用此工作流中未明确出现的任何 JJ 操作来修复问题。

记录实现偏差（执行者）

当实现与规格不同时，无论原因如何，都要记录并说明理由，在实现后添加笔记，创建决策审计轨迹。

适用场景

  • 需要结构化里程碑和清晰规格说明的开发流程
  • 与 AI 子代理配合，由监督代理规划、子代理顺序执行
  • 需要可审计的开发决策记录
  • 使用 Jujutsu 版本控制系统的项目

限制

  • 依赖 Jujutsu（JJ）版本控制系统
  • 子代理必须顺序工作，并行需要 JJ 工作区且处于 beta 阶段
  • 辅助脚本需使用完整路径调用
  • 部分脚本来自 working-with-jj 技能
  • 未提供具体的安装命令、收费信息或平台支持细节