Skip to main content

/moai todo NEW

更新 2026-10-17 17分で読めます GitHub で編集 ↗
NEW · v3.1
情報
moai gtd と /moai gtd は、既存の自動化やスクリプト向けの 互換入口 として引き続き完全にサポートされます。正式名称は /moai todo と moai todo です。どちらも同じ SQLite キュー、カード ID、並び順、アーカイブ・復元動作を使います。

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

情報
一行要約: /moai todo は次に取り組む作業を記録するキューです。項目を追加し、一覧を確認し、完了したカードをアーカイブして、次のカードを選びます。選択だけでは SPEC は作成されず、カードの分類によって手順が決まります。
情報
スラッシュコマンド: Claude Code で /moai:todo を入力するとすぐ実行されます。/moai だけを入力すると、利用可能なすべてのサブコマンドの一覧が表示されます。

概要

バックログの項目は意図の一行であり、SPEC や計画書ではありません。選択後、Class A は直接完了処理へ、Class B は SPEC なしで run → sync へ、Class C は plan で SPEC を作成してから run → sync へ進みます。

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

flowchart TD
    Add["/moai todo 説明
項目追加"] --> Queue["バックログキュー"] Queue --> Pick["ファクトリーリーダーの質問チャネルで
人がひとつ選択"] Pick --> Class{"カードの分類"} Class --> A["A: 直接完了処理"] Class --> B["B: run → sync"] Class --> Plan["C: plan → run → sync
plan で SPEC 作成"] Plan --> Spec["SPEC ID を項目に記録"]

使い方

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

# キューを表示
> /moai todo
呼び出し動作
/moai todo "<説明>"項目をキューの末尾に追加し、追加された項目と位置を表示します。
/moai todoキューを順に、位置番号付きで表示します。

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

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

状態ファイル

通常のプロジェクトディレクトリであれば、キューは ~/.moai/db/<project-key>/todo/backlog.db という 1 つの SQLite データベースに保存されます。ただしプロジェクトが一時ディレクトリ(os.TempDir(), /tmp, /var/folders の下)を起点とする場合は、絶対パスの MOAI_HOME 上書きがなければホームではなく <base>/.moai/state/todo/backlog.db にプロジェクトローカルで保存されます。プロジェクトキーによってリンクされた worktree がホーム内の 1 つのキューに結び付けられ、データベースはコミットされません。下の形は moai todo list --json と moai todo export-json が出力するレコードの形で、データベースも同じフィールドを持ちます。移行とダウングレードの方法は、プロジェクト内の .moai/docs/todo-queue-storage.md にあります。

データベースのパスは推測せず、moai paths で確認します。~/.moai/db/todo.db のように推測したパスを sqlite3 で開くと空のファイルが作られるため、開きません。直接読む必要があるときは、.db、.db-wal、.db-shm を一緒にコピーしたスナップショットだけを読み、普段は moai todo list --json や moai factory status などの CLI を優先します。

json
{
  "version": 1,
  "project_uuid": null,
  "items": [
    {
      "id": "t1",
      "text": "認証ミドルウェアのエラー経路を整理",
      "added_at": "<RFC3339 時刻>",
      "spec_id": null,
      "state": "queued",
      "card_uuid": null
    }
  ],
  "findings": [
    {
      "subject_id": "t2",
      "related_id": "t1",
      "relation": "near-duplicate",
      "source": "mechanical",
      "score": 0.83,
      "note": "",
      "at": "<RFC3339 時刻>"
    }
  ],
  "runtime": {
    "runs": [
      {
        "project_uuid": null,
        "run_id": "run-1",
        "backend": "claude",
        "manifest_json": "{}"
      }
    ],
    "assignments": [
      {
        "project_uuid": null,
        "card_uuid": null,
        "run_id": "run-1",
        "card_id": "t1",
        "owner_label": "lane-1",
        "reported_state": "picked",
        "event_kind": "card.assigned",
        "provenance_json": "{}"
      }
    ]
  }
}
フィールド意味
id追加時に付く短く安定した識別子。削除後に再利用されません。
project_uuid / card_uuidプロジェクトとカードの永続 identity です。identity を持たない旧データも list --json ではキーを省略せず null を返し、この純粋な読み取りでは UUID の発行もデータベースの変更も行いません。その後、許可された書き込みが成功すると canonical lowercase UUIDv7 文字列で埋まります。Git リポジトリと Git を使わない通常のフォルダーに同じ契約を適用します。
spec_idSPEC 識別子への任意の接続です。選択時に --spec で渡せばそのとき埋まり、不明なままなら picked 状態でも null のままです。
runtime最新の実行開始とカード割り当ての報告です。runs と assignments は常に配列で、各 UUID は Todo identity を論理的に投影します。runtime テーブルに UUID 列を別途保存しません。reported_state は報告値であり、カードの完了状態を決める権限ではありません。
findingsカードの組についての記録です。関係はどちらか一方ではなく二枚の間の性質なので、項目ではなくここに置かれます。常に配列です — この機能より前に書かれたファイルも空配列で読み込まれるため、「記録がない」と「そんな機能がない」を取り違える余地がありません。source は機械が測った mechanical か、人やエージェントが書いた agent です。カードがファイルから消えれば、そのカードを指す記録も一緒に消えます。
stateライフサイクルの判別子です。queued · picked · dropped のいずれかで、「まだバックログの項目」と「すでにレーンに渡ったカード」を分けるのはこの値です。選んだ項目もファイルに残り、何が進行中かが見えます。項目が生きているキューから外れる方法は moai todo done ひとつだけで、人が直接実行します — 仕事が終わっても自動的に消える経路はありません。done はカードとそれを指す記録を削除せず、アーカイブします: list · next · why · analyze には現れなくなりますが、moai todo undone <n> が元の位置ごとカードと記録の両方を復元します。破棄はアーカイブとは違います: moai todo drop <n> "<理由>" はカードを生きているキューのファイルに残したまま dropped へ移し、理由をテキストの先頭に付けます。moai todo undrop <n> がそれを正確に元へ戻します。dropped のカードは選択候補から外れます。

変更はキューのロックを取得し、WAL モードの SQLite トランザクションで反映します。キューが存在しなければ空のキューとして扱い、読み取れないデータや壊れたデータはエラーを報告して保持します。Web コンソールも読み取り失敗を 0 件と表示せず、読み取れなかったことを案内します。

自動分析

キューはカードを追加するたび、そして 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. カードの分類に従います。Class A は直接完了処理へ、Class B は SPEC なしで run → sync へ、Class C は plan で SPEC を作成して run → sync へ進みます。
  3. SPEC が必要なカードでは、識別子が決まり次第 moai todo next <n> --spec <SPEC-ID> で関連付けます。この操作は明示的に行います。選択済みのカードに SPEC がなくても正常な場合があります。

ファクトリーモードの外で

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

境界

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

CLI 表面

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

bash
# 項目追加 — 発行された 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 undone 4

# テキストがその接頭辞で始まるときだけ実行 — 誤ったカードを閉じる事故を防ぐ
$ moai todo done 4 --expect "auth middleware"

# 着地したかを尋ね、「着地していない」という肯定的な答えが返ったときだけ拒否
$ moai todo done 4 --require-landed

# 着地したカードを一括クローズ(リーダー専用、バッチpush確認後)— まずドライラン
$ moai todo auto-done --fetch --dry-run
$ moai todo auto-done --fetch

# 待機中の項目を古いものから出力(読み取り専用)
$ 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
コマンド動作
moai todo (bare)キューを出力します。list と同じ出力です。
moai todo <2語以上>自然言語をそのまま項目として追加します。1語(動詞の打ち間違いを含む)は追加ではなくエラーになります。動詞のような最初のトークンの後にカード id が続く場合(moai todo pick t151)は打ち間違いの動詞と見なしてエラーです — 文中で id に触れるだけのカードはそのまま追加されます。
moai todo add "<text>" [--pick]項目を追加し、発行された id と位置を出力します。--pick を付けると追加と選択マークが一度のロックされた書き込みで行われます。
moai todo list / --jsonキューを表示します。--json はレコード全体を JSON で出力します。
moai todo done <n> [--expect <prefix>] [--require-landed]n 番の項目をロックの下で生きているキューから外します。明示的な t<n> id 推奨 — 同時追加で位置が動きうるためです。カードとそれを指すすべての記録は削除ではなくアーカイブされ、undone が両方を復元します。アーカイブされた行は list · next · why · analyze および重複判定の入力には現れません。--expect <prefix> はカードのテキストがその接頭辞で始まらない限り拒否します — 誤ったカードを閉じる事故への安全策です。--require-landed は着地判定に問い合わせ、「着地していない」という肯定的な答えが返ったときだけ拒否し、判定が不確実なときは通過させます — この判定は、答えた ref 上のコミットの件名が 6 つの帰属位置のうちのどれかでカードを指すかだけを見ます(慣例的なコミットスコープ、末尾括弧クレジット、クレジットに続く PR 参照、カード主導マージ、統合マージの末尾括弧内カードトークン、merge: <card>)。本文での言及、文の途中での言及、ブランチ名は何も数えません — 帰属とはメッセージのどこかに現れるトークンではなく、件名の中の位置です。ref はプロジェクト設定(git_strategy.worktree_base_branch)→ refs/remotes/origin/HEAD → 組み込み既定値(origin/main)の順に決まり、設定なしで下位の段階が答えたときはその出所を標準エラー出力に知らせます。フラグがなければ done は着地クエリを一切実行せずコストも増えず、どの拒否経路でもキューの記録はバイト単位で変わりません。成功したすべての done は標準出力に着地判定トークンをちょうど一つ残します — フラグがあれば `done landing=landed
moai todo undone <n>アーカイブされたカードを、それを指すすべての記録とともに、元の位置のまま生きているキューへ復元し、アーカイブ項目を空にします。done の後に undone を実行すると、キューの記録は正確に同じバイト列に戻ります。id がその間に別の生きているカードへ再発行されていた場合は、その衝突を名指しして拒否され、生きているカードは変更されません。
moai todo next待機中の項目を古いものから表示します。読み取り専用です。
moai todo next <n> [--spec <SPEC-ID>]項目を picked とマークし、--spec を渡すと識別子をそのまま記録します。一度のロックされた書き込みで行われます。
moai todo unpick <n>picked マークを取り消します。選択自体が人の判断なので、取り消しも人が直接行います。
moai todo drop <n> "<理由>" [--expect <prefix>]待機中のカードを dropped へ移し、テキストの先頭に [DROPPED — <理由>] の目印を付けます。引数は2つとも必須で、理由が空、または ] を含む場合は拒否します。カードはファイルに残り、選択候補から外れるだけです。--expect はカードのテキストがその接頭辞で始まるときだけ実行します。
moai todo undrop <n> [--expect <prefix>]dropped のカードを queued に戻し、目印があれば取り除きます。判断の基準は目印ではなく状態なので、手で dropped と書いたカードもテキストをそのままに復帰します。drop の正確な逆操作です。
moai todo edit <n> "<text>" [--expect <prefix>]カードのテキストだけを書き換えます。id · added_at · state · spec_id は保たれるため、done してから再追加する場合のようにカードの同一性が変わることはありません。確認行には新しいテキストと以前のテキストが併記されます。
moai todo move <n> (--top | --bottom | --before <m> | --after <m>)キューファイルの順序の中でカードの位置を動かします。行き先フラグはちょうど1つ必要で、無い場合も2つある場合も不正な呼び出しとして拒否します。項目を並べ替えるだけで何も削除・変更しないので、誤って動かしたらもう一度動かして戻します。
moai todo add "<text>" --force機械が正確な重複と読んだカードもそのまま追加します。強制された重複という記録が残るので、衝突は見えたままになります。
moai todo analyzeキュー全体を再分析し、記録だけを残します。追加・削除・並べ替え・編集は行わず、再実行しても同じ記録が二度積まれることはありません。
moai todo relate <a> <b> --relation (contains | absorbs | replaces | conflicts) [--note <text>]二枚のカードの関係を一つ記録します。記録のみなので両方のカードはそのままで、absorbs が吸収を実行することはありません。
moai todo unrelate <index>指定した記録を一つ削除します。番号は why が出力するものです。カードは変わりません。
moai todo why <n>そのカードを指す記録をすべて出力します。なければ「ない」と明示します — 何も出力しなければ故障と区別がつかないからです。
moai todo export-json生きているキューを旧形式の backlog.json としてデータベースの横に書き出します。データベースを知らない以前のリリースに読ませるためのものです。実行した瞬間のコピーであって実時間の鏡ではないので、バイナリを入れ替える直前に書き出してください。生きている項目と違い、アーカイブされたカードはこのエクスポートに含まれます — ただし出力するレコードに実際にアーカイブ行があるときは、アーカイブ機能を知らないバイナリが最初の書き込みでそのフィールドを捨てることを stderr で知らせます。以降の todo 動詞はこのファイルを置かれた場所にそのまま残します。読み取り動詞である list・show・why・pr・history はそれに加えて、データベースの横にあるこのファイルがキューではないことを stderr で知らせます。古いエクスポートを生きた状態と取り違えないためです。

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

リンクされた worktree の中で実行しても、キューはプライマリチェックアウトの 1 つのプロジェクトキーに帰属します — リポジトリ 1 つにキュー 1 つという契約です。カードの worktree で moai todo add をすると、リーダーとフォアマンループが読む同じデータベースに追加されます。git メタデータのないプロジェクトも同じホーム構成を使います — ただし一時ディレクトリを起点とするプロジェクトは、絶対パスの MOAI_HOME 上書きがなければ <base>/.moai/state/todo/backlog.db を使います。

両表面は同じ保存層を共有します。変更はデータベース横のロックファイル(backlog.lock)を握った後、WAL モードの SQLite トランザクション 1 つで反映され、読み取りはロックを取りません。項目 id はファイルに残った最高水準標識(last_seq)から発行されますが、この値は挿入と同じトランザクション内で進み、id には UNIQUE 制約が掛かっているため、プロセスが変更途中で死んでも削除された項目の id が再利用されることはありません。

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

関連ドキュメント