/moai

完全自律の自動化コマンドです。ユーザーが目標を提供すると MoAI が plan → run → sync パイプラインを自律的に実行します。

情報

一行要約: /moai は「完全自律の自動化」コマンドです。ユーザーは望む 機能を自然言語で説明するだけで、MoAI が SPEC 生成から実装、ドキュメント化まで すべての プロセスを自動的に 行います。

プラットフォームの基礎

プラットフォーム層の背景については セッション管理 を参照してください。MoAI-ADK としての説明はこのページです。

情報

スラッシュコマンド対応: MoAI のすべてのサブコマンドはスキルでラップされているので、/moai だけ入力すると利用可能なサブコマンド一覧が表示されます。各サブコマンドは /moai:fix、/moai:loop、/moai:review などの形式ですぐに実行することもできます。

/moai は MoAI-ADK の 完全自律の自動化ワークフロー コマンドです。下位コマンドを別々に実行する必要なく、たった 1 回のコマンドで開発プロセス全体が自動化されます:

1. SPEC 生成 (manager-spec)
2. DDD/TDD 実装 (manager-develop — quality.yaml の development_mode に応じて)
3. ドキュメント同期 (manager-docs)

v3 から /moai の基本ルーティングは Analyze-First — 言語独立的な意図分析です。英語のキーワードマッチングではなくリクエストの意味を分類するので、どの conversation_language でリクエストしても同じ品質でルーティングされます。

ルーティングは次の順序で進行します:

1. 意図分析: ユーザーリクエストの意図を分類 (入力言語とは無関係)
2. コンテキスト十分性の確認: 不十分なら Socratic インタビューで明確化
3. 実行計画の構成: スキル / エージェント / 動的ワークフローのチェーンを選択
4. オーケストレーションモードの選択 (Phase 4): 4モードカタログ (direct / serial / fanout / sweep、agent-teamは明示要求専用の実験的脚注) からの自律選択

つまり /moai "ログインバグを直して" のようにサブコマンドなしで自然言語だけ入力しても、意図分析を経て適切なワークフロー (修正なら fix 系列、新機能なら plan→run→sync パイプライン) につながります。

# 基本的な使い方
> /moai "実装したい機能の説明"

# ブランチと一緒に
> /moai "機能の説明" --branch

# ループモードの有効化
> /moai "機能の説明" --loop

# 既存 SPEC の再開
> /moai --resume SPEC-AUTH-001

実装が完了した後に自動的に反復修正を実行してすべてのエラーを修正します:

> /moai "JWT 認証システム" --loop

このオプションを使うと:

1. SPEC 生成
2. DDD 実装
3. 自動ループ実行 (LSP エラー、テスト失敗、カバレッジ不足の解決)
4. ドキュメント同期
5. PR 生成

情報

--loop オプションは 実装後の整理作業を完全に自動化 して生産性を 最大化します。

フラグなしで実行すると MoAI が作業規模を見てオーケストレーションモードを自動選択します。モードは同時スポーン数を軸とする 4 個のカタログ (direct / serial / fanout / sweep) です:

自動選択の基準 (フラグがないとき):

• 影響ドメイン >= 3 個 → fanout (並列実行)
• 修正ファイル >= 10 個 → fanout (並列実行)
• 複雑度スコア >= 7 → fanout (並列実行)
• それ以外 → serial (順次実行、デフォルトのフォールバック)

情報

Agent Teams — 実験的な再許可: v3.0.0 で引退していた Agent Teams は、実験的な面として再許可されました。明示的な --team 要求がネイティブ teammate ランタイムを選択し、自動選択はありません。引退時代に --team を強制すると MODE_TEAM_UNAVAILABLE を通知して下位エージェントモードにフォールバックしましたが、このセンチネルは文書化された履歴として残っています。Tier L の調整は manager-lead が、並列調査は fanout と sweep が担います。

並列実行はエージェントごとに独立したコンテキストウィンドウを使うので、その分トークンを余分に消費します。単一ドメインの単純な作業なら --solo (順次) の方が経済的です。規模を見て自動的に選ぶ方式がデフォルトである理由です。

/moai が内部的に行う全体のプロセスです:

