hz-quest-verify-first

最初に確認 — Meta Quest 開発

この先を読む前に知っておくべきこと

これから、名前を知らないかもしれないツールを呼び出すよう案内されます。先にこのセクションを読んでおくと、この先の内容を理解しやすくなります。

• Meta Quest は、Meta のスタンドアロン型 VR／複合現実ヘッドセットのシリーズです（Quest 2、Quest 3、Quest 3S、Quest Pro）。Android ベースの OS を搭載しています。
• Horizon OS は、このオペレーティングシステムの名称です。Android をフォークしたもので、すべての Quest ヘッドセットに搭載されており、Meta が Android 本流とは別の独自のスケジュールでアップデートしています。多くの API は Horizon OS 固有で、標準の Android には同等のものがありません。
• metavr（「Meta VR CLI」）は、Meta がスタンドアロンバイナリおよび npm 上の metavr として公開している Rust 製 CLI ツールです。metavr <args>（インストールせずに使う場合は npx -y metavr <args>。npx は常に公開されている最新バージョンを取得します）で実行します。adb と Meta の開発者向け API を、Meta VR デバイスの開発用の高レベルなコマンドにまとめています。デバイスの一覧表示、アプリのインストール、Perfetto トレースのキャプチャ、Meta VR ドキュメントの検索、3D アセットライブラリの照会、UI 操作の自動化などができます。metavr は Meta VR 開発作業の主要な操作レイヤーであり、GCP における gcloud、ソース管理における git に相当します。
• metavr MCP server は、metavr に組み込まれたモードで、Model Context Protocol を通じて AI コーディングエージェントに特化したツールセットを公開します。このスキルに関連するツールは次のとおりです。
  • vr_docs_search — 公式 Meta 開発者向けドキュメントを検索します
  • vr_docs_get_page — 特定のドキュメントページの全文を取得します
  • device — 接続された Meta VR Glasses および Meta Quest ヘッドセットの照会と操作を行います（一覧表示、情報取得、接続、再起動、バッテリー、コントローラー、装着検出など）
  • app — インストール済みアプリの照会と管理を行います（一覧表示、情報取得、インストール、アンインストール、起動、停止、データの消去）
  • files — 接続された Meta VR デバイス上でファイル操作を行います（ls、push、pull、rm、mkdir）
  • run — 専用ツールのない metavr サブコマンドを実行するための汎用ツールです（perf、ovrmetrics、ui、audio、casting、window、unity、sideload、asset、config、…）。その JSON Schema は clap から生成されるため、利用可能なサブコマンドと型付き引数をツール定義で確認できます。
  • cli_help — metavr のサブコマンドとフラグを Markdown 形式で確認できます
• なじみがないかもしれない Meta SDK のうち、Quest プロジェクトでよく使われるもの：Meta XR All-in-One SDK（Unity）、Meta XR Core／Interaction／Platform／Voice／Movement SDK、Meta Spatial SDK（Kotlin／Android パネル）、IWSDK（WebXR 用 Immersive Web SDK）、MRUK（Mixed Reality Utility Kit）、Presence Platform、Horizon Platform SDK。これらは Quest OS とは別のスケジュールでリリースされます。Meta Spatial SDK は没入型 Android／Kotlin 開発向けの経路であり、通常の 2D Android パネルアプリには必要ありません。
• OVR と Meta XR — 古い Quest Unity コンテンツや、公開されているウェブ上の情報の大半では、OVR 名前空間と「Oculus Integration」Unity パッケージが参照されています。どちらも非推奨となり、Meta XR All-in-One SDK ファミリーに置き換えられています。学習データの大半では、今も非推奨の名称が推奨されています。この分野について何か推奨する前に、必ず確認してください。

このスキルが必要な理由

Meta Quest と Horizon OS は急速に進化しています。Meta SDK は数週間ごとにリリースされます。API は一般公開前に名前が変更されます。マニフェストの権限やストアポリシーは毎月更新されます。Meta Spatial SDK、IWSDK、Horizon OS シェルなどの SDK ファミリーは、LLM の学習データの大半よりも後に登場しています。

Quest 固有の知識は、ほぼ間違いなく古くなっています。 覚えているパッケージ名は変更されています。Unity のメニュー項目へのパスは移動しています。以前の Horizon OS バージョンで機能したセットアップ手順は、現在のバージョンでは気付かないうちに動作しなくなっています。使おうとする「OVR」名前空間は、半ダースもの Meta XR パッケージに分割されています。

