MoAI-ADKとは？

MoAI-ADKはClaude Codeのための 高性能AI開発環境 です。28の専門AIエージェントと52のスキルが協力して高品質なコードを生産します。新規プロジェクトと機能開発にはTDD (デフォルト) 、テストカバレッジが低い既存プロジェクトにはDDDを自動的に適用し、Sub-AgentとAgent Teamsの二重実行モードをサポートします。

Goで記述されたシングルバイナリ — 依存関係なしですべてのプラットフォームで即座に実行できます。

MoAI-ADKの紹介

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

MoAI-ADKは Claude Code内でエージェントが相互作用を通じてエージェントコーディングを実行できるようにするAgentic Development Kit です。まるでAI開発チームが協力してプロジェクトを完成させるように、MoAI-ADKのAIエージェントがそれぞれの専門分野で開発作業を行い、相互に協力します。

なぜMoAI-ADKなのか？

PythonからGoへの完全書き換え

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

主要数値

• 34,220行 Goコード、32個 パッケージ
• 85-100% テストカバレッジ
• 28個 専門AIエージェント + 52個 スキル
• 18個 プログラミング言語サポート
• 16個 Claude Code Hookイベント

バイブコーディングの問題点

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

実務で直面する具体的な問題:

MoAI-ADKの解決策

システム要件

必須条件:

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

クイックスタート

1. インストール

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

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

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

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

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

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

プリビルドバイナリは Releases  ページからダウンロードできます。

2. プロジェクト初期化

moai init my-project

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

3. 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作成

コア哲学

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

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

MoAI開発方法論

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

TDD方法論 (デフォルト)

新規プロジェクトと機能開発のデフォルト方法論です。テストを先に作成し、その後実装します。

ブラウンフィールドプロジェクト (既存コードベース) の場合、TDDに pre-RED分析段階 が追加されます: テスト作成前に既存コードを読んで現在の動作を理解します。

DDD方法論 (既存プロジェクト、10%未満カバレッジ)

テストカバレッジが低い既存プロジェクトを安全にリファクタリングするための方法論です。

ANALYZE   → 既存コードと依存関係を分析、ドメイン境界を特定
PRESERVE  → 特性化テストを作成、現在の動作スナップショットをキャプチャ
IMPROVE   → テスト保護下で段階的に改善。IMPROVE 完了後に /simplify が自動実行されます。

Harness Engineering アーキテクチャ

MoAI-ADK は Harness Engineering パラダイムを実装しています — 直接コードを書くのではなく、AI エージェントが作業する環境を設計するアプローチです。

自動品質・スケールアウトレイヤー

MoAI-ADK v2.6.0+ は、MoAI が自律的に呼び出す 2 つの Claude Code ネイティブスキルを統合しています — フラグや手動コマンドは不要です。

/simplify — 自動品質パス

並列エージェントを使用して変更コードの再利用機会、品質問題、効率性、CLAUDE.md 準拠を確認し、自動修正します。MoAI が実装サイクルごとに直接呼び出します。

/batch — 並列スケールアウト

隔離された git worktree で数十のエージェントを生成し、大規模な並列作業を実行します。各エージェントがテストを実行して結果を報告し、MoAI がマージします。ワークフロー別自動トリガー：

AIエージェントオーケストレーション

MoAIは 戦略的オーケストレーター です。直接コードを書かず、28の専門エージェントに作業を委譲します。

エージェントカテゴリ

52個スキル (Progressive Disclosure)

3レベルProgressive Disclosureシステムでトークンを効率的に管理します:

MoAIワークフロー

Plan → Run → Syncパイプライン

MoAIのコアワークフローは3段階で構成されています:

実際の使用例:

# 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 を表示します。

このゲートにより、環境状態に関わらず正しい実行モードが使用され、実装中のモード不一致が防止されます。

/moaiサブコマンド

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

コアワークフロー

品質とテスト

ドキュメントとコードベース

デフォルトワークフロー

実行モードフラグ

エージェントがワークフロー実行中にどのように配置されるかを制御します:

--teamは3つの実行環境をサポートします:

自律開発ループ (Ralph Engine)

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

/moai fix       # シングルパス: スキャン → 分類 → 修正 → 検証
/moai loop      # 反復修正: 完了マーカー検知まで反復 (最大100回)

Ralph Engineの動作方式:

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

