dex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Coordination with dex

使用dex进行Agent协作

Command Invocation

命令调用

Use

dex

directly for all commands. If not on PATH, use

npx @zeeg/dex

instead.

bash

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

直接使用

dex

执行所有命令。如果未在PATH中，可改用

npx @zeeg/dex

。

bash

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

Core Principle: Tickets, Not Todos

核心原则：工单而非待办事项

Dex tasks are tickets - structured artifacts with comprehensive context:

Name: One-line summary (issue title)
Description: Full background, requirements, approach (issue body)
Result: Implementation details, decisions, outcomes (PR description)

Think: "Would someone understand the what, why, and how from this task alone?"

Dex任务是工单——包含全面上下文的结构化工件：

名称：单行摘要（对应议题标题）
描述：完整背景、需求、实现方案（对应议题正文）
结果：实现细节、决策、产出（对应PR描述）

思考：“仅通过这个任务，其他人能否理解工作内容、原因和实现方式？”

Dex Tasks are Ephemeral

Dex任务是临时的

Never reference dex task IDs in external artifacts (commits, PRs, docs). Task IDs like

abc123

become meaningless once tasks are completed. Describe the work itself, not the task that tracked it.

切勿在外部工件（提交记录、PR、文档）中引用dex任务ID。类似

abc123

的任务ID在任务完成后会失去意义。应描述工作本身，而非跟踪它的任务。

When to Use dex

何时使用dex

Use dex when:

Breaking down complexity into subtasks
Work spans multiple sessions
Context needs to persist for handoffs
Recording decisions for future reference

Skip dex when:

Work is a single atomic action
Everything fits in one session with no follow-up
Overhead exceeds value

使用dex的场景：

将复杂工作分解为子任务
工作跨多个会话进行
上下文需要保留以便交接
记录决策供未来参考

无需使用dex的场景：

工作是单一原子操作
所有内容可在一个会话内完成且无后续工作
成本超过价值

dex vs Built-in Task Tools

dex与内置任务工具对比

Some AI agents (like Claude Code) have built-in task tools. These are session-only and not the same as dex.

	dex	Built-in Task Tools
Persistence	Files in `.dex/`	Session-only
Context	Rich (description + context + result)	Basic
Hierarchy	3-level (epic → task → subtask)	Flat

Use dex for persistent work. Use built-in task tools for ephemeral in-session tracking only.

部分AI Agent（如Claude Code）拥有内置任务工具。这些工具仅适用于当前会话，与dex不同。

	dex	内置任务工具
持久性	存储在 `.dex/` 目录的文件中	仅会话有效
上下文	丰富（描述+上下文+结果）	基础
层级结构	三级（Epic → 任务 → 子任务）	扁平化

使用dex处理持久化工作。内置任务工具仅用于临时的会话内跟踪。

Basic Workflow

基础工作流

Create a Task

创建任务

bash

dex create "Short name" --description "Full implementation context"

Description should include: what needs to be done, why, implementation approach, and acceptance criteria. See examples.md for good/bad examples.

bash

dex create "简短名称" --description "完整实现上下文"

描述应包含：需要完成的内容、原因、实现方案以及验收标准。可查看examples.md中的正反示例。

List and View Tasks

列出和查看任务

bash

dex list                  # Pending tasks
dex list --ready          # Unblocked tasks
dex show <id>             # Full details

bash

dex list                  # 待处理任务
dex list --ready          # 未阻塞任务
dex show <id>             # 完整详情

Complete a Task

完成任务

bash

dex complete <id> --result "What was accomplished" --commit <sha>

GitHub/Shortcut-linked tasks require either

--commit <sha>

--no-commit

Use
```
--commit <sha>
```
when you have code changes (issue closes when merged)
Use
```
--no-commit
```
for non-code tasks like planning or design (issue stays open)

Always verify before completing. Results must include evidence: test counts, build status, manual testing outcomes. See verification.md for the full checklist.

bash

dex complete <id> --result "完成的工作内容" --commit <sha>

关联GitHub/Shortcut的任务需要指定

--commit <sha>

或

--no-commit

：

当有代码变更时使用
```
--commit <sha>
```
（合并后议题会自动关闭）
对于规划或设计等非代码任务，使用
```
--no-commit
```
（议题保持开放状态）

完成前务必验证。结果必须包含验证证据：测试数量、构建状态、手动测试结果。完整检查清单请查看verification.md。

Edit and Delete

编辑和删除

bash

dex edit <id> --description "Updated description"
dex delete <id>

For full CLI reference including blockers, see cli-reference.md.

bash

dex edit <id> --description "更新后的描述"
dex delete <id>

包含阻塞项在内的完整CLI参考，请查看cli-reference.md。

Understanding Task Fields

理解任务字段

Tasks have two text fields:

Name: Brief one-line summary (shown in
```
dex list
```
)
Description: Full details - requirements, approach, acceptance criteria (shown with
```
--full
```
)

When you run

dex show <id>

, the description may be truncated. The CLI will hint at

--full

if there's more content.

任务包含两个文本字段：