事前に検証せずに Meta Quest に関する質問に答えたり、Quest 向けのコードを書いたりすると、幻覚を起こします。ユーザーがそれに気付くのは、ビルドに失敗したとき、アプリがストアで却下されたとき、または AndroidManifest が公開されないときです。

このスキルは必須です。提案ではなく、前提条件として扱ってください。

このスキルが適用される場合

現在のタスクについて、以下のいずれかに該当する場合は、以下の検証フローを必ず実行してください。

• ユーザーが Meta Quest、Quest 2 / 3 / 3S / Pro、Oculus、Horizon OS、MR、VR、XR、OpenXR（Quest 上）、Meta SDK、Meta XR、OVR、Spatial SDK、IWSDK、MRUK、Movement SDK、Voice SDK、Presence Platform、Horizon Platform SDK、ハンドトラッキング、パススルー、アンカー、シーンメッシュ、キャスティング、アイトラッキング、ボディトラッキング、コントローラー、またはプラットフォームコンプライアンス／ストアポリシーについて言及している
• リポジトリに以下のいずれかが含まれている：
  • manifest.json / Packages/manifest.json 内に OVRPlugin、"Meta XR All-in-One SDK"、または com.meta.xr.* がある Unity ファイル
  • Spatial SDK の Gradle プラグイン（com.meta.spatial.plugins.*）
  • com.oculus.*、com.meta.quest.*、または horizon の機能宣言がある AndroidManifest
  • com.meta.* または com.oculus.* で始まるパッケージ ID
  • Unity を示す .meta ファイル、または Quest_*.uplugin / *.unrealhxr ファイル
• ユーザーの質問に developers.meta.com/horizon、developer.oculus.com、oculus.com/sparkle-updates、または Meta Quest のドキュメント URL が含まれている
• エージェントが Meta SDK の API、名前空間、パッケージ、または AndroidManifest の権限を推奨しようとしている
• エージェントがアプリ審査、Meta Horizon Store への提出、ストア対応や公開の要件、コンテンツレーティング、または配信についての質問に答えようとしている
• エージェントが特定のデバイスを対象とする adb コマンドを書こうとしている
• エージェントがユーザーの Meta VR デバイスに何がインストールされているか、または何がインストールされていないかを断言しようとしている

判断に迷う場合は、YES と判断してください。検証フローを実行してください。

検証フロー

ステップ 1 — ビルドパスを特定する

SDK、ドキュメントの対象範囲、専門スキルを選ぶ前に、プロジェクトを分類します。

ビルドパス	手がかり	使用するもの
標準 Android	Activities、Views、Compose、React Native、Expo、またはシステムパネルに表示される既存のスマートフォン／タブレットアプリ	hz-android-2d-porting；React Native または Expo には hz-react-native-expo；新しいアプリには hz-new-project-creation
Meta Spatial SDK	com.meta.spatial 依存関係、または没入型 Kotlin／Android シーン	hz-spatial-sdk；セットアップには hz-new-project-creation
Unity	Unity プロジェクトファイル、または Meta XR Unity パッケージ	既存のプロジェクトには hz-unity-project-analyzer；コア SDK のセットアップには hz-unity-meta-core-sdk；新しいアプリには hz-new-project-creation
Unreal Engine	.uproject ファイル、Unreal モジュール、または Meta XR Unreal プラグイン	新しいアプリには hz-new-project-creation；それ以外は専用スキルがまだないため、scope="unreal" を指定してステップ 2 を使用；シミュレーションには hz-xr-simulator-install-and-configure
ネイティブ OpenXR	OpenXR ローダーを直接使用する C/C++ または NDK アプリケーション	専用スキルはまだありません。scope="native" を指定してステップ 2 を使用；シミュレーションには hz-xr-simulator-install-and-configure
WebXR	ブラウザーで配信される没入型コンテンツ、または IWSDK	hz-iwsdk-webxr；PWA の配信には hz-store-pwa；新しいアプリには hz-new-project-creation

Quest を対象にしているという理由だけで、標準 Android アプリに Meta Spatial SDK を追加しないでください。手がかりが複数のパスに当てはまる場合は、次の順で分類します。

