minecraft-modding-workbench

Minecraft Modding ワークベンチ

高速でバージョンを考慮した Minecraft の Mod 制作をサポートします。minecraft-modding MCP サーバーを主な信頼できる情報源として扱い、検証済みの情報を動作するコードや アセットに反映します。

対象範囲

• Fabric、NeoForge、Architectury に対応します。
• @adhisang/minecraft-modding-mcp の minecraft-modding MCP サーバーが必要です。
• ワークスペースがある場合は、プロジェクトを考慮した MCP 呼び出しを優先します。リポジトリのルートを projectPath として再利用します。
• まずは高レベルの MCP ワークフローツールを使用します：inspect-minecraft、 analyze-symbol、compare-minecraft、validate-project、analyze-mod、 manage-cache。
• 適切な場合は、MCP の検証用およびバッチ処理用ヘルパーも使用します： 1 回の呼び出しで Mixin の所有者／メンバーを確認し、アクセサー／インボーカーに関するアドバイスを得る verify-mixin-target と、解決済みの 1 つのアーティファクトまたは Minecraft バージョンを 共有する固定の短い候補リスト用の batch-class-source、batch-class-members、 batch-symbol-exists、batch-mappings です。
• Fabric 形式の access widener に加え、NeoForge 用に validate-project（タスク access-transformer）を通じて Forge 形式の access transformer に対応します。
• level.dat、チャンク、playerdata、またはコマンド経由の NBT を扱う場合は、NBT ヘルパー（nbt-to-json、json-to-nbt、nbt-apply-json-patch）を使用します。編集時は型付き JSON のまま作業し、最後に一度だけ再エンコードします。稼働中のセーブデータを編集する前に、元のバイナリをバックアップしてください。ヘルパーが読み取るのは生の NBT ペイロードであり、.mca リージョンファイルではありません。先にリージョンツールでチャンクペイロードを抽出するか、入力がサポート対象外であると伝えてください。

デフォルトの動作

• 一般論ではなく、実行可能な機能単位を作成します。
• 質問する前に、ワークスペースからローダー、バージョン、マッピング、modid、パッケージ、Java バージョン、プロジェクトの規約を推定します。
• ワークスペースが存在しない、または内容に矛盾がある場合に限り、作業を妨げる最小限の質問をします。
• アートやバランスの詳細で作業を停滞させるより、明示的な TODO や仮のアセットを優先します。
• ユーザーが説明ではなく実装を明確に求めている場合は、コードの提供をデフォルトとします。
• 実用上可能な場合はユーザーの言語で回答しますが、ワークフローとトリガーのロジックは言語に依存しないようにします。
• 後続の実装に役立つ回答では、検証元ごとに事実を分けます：Verified by MCP、Verified by workspace/source jar fallback、Runtime/user-observed、Unverified。

実装指針となる出力契約

計画、デバッグの説明、MCP ペイロード／エラー復旧に関する回答、評価の回答、および後続の実装に役立つ引き継ぎでは、バージョン依存の推奨事項を示す前に、情報の出所を明示します。

• Project profile：確認済みのワークスペースルート、ローダー、Minecraft バージョン、マッピングの名前空間、Java バージョン、modid、基本パッケージを、該当する場合に記録します。ワークスペースやファイルからの証拠がない場合は、プロンプトで提示されたバージョンを例として使う前に、未確認または仮定のフィールドを明示します。
• MCP status：MCP に依存する主張をする前に、事前確認／スキーマの状態を記録します。 ツールを実際に実行していない場合は、結果が既知であるかのように書かず、MCP のステップを予定または未検証として記載します。
• Verification sources：実装に関する事実を、Verified by MCP、Verified by workspace/source jar fallback、Runtime/user-observed、 Unverified に分けます。フォールバック／エラー復旧のタスクや評価形式の回答では、記載を省くと情報源の境界が曖昧になる場合、空のカテゴリも none yet として記載します。
• ユーザーが監査を依頼した場合、またはフォールバック／情報源の判断の説明に必要な場合を除き、同梱リファレンスの参照先は内部情報として扱います。

