MoAI-ADK

検証駆動のエージェント・オーケストレーション・ハーネス — Claude Code の書くコードを信頼できるものにする構造

English · 한국어 · 日本語 · 中文

公式ドキュメント · 書籍：Claude Code ではじめる実践エージェンティック・コーディング · Discord

---

「モデルはトークン単位で進む確率的な作業者である。今のターンで何をどれだけ使ったか、成果の質はどうか、前のセッションでどこまで進んだかを、ターンごとに覚えてはいない。ハーネスはこの三つを外から強制する。」

---

v3.2 の新機能 — ファクトリーモード

セッションはコンテキスト・ウィンドウをひとつ消費する。長い SPEC がその窓を埋め、後続の作業は先行するすべてを背負って進む。もう不要になった計画はレビュー中も窓に残り、そのレビューはドキュメント執筆中もまた残っている。よくある脱出口である /clear は、荷物と一緒に文脈ごと捨ててしまう。

ファクトリーモードは作業をリーダー・セッション 1 つと、番号付きのレーン・セッション複数に分ける。リーダーはキューを見張り、空いているレーンにカードを運ぶ。カードは段階ごとにセッションを乗り換えず、丸ごと 1 本のレーンへ入る。そのレーンが自分のセッションの中で plan → run → sync を順に最後まで受け持つ。各段階は Agent() サブエージェントとしてスポーンし、レーン自身はオーケストレーションだけを行う。無制限になるわけではない。セッションごとの上限はそのままある。変わるのは、カード 1 枚の履歴がそのカードを担当するレーンにしか積もらない点だ。だから同じ予算ではるかに遠くまで届き、レーンはカードが 1 枚終わるたびに文脈を空にして次のカードを受け取る。

始め方

moai cc -f                    # リーダー — ファクトリーを開く
moai cc -l                    # レーン、各自別ターミナルで — 次の空き番号で合流
moai cc -l                    # lane-1、lane-2 … の順に付く
moai glm -l                   # GLM バックエンドのレーン
moai codex -l                 # Codex のレーン

-f（長い形 --factory）がリーダーを開き、-l（長い形 --lane）が稼働中のファクトリーにレーンとして合流する。どちらも引数を取らない。レーン番号はオペレーターが選ぶものではなく、自動で割り当てられる。レーンはターミナルを 1 つずつ新しく開いて手動で立ち上げる。セッションが別のセッションの代わりに立つことはない。moai codex にリーダーの進入はなく、レーンとしてしか合流できない。

1 回の起動に進入トークンは 1 つだけなので、-f と -l の併用はエラーになる。値を付けた形（moai cc -f <値>、moai cc -l lane-2）も 1 行のエラーで拒否され、エラー文が正しい形を教えてくれる。かつてのマルチセッション・ボードモードの -k は削除済みです。GPT モデルは moai codex で動かします。

どのバックエンドで動かすか

バックエンドはレーンごとに選ぶ。moai cc -l は Claude、moai glm -l は GLM、moai codex -l は Codex のレーンだ。リーダーは判定を下す席ではなく、キューを見張ってカードを運ぶ席なので、待たせ続けても安い GLM（moai glm -f）が合う。あるアカウントが 429 で詰まり始めたら、レーンをアカウントに分散して置く運用が効く。この組み合わせはあくまで一例で、全セッションをひとつのバックエンドに統一しても構わない。

レーン N 本で複数のカードを同時に

レーンは -l をもう一度打って 1 本ずつ増やす。番号は自動割り当てなので、--name/-n を併せて渡すとエラーになる。番号は生きているセッションが握っているものだけを飛ばす。死んだレーンの claim はその番号をもう塞がないが、自動割り当ては常に生存中の最高番号+1を取るだけで、途中の空き番号は埋めない。レーンの所有権は ~/.moai/db/<project-key>/factory/factory.db に記録される。起点ディレクトリが一時ディレクトリなら（絶対 MOAI_HOME オーバーライドなし）プロジェクトローカルの <base>/.moai/db/<project-key>/factory/ の下に記録される。バックログキューと同じ例外だ。従来の .moai/state/factory/workers.json は一度だけ取り込まれ、ロールバック用の証跡として残る。

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

1 本のレーンは最大 10 個の Agent() サブエージェントを同時に走らせ、書き込みを担うスポーンはそれぞれの worktree に隔離される。レーンを一度に全部立ち上げてはいけない。まず最初の 1 本を上げ、実際に出力が出ているのを確かめてから残りを立ち上げる。カードがレーンをまたいで分割されることはない。

ファクトリー run は、自分を所有するセッションのプロセス識別を記録する。リーダーが死んだ run は、次にレーンが合流した時点で自動的に retire されるので、その合流が AMBIGUOUS_FACTORY で止まることはない。逆も防がれている。レーンが合流するとき run の記録が欠落または退役済みで、リーダー・セッションが生きていれば、合流はそのリーダーを検証し（pid とプロセス開始フィンガープリント、対象は長い形の --leader <名前> で指定、既定値は leader）、run の記録を復元してそのまま合流する。検証済みリーダーが二人以上なら、候補を全員名指してフェイルクローズする。--leader は -l/--lane とだけ組み合わせるセレクターで、進入トークンの短縮形ではない。moai factory runs は全 run を所有者の生死とともに一覧し、moai factory runs --retire <run-id> は指定した run を手で retire する。所有者が実際に死んでいなければ拒否され、完了・失敗・中止のいずれでもないカードが残っている run も拒否される。拒否時にはそのカードの一覧と代わりに使える手段（moai cc -l --factory-run <run-id> で合流、moai cc -f --factory-run <run-id> で引き継ぎ、カードごとに moai factory decide <カード> --choice abandon --run <run-id>）が表示される。合流と引き継ぎは run が有効な間だけ使え、カードの中止は取り消せない。強制的に retire するフラグはない。すでに retire 済みの run を指定すると、書き込みなしで結果を知らせ、残っているカードを並べる。そのようなカードが残る有効な run は moai factory relaunch --from-run でも有効なまま残され、left active (N in-progress cards) と報告される。retire 済みの run には手を付けない（not active (retired), left untouched）。

run が死んだり入れ替わったりしても、レーンのセッションは環境に固定された古い run を指し続ける。そのレーンは moai factory relaunch で生きている run に付け直す。このコマンドはプロバイダー自身のレーン合流行（moai cc -l、moai glm -l、Codex は moai codex -l のみ）をそのまま再実行し、オプションは --provider・--lane・--run・--from-run <run-id>・--dry-run だ。-l は引数を取らないので、--lane を渡しても合流行には載らない。コマンドが stderr でそう知らせ、レーンは次の空き番号で合流する。--from-run はその run が有効で所有者が死んでいる場合に限って先に retire し、--dry-run は実行行を表示するだけで何も変えない。1 つの run の中でカードを順に回す --clear-policy relaunch ループとは別の、1 回限りのコマンドである。stale-run の案内文も、文章の代わりにこのコマンドを埋めた行を表示する。

詳しくは: ファクトリーモード

カードはキューから出発する。backlog には意図的に担当セッションを置かない。だから仕事は人が入れたときだけキューに入る。

/moai gtd "rename のヒントが古い"   # カード追加
/moai gtd                          # キュー確認