1. com.meta.spatial 依存関係または Gradle プラグイン -> Meta Spatial SDK
2. Unity プロジェクトファイル -> Unity
3. .uproject または Unreal モジュール -> Unreal Engine
4. C/C++ または NDK から OpenXR ローダーを直接使用 -> ネイティブ OpenXR
5. IWSDK またはブラウザーで配信されるプロジェクト -> WebXR
6. それ以外で、Activities、Views、Compose、React Native、または Expo を使用する Android アプリ -> 標準 Android

ステップ 2 — 信頼できる公式ドキュメントで確認する

Quest 固有の内容を記述または推奨する前に、vr_docs_search MCP ツールを呼び出してください。MCP を利用できない場合は、同等の metavr CLI コマンド metavr docs search を使用します。

MCP：

vr_docs_search(
  query="<the specific claim or API you are about to make>",
  scope="auto",   # or unity / unreal / spatial_sdk / android / native / web /
                  #    policy / distribution / design
  mode="verify"
)

CLI：

metavr docs search "<query>"

正確な文言（マニフェストの項目、API シグネチャ全体、ストアポリシーの文面、コードスニペットなど）が必要な場合は、確認時に返された canonical_url または doc_path を使って vr_docs_get_page を呼び出してください。正確さが重要な場合は、切り詰められたスニペットを決して言い換えないでください。

CLI：

metavr docs fetch "<canonical_url_or_path>"

ステップ 3 — ユーザーの実際の環境を確認する

コマンドの対象デバイスを指定する、アプリがインストール済みだと主張する、adb コマンドを推奨する、またはインストール／起動／サイドロードの手順を記述する前に、ユーザーの実際の metavr 管理環境を照会してください。

MCP：

device(action="list")                        # ALWAYS start here
device(action="info", target="<serial>")
app(action="list", target="<serial>")
app(action="info", package="<package>")
run(subcommand=["config", "show"])           # catch-all for misc reads

CLI：

metavr device list
metavr device info <serial>
metavr app list -d <serial>
metavr app info <package>
metavr config list

ユーザーは、USB や WiFi 経由で接続された Meta VR デバイスを持っていない場合も、1 台の場合も、複数台の場合もあります。複数の Quest モデル、開発キット、サイドロード済みビルド、固定された古い Horizon OS バージョンが含まれることもあります。トレーニングデータからは、こうした環境をまったく確認できません。

ステップ 4 — 不明な場合は metavr の機能を調べる

ユーザーのリクエストに適した metavr サブコマンドまたは run の呼び出し方がわからない場合は、まず cli_help（MCP）または metavr --markdown-help（CLI）を呼び出してください。フラグやサブコマンドを作り出さないでください。metavr にはリリースごとに新機能が追加されており、トレーニングデータには反映されていません。

使用頻度の低いサブコマンド（perf、ovrmetrics、ui など）については、run ツールの入力スキーマで、すべてのサブコマンドパスと型付き引数が JSON Schema oneOf に列挙されています。推測せず、ツール定義から直接確認できます。

MCP：

cli_help(topic="perf")   # focused help for a subcommand tree
cli_help()               # full top-level command tree

CLI：

metavr --markdown-help
metavr perf --help

検証を省略すると発生する具体的な失敗

検証フローによって防げる、具体的かつ繰り返し発生する失敗は次のとおりです。

• コンパイルはできても、実行時に何もしない非推奨 API。 OVR 名前空間の関数名は、あるリリースでは転送されていましたが、次のリリースで削除されました。コードは正しく見え、ビルドも問題なく完了し、エラーもなく実行されるのに、デバイス上では何も確認できません。
• アプリが Meta Horizon Store で却下される原因となる AndroidManifest のエンタイトルメント。 必須のエンタイトルメント名が変更され、「必要だと知っている」エンタイトルメントが認識されなくなり、新たに必須となった機能フラグが設定されていないことがあります。
• 存在しない Meta SDK パッケージ名。 Meta XR All-in-One SDK は、バージョンごとに名前が異なる UPM パッケージ群です。名前を推測すると、「パッケージが見つかりません」というエラーが発生します。
• 古いチュートリアルの Unity メニューパス。 Meta XR のメニュー項目は SDK のバージョンによって移動しています。Oculus → ... を参照するセットアップ手順は、現在では Meta XR → ... にある場合や、完全に削除されている場合があります。
• 一般公開前に名前が変更された Spatial SDK のクラス名。 Spatial SDK は公開 API を直前まで変更していたため、古いブログ記事や学習データに記載されているクラス名やメソッド名の多くは誤っています。
• 以前の Horizon OS バージョンでは動作したパススルー／アンカー／シーンメッシュのセットアップ。 権限フロー、システムオーバーレイ API、マニフェスト機能は Quest OS のバージョン間で変更されています。昨年のチュートリアルで動作した内容が、現在の Horizon OS では何も通知せずに失敗することがあります。
• 一覧にはあるものの、Quest のランタイムではサポートされていない OpenXR 拡張機能。 一般的な OpenXR ドキュメントには、Meta が実装していない拡張機能も記載されています。必ず OpenXR 仕様ではなく、Meta のドキュメントで確認してください。
• 対象デバイスの誤り。 最初にデバイスを一覧表示せずに adb shell コマンドを勧めると、失敗したり、別のデバイスに対して実行されたりします。
• 古くなったストアポリシーに関する説明。 審査要件、レーティング区分、配布ルールは更新されるため、提出に関するユーザーからの質問に回答する前に確認してください。