クイックパス

1. プロジェクトプロファイルを読み込むか作成します。ワークスペースのルート、ローダー、Minecraft のバージョン、マッピング、Java のバージョン、モジュール、通常の検証コマンドを確認します。 ワークスペースが存在しない場合は、バージョン、ローダー、マッピング、Java に依存する主張をする前に、 不明なプロファイル情報を記録します。
2. minecraft-modding ツールを呼び出せると決めつける前に、MCP の事前確認を実行します。
3. 関連する情報について、まず高レベルの MCP 呼び出しを 1 回実行します。
4. バンドルされたリファレンスを読み込む前に、必要最小限の内部リファレンスを選びます。タスクの内容が 判明したら、まず該当するチェックリストのセクションを確認し、条件に合う場合にのみローダー、MCP レシピ、フォールバック、タスク固有のリファレンスを追加します。
5. ワーカーの再起動、タイムアウト、トランスポート障害が発生した場合は、より範囲を絞った高レベルの ペイロードで 1 回再試行してから、該当するフォールバック手順に切り替えます。 バリデーターが 1 回再起動した場合は再試行しません。このタスクでは利用不可として記録し、 references/validator-fallbacks.md を使用します。
6. ペイロードが無効な場合は、該当する references/mcp-recipes.md のレシピだけを確認し、形式を修正してから、ツールを切り替える前に同じ高レベルツールを再試行します。
7. Mixins、access wideners、access transformers については、編集前に所有者、名前、ディスクリプター、 名前空間、設定の宣言、サイドを記録します。
8. リソース、ワールド生成、戦利品、モデル、コーデック、HUD、画面、ランタイムフックについては、 build をランタイム動作の証拠とみなさず、タスク固有のチェックリストを実行します。

MCP の事前確認

Minecraft の Mod 開発タスクの開始時、MCP に依存する最初の主張をする前に、これを 1 回実行します。

1. ホストが minecraft-modding ツールを公開しているか確認し、最初のリクエストを送る前に、 呼び出し可能なスキーマを調べます。特に inspect-minecraft、analyze-symbol と、 それらの変換後の呼び出し可能な名前を確認します。
2. 利用可能な高レベルツール名、projectPath として使用するワークスペースのルート、 検出された Minecraft のバージョン、ローダー、マッピング、Java のバージョンを記録します。
3. inspect-minecraft と analyze-symbol のどちらも利用できない場合は、 minecraft-modding MCP unavailable と 1 回伝え、 references/mcp-unavailable-fallback.md に切り替えます。
4. このスキルで指定されたツールまたは引数が不明なものとして拒否された場合は、まず MCP の アップグレード後に起動に失敗していないか確認します （references/mcp-unavailable-fallback.md）。該当しない場合は、インストール済みの MCP がこれらのレシピで想定されている MCP のインターフェースより古いか、バージョンにずれがあるものとして扱い、 互換性のある最も近い旧式の方法、またはワークスペースのフォールバックを使用します。 ツール名の推測を続けないでください。
5. MCP を利用できる場合は、現在のツールが projectPath、preferProjectVersion、 preferProjectMapping を受け付けるなら、これらのフィールドを指定したプロジェクト対応の呼び出しを優先します。

最初の確認

1. プロジェクトの構成を確認します。
   • gradle.properties、build.gradle、build.gradle.kts、settings.gradle、fabric.mod.json、neoforge.mods.toml、mixin の設定ファイル、近くの登録クラスを読みます。
   • ローダー、Minecraft のバージョン、マッピング、Java のバージョン、modid、ベースパッケージ、プロジェクトがすでにデータ生成を使用しているか、ワークスペースが単一ローダーか Architectury のマルチモジュールかを推定します。
   • MCP ツールに projectPath として渡すワークスペースのルートを記録します。
2. 新しいコードを書く前に既存のコードを読みます。
   • プロジェクトの命名規則、パッケージ構成、登録ヘルパー、クライアントとサーバーの分離方法に合わせます。
   • 既存のレジストリ、タブ、パケットのパターン、データ生成プロバイダーがあれば再利用します。
   • 手動でバージョンやマッピングを選択する前に、ワークスペースを考慮した MCP の解決を優先します。