/moai gtd が正式なタスク管理入口です。/moai todo は同じ SQLite キュー、カード ID、並び順、アーカイブ・復元動作を使う互換名として残ります。moai gtd capture|clarify|organize|reflect|engage は、承認済みの仕事が従来の backlog → plan → run → sync → done 開発フローへ入る前に Capture → Clarify → Organize → Reflect → Engage を実際の SQLite 状態として引き継ぎます。操作 receipt と実状態の再確認が、中断後の発行・選択・配車の重複を防ぎます。

ファクトリーを正直に保つルールが 2 つある。リーダーはカードの progress.md を自分で読んだ証拠だけでカードを進める。レーンの返信では進めない。返信は観測ではなく主張であり、セッション間の配信は保証されないからだ。そしてカードが終わると、レーンが /clear を依頼する。/clear は人が直接打つコマンドなので、指示としては送れない（--clear-policy で変えられる）。

ファクトリーが使う言葉

ファクトリーの文書が繰り返す語彙を 1 か所にまとめるとこうなる。リーダー (leader) はキューを見張ってカードを運ぶセッションで、レーン (lane) はカード 1 枚を最後まで運ぶセッションとワークツリーの組である。

語	一行定義
カード (card)	作業単位 1 つ。/moai gtd で入り、短い ID で呼ばれる
バックログ (backlog)	入口の待ち列。担当セッションがなく、人だけが投入できる
リーダー (leader)	調整するセッション。読んだ証拠だけでカードを進め、コードは自分で書かない
レーン (lane)	カード 1 枚を最後まで運ぶセッション＋ワークツリーの組。並行作業の流れ 1 つで、lane-1、lane-2 … の番号が自動で付く
ラン ID (run-id)	ファクトリーの実行 1 つを指す短い識別子。実行が複数生きているときは --factory-run <run-id> で合流先を選ぶ
ワークツリー (worktree)	カード専用の隔離チェックアウト。ディレクトリがカード ID、ブランチは何をしたかを表す WT-<スラッグ>
ディスパッチ (dispatch)	リーダーがレーンに送る指示。仕事へのポインタであって複製ではない

カードも形によって、レーンが通る段階が変わる。リーダーはカードがキューを離れるとき、3 つのクラスに分類してディスパッチに名前を付ける。

クラス	形	近道
A — 即時クローズ	1 ファイル・1 行、設計判断なし、回帰は CI が捕まえる	1 本のレーンが PR まで丸ごと (plan を飛ばす)
B — 原因未確認の欠陥	壊れているのは明確なのに、原因がまだ立っていない	run → sync (plan なし、SPEC なし)
C — 設計変更	決定を含むか、サブシステムにまたがる	3 段階すべて

クラス A は主張ではなく、確認された証拠だけで認める。1 ファイルに測定された diff と、マージされる HEAD のグリーンの CI を引用できなければクラス A ではない。クラス B は plan だけを飛ばし、sync ゲートのレビューはそのまま回り、原因確立の証拠 (再現コマンドと出力) をカードの進行記録に残す。

ファクトリーを目で見る

moai web はローカル・コンソールを立ち上げる。Factory 画面でファクトリーのレーンと SPEC パイプラインを一緒に眺め、Overview・Specs・Monitor・Settings・Todo 画面も併せ持つ。

詳しくは: ファクトリーモード · manager-lead リーダーコーディネーター · /moai todo

v3.1.1 で加わったもの

先に v3.1.1 へ入ったものを挙げる。それぞれは後段の該当節で詳しく扱う。

ホーム・ディレクトリの整理。 長く使うほど ~/.moai には過去の実行成果物が積もる。moai clean --home が、許可リストの範囲に限ってそれを片付ける — 既定は dry-run なので何が消えるかを先に見せ、実際の削除には --force が要る。何日経ったものから片付けるかは state.home_retention_days (既定 30 日、0 なら無効) で決める。いまどれだけ膨らんでいるかは moai doctor の Home Disk Usage 項目が知らせる。ホームのパス自体は MOAI_HOME 環境変数で移せる — 絶対パスしか受け取らない。ただしこの変数を読むのは Go のプロセスだけで、パスを移してもステータスラインとシェル・フックは相変わらず $HOME/.moai を見る。.env.glm のようなシェル側の資格情報とステータスラインのデータだけが元の場所に残り、状態が黙って二つに割れる。

セッション間メッセージの設定。 ほかの Claude Code セッションが送ってくるメッセージを、そのまま受け取るか、承認を挟んで受け取るか、まったく遮るかを crosssession.yaml で決める。このマシンの外へ出ていくメッセージに承認を要求するスイッチもここにある。

ステータスラインの GitLab 対応。 statusline.forge で、開いている作業を GitHub と GitLab のどちらで数えるかを選ぶ。空のままなら origin リモートのホストを見て判断する。

素の /loop がファクトリーの職長になる。 引数なしで /loop だけを打つと、バックログ・キューを見張ってオペレーターがすでに picked にした次のカードを隔離されたワーカーへ配車し、完了は主張ではなく読んだ証拠で確かめてから報告する、というサイクルが回る。人が見ていない席なので、キューにカードを入れることも選ぶこともオペレーターの仕事であり、職長は選ばず運ぶだけだ。

---

なぜ moai-adk なのか

エージェントがコードを書く時代になったが、エージェントの出力をそのまま信頼することはできない。「テストが通りました」という言葉が、実際にテストを回した結果なのか、単なるエージェントの推測なのかを見分けることが、最初から最大の問題だった。moai-adk はまさにその地点から出発する — 検証していない完了宣言をシステム・レベルで禁止し、すべての完了主張に、実際に実行したコマンドとその出力を証拠として結び付ける。

moai-adk は Claude Code を外から包むハーネスである。Claude Code を置き換えるのではなく、ユーザーが手で管理してきた部分 — どのモデルを使うか、どれだけ深く推論するか、結果をどう検証するか、セッションが切れたときどうつなぐか、並行実行時にお互いを踏まないようどう分離するか — を構造として引き受ける。検証の完全性、SPEC ライフサイクル、本物の境界を持つ自律実行、生きたコードベース・ナビゲーター、自己改善ループ、並行安全な構造。この 6 つが moai-adk のアイデンティティを形づくる。

このアイデンティティは 3 つの核に整理される — 同じ品質をより少ないトークンで得るコスト (トークノミクス)、観測をルールに変えて動くほど賢くなる自己改善 (エージェンティック・ループ・エンジニアリング)、そして手戻りを構造的に防ぐ品質管理 (SPEC ライフサイクル・TRUST 5 ゲート・分離)。どれ 1 つだけでは足りない — それぞれがなぜ他を必要とするかは下で見る。

8 つの差別化ポイント

