MoAI-ADK とは?

MoAI-ADK は コスト・自己改善・品質統制 の 3 つの核心要素で Claude Code を包む Agentic Development Kit です。同じ品質のコードをより少ないトークンで (コスト、トークノミクス)、セッションが回るたびに観察をルールとして積み重ねハーネスが良くなっていき (自己改善、エージェンティック・ループ・エンジニアリング)、SPEC 3-phase と TRUST 5 ゲートで手戻りを防ぎ「終わり」を証拠で判定します (品質統制、エージェンティック・ハーネス) — モデル選択・推論深度・コンテキスト使用量をシステムが外から強制します。11 個の専門 AI エージェントと 31 個のスキルが協力し、新規プロジェクトには TDD (デフォルト)、テストカバレッジが低い既存プロジェクトには DDD を自動的に適用します。

Go で書かれた単一バイナリ – 依存性なしですべてのプラットフォームで即座に実行されます。

情報

一行要約: MoAI-ADK は「AI と交わした対話をドキュメント (SPEC) に残し、安全にコードを改善 (DDD/TDD) し、品質を自動検証 (TRUST 5) する」ことを — コスト・自己改善・品質統制という 3 つの核心要素をシステムが外から強制しながら 行うエージェンティック開発キットです。

MoAI は「モドゥのAI」(MoAI - Everybody’s AI) を意味します。ADK は Agentic Development Kit の略で、AI エージェントが開発プロセスを主導するツール群を意味します。

MoAI-ADK は Claude Code の中でエージェント同士が協力してエージェンティックコーディングを行うようにする開発キット です。AI 開発チームが協業してプロジェクトを完成させるように、各エージェントが自分の専門分野の作業を担当します。

v3.0 の価値は 3 つの核心要素に要約されます。

コスト対品質を最大化する知的な資源配分です。作業ステップと SPEC のサイズに応じてモデルと推論深度を宣言的に割り当てる 3 階層モデルポリシー、Claude リーダーと GLM ワーカーを組み合わせて実装コストを 60-70% 減らす CG モード、予算超過前に安全に止まる Token Circuit Breaker、そして常時ロードコンテキストを減らす コンテキストダイエット がこの核心要素を成します。

ループが自ら働き、その過程で観察が積み重なります。完了条件を宣言すると条件が満たされるまでセッションが働き続ける goal エンジン、診断ツールが見つけた課題を全部空にするまで反復修正する Ralph Engine (/moai loop)、自然言語リクエストを言語と無関係に意図分析してルーティングする Analyze-First ルーティング がここに属します。蓄積された観察はハーネス学習の原料になり、4 階層の学習のはしご (観察 → ヒューリスティック → ルール → 自動アップデート) に沿って指針が進化します — 自動アップデートは常にユーザー承認ゲートの下でのみ適用されます。

コードを直接書く代わりに、エージェントがうまく働く環境を設計します。11 個のエージェントカタログ、SPEC ベースの 3-phase ワークフロー (plan → run → sync)、TRUST 5 品質ゲート、自然言語リクエストでプロジェクト専用ハーネスを生成する Harness v4 Builder がこの核心要素です。詳しい概念は ハーネスエンジニアリング ドキュメントを参照してください。

コストだけを最適化すれば品質が崩れ、続いて手戻りとデバッグのループがついてきます — ところが手戻りこそ、すべてのトークン支出のなかで最も高くつきます。品質ゲートだけを立てればセッションごとに同じ失敗が反復されます。コスト上限なしに自律ループを回せば、一つの課題が突出して割り当てを削り取っていきます。3 つの核心要素は互いを支え合います — コストは品質が手戻りを防ぐことで経済的に保たれ、品質はループが通ったパターンを記憶して強制可能になり、ループはコストゲートが超過前に止めて適正な価格に留まります。

トークン単価は下がり続けますが、エージェンティック開発のトークン使用量はそれより速く増えます。エージェントが複数回り、コンテキストが長くなり、推論が深くなるほど、コストを決めるのはモデル価格ではなく トークン運用方式 です。

コストの実践方式は 3 つです。

1. 作業ごとに合ったモデル・推論深度を割り当てる — 計画は深く、実装は安く、検証は独立して。
2. コンテキストをダイエットする — 常時ロードされる指針を最小化し、プロンプトキャッシュヒット率を測定します。
3. 予算をシステムが守る — トークン使用を追跡し、閾値超過前に安全に止まります。

