アップデート

MoAI-ADK を最新バージョンに保つ方法を案内します。moai update 一つでバイナリとテンプレートが一緒に更新され、ユーザーが作ったカスタム資産は自動的に保存されます。

フラグなしで実行するとバイナリとテンプレートの両方を更新します — これがデフォルトの動作です。

moai update

flowchart TD
    A["moai update 実行"] --> B["Stage 1: パッケージバージョン確認"]
    B --> C{"最新バージョン?"}
    C -->|"はい"| D["Stage 2: 設定バージョン比較"]
    C -->|"いいえ"| E["すでに最新状態"]
    D --> F{"設定形式の変更?"}
    F -->|"はい"| G["設定マイグレーション (バックアップ後)"]
    F -->|"いいえ"| H["設定維持"]
    G --> I["Stage 3: テンプレート同期"]
    H --> I
    I --> J["完了報告書"]

現在インストールされているバージョンと GitHub Releases の最新バージョンを比較します。

# 現在のバージョン確認
moai --version

# 利用可能なアップデートのみ確認 (実際のアップデートはしない)
moai update --check

moai update の binary ダウンロードは checksum 検証を回避できません。release の checksums.txt ダウンロードが失敗するかパースが失敗するとアップデートフローを 中止(abort) します — binary のダウンロードを試みません。

checksums.txt のダウンロードは 3 回 retry を指数バックオフで試行します:

すべての retry が失敗すると次のようなメッセージが出力されます:

error: checksum unavailable: persistent retry failure after 3 attempts

--skip-checksum のような回避オプションは存在しません (CWE-345 の意図されたポリシー)。

1. ネットワーク接続の確認:
   bash コピー

   curl -I https://github.com/modu-ai/moai-adk/releases/latest

2. Proxy / firewall の確認 — GitHub release asset ドメイン (github.com、objects.githubusercontent.com) の許可有無
3. 一時的な GitHub CDN 障害の可能性 — しばらくして再試行
4. 手動 binary インストール (永久遮断時):
   bash コピー

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

   手動インストール時は GitHub Release の checksums.txt を別途確認することを推奨します。

詳しい脅威モデルは セキュリティノート — CWE-345 を参照してください。

設定ファイルの形式と互換性を検査します。形式が変更された場合、自動的にバックアップ後にマイグレーションします。

検査ファイル:

• .moai/config/sections/ 配下の YAML ファイル

情報

設定マイグレーションの前に必ず .moai/config/ ディレクトリがバックアップされます。

プロジェクトテンプレートと基本ファイルを最新バージョンに同期します。ユーザーが修正したファイルは保存され、新バージョンとの衝突時はバックアップ後にマージされます。

graph TD
    A["テンプレート同期"] --> B["SKILL.md テンプレート"]
    A --> C["エージェントテンプレート"]
    A --> D["ルールファイル"]
    A --> E["設定デフォルト値"]

    B --> F{"ユーザー変更?"}
    C --> F
    D --> F
    E --> F

    F -->|"いいえ"| G["自動アップデート"]
    F -->|"はい"| H["バックアップ後 3-way マージ"]

    G --> I["同期完了"]
    H --> I

バイナリのみアップデートしテンプレートは同期しません:

moai update --binary

moai update --version <tag>は、特定の GitHub リリースタグ(stable、rc、旧バージョン)を、デフォルトのアップデートと同じチェックサム検証ダウンロード経路でインストールします。1つのフラグで3つの用途(stable版の固定、テスト用rcへの切替、リグレッション後の旧バージョンへのロールバック)をカバーします。

# stable リリースへの固定
moai update --version v3.0.0

# 先頭の "v" は省略可能
moai update --version 3.0.0

# rc の試用
moai update --version v3.1.0-rc1

# 旧バージョンへのロールバック
moai update --version v2.14.0

情報

このフラグは api.github.com ホストの https のみを使用し、ダウンロードしたバイナリをリリースの公開チェックサムで検証します — --skip-checksum / --insecure のバイパスはありません。プラットフォームに合致するバイナリアセットがない場合やチェックサム不一致の場合は、0以外の終了コードで終了しファイルシステムは変更されません。

--versionは一部のフラグと排他で、他のフラグとは併用できます:

要求タグが実行中バージョンより古い場合、対話型ターミナルで確認プロンプトが表示されます。--yes を渡すか(CI等)非 TTY stdin で実行すると、プロンプトをスキップして進行します。

デフォルトの moai update(–version なし)は GitHub の /releases/latest を取得し、これはプレリリースを自動的に除外します — したがって rc やプレリリースタグはデフォルトフローでは決して公開されません。--version <tag> だけが rc や特定の旧タグを明示的にインストールする唯一の経路です。

テンプレートのみ同期しバイナリはアップデートしません:

moai update --templates-only

設定ウィザードを再実行してプロジェクト構成を変更します (テンプレート同期は行いません):

moai update -c
# または
moai update --config

実際の変更なしで計画されたアーカイブとインストール作業を事前に確認します:

moai update --dry-run

すべての確認を自動承認します:

moai update --yes

moai --version

moai doctor

moai --help

MoAI-ADK アップデート時に CLAUDE.md と settings.json は新バージョンに同期されます。個人的な修正事項は別のファイルに保管してください。

情報

設定の優先順位: Local > Project > User > Enterprise
settings.local.json がプロジェクト設定をオーバーライドします。

MoAI-ADK は次のフォルダでのみファイルを管理します:

.claude/
├── agents/
│   ├── moai/                # MoAI-ADK エージェント (アップデート対象)
│   └── harness/             # ユーザーハーネスエージェント (アップデート除外、保存)
│
├── hooks/
│   └── moai/                # MoAI-ADK フックスクリプト (アップデート対象)
│
├── skills/
│   ├── moai-*               # MoAI-ADK スキル (moai- 接頭辞、アップデート対象)
│   └── hns-*                # ユーザー生成スキル (アップデート除外、保存)
│
└── rules/
    └── moai/                # ルールファイル (moai 管理)

注意

重要: moai- 接頭辞を持つスキルは MoAI-ADK が管理し、アップデート時に上書きされます。自分で作ったスキルは hns- 接頭辞 (ユーザー所有ネームスペース) を、エージェントは .claude/agents/harness/ ディレクトリを使ってください。

アップデート後に問題が発生したら、以前のバージョンにロールバックできます:

# インプロセスで特定バージョンにロールバック (推奨)
moai update --version <リリースタグ>

# ブートストラップ経路 (moai インストール前): インストールスクリプトを使用
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <リリースタグ>

# バックアップから設定を復元
cp -r .moai/config.bak .moai/config

注意

ロールバックの前に現在の作業をコミットしてください。

# ネットワーク確認
curl -I https://github.com/modu-ai/moai-adk/releases/latest

# 手動再インストール
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# バックアップから復元
cp -r .moai/config.bak .moai/config

# 設定検証
moai doctor

ユーザーが修正したテンプレートファイルは自動的にバックアップ後 3-way マージされます。衝突が発生したら --verbose で詳細な警告を確認してください:

moai update --verbose

強制的に上書きするには --force を使います (既存のユーザー変更事項は .moai/archive/ にバックアップされます):

moai update --force

1. 変更ログの確認 — 新機能の学習
2. 核心概念 — 新しいエージェントおよび機能の習得
3. クイックスタート — プロジェクトへの新機能の適用