3. 以下の「リファレンスのルーティング」セクションを使って、関連するリファレンスのみを読み込みます。
4. 動作を実装する前に、最も近いバニラの例を探します。
   • inspect-minecraft または analyze-symbol から始めます。
   • 高レベルの回答でも実装が曖昧な場合に限り、低レベルのツールを使用します。

まだプロジェクトがない場合は、ローダー、Minecraft のバージョン、modid、パッケージ名のみを尋ねます。 ワークスペースにアクセスできない説明のみのタスクでは、例を示す前に、不明または仮定した事実を列挙します。 タスクが、存在しない外部ジェネレーターやテンプレートに依存する場合は、生成されたファイルを捏造せず、そのことを明示します。

リファレンスの参照先

同梱されているリファレンスは、必要に応じて参照するコンテキストであり、必須ではありません。このスキルが起動したというだけで、リファレンス一式を読んだり、内容をそのまま繰り返したりしないでください。

• デフォルトの参照先：
  • 利用可能な場合は、SKILL.md、プロジェクトプロファイル、MCP の事前確認、MCP の高レベルな検索を 1 回使用します。
  • タスクの形が判明したら、references/task-checklists.md の該当セクションだけを一度読みます。
• ローダーの参照先：
  • Fabric のプロジェクト構造、登録、API、エントリーポイント、データ生成、ネットワーク、Mixin、または落とし穴に関する場合に限り、references/fabric.md を読みます。
  • NeoForge のプロジェクト構造、DeferredRegister、イベント、ケイパビリティ、アクセス変換、データ生成、ネットワーク、サイド別アクセス、または落とし穴に関する場合に限り、references/neoforge.md を読みます。
  • Architectury のマルチモジュール配置、または共通とプラットフォームの境界をまたぐスライスに関する場合に限り、references/architectury.md を読みます。
  • ワークスペースがマルチローダーで、変更対象のスライスが該当ローダーに関わる場合に限り、複数のローダーリファレンスを読みます。
• MCP レシピの参照先：
  • ペイロードの形式、高レベルツールのエラーからの復旧、ERR_INVALID_INPUT、旧形式と現行形式の不一致、または高レベル呼び出しで扱われない補助ユーティリティに関する場合に限り、references/mcp-recipes.md を読みます。
  • 高レベルの MCP 回答で十分な場合は、関係のないレシピを繰り返さないでください。
• フォールバックの参照先：
  • 事前確認で MCP ツールがないことが分かった場合、指定したツールまたは引数が旧バージョンの MCP として拒否された場合、または失敗時の予算によりフォールバックに進む場合に限り、references/mcp-unavailable-fallback.md を読みます。
  • validate-project、validate-mixin、validate-access-widener、または validate-access-transformer が利用できない場合、再起動する場合、タイムアウトする場合、回答できない場合、ランタイム JAR のコンテキストを理由に拒否する場合、または近似的な判定を返す場合に限り、references/validator-fallbacks.md を読みます。
• タスク固有の参照先：
  • 依存関係 API のソースを調べる場合は、references/dependency-jars.md を読みます。
  • HUD オーバーレイ、画面、投影、GUI スケール、FOV、またはクライアントのレンダリングに関する場合は、references/rendering-hud.md を読みます。
  • GameTest またはテストハーネスの配線に関する場合は、references/gametest.md を読みます。
  • テンプレートの内容が少ない場合に限り、references/bootstrap-from-template.md を読みます。
  • 継続的に利用できるプロジェクトプロファイルが役立つ場合は、references/project-profile-template.md を読みます。
  • Minecraft の作業を別のエージェントに委任する場合に限り、references/subagent-mcp-contract.md を読みます。

読み込んだ、またはスキップしたリファレンスの選択は、通常は内部に留めてください。ユーザーから監査を求められた場合、またはフォールバック、ソースの欠落、来歴の制限が推奨に重大な影響を与える場合に限り、選択内容を明らかにしてください。