差別化ポイント	説明
偽りの検証なし	「テストが通った」という主張は、必ず実際に実行したコマンドとその出力に帰属する。回していない検証を成功として語ることをシステムが禁止する — 検証主張の完全性 (verification-claim integrity) がすべてのエージェントとオーケストレータの表面に結び付いている。
自律 + 本物の境界	/moai goal が完了条件を宣言すると、セッションは条件が満たされるまで自力で作業する。ただしターン上限（デフォルト 30）、停滞ガード、実時間予算、事前承認ゲートという 4 つのハードな境界が付いており、無限ループに陥らない。
並行安全	SPEC ごとに独立した作業ツリーを与え、ブランチ状態ガードがプライマリ・チェックアウトでの誤ったブランチ切替を防ぎ、書き込みエージェントの起動前にリモートとの乖離を検査する。書き込み可能なエージェント 2 つが同時に動くことはない。
長期の継続	/clear を越えて作業は続く。進行状況は progress.md に、ハンドオフ・メッセージはメモリに、ルーティング決定は決定メモリに残る。次のセッションは更地からではなく、前のセッションが学んだ地点から始める。
コスト効率	セッションのモデルと推論強度を一度選べば、すべてのエージェントがそれをそのまま引き継ぐ。プロンプト・キャッシュを再利用し、長い出力はディスクに流してコンテキストを軽く保つ。
16 プログラミング言語の同等サポート	Go、Python、TypeScript、JavaScript、Rust、Java、Kotlin、C#、Ruby、PHP、Elixir、C++、Scala、R、Flutter、Swift — 16 のプログラミング言語をマーカー・ベースの自動検出でひとつの集合として扱う。どれか 1 つが優遇されることはない。
自己改善	繰り返される失敗パターンを観測すると、ルール変更提案として上げる。黙って適用せず、承認を受けて反映する。ルーティング決定とゲート証拠が決定メモリに蓄積され、次の実行の材料になる。
母語への配慮	韓国語・日本語・中国語・英語の 4 ロケールを同じ PRで扱い、翻訳調を禁じ、母語の文を別に持つ。母語を使うユーザーに英語を強要しない。

何が違うのか

	Claude Code 単独	一般的なハーネス	moai-adk
完了主張の証拠帰属	ユーザーが手で確認	通常ない	システムが強制（5 セクション証拠レポート形式）
SPEC ライフサイクル	なし	限定的	plan→run→sync 3 フェーズ + Tier S/M/L
自律ループのハードな境界	該当なし	大抵ターン上限のみ	ターン上限 + 停滞ガード + 実時間 + 承認ゲート
並行作業の分離	手動	限定的	worktree + ブランチガード + 起動前同期検査
セッション継続性	/clear で切断	限定的	ハンドオフ + メモリ + 進行ファイル
16 プログラミング言語の同等扱い	該当なし	該当なし	マーカー自動検出 + 言語別ツールチェーン
自己改善ループ	なし	限定的	失敗観測 → ルール昇格（承認制）

flowchart TD
    User["ユーザー要求"] --> Analyze["意図分析<br/>Analyze-First ルーティング"]
    Analyze --> Plan["plan — SPEC 作成"]
    Plan --> Audit["独立監査<br/>plan-auditor"]
    Audit --> Run["run — TDD/DDD 実装"]
    Run --> Verify["trust-but-verify<br/>検証バッチ実行"]
    Verify --> Sync["sync — ドキュメント + PR"]
    Sync --> Learn["決定メモリ + 教訓"]
    Learn -.次のセッション.-> Analyze

3 つの核が互いを支える

コストだけを押すと品質は静かに崩れる — 手戻りとデバッグ・ループが続き、手戻りはあらゆるトークン支出のうち最も高くつく。品質ゲートだけあって学習ループがなければ、同じ失敗が毎セッション繰り返される。コスト上限のない自律ループは、暴走した 1 件のタスクが割り当て全体を燃やし切る。3 つの核は互いを支える — 品質が手戻りを防ぐからコストは経済的に保たれ、ループが効いたものを拾うから品質は強制可能のままであり、コスト・ゲートが超過前に止めるからループは手の届く範囲に留まる。

すべての設計判断はこの 3 つの核のどれかに属する。どのモデルを使うか、どれだけ深く推論するか、コンテキストをどう使うか — 何 1 つターンごとのその場勘に任されない。システムが決定し、その決定を記録して次の実行を賢くする。

コストは単価ではなく割り当てで決まる

トークン価格は 3 年間で 98% 下がったのに (Linux Foundation)、同じ期間に企業の AI 支出は 320% 上昇した。価格下落を利用量の増加が上書きしたのである。エージェントは 1 課題を解くために数十〜数百ステップを回り、トークンをそれに比例して燃やす。従量課金ではこれがそのまま請求書になり、サブスクリプションでは全モデルが共有する週次割り当てを食い潰す。

Uber は Claude Code をエンジニア 5,000 人に展開し、4 か月で 1 年分のコーディング予算を燃やして月次トークン上限を導入した。Meta・Amazon・Microsoft もそれぞれ無制限 AI ポリシーを撤回した。課題に合うモデルを割り当ててトークン効率を上げるトークノミクスは、テック業界の新しい基準線になった。

従来のコスト管理は単価の上昇に合わせて作られたので、単価は下がるのに総支出は増えるというこの逆説の前で無力だ。ボトルネックは単価ではなく利用量、正確には、エージェントが課題を終える前に回すステップ数である。

DeepSWE リーダーボード（課題 113、努力度別ビュー）がこれを示す。同じ Claude 系の中で、課題ごとのコストはモデルがトークンをいくらで売るかではなく、どれだけ効率的に終えるかに追従する。

モデル [effort]	スコア	課題コスト	備考
opus-5 [low]	58%±2	$1.66
opus-5 [medium]	69%±1	$3.29	費用対効果の変曲点
opus-5 [high]	73%±2	$6.08	スコア +4、コスト 1.8 倍
opus-5 [xhigh]	73%±3	$9.07	純損 — high と同点、コストだけ +49%
opus-5 [max]	74%±4	$11.84
glm-5.2 [max]	44%±2	$3.92	API 課金では不利 · z.ai 定額制では有用
sonnet-5 [max] (Sonnet 5)	54%±4	$26.40	opus-5 [low] に支配される

Opus 5 を最も低い努力度で回した方が、Sonnet 5 を最も高い努力度で回したよりスコアが高く (58% vs 54%)、課題コストは 16 分の 1 だ ($1.66 vs $26.40) — Sonnet のトークン単価が安いという事実には勝てない点に注意。原因は 268 ステップ対 36 ステップである。請求書を書くのはトークン単価ではなく、再試行ループだ。コストは課題ごとに正しいモデルと推論の深さを割り当てることで決まる。

上の表は Opus 5 で測定した値だ。MoAI の opus エイリアスは現在 Opus 5.5 を指しており (Claude Code v2.1.280 以上が必要、デフォルト effort は medium)、sonnet エイリアスは現在 Sonnet 5.5 を指している(公式ドキュメント基準で 1M コンテキスト)。どちらもまだ再測定していない。

出典: DeepSWE v1.1 リーダーボード (datacurve.ai、課題 113、2026-07-25)

---

クイックスタート

インストール

macOS / Linux / WSL

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell 7.x+)

irm https://adk.mo.ai.kr/install.ps1 | iex

ソースからビルド (Go 1.26+)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

すでにインストール済みなら、moai update で最新版に上げる。v3.2.0 から moai update は既存プロジェクトを保存ベースで更新する — テンプレート管理ディレクトリを消して敷き直すことはもうない。自分で置いたファイルはその場に残り、テンプレートファイルへの変更は 3-way マージされる(衝突時は編集分を残し、新版を <path>.moai-new.N サイドカーとして隣に置く)。テンプレートがもう運ばないファイルは削除前に .moai/archive/files/ へ退避される — サマリーが更新・マージ・衝突・保存・アーカイブを経路ごとにすべて報告する。

