看板术语
介绍看板模式的文档与运维备忘共用一套九个词的词汇表 — 无论打开看板、链还是会话启动器的指南,出现的都是同一批词。本页把这些词集中在一处定义。每个条目是一行定义加一个示例;其余文档都以这些含义为前提。
先从最容易绊住人的地方说起:泳道 (lane) 和列 (column) 是两个不同的词。二者的区别在下面单独一节展开。
看板固定为五列:
flowchart TD
Backlog["backlog — 队列
(没有归属会话)"]
Plan["plan 列
(plan 伴随会话)"]
Run["run 列
(run 伴随会话)"]
Sync["sync 列
(sync 伴随会话 + 评审判定)"]
Done["done — 终点
(不向这里派发任何东西)"]
Backlog --> Plan --> Run --> Sync --> Donebacklog 和 done 刻意不设归属会话。中间三列各自对应一个伴随角色,这让派发变成一次查表而不是一个决定 — 卡片在哪一列,就决定了它发给谁。review 列并不存在:评审判定由 sync 关卡吸收,由 sync 阶段亲自运行评审视角。
| 词 | 含义 | 示例 |
|---|---|---|
| 泳道 (lane) | 把一张卡片从头送到尾的一条并行工作流:一个会话配一个工作树。就像实体看板上的泳道一样,每条流各走各的车道,绝不共享工作树。“泳道内验证” (lane-local verification) 指该泳道只跑自己的改动可能影响的测试。 | run 会话在工作树 .claude/worktrees/t0 里干活,这就是一条泳道 |
| 卡片 (card) | 看板上的一个工作单元。运维者用 /moai todo "<描述>" 投入,以短ID相称。一张卡片拥有一个工作树、一份进度记录和它的完成证据。 | t0 — 一行修复的卡片 |
| 列 (column) | 看板上的一个阶段,顺序固定:backlog → plan → run → sync → done。中间三列各自对应一个伴随角色。 | /moai run <SPEC-ID> 发生在 run 列 |
| 待办 (backlog) | 看板的入口队列。刻意不设归属会话 — 工作只有运维者亲手投入才会进入看板。 | /moai todo "rename hint is stale" 向待办追加一张卡片 |
| 主导会话 (lead) | 唯一的协调会话 (moai cc -k)。只凭自己读到的证据把卡片移入下一列,在阶段之间请运维者对相应会话执行 /clear,并且从不亲自写代码。 | 把一张卡片连同工作树指示一起派发出去的那个会话 |
| 伴随会话 (companion) | 由人亲手、一次一个终端启动的工作会话 (moai cc -k --name <role>),一次承担一列的工作。名字只用角色名;同一个角色名已被占用时,下一个会话顺次拿编号。 | plan、run、sync |
| 运行ID (run-id) | 主导会话启动时给出的短标识符。它只存在于主导套接字路径和 MOAI_KANBAN_ID 中,任何会话名都不携带它,主导会话也不例外 —— 所有会话都以角色名相称。 | 主导会话打印的 a1b2c3;会话名本身是 lead |
| 工作树 (worktree) | 卡片工作发生的隔离检出。通过启动器进入 (moai cc -w <name> / EnterWorktree) — 绝不用 raw git worktree add 创建。目录名承载卡片 ID,分支名则用能看出做了什么的 WT-<slug> 形式 — 至多 3 个连字符片段、至多 24 个字符,且不放卡片 ID。工作树比阶段活得久:一棵树从run贯穿到sync。 | 分支 WT-todo-queue 上的 .claude/worktrees/t0 |
| 派发 (dispatch) | 主导会话发给某个伴随会话的指示。不是工作的副本而是指针 — 卡片ID、SPEC ID、阶段命令、完成信号。用运维者的对话语言书写。 | “card: t0 — wt: EnterWorktree(t0) … evidence: .moai/reports/t0/” |
列 (column) 指工作的一个阶段;泳道 (lane) 指载着一张卡片穿过这些阶段的主体。一个是看板上的停靠站,另一个是穿过停靠站的路线。
flowchart TD
subgraph LaneA["泳道 — 卡片 t0: run 会话 + worktrees/t0"]
A0["卡片 t0"] --> A1["实现与验证
只发生在 worktrees/t0 里"]
end
subgraph LaneB["泳道 — 卡片 t1: 第二个 run 会话 + worktrees/t1"]
B0["卡片 t1"] --> B1["实现与验证
只发生在 worktrees/t1 里"]
end两条泳道可以同时流向同一块看板,并且从头到尾不进入彼此的工作树。这正是并行得以安全的原因 — 任何泳道的提交都不会漏进另一条泳道的工作树。
一个每个词都出现一次的真实流程:
- 运维者用
/moai todo "rename hint is stale"把卡片t0放进待办。 - 主导会话从队列里选出
t0,把它派发给 plan 伴随会话。 plan伴随会话写好SPEC后,主导会话亲自读证据,把卡片移入下一列。run在工作树.claude/worktrees/t0里实现,分支名不放卡片 ID,而是写清做了什么(用WT-todo-queue,不用WT-t0) — 这个会话与工作树的对子就是泳道,验证也在泳道内进行(只跑改动可能影响的测试)。主导会话启动时打印的a1b2c3就是运行ID,而会话名本身是lead。- sync 列照同样方式通过 —— 期间 sync 关卡吸收评审判定 —— sync 开出PR后,卡片抵达done。
在这整个过程中,卡片的工作只发生在 .claude/worktrees/t0 里,从头到尾不与并行泳道的工作树相混。
- 看板模式 — 进入条件、Origin-Trail Chain 设计、链的阶段
/moai todo— 把卡片放上看板的待办队列- Harness 工程学 — 阶段链与观测如何架在 Harness 设计之上