Skip to main content

よくある質問

更新 2026-08-26 6分で読めます GitHub で編集 ↗

MoAI-ADK 使用中によくある質問と回答です。

Q: moai と /moai は何が違いますか?

まったく別の 2 つです。最もよくある混同なので先に押さえます。

moai (ターミナル CLI)/moai (スラッシュサブコマンド)
実行場所ターミナルシェルClaude Code の対話画面
正体Go バイナリClaude Code スキル呼び出し
用途プロジェクト設定、テンプレート配布AI エージェント開発ワークフロー
例moai init my-project/moai plan "認証機能"
  • ターミナルで moai plan を実行しても動作しません — /moai plan は Claude Code の中でのみ有効です。
  • Claude Code で /moai init と入力しても動作しません — moai init はターミナルコマンドです。

Q: statusline のバージョン表示は何を意味しますか?

MoAI statusline はバージョン情報とアップデート通知を併せて表示します:

text 
🗿 v3.1.2 -> 🗿 v3.1.3
  • 🗿 v3.1.2: 現在インストールされているバージョン
  • -> 🗿 v3.1.3: アップデート可能な新しいバージョン (ASCII 矢印 -> でつながれます)

最新バージョンを使用中のときはバージョン番号だけが表示されます:

text 
🗿 v3.1.3

アップデート方法: moai update 実行時にアップデート通知が消えます。

情報
参考: Claude Code のビルトインバージョン表示 (🔅 v2.1.38) とは異なります。MoAI の表示は MoAI-ADK のバージョンを追跡し、Claude Code は自身のバージョンを別途表示します。

Q: statusline に表示されるセグメントをカスタマイズするには?

statusline はセグメント単位でオン・オフします。各セグメントを個別にトグルして、欲しい情報だけを残してください。ディスプレイプリセットはありません — 設定はテーマとセグメントの2つだけです。

moai init または moai update -c ウィザードで設定するか、.moai/config/sections/statusline.yaml を直接編集します:

yaml 
statusline:
  segments:
    model: true
    context: true
    output_style: false
    directory: false
    git_status: true
    claude_version: false
    moai_version: false
    git_branch: true

segments: ブロックが無ければ、すべてのセグメントがデフォルトで有効になります。

情報
詳しい内容は SPEC-STATUSLINE-001 を参照してください。

Q: モデルポリシーをどう選びますか?

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

ティア比較

ティア特徴
high最高品質 — 呼び出し頻度が最も低い2つのエージェントに max の推論深度
medium (デフォルト値)品質とコストのバランス — コスト/スコア曲線の膝
low作業あたり最低コスト — エージェンティックなエージェントは Opus low effort に下がる
注意
なぜ重要ですか? ティアを下げることはモデルクラスではなく 推論深度 を下げることです。長期にわたるエージェンティックな作業では、Opus の low effort が max を含むあらゆる effort の Sonnet よりもスコアが高く、作業あたりのコストも低くなります — 請求額を決めるのはトークン単価ではなく、モデルが完了までに費やしたステップ数です。したがって low は Opus の中で節約し、複数ステップを踏んでから失敗するおそれのない単発の行 (manager-git、Explore) でのみ Sonnet を使います。

ティア別エージェントモデル割り当て

11 個のエージェントカタログ (10 MoAI カスタム + 1 Anthropic ビルトイン Explore) のうち MoAI カスタムエージェントはティアに応じてモデルが割り当てられます。かつての 12 個の保管エージェント (archived agents) は利用できません。

Manager Agents (5 個)

エージェントhighmediumlow
manager-specopus / highopus / mediumopus / low
manager-developopus / maxopus / mediumopus / low
manager-docsopus / mediumopus / lowsonnet / low
manager-gitsonnet / lowsonnet / lowsonnet / low
manager-designopus / highopus / mediumopus / low

Evaluator · Builder · Advisor · Specialist Agents (5 個)