💡 コストを減らすには — z.ai GLM 推奨: このリンクから z.ai に登録すると一定トークンがボーナスでもらえる。このリンクは moai-adk オープンソース開発を支援する経路でもある。無料モデル (GLM-4.7-Flash, GLM-4.5-Flash) もあるので、z.ai 料金プランを参照のこと。

プロジェクトの初期化

moai init my-project
cd my-project

対話式ウィザードが言語・フレームワーク・方法論を自動検出し、Claude Code 統合ファイルまで生成する。

エージェントハーネスの選択

ウィザードは、プロジェクトにデプロイして接続するエージェントハーネスを尋ねます。--llm フラグで非対話的に同じ選択ができます:

選択	プロジェクトルートに生成されるもの
claude (デフォルト)	.claude/ サーフェス全体と AGENTS.md — 従来のデフォルト動作
gpt	Codex のみのデプロイ: AGENTS.md と Codex サーフェス（.codex/、.agents/skills/、.moai/）のみ。.claude/ ツリー、CLAUDE.md、.mcp.json は生成されません。Claude 専用ランタイム機能（AskUserQuestion、サブエージェント、output style、スラッシュコマンド、Workflow スクリプト）は利用できません
both	claude デプロイに .codex/ 接続を追加。.mcp.json のプロビジョニングは強制有効化されます

デプロイモード: プラグイン既定とフルローカルデプロイ

既定の経路（プラグインモード）では、スキルとコマンドをプロジェクトにコピーしません — moai プラグインが運びます。.claude/ サーフェスの残り（エージェント、ルール、フック登録、設定）は従来どおりデプロイされます。スキルとコマンドをローカルファイルに残したいときは --no-plugin（フルローカルデプロイ — .mcp.json の moai エントリと Codex ミラーを含む）を、オプションパックのカタログまでローカルに展開するなら --all を使います。デプロイモードは .moai/config/sections/llm.yaml の deployment_mode に記録され、moai update はその記録に従って同じ範囲を保ちます。プラグインのインストールが確認できなかったプロジェクトは、安全側の local として記録されます。

GPT ゲートウェイの撤回（2026-09-16）。 内蔵トランスレーションゲートウェイで GPT モデルを Claude Code に載せていた旧ランチャーは削除されました。GPT モデルはネイティブハーネスの moai codex（Codex CLI）から利用してください。上記の --llm gpt init 値には影響しません — 撤回されたランチャーではなく、Codex 専用デプロイを選ぶ値です。

moai init my-project --llm gpt   # Codex のみのプロジェクト

この選択が存在する前に初期化されたプロジェクトには llm.harness キーがなく、update でも claude の動作を保ちます — 移行作業は不要です。

最初のワークフロー

claude        # または moai cc — プロジェクト内で Claude Code を実行

/moai plan "JWT ログインを追加"      # SPEC 作成
/moai run SPEC-AUTH-001              # TDD/DDD 実装
/moai sync SPEC-AUTH-001             # ドキュメント同期 + PR 作成

自然言語でも通じる。/moai "ログインのバグを直して" のように書くと、意図分析 (Analyze-First ルーティング) がリクエストを読んで適切なワークフローへ渡す。

要件

プラットフォーム	対応環境	備考
macOS	Terminal, iTerm2	完全対応
Linux	Bash, Zsh	完全対応
Windows	WSL 推奨, PowerShell 7.x+	ネイティブ cmd.exe 非対応

• Git — 全プラットフォームで必須
• Claude Code — moai-adk は Claude Code のためのハーネスである
• 推奨: gh CLI（PR 自動化）、tmux（worktree ウィンドウ）、使用言語のリント/テスト・ツールチェーン（例: golangci-lint）

---

主要機能

単一エントリポイント /moai

自然言語と 16 個のサブコマンドが同じパイプラインに入る。/moai plan・/moai run・/moai sync が SPEC パイプラインの主軸で、goal・loop・fix・review・gate・clean・codemaps・e2e・mx・feedback・project・harness・todo が周囲を埋める。

引退したサブコマンド 4 つ — design · brain · coverage · security。security の役割は moai-ref-owasp-checklist + moai-ref-llm-security スキルが引き継ぐ。

MCP サーバー

moai init はデフォルトでちょうど 1 つの有効な MCP エントリを用意する — 自前の moai mcp-server（ローカル stdio サーバー）だ。このサーバーが MoAI のツール群を Claude Code に公開する。下の表は主要なグループだけを載せる — 全一覧は MCP サーバーガイド にあり、ツール数と一覧の基準はインストールされたバイナリが tools/list で返す一覧だ。ドキュメントに記載された非活性の 4 エントリ（context7・chrome-devtools・playwright・ast-grep）は moai mcp add <名前> で有効化する。moai mcp add|remove|list CLI が atomic-RWM seam でエントリを管理するため、ユーザーが .mcp.json を手で編集する必要はない。

グループ	ツール	目的
SPEC ライフサイクル	spec_progress, spec_audit, spec_drift	時代分類 + ドリフト検出
検証	verify_snapshot, verify_trend	キー別証拠スナップショット
ゴール + セッション	goal_arm, goal_status, session_list	自律ループ + マルチセッション調整
クロスモデル監査	audit_multi, claude_audit, codex_audit, glm_audit, audit_cache	多監査者収束
codex 委譲	codex_task, codex_setup, codex_job_*	バックグラウンド・クロスモデル作業
GLM 委譲	glm_task, glm_job_status, glm_job_result, glm_job_cancel	GLM(z.ai)へのバックグラウンド作業委譲

すべてのバックエンドは fail-open だ — GLM（~/.moai/.env.glm）と codex（~/.codex/auth.json）はオプションであり、利用不能なバックエンドは inconclusive を返すだけで hard error ではない。

Codex を有効にしたハーネス（moai init --llm gpt|both）では、Codexのステータスラインは組み込み識別子配列（tui.status_line）のみをサポートするため、goal・todo・SPEC状態のような MoAI 固有の項目は表示できない — コマンドベースのステータスラインをサポートする openai/codex#17827 が解決されるまでの制限である。

詳しくは: MCP サーバー・ガイド · Claude Code MCP

ゴール・エンジン — 本物の境界を持つ自律ループ

完了条件を宣言すると、セッションは条件が満たされるまで自力で作業する。ターン上限、停滞ガード、実時間予算、事前承認ゲートが付いており、無限ループに陥らない。機械的条件（コマンドの終了コード）とモデル条件（対話記録の主張）を併用できる。--max-turns 0 で auto-compact 駆動の無限ゴールを武装することもできる — その場合は --max-duration と停滞ガードが境界を作る。

moai goal --auto "<ミッション>" は別の mission_mode=auto 草案を作り、approve が範囲・行為・根拠・上限を一度封印します。その後は run、status、revoke、ポリシー制約付き resume が保存契約を使います。super-advisor は非拘束の助言者で、manager-todo の読み取り専用判定サブロールが構造化判断を作り、決定論的 owner adapter が receipt 付きキュー・配車、明示パスのコミット、lease 付き local develop --no-ff マージを実行します。持続実行能力が実プロバイダーで確認されなければ active-session-only に下がり、リモート push・PR・マージ完了はまだ実証されていません。GTD と auto ミッションの案内