完了条件を宣言すると条件が満たされるまでセッションが自ら働き (/moai goal)、ルーティングの決定とゲートの証拠が観察として積み重なりハーネス学習の原料になります。観察は 4 階層の学習のはしご (観察 → ヒューリスティック → ルール → 自動アップデート) に沿って指針へ昇格され、自動アップデートは常にユーザー承認ゲートの下でのみ適用されます。

コードを直接書く代わりに、エージェントが働く環境を設計します。11 個のエージェントカタログは計画と監査を設計段階から分離し、書いた側が自分の作業に点数をつけないようにし、SPEC 3 段階 (plan → run → sync) と TRUST 5 ゲート、worktree 隔離が「できたようだ」ではなく証拠で完了を判定します。

Python ベースの MoAI-ADK (~73,000 行) を Go で完全に書き直しました。

• 11 個 のエージェントカタログ (10 MoAI カスタム + 1 Anthropic ビルトイン Explore)
• 31 個 のスキル (template-managed)
• 36 個 の CLI コマンド · 16 種 の /moai サブコマンド
• 16 個 のプログラミング言語対応
• 3 段階ハーネス (minimal / standard / thorough) — SPEC の複雑度に応じた適応型品質ゲート
• 543 個 の SPEC ドキュメントを基に開発されたコードベース

バイブコーディング (Vibe Coding) とは AI と自然に対話しながらコードを書く方式です。「こんな機能を作って」と言えば AI がコードを生成します。直感的で速いですが、実務では深刻な問題が発生します。

flowchart TD
    A["AI と対話しながらコード作成"] --> B["良い成果物を導出"]
    B --> C["セッション切れまたは\nコンテキスト初期化"]
    C --> D["文脈喪失"]
    D --> E["最初から説明し直し"]
    E --> A

実務で遭遇する具体的な問題:

必須条件:

• すべてのプラットフォームに Git のインストールが必要
• Windows ユーザー: Git for Windows 必須 (Git Bash を含む)
  • 最良の体験のため WSL (Windows Subsystem for Linux) の使用を推奨
  • PowerShell 7.x 以上は代替として対応
  • レガシー Windows PowerShell 5.x と cmd.exe は 非対応

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

推奨: 上記の Linux インストールコマンドで WSL を使うと最良の体験を提供します。

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

Git for Windows が先にインストールされている必要があります。

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

事前ビルドされたバイナリは Releases ページからダウンロードできます。

moai init my-project

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

# Claude Code 実行後
/moai project                            # プロジェクトドキュメント生成 (product.md, structure.md, tech.md)
/moai plan "ユーザー認証の追加"              # SPEC ドキュメント生成
/moai run SPEC-AUTH-001                   # DDD/TDD 実装
/moai sync SPEC-AUTH-001                  # ドキュメント同期および PR 生成

自然言語で直接リクエストしてもかまいません — /moai "ログインバグを直して" は Analyze-First の意図分析を経て適切なワークフローにルーティングされます。

注意

「バイブコーディングの目的は速い生産性ではなくコード品質だ。」

MoAI-ADK は速くコードを打ち出すツールではありません。AI を活用しつつ、人が直接書いたものより より高い品質 のコードを作ることが目標です。速い速度は品質を守りながら自然についてくる副次的な効果です。

この哲学は 3 つの原則で具体化されます:

1. 仕様優先 (SPEC-First): コードを書く前に何を作るかをドキュメントで明確に定義します
2. 安全な改善 (DDD/TDD): 既存コードの動作を保存しながら段階的に改善します
3. 自動品質検証 (TRUST 5): 5 つの品質原則ですべてのコードを自動検証します

MoAI-ADK はプロジェクトの状態に応じて最適な開発方法論を自動的に選択します。

新規プロジェクトと新機能開発の基本となる方法論です。テストを先に書き、そのテストを通す順序で進めるため、作ろうとしている動作がコードよりも先に確定します。MoAI-ADK がこの方式をデフォルトに据えているのは、「できあがった」の判定を人の感覚ではなくテスト結果に委ねるためです。サイクルの各ステップと、ブラウンフィールドプロジェクト向けの pre-RED 分析ステップは SPEC ベース開発 で扱います。

