AIに従ったら壊れた。Roblox開発環境を“再現性”で再設計した話

はじめに

Robloxの開発シーンにおいて、Roblox Studio内蔵のエディタではなく、VS Codeなどの外部エディタ（Luau LSP）やGit連携を用いたモダンスタイルの開発、いわゆる「外部開発環境」を構築することは、もはやスタンダードになりつつあります。
その中心となるのが、Roblox Studioとローカルファイルを同期する「Rojo」と、ツールチェーンをプロジェクト単位で管理する「Aftman」です。

今回、macOS環境にて新規プロジェクトを立ち上げる際、生成AIに「AftmanとRojoを使った最新の環境構築手順」を出力させ、そのままコマンドを実行してみました。結果として何が起きたかというと、環境が見事に壊れました。

コマンドが通らない、ツール同士が通信できない、挙動が不完全等々。結局、手動で一つずつエラーログを追い、原因を特定して直すという泥臭い作業を強いられました。
この記事は、AIの精度を批判するためのものではありません。このトラブルを通じて見えてきた「AIが提示する環境構築手順の構造的欠陥」と、そこから導き出した「誰が・いつ・どのMacで実行しても同じ状態になる（再現性が高い）」Roblox開発環境のベストプラクティスについて、技術的な観点から整理し、共有するためのものです。

何が壊れたのか（実際に起きた問題）

AIが提示した手順通りにコマンドを実行した結果、具体的に以下の4つのクリティカルな問題が発生しました。

① aftman trust が引数必須でエラー

AIの指示には、初期化フローの一部として以下のようなコマンドが含まれていました。

aftman trust

しかし、これを実行すると「引数が不足しています」というエラーが発生。Aftmanの仕様上、trust コマンドは特定のリポジトリや実行可能ファイルを明示的に信頼するために用いるものであり、単体（引数なし）でマニフェスト全体を信頼するようなマジックコマンドは存在しませんでした。

② aftman install が alias 作成で失敗

気を取り直してツールをインストールしようと aftman install を実行したところ、今度は Failed to create Aftman alias（エイリアスの作成に失敗しました）というエラーで停止しました。
Aftmanは管理下のツール群の実行バイナリのエイリアス（プロキシ）を所定のディレクトリに作成しますが、その権限やディレクトリの存在検知の段階で躓いていました。

③ ~/.aftman/bin のPATH問題

実は②のエラーは、環境全体の前提が間違っていたことに起因します。AIの手順には「必要なバイナリがどこに配置され、どのようにPATHを通すべきか」というインフラとしての前提手順が完全に欠落していました。macOSにおけるzshの環境変数PATH設定を暗黙の了解としてスキップされていたため、OSがツールを認識できなかったのです。

④ Rojo 7.7.0-rc.1 と Plugin 7.6.1 で protocol mismatch

権限周りをなんとか手動で突破し、ついに rojo serve を実行。Roblox Studio側からもRojoプラグインを起動して「Connect」ボタンを押しました。しかし、次に出たのは無情にも以下のエラーでした。

Protocol mismatch!
Server is using protocol version X, but client is using protocol version Y.

原因は、AIが提示した aftman add rojo-rbx/rojo というバージョンを指定しないコマンドにありました。これにより当時の最新タグである「RC版（Release Candidate: 7.7.0-rc.1）」がインストールされてしまい、Studio側の安定版プラグイン（7.6.1）とプロトコルの互換性が崩壊していたのです。

問題の本質：再現性がなかった

これら一連のトラブルの根本原因は、単なるAIのハルシネーション（もっともらしい嘘）ではありません。問題の本質は「提供された手順に環境の再現性が担保されていなかった」という設計思想の欠如にあります。

「最新のものを入れる」「PATHは通っている前提とする」「システムレベルの設定が見えない」といった、属人的・環境依存的なアプローチによって構築された環境は、別のPCや別の開発メンバーに共有した瞬間に脆くも崩れ去ります。
開発環境におけるベストプラクティスとは「最新を追うこと」ではなく「いつ誰が実行しても確実に指定された状態が復元されること（Idempotency: 冪等性）」です。

Aftman v1系とv2系の違い（歴史的背景と仕様）

そもそも、Aftmanとは何なのでしょうか。Robloxのエコシステムでは、かつて Foreman というツールマネージャが広く使われていました。しかし、Rustベースで再構築され、より厳格かつセキュアにツールチェインを管理する現在のデファクトスタンダードが「Aftman」です。

• Foreman時代の遺物とAftman
  AIが出力した aftman trust 無印コマンドのような振る舞いは、過去のパッケージマネージャにおいてグローバルに行われていた信頼設定の概念が学習データに混ざったものと推測されます。現在のAftman（v0.2.x〜等）は、セキュリティの観点から「どのスコープのツール群を明示的に信頼するか」を厳密にマニフェスト化する仕様に変わっています。
• エイリアス（Shims）の仕組み
  Aftmanは ~/.aftman/bin というディレクトリに「プロキシ（Shim）」を置きます。ユーザーがターミナルで rojo と叩くと、このShimが現在のディレクトリの aftman.toml を読み取り、適切なバージョンの実体バイナリへとルーティングします。この仕組みの概念を理解していないと、PATH設定の抜け漏れやエイリアス作成エラーに対して的確な推論を行えません。

Rojo Protocol Mismatchの技術的解説

Roblox開発で最も頻発しかつ開発者を悩ませるのが、この Protocol Mismatch です。
Rojoは、ローカルPC上で動く「サーバー（CLI）」と、Roblox Studio上で動く「クライアント（プラグイン）」が、指定ポート経由でJSONデータをリアルタイム同期し続けるアーキテクチャを採用しています。