最終実行境界はさらに厳格です。run --supervise は publish→pick→lease 付きディスク配車→commit→local develop --no-ff を有限実行します。監督下の Git 効果には分離した --card-worktree と --develop-worktree が必要で、従来の --repo だけでは効果は 0 件です。完了には true と判定された typed evidence とマージ ancestry を封印した 0600 --completion-receipt も必要で、行為リストの消化だけでは完了しません。完了状態の再実行も効果 0 件です。--recommend は権限を与えず、各効果にはリポジトリ内 0600 governor receipt と独立監査 PASS receipt の両方が必要です。未構成の remote/release provider は成功を装わず provider_unsupported を返します。

並行 worktree

SPEC ごとに独立した作業ツリーを与える。moai cc -w <名前> で入り、--spawn を付けると現在のセッションを保ったまま新しいウィンドウで開く。ブランチ状態ガードがプライマリ・チェックアウトでの誤ったブランチ切替を防ぐ。

ファクトリーモード

-f（--factory）がファクトリーリーダーを、-l（--lane）がレーンを開く。どちらも引数を取らない。リーダー 1 つがキューのカードを番号付きのレーンへ運び、レーンはカード 1 枚を plan → run → sync で最後まで受け持つ。起動手順は上の「v3.2 の新機能 — ファクトリーモード」節にある。

セッションの系譜は Origin-Trail Chain が別に担う。ファクトリーモードとは独立で、リーダーもレーンも要らない。moai cc -w <名前> のようにワークツリーを指定して立ち上げたセッションは、すべてチェーンに載る。append-only の JSONL 系譜ツリーでワークツリーの祖先を追跡し、深さの健忘（/clear 後のルートからリーフへのチェーン復元）を解決し、ハートビートが途絶えたセッションを stale と判定する。

概念	機能
Origin-Trail Chain	.moai/state/chain/events.jsonl の append-only JSONL イベント・ストリーム
WorktreeNode (13 フィールド)	セッションごとの状態: ID、親、深さ、origin チェーン、マイルストーン、再開目標
CWD 衝突の解決	(worktree_path, session_id) の組で再利用パスを区別
深さの上限	入れ子の複雑さを制限

今すぐ使える: moai chain <status|lineage|back|list|prune> で系譜を読み、moai todo（引数なしでキュー表示、add·list·next·done·unpick·drop·undrop·edit·move·analyze、2 語以上はそのままカード追加）で backlog キューを運用する。

詳しくは: ファクトリーモード · セッション系譜チェーン

CG の廃止と設定の移行

CG ランチャーは廃止されました。移行手順は CG の廃止と設定の移行 を参照してください。

moai migrate cg
moai migrate cg --target claude-only --apply --accept-role-change

llm.team_mode: claude、llm.gateway.teammate_mode: in-process、llm.gateway.teammate_provider: inherit を保存します。従来の混合構成の役割分担を解除する変更です。Claude リーダーと GLM チームメイトのペインを維持する移行ではありません。

claude-glm は Claude リーダーと tmux 内の GLM チームメイトを表します。現在は TEAMMATE の統合検証を通過していないため、適用と起動は利用できず、プレビューのみ可能です。tmux のインストールや verified: true の設定では、この制限は解除されません。

16 プログラミング言語の同等サポート

Go、Python、TypeScript、JavaScript、Rust、Java、Kotlin、C#、Ruby、PHP、Elixir、C++、Scala、R、Flutter、Swift。マーカー・ベースの自動検出で各言語の標準リント/フォーマット/テスト・ツールチェーンを回す。

自動品質ゲート

TRUST 5 (Tested · Readable · Unified · Secured · Trackable) がすべての変更に適用される。/moai gate がリント + フォーマット + 型 + テストを一括で回し、sync-auditor が機能・セキュリティ・制作・一貫性の 4 次元で採点する。

@MX タグ

AI エージェント同士がコンテキスト・不変条件・危険区域をやり取りするインラインのコード注記。ファンインが高い、複雑、危険なコードだけを選んで印を付ける。

Navigator — 生きたコードベース地図

@NAV:DEC・@NAV:SYM・@MX:SPEC の 3 系統を、アドレス指定可能な 1 つのグラフ (nav-graph.json) にまとめる。設計決定・SPEC・コードシンボルが双方向につながり、コードを直すときにその決定の文脈が付いてくる。

セッション・ハンドオフ

/clear を越えて作業は続く。6 ブロックの paste-ready resume メッセージが進行状況を次のセッションへ運び、自動注入モードではメッセージ 1 行でセッションを再開する。

loop / fix — エラー駆動開発

/moai loop が LSP 診断・AST-grep・リンターを並行でさらって拾った問題をレベルごとにまとめ、キューが空になるまで回る。/moai fix は 1 パスで終える単発修理だ。

review --deep

/moai review --deep がマルチエージェントの敵対的脆弱性スキャンを回す。OWASP · LLM セキュリティ · サプライチェーン · DevSecOps のリファレンス・スキルが後ろに付く。

4 ロケール・ドキュメント

韓国語・日本語・中国語・英語のドキュメントを同じ PR で扱う。翻訳調を禁じ、母語の文を別に持ち、4 ロケール・パリティ検査がビルド・ゲートに結び付いている。

moai web コンソール

moai web がローカルホスト限定のコンソールを開く。画面は Overview・Factory・Specs・Monitor・Settings・Todo の 6 つで、設定画面は Identity・Language・Claude settings・GLM Settings・Codex settings・Workflow・Git & Worktree・Audit・Report・MCP・Cross-Session・Feedback・Quality Gate のタブに分かれる。Codex タブは散らばった codex 設定を 1 画面にまとめて見せる読み取り専用の画面で、値の編集は元のタブで行う。プロファイルの作成・改名・削除も同じ画面で行う。

ref / domain スキル

ref スキル 11 個 (moai-ref-api-patterns、moai-ref-owasp-checklist、moai-ref-llm-security、moai-ref-react-patterns、moai-ref-testing-pyramid、moai-ref-ui-polish、moai-ref-secops、moai-ref-supply-chain、moai-ref-seo、moai-ref-git-workflow、moai-ref-cross-model-audit) と domain スキル 7 個 (moai-domain-backend、moai-domain-frontend、moai-domain-database、moai-domain-design-dna、moai-domain-html-report、moai-domain-humanize、moai-domain-svg-infographic) がエージェントに現場の知識を注入する。

SVG 技術インフォグラフィック

moai-domain-svg-infographic スキルは編集可能な SVG 技術インフォグラフィックを作る。マークアップを書く前に座標を数値で計算し、完成したファイルは決定論的なソース lint と寸法検証付き 2 倍解像度 PNG レンダーを通る。承認ゲートフロー、前後比較、KPI カードグリッド、意思決定マトリクス、レイヤースタック、ネストしたスコープ、プロセスフロー、ロードマップタイムライン、コンポーネントトポロジーの 9 形式を外部カタログのベンチマークで実測し、すべて再現可能であることを確認した (形式別の成果物と判定: .moai/reports/t272/verdict.md)。

クロスプラットフォーム

追加の依存なしに macOS・Linux・Windows で動く Go 単一バイナリ。フック・システムがゲートを機械的に強制し、ステータスラインがコストとコンテキストをリアルタイムで示す。

---

どう動くのか

SPEC 3 フェーズ・ライフサイクル

すべての作業は plan → run → sync の 3 フェーズで流れる。Tier S/M/L のサイズ分類が検証の深さと PR ルーティングを決める。GEARS 形式の要件と受入基準が完了を証拠で判定する。