推奨ワークフローチェーン

新機能開発:

/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 coverage → /moai codemaps

ドキュメント更新:

/moai codemaps → /moai sync

TRUST 5品質フレームワーク

すべてのコード変更は5つの品質基準で検証されます:

@MXタグシステム

MoAI-ADKはAIエージェント間でコンテキスト、不変条件、危険領域を伝達するために @MXコードレベルアノテーションシステム を使用します。

@MXタグシステムは 最も危険で重要なコードのみをマーク するよう設計されています。ほとんどのコードにはタグは不要であり、これは正常な設計です。

# コードベース全体をスキャン
/moai mx --all
 
# プレビュー (ファイル変更なし)
/moai mx --dry
 
# 優先度別スキャン
/moai mx --priority P1

モデルポリシー (トークン最適化)

MoAI-ADKはClaude Codeサブスクリプションプランに合わせて28個のエージェントに最適なAIモデルを割り当てます。プランの使用量制限内で品質を最大化します。

設定方法

# プロジェクト初期化時
moai init my-project          # 対話型ウィザードでモデルポリシーを選択
 
# 既存プロジェクトの再設定
moai update                   # 各設定ステップに対する対話型プロンプト

二重実行モード

MoAI-ADKはClaude Codeがサポートする Sub-Agent と Agent Teams の2つの実行モードを提供します。

Agent Teamsモード (デフォルト)

MoAI-ADKはプロジェクトの複雑度を自動的に分析して最適な実行モードを選択します:

Agent Teamsモード は並列チームベース開発を使用します:

• 複数のエージェントが同時に作業し、共有タスクリストで協調
• TeamCreate、SendMessage、TaskListによるリアルタイム調整
• 大規模な機能開発、マルチドメインタスクに適している

/moai plan "大規模機能"          # 自動: researcher + analyst + architect並列
/moai run SPEC-XXX                # 自動: backend-dev + frontend-dev + tester並列
/moai run SPEC-XXX --team         # Agent Teamsモードを強制

CGモード (Claude + GLMハイブリッド)

CGモードはLeaderが Claude API を、Workersが GLM API を使用するハイブリッドモードです。tmuxセッションレベルの環境変数分離によって実現されます。

┌─────────────────────────────────────────────────────────────┐
│  LEADER (現在のtmuxペイン、Claude API)                        │
│  - /moai --team実行時にワークフローオーケストレーション          │
│  - 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 --team "タスクの説明"

Sub-Agentモード (--solo)

既存のClaude Codeの Task() APIを活用した順次エージェント委譲方式です。

• 1つの専門エージェントに作業を委譲して結果を受け取る
• 段階別にManager → Expert → Qualityの順で進行
• シンプルで予測可能なワークフローに適している

/moai run SPEC-AUTH-001 --solo    # Sub-Agentモードを強制

CLIコマンド

Taskメトリクスロギング

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

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

Taskツール完了時にPostToolUseフックがメトリクスをロギングします。このデータを使用してエージェントの効率性を分析し、トークン消費を最適化してください。

プロジェクト構造

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

my-project/
├── CLAUDE.md                  # MoAIの実行指示書
├── .claude/
│   ├── agents/moai/           # 28個のAIエージェント定義
│   ├── skills/moai-*/         # 52個のスキルモジュール
│   ├── hooks/moai/            # 自動化フックスクリプト
│   └── rules/moai/            # コーディングルールと標準
└── .moai/
    ├── config/                # MoAI設定ファイル
    │   └── sections/
    │       └── quality.yaml   # TRUST 5品質設定
    ├── specs/                 # SPECドキュメント保管場所
    │   └── SPEC-XXX/
    │       └── spec.md
    └── memory/                # セッション間コンテキスト維持

主要ファイルの説明:

多言語サポート

MoAI-ADKは4つの言語をサポートしています。ユーザーが韓国語でリクエストすれば韓国語で応答し、英語でリクエストすれば英語で応答します。

次のステップ

MoAI-ADKの全体像を理解したら、次は各コアコンセプトを詳しく学びましょう。

• SPECベース開発 — 要件をどのように文書として定義するかを学びます
• ドメイン駆動開発 — 既存コードを安全に改善する方法を学びます
• TRUST 5品質 — コード品質を自動的に検証する方法を学びます
• MoAI Memory — セッション間でコンテキストがどのように保存されるかを学びます