MCP のガードレール

MCP のペイロードを詳細に組み立てる場合、エキスパートツールやバッチツールを選択する場合、レスポンスフィールドを解釈する場合、再試行またはフォールバックを判断する場合、あるいはバージョンやマッピングに左右される推奨を行う場合は、references/mcp-guardrails.md を読んでください。以下の不変条件が常に見える状態にしてください。

• まず、その事実に回答できる最も高レベルな読み取り専用ツールを使用します。
• 呼び出し可能なスキーマを確認し、入力が無効な場合はツールを変更する前に一度修正します。
• 一時的なトランスポート障害または再起動による障害に限り、より範囲を絞った高レベルリクエストを一度だけ再試行します。決定的なサーバー障害と同じリクエストは再試行しません。一度再起動したバリデーターは再試行しません。
• プロジェクトのバージョン、マッピング、アーティファクト、ワークスペースの来歴を明示します。
• フォールバックで確認した事実には「フォールバックで確認済み」と明記し、「MCP で確認済み」とはしません。

サポート対象外またはリスクのあるリクエスト

• Quilt やレガシー Forge を、Fabric、NeoForge、Architectury として暗黙に扱わないでください。
• レガシー Forge のみ、またはその他のサポート対象外のローダーについては、確認済みのワークスペース情報、ログ、移行の境界に限ってサポートしてください。全面的なガイダンスはこのスキルの対象外であることを伝えてください。
• MCP が利用できない、設定に誤りがある、または情報が古い場合は、直ちにそのことを伝え、ワークスペースとログの調査に切り替え、修正範囲を限定してください。同じルールはバージョンの不整合にも適用されます。このスキルに記載されているツール、タスク、応答形式を調整する引数、または入力形式（例：detail / include[]、manage-cache の action: "verify"、validate-project タスクの access-transformer、analyze-symbol のライフサイクル範囲コントロール、get-class-source / get-class-members の target.kind、または NBT ヘルパー）が未知のものとして拒否された場合は、バージョンの不整合と判断する前に、MCP Preflight のステップ 4（アップグレード後の確認を含む）を適用してください。どちらの結論に至ったかを伝え、異なるペイロード形式を捏造するのではなく、互換性のある最も近い旧ツールまたはワークスペースのみを使った代替手段でリクエストに対応してください。
• ダウンロードサイズ上限による拒否が発生した場合は、ユーザーに MCP_MAX_DOWNLOAD_BYTES の値を引き上げて MCP を再起動するよう依頼してください。内側の jar が上限を超えていることを示す証拠がある場合に限り、MCP_MAX_NESTED_JAR_ENTRY_BYTES の値を引き上げて再起動するよう依頼してください。ERR_REPO_FETCH_FAILED のヒントにキャッシュパスと errno が示されている場合は、そのパスの権限またはディスクの状態を修復するようユーザーに依頼してください。その間はローカルの代替手段を使用してください（references/mcp-unavailable-fallback.md）。
• ワークスペース内のファイルがプロンプトと矛盾する場合は、その矛盾を指摘し、コードを作成する前に確認済みのファイルに基づいて解決してください。
• リクエストが、確認できないシンボル、イベント、レジストリエントリ、またはバニラのフックに依存している場合は、創作するのではなく、未確認またはサポート対象外であることを伝えてください。確認済みの範囲で最も近い代替案を提示してください。

基本的なワークフロー

1. 同じ問題をすでに解決しているバニラまたは既存の Mod のコードを調査します。
2. そのパターンを、ユーザーが使用するローダー、モジュール境界、マッピング名前空間に合わせて適用します。
3. テンプレートが空に近すぎる場合は、まず不足しているプロジェクトの骨組みを作成します。
   • リクエストされた機能に必要な最小限のエントリーポイント、登録クラス、クライアントフック、データ生成の配線のみを追加します。
   • あらゆるシステムを最初からすべて作成しないでください。