flowchart TD
    P["plan — SPEC 作成<br/>GEARS 要件 + 受入基準"] --> PA["plan-auditor<br/>独立監査 (偏り防止)"]
    PA -->|PASS| R["run — TDD / DDD 実装<br/>cycle_type 自動選択"]
    PA -->|DEBT| P
    R --> SA["sync-auditor<br/>4 次元品質採点"]
    SA -->|PASS| S["sync — ドキュメント同期 + PR"]
    SA -->|DEBT| R
    S --> MX["@MX タグ + Navigator 更新"]

方法論 (TDD/DDD) はプロジェクトの状態が選ぶ。moai init がカバレッジを見て自動で決める。

flowchart TD
    A["プロジェクト分析"] --> B{"新規プロジェクトまたは<br/>カバレッジ 10% 以上?"}
    B -->|"はい"| C["TDD (デフォルト)"]
    B -->|"いいえ"| D["DDD"]
    C --> F["RED → GREEN → REFACTOR"]
    D --> G["ANALYZE → PRESERVE → IMPROVE"]

方法論	サイクル	対象
TDD (デフォルト)	RED → GREEN → REFACTOR	新規プロジェクト・機能作業
DDD	ANALYZE → PRESERVE → IMPROVE	カバレッジ 10% 未満の既存コード

13 エージェント・カタログ

分類	エージェント	役割
マネージャー	manager-spec	plan 段階の SPEC 作成
	manager-develop	run 段階の TDD/DDD/autofix 実装
	manager-docs	sync 段階のドキュメント化
	manager-git	PR 作成・ルーティング
	manager-design	デザイン段階の協業 (Claude Design)
	manager-lead	階層チーム Tier L 調整 + ファクトリーのリーダーセッション配車（唯一の Agent 保持、深さ 2 封印）
評価者	plan-auditor	独立 plan 監査（偏り防止）
	sync-auditor	4 次元品質採点（機能性 40 · セキュリティ 25 · 制作 20 · 一貫性 15）
ビルダー	builder-harness	プロジェクト専用エージェント・スキル・コマンド・フックのスキャフォールド
アドバイザー	super-advisor	高推論コンサル（E1-E4 エスカレーション）
スペシャリスト	e2e-tester	Web/モバイル/デスクトップ E2E テスト実行（CLI ファースト）
	manager-todo	タスクキュー管理（キュー ライフサイクル、/moai:todo --auto 直列サイクル、ディスパッチ支援）— 封印スナップショットに対する読み取り専用判定サブロールは判定を 1 つ返すだけで自ら適用しない（GTD ワークフローが呼ぶため、選択の決定木に行を持たない）
内蔵	Explore	読み取り専用のコードベース探査

すべてのエージェントはセッションのモデルと推論強度をそのまま引き継ぐ — セッションをどのモデルと effort で起こしたかが、そのまま全員の配属になる。執筆と監査を最初から分けて担わせるので、自分の仕事を自分で採点する事態が起こらない。

13 個のうち 12 個が moai-adk の作ったエージェントで、Explore は Claude Code に元からある内蔵エージェントだ。

trust-but-verify — 完了主張に証拠を結び付ける

エージェントが「テストが通った」と報告しても、オーケストレータはその主張を額面通りには受け取らず、自分で検証バッチを回す。7 つの読み取り専用検証（テスト・カバレッジ・サブエージェント境界・センチネル・スキャン・CLI スモーク・ベンチマーク・リント）を 1 ターンで並行に回し、それぞれの exit code と出力を証拠として残す。

検証主張の完全性 (verification-claim integrity) ルールがこの流れを背で支える — 回していない検証を成功として語ってはならず、以前に測った値を新しい測定のように持ち込んではならず、観測できなかったことを空欄のまま通してはならない。5 セクションの報告形式（主張 · 証拠 · baseline 帰属 · 未検証 · 残余リスク）が、エージェントとオーケストレータのすべての完了報告に結び付いている。

検証コストを削り、予算超過の前に止まる

検証は必要だが、検証出力までコンテキストに座る必要はない。冗長な検証出力はディスクに流し、コンテキストには exit code と刈り込んだ末尾（最大 50 行）だけを残す。プロンプト・キャッシュを再利用し（キャッシュ読み取りは 0.1 倍の費用）、コンテキスト・ダイエットの /clear 戦略がしきい値（1M 50% / 200K 90%）で勧告を出す。

予算側はトークン・サーキットブレーカーが守る — ハード上限（デフォルト 90%）で実行を中止し、進行状況を progress.md に保存し、貼り付けるだけで再開できる resume メッセージを出す。ステータスラインがコンテキスト使用率・キャッシュ命中率・レート制限消費を常に示すので、超過は見過ごされずに通り抜けない。

ステータスラインの読み方

🤖 Opus | 🧠 xhigh·t | ♻️ 87% | 🔅 v2.1.212 | 🗿 v3.1.3 | ⏳ 2h 34m | 💬 MoAI
🪫 CW: ████████░░ 88% (⚠️/clear) | 🔋 5H: ████░░░░░░ 45% (4h 30m) | 🪫 7D: ████████░░ 82% (Jan 21)
📁 moai-adk-go | 📡 modu-ai/moai-adk, 7/3 | 🅱️ [WT] release/v3.1.3 +3 | 💾 +1 M2 ?0 | 📋 [run SPEC-AUTH-001-run] | 💌 PR #1042 (⌥approved)
🏷️ run | 👤 manager-develop | 🔄 TODO: 1/3

要素	意味
🤖 モデル	現在のアクティブ・モデル
🧠 effort	推論強度 — 拡張推論が有効なら ·t 接尾
♻️ キャッシュ命中率	プロンプト・キャッシュ命中率
CW: コンテキスト	コンテキスト・ウィンドウ使用率 + 2 段階 /clear マーカー (⚠️ ソフト, 🛑 ハード)
5H / 7D	料金プラン使用率 + リセット時刻
📁 ディレクトリ	プロジェクト・ディレクトリ名
📡 リポジトリ	GitHub リポジトリ owner/name + 開いている issue/PR の対（, 7/3、読めなければ , -/-）
🅱️ ブランチ	現在のブランチ — ワークツリーなら [WT]、+ は変更数（修正+ステージ+未追跡）
💾 git 状態	ステージ + · 修正 M · 未追跡 ? の件数 — アイコンは状態によらず 💾 ひとつ
📋 タスク	アクティブな SPEC ワークフロー [コマンド SPEC-ID-フェーズ]
💌 PR	アクティブな GitHub PR 番号 + レビュー状態 (⌥状態)
🏷️ セッション行	最終行に条件付き — セッション名 · 👤 エージェント · 🔄 TODO: 進行中/待機 バックログ

詳しくは: ステータスライン・ガイド

---

ワークフロー例

新機能を作る (TDD)

/moai plan "ユーザー・プロフィール画像アップロードを追加"
/moai run SPEC-PROFILE-001
/moai sync SPEC-PROFILE-001

新規コードやカバレッジが十分なコードには TDD (RED → GREEN → REFACTOR) が付く。moai init がプロジェクト状態を検出し、TDD と DDD のどちらかを選ぶ。

長時間回す (goal)

/moai plan "決済モジュールのリファクタリング"
/moai run SPEC-PAY-001
/moai goal "go test ./... exits 0 && lint clean, or stop after 20 turns"