flowchart TD
    A["コマンド実行
/moai '機能の説明'"] --> B{--resume?}
    B -->|はい| C["SPEC ロード
続けて作業"]
    B -->|いいえ| D["Phase 0
並列探索"]

    subgraph D["Phase 0: 並列探索 (15-30 秒)"]
        D1["Explore 下位エージェント
コードベース分析"]
        D2["Research 下位エージェント
外部ドキュメント調査"]
        D3["Quality 下位エージェント
品質基準線の確認"]
    end

    D --> E{"単一ドメイン?"}
    E -->|はい| F["専門家エージェントに
直接委任"]
    E -->|いいえ| G["Phase 1 継続"]

    C --> G["Phase 1
SPEC 生成"]
    G --> H["manager-spec 呼び出し"]
    H --> I["GEARS 形式の SPEC 生成"]
    I --> J[".moai/specs/SPEC-XXX/spec.md"]

    J --> K["Phase 2
DDD 実装"]

    K --> L["manager-develop 呼び出し
DDD/TDD 循環 (quality.yaml に応じて)"]
    L --> M{"実装完了?"}
    M -->|いいえ| L
    M -->|はい| N{"--loop?"}

    N -->|はい| O["自動ループ実行"]
    O --> P["すべての問題を解決"]
    N -->|いいえ| P

    P --> Q["Phase 3
ドキュメント同期"]

    Q --> R["manager-docs 呼び出し
ドキュメント生成"]
    R --> S{"--pr?"}
    S -->|はい| T["PR 生成"]
    S -->|いいえ| U["完了シグナル"]
    T --> U

核心ポイント:

• Phase 0 (並列探索): 3 つのエージェントが同時に実行され 2-3 倍の速度向上
• 単一ドメインルーティング: 単純な作業は専門家エージェントに直接委任して SPEC をスキップ
• 完了シグナル: 作業完了時に完了報告書に作業完了を明示

3 つのエージェントが 同時に 実行されてプロジェクトの文脈を素早く把握します:

速度向上: 並列実行で順次実行に比べ 2-3 倍速い (15-30 秒 vs 45-90 秒)

単一ドメインルーティング:

• 単一ドメイン作業 (例: 「SQL 最適化」): SPEC 生成なしで専門家エージェントに直接委任
• 多重ドメイン作業: ワークフロー全体を進行

manager-spec 下位エージェントが GEARS 形式の SPEC ドキュメントを生成します:

• .moai/specs/SPEC-XXX/spec.md
• GEARS 形式の要件
• Given-When-Then 受け入れ基準
• conversation_language で書かれたコンテンツ

情報

GEARS 形式 が現在の SPEC 要件の正式な形式です。以前のドキュメント・構成で見られる EARS はレガシー名称で、GEARS に置き換えられました。

manager-develop 下位エージェントが SPEC を基に実装を行います:

• DDD 循環: ANALYZE-PRESERVE-IMPROVE (既存コードのリファクタリング)
• TDD 循環: RED-GREEN-REFACTOR (新機能開発)
• ドメインコンテキストの自動注入 (バックエンド、フロントエンド、セキュリティ、データベースなど)

quality.yaml development_mode 設定:

• development_mode: ddd → DDD 循環を使用 (既存コードの改善)
• development_mode: tdd → TDD 循環を使用 (新機能開発、デフォルト値)

ループ動作 (–loop または loop.enabled が true のとき):

問題が存在 AND 反復 < 最大値:
  1. 診断実行 (LSP エラー、テスト失敗、カバレッジ)
  2. manager-develop に修正を委任
  3. 修正結果の検証
  4. 完了条件の充足有無を確認
  5. 完了文の検出時にループを終了

manager-docs 下位エージェントが実装とドキュメントを同期します:

• API ドキュメントの生成
• README の更新
• CHANGELOG の追加
• 成功時に作業完了を明示

[HARD] TodoWrite ツールが必須: すべての作業追跡に TodoWrite の使用が必須

• 課題発見時: TodoWrite (pending 状態)
• 作業開始前: TodoWrite (in_progress 状態)
• 作業完了後: TodoWrite (completed 状態)
• TODO リストをテキストで出力するのは禁止

すべてのワークフローステップが正常に完了すると、MoAI は完了報告書 (バナー/散文) に作業完了を明示して結果を明確にします。

トークノミクスの核心的な装置です。llm.yaml 設定に応じてステップごとに Claude と GLM を自動ルーティングします — 戦略・計画は Claude が、大量の実装は低コストの GLM が担当するハイブリッドが可能です。

ステップ 1: コマンド実行

> /moai "JWT ベースのユーザー認証システム: 会員登録、ログイン、トークン更新" --loop --pr

ステップ 2: Phase 0 - 並列探索

[並列探索開始]
  Explore 下位エージェント: src/auth/ を分析中...
  Research 下位エージェント: JWT best practices を調査中...
  Quality 下位エージェント: テストカバレッジ 32% を確認...

[探索完了 - 23 秒]
  発見ファイル: 4 個
  推奨ライブラリ: PyJWT, bcrypt
  基準線: LSP 0 エラー、カバレッジ 32%

ステップ 3: Phase 1 - SPEC 生成

[manager-spec 呼び出し]
  SPEC ID: SPEC-AUTH-001
  要件: 5 個 (GEARS 形式)
  受け入れ基準: 3 個のシナリオ

  ユーザー承認: 完了

ステップ 4: Phase 2 - DDD 実装

[manager-spec]
  作業分解: 7 個のタスク
  戦略計画完了

[manager-develop]
  ANALYZE: コード構造の分析完了
  PRESERVE: 特性化テスト 12 個を作成
  IMPROVE: 7 個のタスクの実装完了

[sync-auditor]
  TRUST 5: すべての柱を通過
  カバレッジ: 89%
  状態: PASS

ステップ 5: 自動ループ (–loop)

[ループ開始 - 反復 1/100]
  診断: 型エラー 2 個を発見
  修正: manager-develop 下位エージェントに委任
  検証: すべてのエラーを解決

[ループ終了 - 1 回反復]
  完了条件を充足!

ステップ 6: Phase 3 - ドキュメント同期

[manager-docs]
  API ドキュメント: docs/api/auth.md を生成
  README: 使い方セクションを更新
  CHANGELOG: v1.1.0 項目を追加
  SPEC-AUTH-001: ACTIVE → COMPLETED

ステップ 7: 完了

[完了]
  SPEC: SPEC-AUTH-001
  コミット: 7 個
  テスト: 36/36 通過
  カバレッジ: 89%
  PR: #42 生成 (Draft → Ready)

<moai:COMPLETE />

実装後に自動的にすべてのエラーを修正したいときに使います。特に大規模なリファクタリング後の整理作業に有用です。

単一ドメイン作業 (例: 「SQL クエリの最適化」) は SPEC 生成なしでその領域の専門家エージェントに直接委任して時間を節約します。

はい。Analyze-First ルーティングは言語独立的な意図分析なので、韓国語・日本語・中国語などどの言語でリクエストしても同じように動作します。

• /moai plan - SPEC 生成の詳細
• /moai run - DDD 実装の詳細
• /moai sync - ドキュメント同期の詳細
• /moai loop - 反復修正ループの詳細
• /moai fix - 一回限りの自動修正の詳細