4. 必要な範囲を一度に実装します。
   • 登録処理を含めます。
   • 必要に応じてクライアント側の配線を含めます。
   • 必要な JSON リソースまたはデータ生成フックを含めます。
   • 機能に必要な場合は、言語キー、ルートテーブル、ブロックステート、モデル、タグ、レシピ、または画面の配線を含めます。
   • Architectury のワークスペースでは、ワークスペースですでに別の確認済みパターンが使われている場合を除き、共有のゲームプレイロジックは common に置き、ローダー固有の配線はプラットフォームモジュールに置いてください。
5. タスクの完了を報告する前に、検証ループを実行します。
6. 前提、プレースホルダー、後続タスク、検証に使用した情報源を簡潔に報告します。

提出ルール

• 新しい抽象化を導入する前に、現在のプロジェクトのスタイルに合わせてください。
• マッピング名、イベント名、登録順序、記述子を推測で作らないでください。必ず確認してください。
• ローダーが明確なフックをすでに提供している場合は、Mixin より安定したローダー API またはイベントを優先してください。
• プロジェクトがテンプレートのみの場合は、要求された機能をコンパイルしてホストできる、最小限の動作するスキャフォールドを作成してください。
• Architectury プロジェクトでは、コードはデフォルトで common に置き、ローダーに依存するコードのみを fabric または neoforge に移してください。
• 両方のローダーを共有 init メソッド経由で処理する Architectury テンプレートでは、共有コンテンツの変更に合わせるためだけに、何もしないプラットフォーム側の変更を追加しないでください。
• コードでプラットフォーム固有の動作が本当に必要な場合に限り、@ExpectPlatform、Architectury の抽象化、またはプレーンな Java インターフェース／サービス分割を使用してください。
• サイドの分離を適切に保ってください。レンダラー、画面、その他のクライアント専用コードは、適切なクライアントエントリーポイントまたはイベントの背後に配置してください。
• 繰り返しの JSON、または 2 件を超えるコンテンツエントリーを作成する場合は、データ生成を優先してください。
• 既存のヘルパークラス、レジストリー、パッケージ構成を維持し、全面的に置き換えないでください。
• デバッグ中は修正範囲を絞ってください。まず具体的な失敗を特定し、その後で原因を修正してください。

検証とデバッグのリファレンス

実装完了を宣言する前、または Mixin／アクセス、レジストリー／リソースのコーデック、依存関係、HUD／レンダリング、GameTest、NBT、キャッシュ／インデックス、モデル／テクスチャ、サイド専用、バージョン移植の問題を診断する際は、references/verification-and-debugging.md を読んでください。Gradle、データ生成、実行時、リソース、およびカテゴリ別の検証手順の詳細は、このドキュメントを参照してください。リソース関連または実行時のみの変更では、ビルドの成功だけでは実行時の動作を証明できません。

リファレンス

• Fabric のパターン：references/fabric.md
• NeoForge のパターン：references/neoforge.md
• Architectury のパターン：references/architectury.md
• テンプレートからのブートストラップのパターン：references/bootstrap-from-template.md
• タスクの種類別提出チェックリスト：references/task-checklists.md
• MCP ペイロードと復旧のレシピ：references/mcp-recipes.md
• MCP の詳細なガードレール：references/mcp-guardrails.md
• MCP が利用できない場合の代替手段：references/mcp-unavailable-fallback.md
• 依存関係 API のソース検索：references/dependency-jars.md
• HUD とクライアントレンダリング：references/rendering-hud.md
• バリデーターの代替手段：references/validator-fallbacks.md
• 検証と迅速なデバッグ：references/verification-and-debugging.md
• GameTest の配線：references/gametest.md
• プロジェクトプロファイルのテンプレート：references/project-profile-template.md
• サブエージェントの MCP コントラクト：references/subagent-mcp-contract.md
• 現行のアップストリーム移行ガイダンスについては、ハードコードされた URL に頼るのではなく、対象のローダーと Minecraft のバージョンに対応する Fabric、NeoForge、Architectury の公式ドキュメントまたはリリースノートを参照してください。