完了条件を宣言すると、セッションは条件が満たされるまで自力で作業する。ターン上限はデフォルト 30 で、停滞ガードが付いている。コンテキストがしきい値 (1M 50% / 200K 90%) に達すると /clear を勧め、進行状況を progress.md に保存する。

並行で回す (worktree)

moai cc -w feature-auth        # auth 作業ツリーを開く
moai cc -w feature-billing --spawn   # billing は新しいウィンドウで、現在のセッションを保持

# auth ツリーの中で
/moai run SPEC-AUTH-001

# billing ツリーの中で
/moai run SPEC-BILL-001

SPEC ごとに独立した作業ツリーを与え、2 つのエージェントが互いを踏まないようにする。ブランチ状態ガードがプライマリ・チェックアウトでの誤ったブランチ切替を防ぐ。

CG の廃止と設定の移行

CG ランチャーは廃止されました。移行手順は CG の廃止と設定の移行 を参照してください。

moai migrate cg
moai migrate cg --target claude-only --apply --accept-role-change

llm.team_mode: claude、llm.gateway.teammate_mode: in-process、llm.gateway.teammate_provider: inherit を保存します。従来の混合構成の役割分担を解除する変更です。Claude リーダーと GLM チームメイトのペインを維持する移行ではありません。

claude-glm は Claude リーダーと tmux 内の GLM チームメイトを表します。現在は TEAMMATE の統合検証を通過していないため、適用と起動は利用できず、プレビューのみ可能です。tmux のインストールや verified: true の設定では、この制限は解除されません。

バグを自動で直す (loop)

/moai loop

LSP 診断・AST-grep・リンターを並行でさらって拾った問題をレベルごとにまとめ、キューが空になるまで回る。単発の問題は /moai fix で 1 パスで終える。

---

設定とプロファイル

.moai/config/sections/

プロジェクト設定は YAML のセクション・ファイルに分かれる。moai init が敷くセクション・ファイルは全部で 30 個あり、そのうちよく手を入れるのは下の 6 つだ。

セクション	役割
language.yaml	ユーザー名 · 会話言語 · コードコメント言語 · コミットメッセージ言語
quality.yaml	品質ゲート · 開発モード (TDD/DDD) · カバレッジ
harness.yaml	ハーネスの深さ (minimal · standard · thorough) · 自動検出
workflow.yaml	ワークフローの動作
lsp.yaml	LSP ゲートしきい値 (SSOT)
user.yaml	ユーザー情報

v3.1.1 で手を入れる価値のあるセクションが 4 つ増えた。

セクション	役割
crosssession.yaml	セッション間メッセージの扱い。inbound (空・accept・hold・refuse)、isolate_machines (このマシンの外へ出ていくメッセージに承認を要求するか)、dialog_expiry (保留されたメッセージの承認ダイアログの期限)
cache.yaml	プロンプト・キャッシュの設定ファイル。session_ttl (1h・5m・off) と spec_ttl、キャッシュする最小断片サイズを持ち、moai web の設定エディタをそのまま往復する。ただし今はこの値を読むコードがなく、変えても動作は変わらない
state.yaml	home_retention_days — moai clean --home が何日経ったものから片付けるか。HOME ティア (~/.moai/config/sections/state.yaml) からのみ読み、既定は 30 日、0 を与えるとホーム整理を無効にする
statusline.yaml	既存のテーマ・セグメント切り替えに forge キーが加わった。github・gitlab・none のいずれかで、ステータスラインが開いている作業をどのホスティングで数えるかを決める。空のままなら origin リモートのホストで判断するので、自己ホスト・インスタンスでは自分で書き入れる

gate.yaml の ast_grep_gate.rules_dir は新しいキーではなく、既定値が変わったキー だ。空文字列だった既定値が .moai/config/astgrep-rules になり、moai init/moai update がその場所にバンドルのルールセットを敷く。コード側のフォールバック経路はなくなったので、いまやこのキーがルールセット位置の唯一の出処だ — ルールを別の場所へ移したなら、この値も一緒に直さないとゲートがルールを見つけられない。

環境変数がファイルの値を上書きする。優先順位の詳細と全セクション一覧は CLI リファレンスを参照のこと。

settings.json / settings.local.json の分離

ファイル	役割	テンプレート
.claude/settings.json	テンプレートからレンダリング — プロジェクト共有設定	含む
.claude/settings.local.json	ランタイム管理 — マシンごとの値 (tmux pane ID · API トークン · 絶対パス)	絶対に含めない

settings.local.json は moai glm・moai cc がランタイムに書き換え、SessionStart フックが環境を満たす。誤ってコミットしたら git rm --cached .claude/settings.local.json で除外する。

---

どこでも動く

16 プログラミング言語の同等サポート

Go	Python	TypeScript	JavaScript
Rust	Java	Kotlin	C#
Ruby	PHP	Elixir	C++
Scala	R	Flutter	Swift

各言語をプロジェクト・マーカーで自動検出し、その言語の標準リント/フォーマット/テスト・ツールチェーンを回す。未インストールのツールは静かに飛ばす。Dart/Flutter の正式名称は "flutter" だ。どれか 1 つが優遇されることはない。

4 ロケール・ドキュメント

ロケール	サイト
한국어	adk.mo.ai.kr/ko
English	adk.mo.ai.kr/en
日本語	adk.mo.ai.kr/ja
中文	adk.mo.ai.kr/zh

4 つのロケールを同じ PR で扱い、4 ロケール・パリティ検査がビルド・ゲートに結び付いている。翻訳調を禁じ、母語の文を別に持つ。

オペレーティングシステム

プラットフォーム	状態
macOS	完全対応 (Terminal, iTerm2)
Linux	完全対応 (Bash, Zsh)
Windows	WSL 推奨、PowerShell 7.x+ 対応、ネイティブ cmd.exe 非対応

Claude + GLM

z.ai GLM を Claude Code の代替バックエンドとして使う。環境変数を変えるだけでコードはそのままだ。

コマンド	リーダー	ワーカー	tmux	コスト削減
moai cc	Claude	Claude	不要	—
moai glm	GLM	GLM	推奨	約 70%

GLM Coding Plan は月 $10 から。glm-5.3-flash（デフォルト）、glm-5.3、glm-4.7、glm-4.5-air と無料モデル (GLM-4.7-Flash, GLM-4.5-Flash) が使える。

Claude の各ティアは ANTHROPIC_DEFAULT_*_MODEL 環境変数を通じて GLM モデルにマッピングされる:

Claude ティア	GLM モデル	コンテキスト
Opus	glm-5.3-flash	1M
Sonnet	glm-5.3-flash	1M
Haiku	glm-5.3-flash	1M
Fable	glm-5.3-flash	1M

glm-5.3 はどのティアスロットでも引き続き選択できます（llm.yaml の llm.glm.models.*）。スロットを戻すのも 1 行の設定変更です。

詳しくは: Multi-LLM ガイド · z.ai 料金

---

ドキュメントと学習

公式ドキュメント — adk.mo.ai.kr

adk.mo.ai.kr のオンライン・ドキュメントは 12 セクションに分かれる。