名称：简短单行摘要（在
```
dex list
```
中显示）
描述：完整详情——需求、实现方案、验收标准（使用
```
--full
```
参数查看）

运行

dex show <id>

时，描述可能会被截断。如果有更多内容，CLI会提示使用

--full

参数。

Gathering Context

收集上下文

When picking up a task, gather all relevant context:

bash

dex show <id> --full              # Full task details
dex show <parent-id> --full       # Parent context (if applicable)
dex show <blocker-id> --full      # What blockers accomplished

Before starting, verify you can answer:

What needs to be done specifically?
Why is this needed?
How should it be implemented?
When is it done (acceptance criteria)?

If any answer is unclear:

Check parent task or completed blockers for more details
Suggest entering plan mode to flesh out requirements before starting

Proceed without full context when:

Task is trivial/atomic (e.g., "Add .gitignore entry")
Conversation already provides the missing context
Description itself is sufficiently detailed

接手任务时，收集所有相关上下文：

bash

dex show <id> --full              # 完整任务详情
dex show <parent-id> --full       # 父任务上下文（如有）
dex show <blocker-id> --full      # 阻塞任务的完成情况

开始前，确认你能回答以下问题：

内容：具体需要完成什么？
原因：为什么需要做这件事？
方式：应该如何实现？
完成标准：什么时候算完成（验收标准）？

如果有任何问题不明确：

查看父任务或已完成的阻塞任务以获取更多细节
建议进入规划模式，在开始前完善需求

无需完整上下文即可推进的场景：

任务是微小/原子操作（例如“添加.gitignore条目”）
对话中已提供缺失的上下文
描述本身已足够详细

Task Hierarchies

任务层级结构

Three levels: Epic (large initiative) → Task (significant work) → Subtask (atomic step).

Choosing the right level:

Small feature (1-2 files) → Single task
Medium feature (3-7 steps) → Task with subtasks
Large initiative (5+ tasks) → Epic with tasks

bash

undefined

分为三级：Epic（大型项目） → 任务（重要工作项） → 子任务（原子步骤）

选择合适的层级：

小型功能（1-2个文件）→ 单个任务
中型功能（3-7个步骤）→ 带子任务的任务
大型项目（5个以上任务）→ 带任务的Epic

bash

undefined

Create subtask under parent

在父任务下创建子任务

dex create --parent <id> "Subtask name" --description "..."


For detailed hierarchy guidance, see [hierarchies.md](hierarchies.md).

dex create --parent <id> "子任务名称" --description "..."


层级结构的详细指导，请查看[hierarchies.md](hierarchies.md)。

Recording Results

记录结果

Complete tasks immediately after implementing AND verifying:

Capture decisions while fresh
Note deviations from plan
Document verification performed
Create follow-up tasks for tech debt

Your result must include explicit verification evidence. Don't just describe what you did—prove it works. See verification.md.

在实现并验证完成后立即标记任务完成：

趁记忆清晰时记录决策
标注与计划的偏差
记录执行的验证操作
为技术债务创建后续任务

结果必须包含明确的验证证据。不要只描述做了什么——要证明它有效。详情请查看verification.md。

Commit Messages with GitHub Issues

关联GitHub议题的提交信息

When a task is linked to a GitHub issue (shown in

dex show

output), include issue references in commit messages:

Root tasks (the task itself has GitHub metadata): Use
```
Fixes #N
```
- This closes the issue when merged
Subtasks (parent/ancestor has GitHub metadata): Use
```
Refs #N
```
- This links to the issue without closing it

Check

dex show <id>

for GitHub issue info before committing. The "(via parent)" indicator means use

Refs

, direct metadata means use

Fixes

当任务关联到GitHub议题时（可在

dex show

输出中查看），请在提交信息中包含议题引用：

根任务（任务本身带有GitHub元数据）：使用
```
Fixes #N
```
- 合并后会自动关闭议题
子任务（父/祖先任务带有GitHub元数据）：使用
```
Refs #N
```
- 仅关联议题，不会关闭它

提交前请查看

dex show <id>

中的GitHub议题信息。若显示“(via parent)”则使用

Refs

，直接显示元数据则使用

Fixes

。

Best Practices

最佳实践

Right-size tasks: Completable in one focused session
Clear completion criteria: Description should define "done"
Don't over-decompose: 3-7 children per parent
Action-oriented descriptions: Start with verbs ("Add", "Fix", "Update")
Verify before completing: Tests passing, manual testing done

合理拆分任务：可在一个专注会话内完成
明确完成标准：描述中应定义“完成”的状态
避免过度拆分：每个父任务下保留3-7个子任务
描述采用动作导向：以动词开头（如“添加”、“修复”、“更新”）
完成前验证：测试通过，已执行手动测试

Additional Resources

额外资源

cli-reference.md - Full CLI documentation
examples.md - Good/bad context and result examples
verification.md - Verification checklist and process
hierarchies.md - Epic/task/subtask organization

cli-reference.md - 完整CLI文档
examples.md - 上下文和结果的正反示例
verification.md - 验证检查清单和流程
hierarchies.md - Epic/任务/子任务的组织方式