Skip to main content

/moai goal NEW

更新 2026-08-13 8分で読めます GitHub で編集 ↗
NEW · v3.1

終わる条件だけ宣言すれば、セッションがその条件が成立するまでターンを繋ぐ条件宣言型の自律ループです。毎ターンの終わりに評価器が条件を検査し、条件が満たされればループが自ら止まります。ユーザーが毎段階で「続ける」を押す必要はありません。

情報
v3.1 新規: 無限に持続できるゴール(–max-turns 0)、半自律モードの流れ、そしてブロック上限の自動調整が今回のリリースで追加されました。

このページが扱うこと

/moai goalはセッションに完了条件を1つ登録して武装(arm)します。条件文は2種類の述語にパースされます。

  • 機械条件 (mechanical) — シェルコマンドの終了コードで真偽を判定します。例: “go test ./... exits 0”.
  • モデル条件 (model) — 対話記録に特定の行が現れたかで判定します。例: “すべてのAC行がPASSとして記録された”.

登録した条件をmoai hook stop-goal Stop-フック評価器が毎ターンの終わりに読み込みます。条件が成立しなければ評価器はターンを遮り(block)、次のターンへと繋ぎ、条件が成立すればループが終わります。だからユーザーが1度でも多く入力を省いても、長いホライズンの作業が止まらずに回っていきます。

なぜ必要か

長いホライズンの作業 — 複数マイルストーンのrun、大規模リファクタ、TDDサイクル — で最も高くつくコストは、毎ターン、ユーザーが「続ける」を押す往復です。1度の/moai run SPEC-Xは実装エージェントを呼びますが、そのエージェントが戻ってきたとき、次のターンを誰が繋ぐのでしょうか。通常はユーザーが再びプロンプトを入力しなければなりません。

/moai goalはこの往復をなくします。条件を一度宣言すれば、評価器が毎ターンの終わりに「まだ条件が満たされていない」と判定して自動的に次のターンを開いてくれます。作業が終わる条件が機械的に検証可能なら、ユーザーは1回のコマンドでサイクル全体を押し切れます。だからハーネス設計の「ユーザー介入の最小化」という原則が、このコマンド1つで現実になります。

ただし無条件で1人で回るわけではありません。/moai goalはarm-only、つまり「条件を登録してターンを繋ぐ役割だけ」を担います。条件が登録されたときに本当に作業を始めるコマンド(/moai run SPEC-Xなど)が対で来なければなりません。条件だけをぽつんと武装して作業を始めなければ、毎ターンの終わりに条件が満たされていないのでターンばかりがぐるぐる回るidle loopになります。

使い方

bash 
# 条件の登録 + 武装
> /moai goal "go test ./... exits 0 && lint is clean, or stop after 20 turns"

# 状態の確認
> /moai goal status

# すべてのセッションのゴール状態を確認
> /moai goal status --all

# ループの中断
> /moai goal clear

条件文は二重引用符で括ります。機械条件は評価器が毎ターンの終わりに実際に実行するので、速く決定的なコマンド(go test -run <pattern>)は、遅いスイート全体(go test ./...)よりもターンごとの負担が小さくなります。

よい条件を書く3つの原則

  1. 1つの測れる終了状態 — テスト結果、ビルドの終了コード、ファイル数、キューが空か。抽象的なゴール(「コードが良くなる」)は機械でもモデルでも判定できません。
  2. 測り方の明示 — “go test ./... exits 0”, “git status is clean”。「テストが通る」だけでは評価器が何を実行するか分かりません。
  3. 制約条件の包含 — 「このとき他のテストファイルには触れない」。終了状態だけを見れば、途中で意図しないものを変えることがあります。

いつ使うか

/moai goalは次の4つの場面で真価を発揮します。

  • T1 — 長いrun-phase / 複数マイルストーンSPEC (Tier M/L): run-phase自律性の配線(run.mdのac_convergeブロック)がこの場合を所有します。SPECの全受入基準(AC)がPASSと出るまでrunフェーズを繋ぎます。
  • T2 — 大規模マイグレーション / 複数の呼び出し点に触れるリファクタ: すべての呼び出し点がコンパイルされ、テストが通るまでループを回します。呼び出し点の一覧が対話に現れた後に武装することが前提です。
  • T3 — TDDサイクル / AC収束: RED-GREEN-REFACTORのループを回し、目標のテストスイートがgreenでリントが綺麗になるまで繋ぎます。
  • T4 — /moai loop の代替: 「ツール診断が指摘するものを直す」(/moai loop)と「宣言した終了状態が真になるまで回る」(/moai goal)の選択です。終わりが明確なら/moai goalのほうが適します。