セクション	説明
はじめに	紹介 · インストール · Windows ガイド · init ウィザード · クイックスタート · CLI 概要 · FAQ
基本概念	アイデンティティ · 憲法 · ハーネス・エンジニアリング · SPEC ベース開発 · DDD · TRUST 5
ワークフロー・コマンド	plan · run · sync — SPEC パイプラインの主軸
ユーティリティ・コマンド	fix · loop · gate · review · clean · codemaps · e2e · feedback · goal · gtd (todo 互換)
CLI リファレンス	ターミナル moai バイナリのすべてのコマンド (全 49 個)
Claude Code ガイド	Claude Code 統合 — 基礎 · コンテキスト/メモリ · エージェンティック · 拡張性
Multi-LLM	CG の移行とモデル方針
コスト最適化	プロンプト・キャッシュ戦略とトークン費用の削減
ガイド	CI 自動化 · マルチ LLM CI などの実運用レシピ
Git Worktree	並行 SPEC 開発のための worktree ガイド
Advanced	トークノミクス · トークン予算 · ステータスライン · settings.json · フック · @MX タグ · スキル · Harness v4 Builder · 自己進化 · 決定メモリ
コントリビュート	オープンソース貢献ガイド

書籍

Claude Code ではじめる実践エージェンティック・コーディング — moai-adk 著者による実践ハーネス・エンジニアリング・ガイド。book.mo.ai.kr

CLI コマンド表 (よく使う 17 個)

コマンド	説明
moai init	対話式プロジェクト設定 (言語/フレームワーク/方法論を自動検出)
moai doctor	システム状態の診断と環境検証 — Home Disk Usage 項目が ~/.moai がどれだけ膨らんだかを勧告として知らせる
moai status	プロジェクト状態の要約 (Git ブランチ、品質指標)
moai update	最新版へ更新 (ローカルファイル保存 · 3-way マージ+衝突サイドカー · 削除前アーカイブ)
moai graph <build|query>	コードベースグラフ (edges.jsonl) の生成・照会 — 呼び出し元の検索、影響半径、マイルストーンの交差検査
moai cc / moai glm	Claude 専用 / GLM 専用のセッション
moai codex [cli|status|app]	Codex ランチャー — 引数なしで呼ぶと Codex CLI を起動する。status は準備状態を表示するだけで何も起動しない
moai worktree <sync|done|sweep|hoist|remove|clean|recover|snapshot|verify|restore>	Git worktree の保守 (ワークツリーへの出入りはランチャーの仕事)
moai session <list|register|current>	マルチセッション調整
moai spec <audit|archive|lint|list|new>	SPEC ライフサイクル・ツール
moai goal <arm|status|clear>	ゴール・エンジン CLI
moai harness <status|apply|rollback|disable>	ハーネス学習ライフサイクル
moai handoff <save|show|clear>	セッション・ハンドオフ記録
moai preference <list|decay-scan|toggle>	決定メモリ管理
moai memory <doctor|archive>	エージェント・メモリの点検と古い項目の保管
moai tokens record	プール別トークン使用の台帳記録
moai clean [--home] [--codex-skills] [--reports-archive]	古い実行成果物の整理。--home を付けると ~/.moai を許可リストの範囲で片付け、--codex-skills を付けると ~/.codex/config.toml から、宣言されたパスが不在と証明された [[skills.config]] 登録を削除する。--reports-archive を付けると .moai/reports/ の古い証跡ディレクトリを archive/<YYYY-MM>/ へ移す — 削除はせず移動のみ(既定保持 90 日、--reports-archive-days)。スコープは一度に一つだけ。既定は dry-run で、--force を与えて初めて実際に消す
moai web	Web コンソール — 6 画面 (Overview · Factory · Specs · Monitor · Settings · Todo)、設定タブ

全 49 コマンド: CLI リファレンス

ref / domain スキル

ref (現場の知識) 11 個: moai-ref-api-patterns, moai-ref-owasp-checklist, moai-ref-llm-security, moai-ref-react-patterns, moai-ref-testing-pyramid, moai-ref-ui-polish, moai-ref-secops, moai-ref-supply-chain, moai-ref-seo, moai-ref-git-workflow, moai-ref-cross-model-audit

domain (専門領域) 7 個: moai-domain-backend, moai-domain-frontend, moai-domain-database, moai-domain-design-dna, moai-domain-html-report, moai-domain-humanize, moai-domain-svg-infographic

moai-domain-design-dna は v3.1.1 で新しく入った。スクリーンショットでも画像の束でも生きた URL でも、参考にするデザインを 1 つ受け取り、色・余白・角丸・タイポグラフィといった測れる値と、そのデザインの質感、特殊なレンダリング効果までを Design DNA JSON 一式へ逆抽出する。その JSON を再び入れれば、同じ質感を持つ新しい成果物を作る — 「この画面のように作って」を言葉ではなく値で運ぶ経路だ。ダイアグラムプロファイルにも対応している: アクティブなプロファイルの印はプロジェクトルートの .design-dna/ 配下に保存されて moai update を生き延び、オプトインの mermaid・drawio インポータはソースを信頼しない入力として扱う — 座標・色・フォント・レイアウトは持ち越されない。

CHANGELOG

最近の変更は CHANGELOG.md を参照のこと。

コード品質の要件

すべての貢献は TRUST 5 ゲートを通る — カバレッジ 85% 以上 · リントエラー 0 · 型エラー 0 · Conventional commits。既存コードは特性化テストで振る舞いを固定してから漸進改善 (DDD)、新規コードは RED → GREEN → REFACTOR (TDD)。

---

よくある質問

すべての関数に @MX タグがないのはなぜ?

正常である。タグはファンインが高い、複雑、危険なコードにだけ付く。どのプロジェクトでも大半のコードはタグのしきい値に達せず、タグのないファイルは欠陥ではない。

ステータスラインのバージョン表示は何を意味する?

🗿 v3.1.2 -> 🗿 v3.1.3

前の値が現在インストールされている moai-adk のバージョンで、矢印は利用可能な更新があることを示す。moai update を実行すると消える。

GLM なしで Claude だけ使える?

使えます。moai cc で GLM なしの Claude セッションを起動できます。旧 CG 設定が残るプロジェクトに限り、先に移行が必要です。

既存プロジェクトでも使える?

使える。moai init がプロジェクト状態を検出して方法論を選ぶ — カバレッジ 10% 未満の既存コードには DDD (特性化テストで振る舞いを固定してから漸進改善)、新規・十分にテストされたコードには TDD。

---

一緒に作りましょう

コントリビュート

貢献はいつでも歓迎する。詳細な手順は CONTRIBUTING.md にまとめてある。

1. リポジトリをフォーク
2. 機能ブランチを作成: git checkout -b feature/my-feature
3. テストを書く — 新規コードは TDD、既存コードは特性化テスト
4. テスト · リント · フォーマットの通過を確認: make test · make lint · make fmt
5. Conventional commit メッセージでコミットし、プルリクエストを開く

コード品質の要件: カバレッジ 85% 以上 · リントエラー 0 · 型エラー 0 · Conventional commits

フィードバック

Claude Code の中では /moai feedback でバグ報告と機能要望を GitHub イシューに直接上げる。ターミナルからは GitHub Issues を使う。

コミュニティ

• Discord — リアルタイムの議論と Tips
• GitHub Issues — バグ報告 · 機能要望

ライセンス

Apache License 2.0 — 詳細は LICENSE ファイルを参照のこと。

---

スター履歴

_{MoAI-ADK チームが作りました · adk.mo.ai.kr}