テストがほとんどない既存コードに安全に手を入れるための方法論です。改善に先立って現在の動作を特性化テストで押さえておくため、リファクタリングが既存機能を静かに壊す事故を防げます。MoAI-ADK がカバレッジ 10% 未満のプロジェクトにこの方式を割り当てる理由がここにあります。ステップごとの手順は DDD で扱います。

情報

方法論は moai init 時に自動選択され (--mode <ddd|tdd>、デフォルト値: tdd)、.moai/config/sections/quality.yaml の development_mode で変更できます。

参考: MoAI-ADK v2.5.0+ では二値の方法論選択 (TDD または DDD のみ) を使います。ハイブリッドモードは明確性と一貫性のため除去されました。

MoAI-ADK は ハーネスエンジニアリング (Harness Engineering) パラダイムを実装します — 直接コードを書くのではなく、AI エージェントが働く環境を設計するアプローチです。

情報

「人が方向を定め、エージェントが実行する。」— エンジニアの役割がコード作成からハーネス設計 (SPEC、品質ゲート、フィードバックループ) へ転換されます。概念全体は ハーネスエンジニアリング ドキュメントで扱います。

MoAI は 戦略的オーケストレーター です。直接コードを書かず、11 個の保存エージェント (10 MoAI カスタム + 1 Anthropic ビルトイン Explore) に作業を委任します。核心的な設計原則は 計画と監査の分離 — 作った人が検査しません。

コスト色はデフォルト medium プロファイルの model×effort セル基準です (moai model profile で確認): 🔴 opus+high · 🟠 opus+medium · 🔵 opus+low · 🩵 sonnet+low · ⚪ セッションモデル継承 (ユーザー追加エージェント)。プロファイル (high/low) 切り替え時は割り当てが変わります。

flowchart TD
    MoAI["MoAI オーケストレーター\nユーザーリクエスト分析および委任"]

    subgraph Managers["Manager エージェント (5 個)"]
        M1["manager-spec\nPlan ステップ: SPEC 生成"]
        M2["manager-develop\nRun ステップ: DDD/TDD 実装"]
        M3["manager-docs\nSync ステップ: ドキュメント化"]
        M4["manager-git\nPR 生成、Git 作業"]
        M5["manager-design\nDesign 協業"]
    end

    subgraph Evaluators["評価エージェント (2 個)"]
        E1["plan-auditor\n独立 SPEC 監査"]
        E2["sync-auditor\n4 次元品質評価"]
    end

    subgraph BuilderAdvisor["Builder · Advisor (2 個)"]
        B1["builder-harness\n動的ハーネス生成"]
        B2["super-advisor\n高推論の助言"]
    end

    subgraph Specialist["Specialist (1 個)"]
        S1["e2e-tester\nE2E テスト実行"]
    end

    subgraph Explore["ビルトイン (1 個)"]
        X1["Explore\n読み取り専用コード分析"]
    end

    MoAI --> Managers
    MoAI --> Evaluators
    MoAI --> BuilderAdvisor
    MoAI --> Specialist
    MoAI --> Explore

3 レベルの Progressive Disclosure システムでトークン効率的に管理されます。スキルの説明 (~100 トークン) のみが常時目録に露出し、本文 (~5K トークン) は実際の呼び出し時にのみロードされます — コンテキストダイエットの中核手段の 1 つです。

MoAI の核心ワークフローは 3 段階で構成されます:

flowchart TD
    Start(["開発開始"]) --> Plan

    subgraph Plan["1. Plan ステップ"]
        P1["コードベース探索"] --> P2["要件分析"]
        P2 --> P3["SPEC ドキュメント生成\nEARS 形式"]
    end

    Plan --> Run

    subgraph Run["2. Run ステップ"]
        R1["SPEC 分析および\n実行計画の策定"] --> R2["DDD/TDD 実装"]
        R2 --> R3["TRUST 5\n品質検証"]
    end

    Run --> Sync

    subgraph Sync["3. Sync ステップ"]
        S1["ドキュメント生成"] --> S2["README/CHANGELOG の更新"]
        S2 --> S3["Pull Request の生成"]
    end

    Sync --> Done(["開発完了"])

    style Plan fill:#E3F2FD,stroke:#1565C0
    style Run fill:#E8F5E9,stroke:#2E7D32
    style Sync fill:#FFF3E0,stroke:#E65100