この通信プロトコルは、ツールのメジャー／マイナーバージョンに強く依存しています。
Rojoの開発チームは次期プレビュー機能をRC（Release Candidate）タグで頻繁にリリースします。もしバージョンを固定せずに追加を実行すると、Aftmanは問答無用で最新タグであるRC版を拾ってきます。一方、Roblox Studioのプラグインマーケットプレイスからインストールできるのは「安定版（Stable）」です。
「サーバー側は次世代の新しいプロトコルで喋っているのに、クライアント側は現行バージョンのプロトコルしか理解できない」。これがプロトコルミスマッチの完全な技術的背景です。

再現性ある構成の全体図（ベストプラクティス）

これらの環境破壊の経験を踏まえた上で、以下に「真のベストプラクティス」としての環境設計を定義します。

① ツールはプロジェクト単位でバージョン固定（aftman add tool@version）

決して aftman add rojo-rbx/rojo を使ってはいけません。必ず aftman add rojo-rbx/rojo@7.6.0 のように、現在の安定版のバージョン番号を明記してマニフェストに追加します。パッケージ管理のWally等を導入する場合も同様です。

② aftman.toml をGit管理

Aftmanが生成する aftman.toml は、Node.js開発における package.json と同種のエコシステムです。これをGitリポジトリにコミットしておくことで、他のメンバーはリポジトリをクローンして aftman install を叩くだけで、ミリ単位で同じバージョンのツール群を寸分違わず揃えることができます。

③ PATH設定をオンボーディング手順に明示

~/.aftman/bin へのアクセス権問題とPATH設定はインフラとして必須です。プロジェクトのREADME.mdの冒頭には「必ず以下のコマンドを実行し、環境変数にPATHを通してください」とコードブロックで明記します。

④ .gitignore の堅牢化

Roblox Studio特有の一時ファイル（*.rbxl.lock など）や、RojoのUI設定データ、Wallyのパッケージソース群がGitの履歴を汚さないよう、堅牢な除外設定を行います。

⑤ .vscode 設定の共有

複数人で開発する場合、Luauのルールの解釈違いで波線エラーが出まくる事態を防ぐため、.vscode/settings.json と .vscode/extensions.json を共有し、LSP（Language Server Protocol）の挙動を固定化します。

⑥ 安定版のみ使用（RCを避ける）

これは運用ルールとしての徹底です。RC版を使って新機能を試すのはSandboxな別環境のみとし、本番プロジェクトの aftman.toml には安定版のセマンティックバージョニングのみを記載します。

自動化セットアップスクリプト（setup.sh）

手動でコマンドを叩くのはエラーの温床です。macOS環境でメンバーの属人性を排し、再現性を担保するための完全自動化スクリプトをプロジェクト直下に配置します。

#!/bin/bash
# setup.sh
set -e

echo "🚀 Roblox環境セットアップを開始します..."

# 1. Aftmanのインストール確認
if ! command -v aftman &> /dev/null; then
    echo "📦 Aftmanをインストール中..."
    brew install aftman
else
    echo "✅ Aftmanは既にインストールされています"
fi

# 2. PATHの確認検証
if [[ ":$PATH:" != *":$HOME/.aftman/bin:"* ]]; then
    echo "⚠️ ~/.aftman/bin にPATHが通っていません。"
    echo "👉 以下のコマンドを実行してPATHを追加してください："
    echo "echo 'export PATH="\$HOME/.aftman/bin:\$PATH"' >> ~/.zshrc && source ~/.zshrc"
    exit 1
fi

# 3. 依存ツールのインストール (aftman.tomlに基づく厳格な再現)
if [ -f "aftman.toml" ]; then
    echo "📥 Aftmanツールチェーンをインストール中..."
    aftman install
else
    echo "⚠️ aftman.tomlが見つかりません。プロジェクト設定を確認してください。"
    exit 1
fi

# 4. その他必要に応じた初期化（Wallyなど）
if [ -f "wally.toml" ]; then
    echo "📦 Wallyパッケージをインストール中..."
    wally install
fi

echo "✨ セットアップが完了しました！ 'rojo serve' を実行してStudioと同期してください。"

最終的な理想フロー（3ステップ）

上記のような設計思想を反映したプロジェクトにおいて、新しいMacを買ったばかりのエンジニアがRoblox開発を始める際の手順は、たったこれだけへと圧縮されます。

1. リポジトリを git clone する
2. ターミナルで sh setup.sh を実行する（足りないツールは全自動で入り、設定不足があれば警告が出る）
3. 互換エディタ（VS Code / Antigravityなど）を開き、推奨拡張機能をインストールする

これで参画する全員が、完全に同一バージョンのRojo、Wally、Luau LSPを用いた外部開発環境を瞬時に・安全に構築できます。

まとめ：「AIに任せるときに技術者が考えるべきこと」

AIは「それっぽい」手順を数秒で出力してくれます。しかし、その内部に「再現性」「依存関係の解決」「バージョン固定」「異常系のハンドリング」といった、システムアーキテクチャ設計における重要な思想が含まれているとは限りません。

単にインストール手順の羅列をなぞるだけならAIで十分機能しますが、「チームが崩壊しない堅牢な開発インフラを設計する」のは、依然としてシステムを統括する人間のエンジニアの重要な役割です。
今回のRoblox開発環境破壊トラブルは、「最新コマンドの羅列」ではなく「あるべき冪等なシステム状態（Idempotency）」を定義することの重要性を改めて教えてくれました。Robloxでの外部開発を目指している方は、ぜひバージョン固定と自動化スクリプトを活用し、壊れない環境づくりを実践してみてください。