エージェントhighmediumlow
plan-auditoropus / highopus / mediumopus / low
sync-auditoropus / highopus / mediumopus / low
builder-harnessopus / highopus / mediumopus / low
super-advisoropus / maxopus / highopus / medium
e2e-testeropus / mediumopus / lowsonnet / low

ビルトインの Explore はすべての列で sonnet / low に解決されます — ディスク上にピン留めするエージェントファイルがないため、呼び出し時のデフォルト値です。

設定方法

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

# 既存プロジェクトの再設定
moai update -c                # 設定ウィザードの再実行
情報
デフォルトティアは medium です。moai update -c で設定ウィザードを再実行して変更できます。

Q: “Allow external CLAUDE.md file imports?” 警告が表示されます

プロジェクトを開くとき、Claude Code が外部ファイル import に関するセキュリティプロンプトを表示することがあります:

text 
External imports:
  /Users/<user>/.moai/config/sections/quality.yaml
  /Users/<user>/.moai/config/sections/user.yaml
  /Users/<user>/.moai/config/sections/language.yaml
情報
推奨する対応: “No, disable external imports” を選択してください。

理由:

  • プロジェクトの .moai/config/sections/ にすでにこれらのファイルが存在します
  • プロジェクト別設定がグローバル設定より優先適用されます
  • 必須設定はすでに CLAUDE.md テキストに含まれています
  • 外部 import を無効化する方が安全で、機能に影響を与えません

ファイルの説明:

  • quality.yaml: TRUST 5 フレームワークおよび開発方法論の設定
  • language.yaml: 言語設定 (会話、コメント、コミット)
  • user.yaml: ユーザー名 (オプション、Co-Authored-By 表示用)

Q: TDD と DDD 方法論の違いは何ですか?

MoAI-ADK v2.5.0+ では、方法論を TDD または DDD のどちらか からのみ選べます。明確性と一貫性のため hybrid モードは除去されました。

TDD はテストを先に書いてそのテストを通す順序なので新規開発に向いており、DDD は既存の動作を特性テストで押さえたうえで少しずつ手を入れる順序なので、テストがほとんどないコードに向いています。各サイクルのステップごとの手順は SPEC ベース開発 と DDD で扱います。

方法論選択表

プロジェクト状態テストカバレッジ推奨方法論理由
新規プロジェクトN/ATDDテスト優先開発
既存プロジェクト50%+TDDテスト基盤がある
既存プロジェクト10-49%TDDテスト拡張が可能
既存プロジェクト< 10%DDD段階的な特性テストが必要

設定方法

bash 
# プロジェクト初期化時に自動検出
moai init my-project          # --mode <ddd|tdd> フラグで指定可能

# 手動設定
# .moai/config/sections/quality.yaml を編集
development_mode: tdd         # または ddd

Q: 自分のコードに @MX タグがない理由は?

これは 完全に正常 です。@MX タグシステムは AI が最初に注目すべき最も危険で重要なコードだけを表示するよう設計されています。

質問回答
タグがなければ問題ですか?いいえ。 ほとんどのコードにはタグが必要ありません。
タグはいつ追加されますか?高い fan_in (呼び出し元 >= 3)、複雑なロジック (複雑度 >= 15)、危険なパターン (context のない goroutine) にのみ追加されます。
すべてのプロジェクトが似ていますか?はい。 すべてのプロジェクトでほとんどのコードにはタグがありません。

タグの優先順位

優先順位条件タグの種類
P1 (致命的)fan_in >= 3@MX:ANCHOR
P2 (危険)goroutine、複雑度 >= 15@MX:WARN
P3 (コンテキスト)マジック定数、godoc なし@MX:NOTE
P4 (欠落)テストファイルなし@MX:TODO

コードベースを @MX タグでスキャンするには:

bash 
/moai mx --all        # 全体スキャン
/moai mx --dry        # プレビュー
/moai mx --priority P1  # 致命的な項目のみ

さらに質問がありますか?