Plan ステップの成果物は plan-auditor が独立監査し、Run ステップ進入の直前には 実装着手承認 (ヒューマンゲート) を経ます。Sync ステップが終わると sync-auditor が 4 次元品質評価を行います — 「できたようだ」ではなく証拠で完了を判定します。

実際の使用例:

# 1. Plan: 要件の定義
> /moai plan "JWT ベースのユーザー認証機能の実装"

# 2. Run: DDD/TDD 方式で実装
> /moai run SPEC-AUTH-001

# 3. Sync: ドキュメント生成および PR
> /moai sync SPEC-AUTH-001

Plan ステップから Run ステップへ移行するとき、MoAI は自動的に現在の実行環境 (cc/glm/cg) を検出し、ユーザーが確認または変更できる選択 UI を表示します。

flowchart TD
    A["Plan 完了"] --> B["環境検出"]
    B --> C{"モード選択 UI"}
    C -->|"CC"| D["Claude 専用実行"]
    C -->|"GLM"| E["GLM 専用実行"]
    C -->|"CG"| F["Claude Leader + GLM Workers"]

このゲートは環境の状態に関係なく正しい実行モードが使われるよう保証し、実装中のモード不一致を防ぎます。

すべてのサブコマンドは Claude Code 内で /moai <サブコマンド> として実行します。

MoAI オーケストレーターは作業の複雑度を分析して実行形態を選択します。

情報

v3.0 の変更: かつての Agent Teams 静的オーケストレーション階層は引退しました。--team を強制してもサブエージェントモードにフォールバックします。ただし Claude Code のネイティブ teammate ランタイム — moai cg の tmux 分割画面 — はそのまま維持されます。チームモードの品質フック (TeammateIdle の LSP ゲート検証、TaskCompleted の SPEC 参照確認) も native teammate ランタイムとともに保存されます。

トークノミクスの核心要素の実践ツールです。Leader が Claude API を、Workers が GLM API を使うハイブリッドモードで、tmux セッションレベルの環境変数隔離を通じて実装されます。戦略・計画・監査は Claude が、大量の実装は GLM が担い、実装中心の作業で 60-70% のコストを削減します。

┌─────────────────────────────────────────────────────────────┐
│  LEADER (現在の tmux ペイン, Claude API)                     │
│  - moai cg 有効化後に /moai コマンドでオーケストレーション    │
│  - plan, quality, sync ステップの処理                        │
│  - GLM 環境なし → Claude API を使用                          │
└──────────────────────┬──────────────────────────────────────┘
                       │ Agent Teams (新しい tmux ペイン)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  TEAMMATES (新しい tmux ペイン, GLM API)                     │
│  - tmux セッション環境を継承 → GLM API を使用                │
│  - run ステップで実装作業を実行                              │
│  - SendMessage でリーダーと通信                              │
└─────────────────────────────────────────────────────────────┘

# 1. GLM API キーの保存 (一度だけ)
moai glm sk-your-glm-api-key

# 2. CG モードの有効化
moai cg

# 3. 同じペインで Claude Code を開始 (重要!)
claude

# 4. ワークフローの実行
/moai "作業の説明"

LSP 診断と AST-grep を組み合わせた自律エラー修正エンジンです:

/moai fix       # 単一パス: スキャン → 分類 → 修正 → 検証
/moai loop      # 反復修正: 完了条件の充足まで反復 (デフォルト最大 10 回)

Ralph Engine の動作方式:

1. 並列スキャン: LSP 診断 + AST-grep + リンターを同時に実行
2. 自動分類: レベル 1 (自動修正) からレベル 4 (ユーザー介入) までエラーを分類
3. 収束検出: 同じエラーが繰り返されると代替戦略を適用
4. 完了基準: 0 エラー、0 型エラー、85%+ カバレッジ

完了条件を直接宣言したいなら goal エンジンを使います:

/moai goal "go test ./... exits 0; すべての AC が PASS として記録"
/moai goal status
/moai goal clear

/moai loop は goal エンジンの上のプリセットです — 診断ツールが見つけた課題キューを全部空にするまで反復修正します。

新機能開発:

/moai plan → /moai run SPEC-XXX → /moai sync SPEC-XXX

バグ修正:

