/moai todo NEW
情報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 を項目に記録"]# 項目追加
> /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 を優先します。
{
"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_id | SPEC 識別子への任意の接続です。選択時に --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 が同じ一覧を読み取り専用で出力します。
注意選ぶ主体は人です。 事前選択せず、推定した優先度で並べ替えず、「上から順に」をデフォルトにしません。キューが空なら空と伝えて止まります — 空のバックログは正常な状態であって、仕事をでっち上げろという合図ではありません。
複数のカードを一度に承認することもできます。カードを指差すか、キューが空になるまで順に進めるよう伝える方法です。これも人の選択であり、一枚ずつの代わりに一度にしただけです。リーダーは承認された順にカードを入れ、再度尋ねません。ただしその承認が許す範囲はそれだけです — 項目を追加したり、順序を変えたり、承認範囲外の判断が必要になったカードを代わりに決める根拠にはなりません。
カードを選んだ後はこう続きます。
- 選んだ項目を
moai todo next <n> [--spec <SPEC-ID>]の一度のロックされた書き込みでpickedとマークします。識別子が既知ならその場で添付します。 - カードの分類に従います。Class A は直接完了処理へ、Class B は SPEC なしで run → sync へ、Class C は plan で SPEC を作成して run → sync へ進みます。
- 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で切れます (設定ドキュメント 参照)。切ってもコマンドと動詞はそのまま動作します。
同じキューをターミナルからも操作できます。スラッシュコマンド /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 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 |
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バイナリは、再インストールしてはじめてこのコマンドを得られます。
- ファクトリーモード — バックログから出たカードを引き継ぐレーン
/moai統合コマンド — サブコマンド全体の地図/moai plan— 選んだカードが SPEC になる段階