無限持続ゴール (v3.1)

--max-turns 0でターン上限を切れば、壁時計 / 停滞ガードが掛かるまでループは止まりません。長いunattended runに適した形です。

bash 
# 4時間の壁時計上限、ターン無制限
> /moai goal "<condition>" --max-turns 0 --max-duration 14400

ただしClaude Codeランタイムの連続ブロック上限(CLAUDE_CODE_STOP_HOOK_BLOCK_CAP、既定8)が、ターン上限より先にループを切ってしまいます。無限ゴールを武装するときは、この上限も一緒に上げなければなりません。

bash 
# ブロック上限を 200 に上げて無限ループが本当に持続するようにする
$ CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=200
> /moai goal "<condition>" --max-turns 0 --max-duration 14400

v3.1からはmoai goal arm --max-turns 0で武装するかカンバンモード進入時に、ランチャーがこの上限を自動的に200へ注入します。だからユーザーが直接環境変数を触さなくても、4時間のチェーンが途中で切れません。

arm-only と安全の境界

/moai goalはarm-onlyです。条件を登録してターンを繋ぐだけで、自ら作業を始めません。だから常に作業を始めるコマンドと対で使います。

bash 
# 誤った形 — ゴールだけ武装して作業を始めない (idle loop)
> /moai goal "<condition>"

# 正しい形 — run コマンドと同じターンに武装
> /moai run SPEC-X     # 作業を開始
> /moai goal "<condition>"   # run が終わるまでターンを繋ぐ

武装されたゴールは安全の境界を緩めません:

  • 実装着手承認 (plan→run ヒューマンゲート)は引き続き必須です。ゴールを武装したからといってrun-phase進入が事前承認されるわけではありません。
  • 元に戻しにくい / 共有システムのアクション (PR作成、破壊的演算)の確認の境界もそのままです。評価器は「ターンを繋ぐか」だけを決め、破壊的演算を事前承認しません。

評価コスト

毎ターンの終わりに評価器が機械条件コマンドを実行します。だからターンごとのコストは、すなわち条件に入れたコマンドのコストです。速く決定的なコマンドを使えばターンのループが細かくなります。Stop-フックのタイムアウトは120秒ですが、より速いコマンドがループをより俊敏にします。モデル条件はすでに存在する対話記録を判定するので、別途の追加コストはありません。

比較 — 3つの自律連続方式

方式次のターンを開くもの止まる条件
/moai goal前のターンが終わり、評価器が条件が満たされていないと判定条件成立、ターン上限、停滞ガード、/moai goal clear
/loop (Claude Code 内蔵)固定時間間隔が過ぎるとプロンプト/コマンドを再実行ユーザーが取り消す
/moai loop診断スキャンが有限のイシューキューを作り、ゴールエンジンが毎ターンの終わりに「キューが空で診断が綺麗」と評価キューが空になり診断が綺麗になるか上限到達

/moai goalと/moai loopは補完関係です。/moai loopは「ツールが指摘するものをすべて直す」に適し、/moai goalは「宣言した終了状態が真だと証明されるまで回る」に適します。同じゴールエンジンの上で回りますが、何が「終わり」かを決める主体が異なります。

他のコマンドとの関係

  • /moai loop — 診断主導の決定的ループ。何を直すかをツールが判定する点が異なります。/moai loopはユーティリティコマンドセクションにあります。
  • /moai run — 作業を始めるコマンド。goalと対で使います。/moai run.
  • カンバンモード — /moai goalの無限持続ゴールをplan → run → verify → syncチェーンにまとめた進入スイッチ。カンバンモードで扱います。

このコマンドがしないこと (範囲の境界)

  • 作業を始めません — arm-onlyです。条件だけ武装して作業を始めなければidle loopになります。
  • ヒューマンゲートを越えません — 実装着手承認、PR作成など元に戻しにくい決定は引き続きユーザー固有の権限です。
  • hooks 無効状態では動きません — disableAllHooksやallowManagedHooksOnlyがオンならStop-フック評価器自体が回らず、標準の毎ターン手動の流れに下がります (graceful degradation)。
  • ネイティブの /goal と衝突しません — ランタイムがネイティブの/goal活動信号を送れば、MoAI評価器は譲ります (二重ブロックの防止)。

関連文書