/moai fix (または /moai loop) → /moai review → /moai sync

リファクタリング:

/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai codemaps

ドキュメント更新:

/moai codemaps → /moai sync

すべてのコード変更は Tested · Readable · Unified · Secured · Trackable という 5 つの基準で検証されます。レビュアーの好みではなく、毎回同じ物差しをコードに当てることが目的で、各基準にはカバレッジ · リント · フォーマット · セキュリティスキャン · コミット規約といった機械で判定できる検査が結び付いています。基準ごとの詳しい検証項目は TRUST 5 で扱います。

MoAI-ADK は AI エージェント間でコンテキスト、不変量、危険領域を伝えるために @MX コードレベル注釈システム を使います。

@MX タグシステムは 最も危険で重要なコードだけを表示 するよう設計されています。ほとんどのコードにはタグが必要なく、これは正常な設計です。

# コードベース全体をスキャン
/moai mx --all

# プレビュー (ファイル修正なし)
/moai mx --dry

# 優先順位別スキャン
/moai mx --priority P1

MoAI-ADK は各エージェントに最適なモデルと推論深度を割り当てます。料金プランの使用量制限内で品質を最大化することが目標です — このポリシーは、より弱いモデルクラスに差し替えるのではなく、各エージェントを Opus の effort の階梯に沿って動かします。長期ホライズンのエージェンティックな作業では、弱いモデルほど多くのステップを費やし、作業あたりのコストが高くなるためです。

# プロジェクト初期化時
moai init my-project          # 対話型ウィザードでモデルポリシー選択

# 既存プロジェクトの再設定
moai update                   # 各設定ステップに対する対話型プロンプト

情報

デフォルトポリシーは medium です。GLM 設定は settings.local.json に隔離されます (Git にコミットされません)。設定キーは llm.yaml の profile: high | medium | low(プロファイルマトリクス列)で、legacy performance_tier フィールドが profile 不在時にエイリアスとして読み込まれます (--high/--low はそれぞれ --model-policy high/low の deprecated 別名)。--profile high|medium|low フラグで直接指定でき、legacy の max 値も入力として受け付け high に正規化されます。

MoAI-ADK は開発セッション中に Task ツールのメトリクスを自動的にキャプチャします:

• 場所: .moai/logs/task-metrics.jsonl
• キャプチャするメトリクス: トークン使用量、ツール呼び出し、所要時間、エージェントタイプ
• 目的: セッション分析、性能最適化、コスト追跡

Task ツール完了時に PostToolUse フックがメトリクスをロギングします。このデータを使ってエージェント効率を分析しトークン消費を最適化してください — トークノミクスは測定から始まります。

MoAI-ADK をインストールするとプロジェクトに次のような構造が生成されます。

my-project/
├── CLAUDE.md                  # MoAI の実行指針書
├── .claude/
│   ├── agents/moai/           # 10 個の MoAI カスタムエージェント定義 (+ Explore ビルトイン)
│   ├── skills/moai-*/         # 31 個のスキルモジュール
│   ├── hooks/moai/            # 自動化フックスクリプト
│   └── rules/moai/            # コーディングルールおよび標準
└── .moai/
    ├── config/                # MoAI 設定ファイル
    │   └── sections/
    │       └── quality.yaml   # TRUST 5 品質設定
    ├── specs/                 # SPEC ドキュメント保存所
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # セッション間のコンテキスト維持

主要ファイルの説明:

MoAI-ADK は 4 言語に対応します。ユーザーが韓国語でリクエストすれば韓国語で応答し、英語でリクエストすれば英語で応答します。

情報

言語設定: .moai/config/sections/language.yaml で対話言語、コードコメント言語、コミットメッセージ言語をそれぞれ設定できます。たとえば、対話は韓国語でしつつコードコメントとコミットメッセージは英語で書くように設定できます。

MoAI-ADK の全体像を理解したら、次は各核心概念を詳しく見ていく番です。

• ハーネスエンジニアリング – エージェントが働く環境を設計するパラダイムを学びます
• SPEC ベース開発 – 要件をどうドキュメントで定義するかを学びます
• ドメイン駆動開発 – 既存コードを安全に改善する方法を学びます
• TRUST 5 品質 – コード品質を自動的に検証する方法を学びます
• MoAI Memory – セッション間のコンテキストがどう保存されるかを学びます