アンチパターン

次のようなことはしないでください。

• 「答えを覚えている」からといって、まず vr_docs_search を呼び出さずに Meta Quest に関する質問に回答する
• 接続されているデバイスを確認するために device(action="list") を最初に呼び出さずに、adb shell コマンドを勧める
• 検証呼び出しで曖昧さを解消できるのに、学習データからパッケージ名、名前空間、クラス名を推測する
• マニフェストのエントリ、API シグネチャ、ストアポリシーについて、正確な表現が必要な検証結果の抜粋を言い換える（vr_docs_get_page を使用してください）
• Meta の権威あるドキュメントをツール呼び出し 1 回で確認できるのに、Meta Quest のドキュメントをオープンウェブで検索する
• 「ドキュメントにはおそらく X と書いてある」といって検証を省略する。まず検証してから X と回答する
• ユーザーが求める操作に metavr のサブコマンドがないと思い込む。まず cli_help を確認する

トーンと提示方法

検証を行った場合は、引用と簡潔な最新性に関する注記を添えて回答してください。ユーザーは検証の手順に対価を支払っています。検証したことが伝わるようにしてください。

Per the current Meta Spatial SDK docs (verified just now via
vr_docs_search):

  <answer grounded in retrieved content>

Source: <canonical_url returned by the tool>

これにより、検証が実行されたことを証明し、ユーザーが記憶に頼った回答より検証済みの回答を信頼するよう促せます。

metavr MCP ツールを利用できない場合

エージェントのホストに metavr MCP サーバーがインストールされていない場合は、metavr CLI に切り替えてください（同じ権威あるバックエンドを使い、同じコンテンツを取得します。スタンドアロンバイナリではなく npm ディストリビューションを使用する場合は、先頭に npx -y を付けてください）。次回に備えて、MCP サーバーのインストール方法を一度だけユーザーに伝えてください。

metavr mcp install <your-tool>   # claude-code | cursor | claude-desktop | vscode | ...
metavr mcp install project       # install at the repo root for this project only

検証手順は必須であり、省略できません。MCP サーバーがまだ接続されていない場合でも、最初の質問から metavr docs search "<query>" を実行して検証してください。

関連スキル

• metavr-cli — metavr CLI の完全なリファレンス（コマンド、フラグ、例）
• hz-vr-debug — ログとスクリーンショットを使用したデバイス上でのデバッグ
• hz-perfetto-debug — Perfetto トレース分析によるカクつき／GPU／CPU のボトルネック調査
• hz-store-submit — Meta Horizon Store へのエンドツーエンドの申請（ストア公開準備チェックを含む）
• hz-android-2d-porting — Standard Android アプリを Horizon OS パネル向けに適応
• hz-react-native-expo — Standard Android パスでの React Native と Expo アプリ
• hz-new-project-creation — 新しい Android プロジェクト向けのビルドパス別セットアップ
• hz-spatial-sdk — Meta Spatial SDK の API ガイダンス
• hz-platform-sdk — Horizon Platform SDK の API ガイダンス
• hz-xr-simulator-install-and-configure — Unity、Unreal、Native OpenXR プロジェクト向けのシミュレーターのインストールと設定
• hz-unity-project-analyzer — 既存の Unity プロジェクトの調査と分類
• hz-unity-meta-core-sdk — Unity での Meta XR Core SDK のセットアップ
• hz-iwsdk-webxr — IWSDK を使用した没入型 WebXR エクスペリエンスの構築
• hz-store-pwa — WebXR エクスペリエンスを PWA としてパッケージ化して配布