/moai todo NEW

次にやることを一行ずつ積んでおくバックログキューです。カンバンボードの backlog 列には担当セッションがおらず、誰も自分から仕事を流し込みません。したがって、カードをボードに入れることは常に人の判断であり、/moai todo がその窓口です。

情報

一行要約: /moai todo は「次に何をやるか書き留める行」です。項目を入れ、一覧を見て、終わったものを消し、次に着手するひとつを選びます。SPEC でも計画でもなく、選んだ瞬間にはじめて SPEC になります。

情報

スラッシュコマンド: Claude Code で /moai:todo を入力するとすぐ実行されます。/moai だけを入力すると、利用可能なすべてのサブコマンドの一覧が表示されます。

バックログの項目は意図の一行です。SPEC でも計画書でも見積もりでもありません。人がその項目を選び、リードセッションが plan セッションへディスパッチしてはじめて SPEC になります。

キューは意図的に薄く作られています。SPEC や git 履歴、ボードがよりよく記録するものは格納せず、人が次に何を望むかだけを残します。

flowchart TD
    Add["/moai todo 説明
項目追加"] --> Queue["バックログキュー"]
    Queue --> Pick["リードの質問チャネルで
人がひとつ選択"]
    Pick --> Plan["plan セッションへディスパッチ
ここで SPEC 作成"]
    Plan --> Spec["SPEC ID を項目に記録"]

# 項目追加
> /moai todo "認証ミドルウェアのエラー経路を整理"

# キューを表示
> /moai todo

項目の削除と次のカードの選択はスラッシュ表面にはありません。その2つは、下記のターミナル CLI(moai todo done、moai todo next)またはリードセッションを通じた選択が担います。

その他の引数の形は説明として扱われます。/moai todo CI キャッシュ不安定を解決 はエラーではなく項目追加です — 聞き間違えた場合のコストが、人が一行消すことだけだからです。

キューは .moai/state/kanban/backlog.json に保存されます。プロジェクト内にのみ存在し、コミットされません。

{
  "version": 1,
  "items": [
    {
      "id": "t1",
      "text": "認証ミドルウェアのエラー経路を整理",
      "added_at": "<RFC3339 時刻>",
      "spec_id": null,
      "state": "queued"
    }
  ],
  "findings": [
    {
      "subject_id": "t2",
      "related_id": "t1",
      "relation": "near-duplicate",
      "source": "mechanical",
      "score": 0.83,
      "note": "",
      "at": "<RFC3339 時刻>"
    }
  ]
}

ファイルは原子的に書かれます(一時ファイルに書いて名前を変えます)。書き込み途中で死んでもキューが途切れないためです。ファイルがなければエラーではなく空のキューであり、壊れたファイルは報告だけして触りません — ここに収められた人の意図は、再生できない唯一の値だからです。

キューはカードを追加するたび、そして moai todo analyze の実行時に自分自身を読み、似たカードを見つけて記録します。記録はカードを変えません — テキストも、順序も、状態も。

実際に何かを止めるのは一つだけです。すでに待機中または選択済みのカードと正規化後のテキストが完全に一致するカードは、追加そのものが拒否されます。拒否は何も消さず、キューファイルをバイト単位でそのまま残し、人には id ではなくエラーが見えます。それでも入れたいときは --force が入れ、強制された重複であることを記録に残します。

似ているが同一ではないカード（トークン集合 Jaccard 0.80 以上）はそのまま追加され、近接重複の記録だけが付きます。言葉が違えば意味が同じでも機械は気づきませんが、これは意図した限界です。この層が誤判定すると人が書いたカードが消えます。一方、意味を判定する moai todo relate は記録しか残さないので、そこでの誤りは一行で済みます。

contains · absorbs · replaces · conflicts の四つの関係は、人またはエージェントが手で書きます。名前に反して何も起こしません — absorbs と書いてもカードは吸収されません。どうするかは記録を読んで人が決め、実行は drop · edit · move で行います。

moai todo list は記録を該当カードの下にインデントした行として表示し、同じ組に人が書いた記録が一つもなければ machine-only を付けます。この印が言うのは「機械の記録しかない」ことだけで、「誰も確認していない」ではありません — CLI は自分を誰が呼んだかを知り得ないからです。

選択は、リードセッションの質問チャネルを通じて人が行います。リードがキューを選択肢として表示します — 古いものからひと項目ずつ、ツールが許す4つまで表示し、残りは本文に要約して何も隠されないようにします。/clear 後の初手としてキューを提示するときも同じ方法です。ターミナルから候補を確認したいだけなら、引数なしの moai todo next が同じ一覧を読み取り専用で出力します。

注意

選ぶ主体は人です。 事前選択せず、推定した優先度で並べ替えず、「上から順に」をデフォルトにしません。キューが空なら空と伝えて止まります — 空のバックログは正常な状態であって、仕事をでっち上げろという合図ではありません。

複数のカードを一度に承認することもできます。カードを指差すか、キューが空になるまで順に進めるよう伝える方法です。これも人の選択であり、一枚ずつの代わりに一度にしただけです。リードは承認された順にカードを入れ、再度尋ねません。ただしその承認が許す範囲はそれだけです — 項目を追加したり、順序を変えたり、承認範囲外の判断が必要になったカードを代わりに決める根拠にはなりません。

カードを選んだ後はこう続きます。

1. 選んだ項目を moai todo next <n> [--spec <SPEC-ID>] の一度のロックされた書き込みで picked とマークします。識別子が既知ならその場で添付します。
2. カンバンディスパッチ規約に従い plan セッションへ渡します。カードは plan 列に入り、SPEC 作成はここではなくあちらで行われます。
3. 選択時に識別子が不明だった場合は、判明した後で moai todo next <n> --spec <SPEC-ID> を再度実行して項目に添付します。この後続の添付を自動化する経路はありません — ディスパッチも後続添付も、リードセッションが行う指示であって、キューが自分で行うことではありません。

/moai todo はごく普通の単一セッションでもそのまま動きます — ただのキューだからです。ただしディスパッチはしません。同伴セッションがいなければ指示する相手がいないので、キューの読み書きまでがすべてで、残りは人が直接進めます。

• 作業管理ツールではありません。 優先度も担当者も期限も依存関係もありません。それらが必要な仕事はissueトラッカーや SPEC の領分です。
• ボードではありません。 カードがどの列にいるかはリードセッションと SPEC 状態が握っており、このファイルではありません。
• 進行中の仕事の原本ではありません。 カードに SPEC ができてからは SPEC 成果物が基準で、バックログ項目はそれを指す標識にすぎません。
• 勝手に埋まりません。 TODO コメントやオープンな issue、監査結果をツールが勝手に拾ってくることはありません。項目を入れるのは人です。
• 案内表面は切れます。 セッション開始時の要約・ステータスラインの TODO セグメント・自動ルーティングは、workflow.yaml の workflow.todo.enabled: false で切れます (設定ドキュメント 参照)。切ってもコマンドと動詞はそのまま動作します。

同じキューをターミナルからも操作できます。スラッシュコマンド /moai todo は Claude Code のチャットで、ターミナル CLI moai todo はシェルで呼ぶ別個の表面です — 同じファイルを扱いますが、文法は異なります。

# 項目追加 — 発行された id とキュー位置を一行で出力
$ moai todo add "認証ミドルウェアのエラー経路を整理"

# 2語以上なら add がなくても追加されます (自然言語フォールスルー)
$ moai todo rename のヒントが古い

# キューを表示 (id · 状態 · 本文) — 動詞なしの bare 呼び出しも同じ結果
$ moai todo
$ moai todo list

# 構造化レコードとして表示
$ moai todo list --json

# 項目削除 — 番号(t4)も明示的 id も受け付けます
$ moai todo done 4

# 待機中の項目を古いものから出力(読み取り専用)
$ moai todo next

# ひとつの項目を選択として記録 — SPEC 識別子も一緒に
$ moai todo next 4 --spec SPEC-AUTH-001

# 追加と選択を一度のロックされた書き込みで
$ moai todo add "グラフ問合せドキュメントを整理" --pick

# 選択マークを取り消します — まだ plan に渡っていないカードに
$ moai todo unpick 4

# キュー全体を再分析し、記録だけを残します（カードには触れません）
$ moai todo analyze

# 正確な重複でも追加します — 強制したことが記録されます
$ moai todo add "認証ミドルウェアのエラー経路を整理" --force

# 二枚のカードの関係を記録します（記録のみ。カードはそのまま）
$ moai todo relate t2 t1 --relation absorbs --note "t2 が t1 を含む"

# このカードについてキューが知っていることをすべて出力
$ moai todo why t1

# 記録を一つ削除します — 番号は why が出力するものです
$ moai todo unrelate 2

CLI はプロンプトを出しません。引数とフラグを受け取り一行を出力し、エラーは stderr へ — スクリプトや CI で安全に使える形です。

リンクされたワークツリーの中で実行しても、キューはプライマリチェックアウトのキューひとつに帰属します — リポジトリ 1 つにキュー 1 つという契約です。カードのワークツリーで moai todo add をすると、リードとフォアマンループが読む同じファイルに追加されます。git メタデータのないプロジェクトは ~/.moai/todo/<project-key>/backlog.json にキューを置きます。

両表面は同じ保存層を共有します。変更はキューファイル横のロックファイル(backlog.lock)を握った後、同ディレクトリの一時ファイルに書いて名前を変える原子的書き込みで反映され、読み取りはロックなしで行われます。項目 id はロック内で、ファイルに残った最高水準標識(last_seq)から発行されるため、削除された項目の id が再利用されることはありません。

情報

インストール済みバイナリ: CLI は main に反映済みで配信されます。すでにインストールされた moai バイナリは、再インストールしてはじめてこのコマンドを得られます。

• カンバンモード — バックログから出たカードが流れていくボード
• /moai 統合コマンド — サブコマンド全体の地図
• /moai plan — 選んだカードが SPEC になる段階