rust-java-migration

Java から Rust への移行

Java の構文ではなく、コントラクトと観測可能な振る舞いを移行します。Rust の所有権、エラー処理、並行処理、非同期処理、シリアライズ、フレームワークの仕組みを選択しながら、Java プロジェクトの公開概念とソースの追跡可能性を維持します。

必須の移行レイアウト

• 宣言されたパッケージルート以降の Java パッケージから Rust のディレクトリを導き、意味のあるネストされたパッケージを維持します。フラット化、別の場所への配置、二重ネストは行いません。
• Java のオブジェクト名を頭字語を考慮した snake_case.rs に変換します。Rust の型は PascalCase のままにし、_trait などのサフィックスは追加しません。
• 1 つの Java オブジェクトは、1 つの Rust オブジェクト境界として維持します。Rust にファイル長の普遍的な上限はありません。物理行数が 500 行以下は通常の範囲、501～800 行は凝集性をレビューし、800 行を超える作成済みの .rs ファイルは認めません。
• ファイルに複数の責務が混在する場合にのみ分割します。主要なオブジェクトファイルを 1 つ維持し、別の移行対象オブジェクトを導入せずに、まとまりのある実装群には補助ファイルを使用します。分割やレビュー済みの例外はすべて記録します。
• lib.rs と mod.rs は宣言と再エクスポートのみにします。移動後は親モジュールを更新し、曖昧な外部再エクスポートには :: を付けて明示します。
• 必要に応じて、#[cfg(test)] モジュール内に、非公開の振る舞いに焦点を当てたユニットテストを配置します。公開境界、モジュール間、差分、ホスト、プロジェクト全体のテストは、tests/ または公開されない <project>-test パッケージの下に配置します。ソースフィクスチャは <project>-test/tests/fixtures/ の下に置きます。

ディレクトリパスの整合とレイアウトとガバナンスを読み、移動後にレイアウト監査を実行します。

スコープとルーティング

プロジェクト全体の移行、Maven／Gradle モジュール 1 つの移行、パリティ監査、移行計画、または既存の Rust 移植作業の継続には、このスキルを使用します。

これはクロスランゲージ移行プロファイルの Rust アダプターです。クレート／レイアウト／API、依存関係、マクロ、ドメインの仕組みについては、対応する Rust スキルに振り分けます。検証は rust-java-migration-testing と関連するテストスキルに振り分けます。

ユーザーが監査、計画、ドキュメント作成のみを求めている場合は、移行コードを変更しません。計画のみ、または読み取り専用の依頼では、書き込みを行うドキュメント生成ツールの実行は許可されません。回答で 4 つのドキュメントの内容案を提示するか、--dry-run を使用するか、ユーザーが承認した保存先にのみ書き込みます。許可なくモジュールの移行をリポジトリ全体の書き換えに拡大してはいけません。

必須入力

次の項目を解決するか、不明であることを明示してください。

• Java リポジトリのパス、基準コミット／タグ、ビルドツール、JDK、モジュールの範囲。
• パスマッピングに使用する正確な Java モジュールのパッケージルート。リポジトリや src/main/java のルートだけを渡して、どのセグメントを除外するか推測してはいけません。
• Rust リポジトリのパス、基準コミット、ツールチェーン／MSRV、ワークスペース、対象プラットフォーム。
• 対象製品のトポロジーに関する入力：個別に公開される Rust ユニット、依存関係／フィーチャー／ターゲット／proc-macro／FFI の境界、想定されるクレート数、パッケージ群、ルートディレクトリのノイズ、その他の言語、既存のパス。
• 互換性の目標：ソース形状の同等性、公開 API の同等性、動作の同等性、本番環境での置き換え。
• 依存関係のポリシー：ライセンス、MSRV、サポート対象のターゲット、unsafe のポリシー、アドバイザリーのポリシー、保守期間、許容できる推移的依存コスト。
• コンポーネント候補の情報源とその確認日。チームのポリシー、調査済みの候補、宣言された依存関係、導入が検証済みの項目を区別してください。
• 明示的な例外、利用をブロックしている外部プロジェクト、未サポートの JVM 専用機能、完了期限。
• 必須のホストアプリケーション、実際のスクリプト、テストデータ、並行処理モデル、負荷プロファイル、ロールバックの仕組み。
• 既存の移行ドキュメントとその権威性。過去の資料を統合する前に、現在有効な4つのドキュメント一式を特定してください。
• テストランナーの設定を含む、ソース側のテストルート一式。すべての具体的なテストケース、無効化されたテスト、フィクスチャー、スクリプト、コーパス、ゴールデンファイル、リソース、データファイルを含めてください。分母はソースリポジトリが定めるものであり、Rust に合わせて範囲を狭めてはいけません。

最新のブランチ、生成されたマニフェスト、API 登録リストが動作の基準であると、黙って推測してはいけません。

ワークフロー

宣言された Java ソースモジュール1つと、その Rust 移行先クレート／モジュールを、移行バッチのデフォルトとします。ユーザーが複数モジュールの対象範囲を承認した場合は、1つのバッチとして扱えますが、実装前に境界を固定してください。次の順序で進めます：対象範囲／契約を固定 → バッチを実装 → 固定 → 監査 → 一括検証。

実装バッチ内で依存関係の順序に沿って編集することは認められます。オブジェクトごとに完了させるループは禁止です。

1. 基準とリポジトリの状態を固定する

両方のリポジトリの SHA、変更のあるワークツリー、Java／Rust のツールチェーン、モジュールマニフェスト、有効なフィーチャー、生成コードの境界を記録してください。既存の Rust 作業と無関係な変更は保持してください。

Rust ツールチェーンがワークスペースの MSRV を満たすことを確認してください。デフォルトの rustc が古い場合、rustc X is not supported by the following packages というエラーになります。ゲートは rustup run <ver> cargo ... で実行し、rust-version を黙って引き下げてはいけません。

リポジトリに .codegraph/ がある場合は、テキスト検索やファイルごとの読み込みより先に CodeGraph を使用してください。

1. モジュール／パッケージ／クレートのアーキテクチャを調査します。
2. 代表的な公開型とオーバーロードされたメソッドをクエリします。
3. ファクトリー、レジストリー、インターセプター、シリアライザー、永続化、ネットワーク、並行処理にまたがる重要度の高い呼び出しチェーンをたどります。
4. Rust 側の対応物と、その呼び出し元／テストをクエリします。
5. インデックスの鮮度に問題があると報告された場合は、実装前にモジュール一覧を更新するか、再度クエリします。

インデックスがない場合は、承認なしに初期化してはいけません。言語対応のツール、または対象を絞ったソース調査を使用し、証拠の確度が低いことを明示してください。

クエリのパターンとインベントリのルールについては、CodeGraph の同等性監査を読んでください。 大規模なユーティリティライブラリの移行や、アノテーション／マクロの分割を設計する場合は、ケーススタディから得られた教訓を読んでください。

1.5. Rust クレートの境界とワークスペースの構成を導き出す

Maven／Gradle のモジュールを Cargo パッケージに一対一で対応させないでください。独立した公開・再利用の必要性、依存関係／機能／ターゲットの分離、proc-macro や FFI の制約、ライフサイクルの違いに基づいて Rust パッケージを導き出してください。ソースモジュールはトレーサビリティの範囲として維持します。

配置は rust-workspace を使って選択します。小規模でまとまりのある成果物は通常ルート直下に配置します。実際にアダプター／バインディング／サンプル／テストの各ファミリーがある場合はハイブリッド構成が適しています。大規模なリポジトリ、ルート直下の項目が多いリポジトリ、または複数言語を含むリポジトリでは、crates/ を使用できます。数はレビューを開始する目安であり、厳密な規則ではありません。ロードマップにソースモジュールからクレートへの対応、選択した構成、却下した代替案、互換性計画を記録してください。レイアウトとガバナンスを参照してください。

2. 実装前にインベントリを作成する

以下について、個別の機械可読または表形式のインベントリを作成してください。

• Java の Maven／Gradle モジュールと Rust クレート。
• ソースモジュールからクレートへの対応、およびルート直下、ハイブリッド、または格納・グループ化されたパスがこのプロジェクトに適している理由。
• Java パッケージと Rust モジュールディレクトリ。
• クラス、インターフェース、列挙型、レコード、アノテーション、例外、および該当する内部型。
• 各オブジェクトについて、組織／モジュールのパッケージルートを取り除き、残りのセグメントの末尾 2 つ（2 つ未満の場合は 1 つまたは 0 個）を保持した後の、決定論的な Rust パス。
• public／protected のコンストラクターとメソッド（すべてのオーバーロードを含む）。
• パラメーター名、順序、ジェネリック境界、NULL 許容性、デフォルト値、可変長引数、検査例外、戻り値の契約。
• 既存のオブジェクト、コンストラクター、メソッド、ジェネリック／値パラメーター、戻り値、例外、メタデータタグ、意味を持つインラインコメントと、そのソースアンカー。
• サンプル、テスト、フィクスチャ、スクリプト、設定、リソース、サービス記述子、ドキュメント。
• ソーステストケースのマニフェストとアセットのマニフェスト。リソースを Rust にバイト単位でコピーする前に、具体的なケースとすべてのアセットパス／ハッシュを記録してください。
• プロジェクトレベルのソース再生、コンポーネント横断パス、差分受け入れテストを担当する、公開対象外の <project>-test パッケージ。
• 呼び出し経路と、外部から観測可能な副作用。

package-info、生成ソース、BOM、アグリゲーター、テストサポート、ファサード、Rust 専用インフラストラクチャを除外する場合は、明示的なカテゴリを使ってください。分母を変更して、これらを隠してはいけません。

本番コードの編集前に、インベントリをバッチマニフェストとして確定してください。対象範囲全体、依存関係の順序、共有メカニズム、コンポーネントごとの判断、テストの扱い、承認済みの例外を網羅してください。オブジェクトごとに対象範囲を見つけていくことは避けてください。

この SKILL.md を基準に SKILL_DIR を解決してください。固定のインストールパスを想定してはいけません。Rust 移行ルートからコマンドを実行し、リポジトリ相対の入力／成果物を優先してください。

早期の兆候を確認するため、静的 Rust レイアウト監査を実行してください。

python3 "$SKILL_DIR/scripts/audit_migration_layout.py" \
  --java-package-root ../java-project/source-module/src/main/java/org/example/module \
  --rust-root . \
  --retain-segments 2 \
  --require-source-comments \
  --fail-on-warning

このスクリプトは、想定パスを算出し、不足しているオブジェクトと誤った場所にあるオブジェクトを区別します。また、スネークケースではないパス、複数オブジェクトを含むファイル、ファサード定義、ワイルドカードインポート、スタブマクロ／パニック、空の関数本体、中国語のソースコメントの不足も検出します。501～800 行のファイルについて、承認済みの凝集性レビューを記録するには、--reviewed-large-file path/to/file.rs を繰り返し指定してください。これによって 800 行を超えるファイルが免除されることはありません。厳格なブロッカーが 1 つでもあれば、移行の完了はブロックされたままです。スキャンがクリーンでも、Java と Rust の意味的な同等性が証明されたことにはなりません。

3. 各ソースモジュールに4つのドキュメントを作成する

ドキュメントの作成が許可されたら、実装を始める前に各Javaモジュールのドキュメントディレクトリを生成します。

python3 "$SKILL_DIR/scripts/scaffold_migration_docs.py" \
  --module source-module \
  --java-root ../java-project/source-module \
  --java-package-root ../java-project/source-module/src/main/java/org/example/module \
  --rust-root <selected-target-crate-or-workspace> \
  --output-dir docs/source-module \
  --java-baseline <sha-or-tag> \
  --rust-baseline <sha> \
  --retain-segments 2

このコマンドで、次のドキュメントが作成されます。

1. 迁移路线图.md — 対象範囲、ベースライン、フェーズ、依存関係、リスク、エビデンスのゲート。
2. 对象级对照表.md — すべてのJavaオブジェクトと、それに対応するRustのファイル／型／ステータス。
3. 语义迁移对照表.md — すべての動作の分類と、Rustネイティブな実装。
4. 对象名称一致性检查.md — オブジェクト数、欠落／余分／統合されたオブジェクト、名前、メソッド、パラメーター、ロジックの不足。

ソースのエビデンスに基づいて、すべてのプレースホルダーを埋めてください。生成されたテンプレートは DRAFTであり、エビデンスではなく、完了を示すものでもありません。ドキュメントは コードと同じ変更内で同期してください。テンプレート：

• 移行ロードマップ
• オブジェクト対応表
• セマンティック対応表
• 名称整合性監査

4つのドキュメントはそれぞれ独立して詳細であり、モジュールの現在の移行契約として、ソース／Rust SHA、正確なオブジェクト数、ターゲットルート、retain_segments = 2、ステータスのスナップショット、厳密な完了条件、および各ドキュメントの役割を記載する必要があります。タイトルだけ、件数だけ、またはプレースホルダーだけのドキュメントは受け入れないでください。要約だけにならないよう、実質的なレベル2のセクションを少なくとも3つ設け、エビデンス表またはタスクマトリックスを含めてください。リポジトリで設定したサイズ下限（デフォルトでは空行を除いて45行）を適用し、モジュールが本当に小さい場合は、生成されるオブジェクト表をその規模に応じて小さくできるものとします。

すべてのドキュメントに、JavaとRustのベースラインを別々に記載し、最終監査日とドキュメントのステータスを示してください。移行済み／検証済みの各行には、エビデンスの参照先を付ける必要があります。参照先には、ソースファイルまたはシンボル、ターゲットファイルまたはシンボル、テスト／オラクル、正確なコマンド、および該当する場合は成果物を含めます。実装中は、行ごとにステータスを上げないでください。バッチの凍結後、4つのドキュメントすべてを現在のRust SHAと照合し、ステータスを一括して更新してください。後から作成した件数表が、技術要件のドキュメントや先行するセマンティックギャップと矛盾したままにならないようにしてください。

モジュールのルートには、現行の4つのドキュメント一式を1組だけ置いてください。*-历史详细版.mdや、現行ドキュメントと同名のhistory/**/<current-name>.mdを併置しないでください。以前のパッケージ構成、設計上の背景、判断の履歴で有用なものは、対応する現行ドキュメント内の「历史设计附录」と明確に区分した箇所へ統合してください。生成された現行事実の領域を必ず先頭に置き、再生成しても付録が保持されるようにしてください。古い件数、パス、ステータス、テスト、完了マークは、現在の事実より優先されません。

scaffoldの--forceは破壊的な操作として扱い、破棄可能で未編集のDRAFTに対してのみ使用してください。内容がある現行ドキュメントの統合や更新には決して使用しないでください。過去の詳細は、生成された事実の領域と既存の付録の両方を保持したまま、現行ドキュメントに直接統合してください。

4. すべてのオブジェクトを正直に分類する

以下のオブジェクト状態を一貫して使用してください。検証レベル（V0～V7）は 分けて扱い、より好ましい状態を新たに作ったり、テスト結果をそのまま オブジェクト状態に置き換えたりしないでください。

状態	意味
MISSING	想定される Rust オブジェクトファイルが存在しない
MISPLACED	同名のファイル／型は存在するが、決定論的に定められた想定パスにない
STUB	形だけ、またはプレースホルダーは存在するが、実際の動作がない
PARTIAL	実際の動作はあるが、メソッド、コールバック、エラー、順序、ライフサイクル、または統合のセマンティクスが不完全
UNVERIFIED	ファイル／ロジックは存在するが、ソースコメント、オブジェクト境界、またはセマンティクスを確認するテストの証拠が不十分
IMPLEMENTED	想定パス、一オブジェクト境界、実際の完全なロジック、中国語ソースのセマンティクス、および最新のセマンティクステストがすべて存在する
DEPENDENCY_REUSED	ピン留めされた依存関係が該当する機能を正確に提供しており、クレート／バージョンまたはコミット、上流シンボル、アダプター、およびローカル統合テストが記録されている
PLATFORM_NA	該当する機能が真に JVM／バイトコード／クラスローダー／プラットフォーム固有であり、Rust オブジェクトが該当しない理由を明示した証拠が記録されている
RUST_EXTENSION	意図的な Rust 専用機能であり、Java との同等性を算出する分母から除外される

IMPLEMENTED、DEPENDENCY_REUSED、PLATFORM_NA のみが、対応済みの ソースオブジェクトとして数えられます。MISSING、MISPLACED、STUB、PARTIAL、 UNVERIFIED は未完了です。RUST_EXTENSION は Java の分母に含めません。

計画上のプレースホルダーを許可するのは、ユーザーが明示的に承認した場合に 限ります。ブロッカーはロードマップに記録しますが、影響を受ける各オブジェクトは 事実に即した MISSING または STUB の状態に保ってください。ブロッカーは メタデータであり、完了を示すオブジェクト状態ではありません。

マニフェスト、ファサード、lib.rs、mod.rs、再エクスポート、生成されたレジストリ、 または互換性モジュールにオブジェクト名があるというだけで、MISSING から 状態を引き上げないでください。cargo test が成功したというだけで、 UNVERIFIED から状態を引き上げないでください。

5. コントラクトに基づいてコンポーネントの置き換えを決定する

フレームワーク名をそのまま対応付けないでください。外部の Java コンポーネントまたはフレームワークのサブシステムごとに、次のようにします。

Java のソースモジュールを、オブジェクト名、パッケージ構造、公開コントラクトの正とします。Rust の依存関係は、実装を再利用する境界にすぎません。依存関係のファイルツリーに合わせて移行の構成を変更したり、パリティのカウントを増やすためだけに依存関係が所有する実装をローカルファイルにコピーしたりしないでください。たとえば AOP に類似する処理では、Advice／Interceptor／Advisor のオブジェクト一覧は Spring が定義し、aspect クレートは特定のランタイムシンボルを DEPENDENCY_REUSED によって満たすことができます。

1. 動作のコントラクトを抽出します。API の形状、ワイヤ形式／ストレージ形式、順序、失敗の分類、ライフサイクル、トランザクション、並行性、キャンセル、バックプレッシャー、セキュリティ、可観測性、デプロイの前提条件を確認します。
2. 置き換えの形態を選びます。標準ライブラリ、直接利用するクレート、ラップしたクレート、トレイトとアダプター、明示的なレジストリ／SPI、コンパイル時マクロ／コード生成、アプリケーションホスト側の責任、または検証済みの PLATFORM_NA を選択します。
3. 共通マッピング表と候補カタログは、調査の出発点として確認します。自動的に承認されたものとは見なさないでください。
4. 検証済みのマッピングが見つからない場合は、機能、プロトコル、制約に関する英語の検索クエリを複数作成し、crates.io と関連する一次情報を調べます。そのうえで、標準ライブラリ、直接利用するクレート、ラッパー、トレイト／アダプター、コード生成、ホスト側の責任、除外の各形態を含む候補を 5～10 個に絞り込みます。
5. crates.io のメタデータ収集とエコシステムの健全性比較は、利用可能な場合は rust-crate-discovery に依頼します。ここで移行固有のコントラクトおよび互換性のゲートを適用します。数値化された健全性スコアだけで置き換え先を決めないでください。
6. 必須のコントラクト、ライセンス、MSRV／ターゲット、ランタイム／ブロッキング、プロトコル、セキュリティ、保守状況／所有権、依存関係グラフの制約を満たさない候補は、スコアリング前に除外します。
7. 実現可能な候補を、意味的な適合性、保守状況、採用状況、ドキュメント／テスト、プロジェクトとの互換性、セキュリティ／サプライチェーン、成熟度、コスト、撤退戦略に基づいて比較します。ダウンロード数、逆依存関係の数、スター数、リリースの新しさ、コミット数は、文脈を示す手掛かりとして解釈し、証明とは見なさないでください。
8. アーキテクチャを確定する前に、上位候補について、意味上のリスクが最も高い経路のスパイクを実施します。
9. 検索クエリと検索日、所有権、バージョン／機能、次元ごとの根拠／確信度、却下した代替案、回避策、ロールバック計画を記録します。
10. 正確な上流シンボル、固定した依存関係の根拠、アダプター境界、ローカルの統合テストがすべて記録されている場合に限り、オブジェクトを DEPENDENCY_REUSED に昇格させます。「エコシステムに存在する」または「意味的に類似している」だけでは、引き続き UNVERIFIED です。

複数の対象フレームワークがある場合は、フレームワークに依存しないコントラクトと薄いアダプターを定義し、すべてのアダプターに対して共通の適合性テストスイートを実行します。ランタイムのトレイト／型は、薄い手続き型マクロや生成コードと分離してください。

サードパーティ製の置き換えを選択または承認する前に、コンポーネント置き換えの意思決定 SOP、クレート置き換えの調査と評価、コンポーネント候補カタログをお読みください。カタログは調査のための入力であり、承認済みの一覧ではありません。判断時に、リリース状況、保守状況、ライセンス、MSRV、ターゲット、アドバイザリ、unsafe／ビルドスクリプトの対象範囲、必須コントラクトを再検証してください。

6. 宣言済みバッチを一度の意味的な実装パスで完了する

コードを変更する前に、レイアウトと移行ルール、 ディレクトリパスの対応パターンとエラーカタログ、 意味マッピングを読んでください。その後、オブジェクト単位の受け入れ確認で中断することなく、凍結済みバッチ全体を実行します。

1. 対象モジュールツリー、共有エラー、トレイト、レジストリ、アダプター、 シリアライズ規則、並行処理モデル、依存関係の境界を一度確立します。
2. 対応するすべての Java オブジェクトと操作を依存順に実装します。Java オブジェクトごとに プライマリの .rs ファイルを必ず 1 つだけ用意し、実際のロジックは 対応するオブジェクトまたは明示的なコラボレーターファイルに記述します。
3. バッチ全体を通じて、JavaDoc の意味を中国語の Rust ドキュメントコメントにコピーして翻訳します。既存のオブジェクトコメント、コンストラクター／メソッドのコメント、ジェネリックおよび値の @param、@return、@throws、@since、@deprecated、該当する @see、意味を持つインラインコメントを、漏れなくすべて移行します。パラメーターごとの契約を維持します。Java から Rust への名前、シグネチャ、例外のマッピングは 4 つの移行ドキュメントに記載し、生成される Rust ドキュメントは Rust 固有の形式にします。
4. 対応するすべてのオーバーロード、例、フィクスチャ、ソーステストに対応するテスト、Rust 固有の必須項目、リスクに基づくテストをバッチ成果物として実装します。ただし、まだ検証は実行しません。ソーステストの入力、アサーション、エラーに関する期待値、状態、副作用、クリーンアップを 100% 維持します。ソースのテストファイル／データ／リソースは編集せずにコピーし、Rust 固有の派生物は別ファイルに格納します。
5. 保留中の問題は単一の台帳で管理します。局所的な不明点は作業を続け、凍結済みの公開契約、アーキテクチャ、依存関係ポリシー、または承認済みスコープを変更する阻害要因がある場合にのみ停止します。
6. 免除対象ではないマニフェストのすべての項目に実装が完了したら、Rust バッチを凍結します。その後に限り、4 つのドキュメントをまとめて更新し、監査に進みます。

このパス中は、cargo check、テスト、Clippy、カバレッジ、差分比較、オブジェクトごとの CodeGraph 再照会、オブジェクトごとの完了レビューを実行しないでください。ファイルを編集しただけでオブジェクトを受け入れ済みと報告しないでください。復旧コミットは許可されますが、検証ゲートとしては扱いません。

ドキュメントを移行する前に、コメント移行の契約と例を読んでください。ソースコメントが欠けている場合は、任意の整理ではなく移行漏れとして扱ってください。

7. 命名とオーバーロードの意図を保持する

• Rust のディレクトリ、ファイル、メソッド、パラメーターには snake_case を使用します。
• Rust の型には PascalCase を使用します。
• loadOrCreateAgentState(slotKey) は load_or_create_agent_state(slot_key) に対応させます。
• 組織名と宣言されたソースモジュールのパッケージルートを取り除き、残ったパッケージセグメントの末尾から正確に 2 つを保持します。残りが 1 つだけの場合はそれを保持し、ルートパッケージのオブジェクトはクレートのルートに配置します。例： factory/xml/support/Foo.java → xml/support/foo.rs； propertyeditors/PatternEditor.java → propertyeditors/pattern_editor.rs。
• lib.rs と mod.rs には宣言と再エクスポートのみを含めます。
• Java のクラス／インターフェース／列挙型／レコードは、Rust のファイルごとに 1 つにします。主要な型が密接に所有する内部ビルダーは、同じファイルに残してもかまいません。
• 500 物理行を凝集性レビューの基準とし、800 行を作成ファイルの上限とします。行数の範囲ではなく責務に基づいて分割し、下位ファイルに別の移行対象オブジェクトを追加してはなりません。
• 関数／メソッドのレビュー指標として、clippy::too_many_lines をデフォルトの 100 行で有効にします。長いルーチンに複数の異なる責務が含まれる場合はリファクタリングします。
• Rust の慣用的なテスト構成を使用します。焦点を絞った単体テストは #[cfg(test)] モジュール内に配置し、公開境界、モジュール間、差分、ホスト、およびプロジェクト全体のテストは tests/ または test/testkit パッケージに配置します。
• 意図的な名前変更はすべて、オブジェクト文書と名前整合性文書の両方に記録します。

Rust にはメソッドのオーバーロードがありません。シグネチャが同じ意味の操作を示す場合に限り、正規の snake_case 名を 1 つ使用します。追加のバリエーションには、_with_charset、_into、_from_reader など、意味を表す安定したサフィックスを付け、対応する正確な Java シグネチャを各 Rust 関数に記録します。デフォルト値、検証、副作用、またはエラー動作が異なるオーバーロードを決して統合してはなりません。

移行するすべての公開 Rust API には、ローカルの rust-api-design 規約を適用します。JavaBean のアクセサーを機械的に変換してはなりません。通常は get_name() ではなく name() を優先し（実際の検索操作は除く）、制御された変更には set_name(value) を使用します。不変条件を損なう可能性がない場合に限り name_mut() を使用し、所有権の移動には into_name()／into_inner()、ビルダーにはチェーン可能な形式を使用します。Rust における意味に従って as_／to_／into_、From／TryFrom／AsRef、および IntoIterator を使用します。Java の継承を模倣するために Deref を使用してはなりません。不変条件と API の将来的な変更への対応に問題がない場合に限り、フィールドを直接公開します。検証、可視性、副作用、例外、同期、遅延計算の動作を保持します。

スクリプト、式エンジン、シリアライザー、リフレクションファサード、またはその他の互換性サーフェスが Java のプロパティセマンティクスを公開する場合、Rust API は慣用的な形式に保ち、旧来のフィールド／ゲッター／セッターの動作は明示的なレジストリまたはメンバーリゾルバーに実装します。この関係はマッピング形式 ADAPTED として記録します。これは完了状況とは独立しており、IMPLEMENTED、UNVERIFIED、またはその他の事実に基づく状態も引き続き必要です。

ゲッター、セッター、ビルダー、またはスクリプトから参照可能なプロパティを移行する前に、Rust API と JavaBean プロパティの適応を読んでください。

8. フレームワークをそのまま置き換えるのではなく、仕組みを翻訳する

この表を共通の出発点として使用し、正確な契約と現在のクレートの根拠を確認してください：

Java での役割	Rust での出発点
Jackson の JSON アノテーション／モジュール	serde、serde_json、プロジェクト独自のカスタムシリアライザー
Jackson XML／JAXB 形式の XML	quick-xml に、名前空間、属性、混在コンテンツ、順序の明示的な処理を組み合わせます
null、チェック例外	Option<T>、型付きの thiserror 列挙型と Result
SLF4J/Logback/MDC	tracing、tracing-subscriber、フィールド／コンテキストの明示的な伝播と機密情報のマスキング
synchronized／ConcurrentHashMap	まず所有権を活用し、そのうえでアクセスパターンに応じて標準の Mutex／RwLock または DashMap を使います
CompletableFuture、スケジュール実行機能	非同期フューチャー、監視対象の Tokio タスク、キャンセルトークン、タイマー／インターバルを使います。より高度な契約が必要な場合に限り、スケジューラーのクレートを選びます
Reactor の Mono<T>／Flux<T>	async fn -> Result<T, E>、上限付きの Stream<Item = Result<T, E>>
OkHttp／Apache HttpClient	高水準クライアントには reqwest、プロトコルレベルの制御には Hyper を使います。TLS、プロキシ、接続プール、リダイレクト、再試行、ストリーミングのセマンティクスを確認してください
Spring MVC/WebFlux／JAX-RS	フレームワークに依存しないコアと、承認済みの Axum、Actix Web、Poem、またはその他の薄いホストアダプターを組み合わせます
JDBC/JPA/MyBatis	クエリ、マッピング、トランザクション、マイグレーション、ランタイムの契約に基づいて選定した SQLx、Diesel、SeaORM、RBatis、または検証済みの別のデータレイヤー
Caffeine/Guava キャッシュ	Moka またはプロジェクト独自のキャッシュを使います。エビクション、TTL/TTI、ロード、無効化、並行性を確認してください
Jedis/Lettuce	redis を使います。クラスター／Sentinel、再接続、パイプライン／トランザクション、TLS、非同期動作を確認してください
Kafka/RabbitMQ/Pulsar/NATS/MQTT	rdkafka、Lapin、pulsar、async-nats、rumqttc などのプロトコル固有クライアントを使います。実際のブローカーでのセマンティクスと復旧テストを必須とします
Protobuf／gRPC	Prost、gRPC には Tonic と Prost
Bean Validation	validator またはプロジェクト独自のバリデーションを使い、フレームワークのエクストラクターとは分離します
java.time、UUID/ULID、BigDecimal、正規表現	time／chrono、uuid／ulid、rust_decimal／bigdecimal、regex を使います。クレートの好みよりも先に、表現方法と互換性を決定してください
.properties、YAML、TOML、設定バインディング	java-properties、serde_yaml_ng、toml、または検証済みの設定クレートに、プロジェクト独自の優先順位／プロファイル規則を組み合わせます
Apache Commons/Hutool の汎用ユーティリティ	まず標準ライブラリを使い、次に url、bytes、regex、base64、hex など目的に特化したクレートを使います。名前だけを頼りに包括的なクレートを探さないでください
Micrometer/OpenTelemetry/Prometheus	metrics、OpenTelemetry エコシステム、Prometheus エクスポーター、tracing 連携を使います。名前、ラベル、カーディナリティ、コンテキスト、シャットダウンを維持してください
JavaMail	lettre を使います。MIME、添付ファイル、TLS／認証、再試行、配信レポートを確認してください
JWT／パスワード／汎用暗号	jsonwebtoken、argon2、目的に特化した RustCrypto クレートを使います。利便性だけでなく、セキュリティ要件に基づいてアルゴリズム／形式を選んでください
Groovy/Nashorn／組み込みスクリプト	言語、サンドボックス、リソース制限、スレッド、パッケージングの要件に応じて、rhai、boa_engine、mlua、PyO3、Wasmtime を使います
Apache POI／ドキュメント形式	rust_xlsxwriter、calamine、docx-rs、printpdf、lopdf などの形式固有クレートを使います。実際の Office／PDF のサンプルファイルと、サポートされていない機能を検証してください
ServiceLoader/SPI	まず明示的なレジストリを使います。リンク時の登録が必要な場合に限り、inventory を使います
Spring IoC/AOP／ランタイムアノテーション	コンストラクター／ビルダー、トレイト、ミドルウェア、レジストリ、ラッパーを使います。マクロはコンパイル時の動作に限って使用してください
FreeMarker／Velocity／コンパイル時ビュー	Tera／Handlebars、コンパイル時テンプレートには Askama、Rust ネイティブのマークアップには maud を使います
Lombok のデータ用定型コード	標準の derive と、不変条件を維持する API／ビルダーを使います。lombok-macros は生成される API の契約に照らして評価してください
JUnit/Testcontainers	Rust のユニット／統合テストを使います。一時的な実依存関係には testcontainers を使います
JNI／手動の Swift/Kotlin/Python バインディング	サポートされる型／エラー／非同期モデルが適合する場合は UniFFI を使います。配布とパッケージングは別途対応が必要です
成熟した Rust クレートを組み合わせることを優先し、Java のオールインワン実装を再現することは避けます。ただし、互換性のために必要な場合は、ソースプロジェクトで外部から確認できるファサードを維持してください。

9. アノテーションの動作を安定したマクロ境界の背後に切り出す

通常のランタイムクレートに手続き型マクロのエントリーポイントを配置しないでください。次を使用します。

project-core      # runtime traits, types, errors, and generated-code contract
project-macros    # thin proc-macro entry points and syntax parsing
project-web-*     # framework adapters that may re-export approved macros

公開インターフェースが derive マクロのみの場合は -derive を、属性マクロ、関数形式マクロ、または複合型のマクロには -macros を使用してください。ただし、既存のクレート群で意図的に確立された命名がある場合は除きます。生成コードは、proc-macro の内部ではなく、公開ランタイム API に依存させてください。展開の成功、コンパイルエラー、ジェネリクス、可視性、依存関係の名前変更、および各フレームワークの再エクスポートをテストしてください。

Java のランタイムアノテーションが、自動的に Rust のマクロになるわけではありません。ランタイム状態と動的ディスパッチが動作を担う場合は、ミドルウェア、トレイト、レジストリ、または明示的なビルダーを使用してください。

10. 一度に監査し、バッチ全体を検証する

実装を凍結した後、適用可能な検証手順を、宣言したバッチ全体に対して実行します。

1. すべてのオブジェクト、ファイル、正確なシグネチャ、パラメーター、オーバーロード、呼び出し経路、動的境界、サンプル、テスト、ドキュメント、プレースホルダーを対象に、CodeGraph／静的パリティ監査を一括で実行します。Java のコメント全件を、Rust のオブジェクト、メソッド、パラメーター、戻り値、エラー、メタデータ、インラインコメントと照合します。4 つすべての文書を一度の作業で整合させます。
2. Rust のフォーマット、チェック、ユニットテスト、ドキュメントテスト、統合テスト、Clippy、機能、ターゲット、プラットフォームの各ゲートを、統一されたエンジニアリングスイートとして実行します。
3. 移植／ミラーリングした Java の契約テストをすべて実行し、差分検証の証拠ではないことを明確に示します。
4. 固定された Java テストスイート全体と、Rust のロスレス移植テストスイート全体を実行し、その後、すべての具体的なソースケースを対象に、Java のゴールデンエクスポーター全体、または Java／Rust のライブ差分検証スイート全体を実行します。両方のスイートが成功し、すべてのケースで MATCH が報告されることを必須とします。不一致、ハーネスの失敗、未実行のケースはゼロでなければなりません。専用の <project>-test パッケージから実行してください。本番クレート内のローカルテストは、サブシステムの証拠にのみ使用します。
5. 実際のユーザースクリプトとサンプルの全セットを、両方の実装に対して再実行します。
6. 順序、キャンセル、バックプレッシャー、競合、シャットダウン、および有用な場合は Loom／モデルの各プロパティについて、並行処理の受け入れテストを実行します。
7. スループット、レイテンシのパーセンタイル、メモリ、ハンドル／タスク、再接続、長時間実行を対象に、負荷／安定性テストを実施します。
8. セキュリティプロパティテスト、不正入力テストスイート、cargo-fuzz、unsafe コードのレビュー、依存関係のアドバイザリ、シークレットのマスキングチェックを実施します。
9. データベース、ネットワーク、ファイル、フレームワーク、デプロイトポロジーを使用して、実際の業務ホストとの統合をテストします。
10. 復旧時間と状態の互換性を記録しながら、グレーロールアウトとロールバックの訓練を実施します。

ゲートに失敗した場合は、共通のサブシステムまたは根本原因ごとに失敗をまとめ、バッチを修正して、影響を受ける統合ゲートと、その下流で無効になったゲートを再実行します。オブジェクトを一つずつ移行、比較、テストする方法には、決して切り替えないでください。

証拠設計については検証と受け入れを参照し、3 つの台帳を用いたテストの標準作業手順には rust-java-migration-testing を使用してください。コンパイルできない、または警告が多いワークスペースを修正する前に、コンパイルのずれと移行のクリーンアップを読んでください。依存関係／バージョンのずれ、MSRV、クレートルートの再エクスポートチェーンの破損、クレート間で重複する型、Java ミラーの命名／スキャフォールディング規約、警告ゼロのチェックワークフロー（デフォルト＋--all-features、--keep-going による段階的なエラー表示、クレートごとの原因特定、クリーンアップ後のテスト）について説明しています。

11. 完了を報告する際に、カバレッジを誇張しない

構造、実装、動作、テスト、統合、本番環境への対応状況をそれぞれ分けて報告してください。動作については、ミラーされた契約、ゴールデン差分テスト、実環境での差分テスト、承認済みの同等なオラクルを区別してください。テストについては、損失なく移行されたソーステストと、Rust ネイティブの追加テストを分けてください。

正確なコマンド、SHA、テスト数、失敗、例外、未検証の範囲を必ず含めてください。コードがコンパイルできることや、パリティマニフェストが 100% に達することを理由に、移行が完了したと決して表現してはいけません。

レッドライン

• 移行したオブジェクトを多数 lib.rs、mod.rs、compat.rs に定義しないでください。
• すべてのオブジェクトを単一の compat.rs の実装に委譲しないでください。
• 移行を完了したものとして、空の本体、todo!()、unimplemented!() を使用しないでください。
• 件数を合わせるために、移行済みの動作を削除したり単純化したりしないでください。
• 本番環境向けの移行コードでワイルドカードインポートを使用しないでください。
• 複数の Java オブジェクトを機械的に 1 つの Rust ファイルにまとめないでください。
• 作成した .rs ファイルを物理行数 800 行超のままにしないでください。500 行を超えるファイルはすべて見直し、まとまりが弱い場合は分割してください。
• サイズゲートを通過するためだけに、コードを機械的に圧縮したり、有用なコメントを削除したり、任意の行範囲で分割したりしないでください。
• 統合テスト、差分テスト、ホストテスト、負荷テスト、プロジェクト全体の受け入れテストを本番モジュールに埋め込まないでください。対象モジュール内の非公開動作に焦点を絞った #[cfg(test)] のインライン単体テストは引き続き有効です。
• オーバーロードされた動作を、情報を損なう単一の便利関数に置き換えないでください。
• 慣用的な Rust メソッドと明示的な互換アダプターで契約を維持できる場合、JavaBean の表記に合わせることだけを目的に get_* メソッドを作成しないでください。
• スクリプトや動的なメンバーアクセスで Java のフィールド／ゲッター／セッター解決が引き続き必要な場合、慣用的な Rust のゲッター／セッターだけで十分だと見なさないでください。
• 依存関係の宣言、コンパイルの成功、孤立した POC を、検証済みのコンポーネント置換と呼ばないでください。
• 置換用依存関係のパッケージ／ファイル構成を対象オブジェクトの一覧として使用しないでください。ソースの Java オブジェクトと決定論的なパス規則を引き続き正としてください。
• ピン留めされたクレート／コミット、正確なソースシンボル、アダプターの証拠、ローカル統合テストがないまま、意味的に類似した依存関係を DEPENDENCY_REUSED としないでください。
• 難しい、または情報が不足しているだけの作業に PLATFORM_NA を使用しないでください。JVM／バイトコード／クラスローダー／プラットフォーム固有の証拠を必須としてください。
• 調査リストやローカルの規約文書から持ち込んだコンポーネントを、現行の厳格なフィルターと契約の証拠なしに「選定済み」にしないでください。
• Java テストをコピーした Rust テストについて、両方の実装または Java が生成したゴールデンアーティファクトが参加していない限り、差分テストと呼ばないでください。
• 判定結果だけでソーステストとのパリティを宣言しないでください。ソースの各ケースには損失のない移行先と、ゴールデン／ライブの MATCH が必要です。MISSING、BLOCKED、NOT_APPLICABLE がある場合は完了できません。
• コピーしたソースフィクスチャ、スクリプト、コーパス、ゴールデンファイル、テストデータを直接変更しないでください。ソースとターゲットの SHA-256 を検証し、生成された派生物は別に保管してください。
• 各スイートが独立して成功したことやテスト総数が同じであることをパリティと見なさないでください。ケースごとの出力、エラー、状態、副作用、クリーンアップを比較してください。
• 公開されていない <project>-test のプロジェクト全体受け入れパッケージの代わりに、本番／バインディングクレートのローカルテストを使用しないでください。
• Rust の公開、依存関係、ターゲット、マクロ／FFI、ライフサイクル上の理由がない限り、Maven／Gradle モジュールを Cargo パッケージに 1 対 1 でコピーしないでください。
• すべてのワークスペースを crates/ 配下やルート直下のフラット構成に無理に当てはめないでください。製品の規模、ファミリー、リポジトリのノイズ、互換性に基づいて構成を記録してください。
• ファイル数、パーサーによる受理、汎用的な is_ok()／is_err()、または「オブジェクトごとに少なくとも 1 つのテストがある」ことだけを根拠に、行の動作検証済みとしないでください。
• 4 つの移行ドキュメントでベースラインを食い違わせたり、完了状態を矛盾させたりしないでください。
• 現行のドキュメントと -歴史詳細版／ネストされた重複版を併存させないでください。有用な履歴は生成された事実領域の後に統合してください。
• 生成された現行の事実領域を置き換えたり、再生成によって統合済みの付録が破棄されたりしないようにしてください。
• モック、コンパイル、静的検査しか実行していないのに、実際にテストしたと主張しないでください。
• パターンを抽出する際に、参照元のリポジトリを編集しないでください。
• オブジェクト、ファイル、メソッドごとに、移行、比較、テストを交互に行わないでください。
• 実装中にオブジェクト単位の受け入れテストを実行しないでください。統合監査と一元的な検証に進む前に、固定したバッチを完了してください。
• 復旧コミットやローカル編集の節目を完了チェックポイントにしないでください。
• 既存の Java オブジェクト、コンストラクター、メソッド、パラメーター、戻り値、例外、ライフサイクル、スレッド安全性、非推奨情報、意味を持つインラインコメントを省略しないでください。
• ソースのドキュメントを一般的な文章に置き換えたり、cargo doc だけでコメントのパリティが確認できたと主張したりしないでください。
• パラメーター、戻り値、エラーバリアント、フィールド、インラインコメントに 対応 Java と書かないでください。任意の対応付けは Rust の型およびコンストラクター／メソッドのドキュメントに限定し、詳細な対応関係は 4 つのドキュメントに記載してください。
• non_camel_case_types／dead_code を抑えるために、Java を反映した SCREAMING_SNAKE enum バリアントの名前を変更したり、Java を反映したスキャフォールディング型を削除したりしないでください。#[allow(...)] とコメントを使用し、Java の一覧を維持してください。
• デフォルト機能のゲートを通過しただけでワークスペースがクリーンだと宣言しないでください。--all-features でも警告ゼロにする必要があります。また、古いローカルの rustc に合わせるために rust-version を暗黙に下げないでください。固定されたツールチェーンを rustup run <ver> cargo ... で実行してください。
• 依存先クレートをクリーンアップする際に、そのパス依存関係を編集しないでください。まず --> のパスを基に、各警告の所有クレートを特定してください。
• 1 回の --keep-going 出力に含まれる「すべてのエラー」を修正しようとしないでください。エラーは段階的に表面化します。最初の層を修正し、再実行して、繰り返してください。

完了基準

• 各ソースモジュールの最新ドキュメント4件で、ベースライン、コントラクト、Rust SHA が共有されており、重複がありません。
• ロードマップには、ソースモジュールからクレートへの境界の根拠と、プロジェクト主導のトポロジーが記録されています。実際のマニフェストとメンバーのパスは、ロードマップと一致しています。
• すべてのオブジェクトに、決定的な末尾2セグメントのパスが設定されています。物理的に配置が一致するまでは、MISPLACED は未完了のままです。
• すべての Java オブジェクト、メソッド、オーバーロード、パラメーターに、処置が定められています。
• すべてのソーステスト／ケースに対して、情報を損なわない Rust 実装があり、すべてのソースアセットにはバイト単位で同一のチェック済みコピーがあります。
• <project>-test は選定されたパスにワークスペースメンバーとして存在し、publish = false が設定され、ソーススイート全体／差分コマンドとアーティファクトを所有しています。
• Java／Rust の全スイートが合格し、全ケースの差分結果が 100% MATCH です。ハーネスの失敗や未実行ケースはありません。
• 依存関係の再利用、プラットフォームの除外、ブロッカー、例外、Rust 拡張には、いずれも具体的な証拠があり、分母の扱いも正確です。
• 作成したすべての .rs ファイルが、物理的に800行以下です。500行を超えるファイルと、Clippy が示す100行を超える関数には、凝集度レビューが記録されています。また、分割する場合も Java のオブジェクト境界を維持しています。
• ユニットテストは、対象モジュールの動作を重点的に検証する場合に限り、同じ場所に配置されています。統合、差分、ホスト、負荷、プロジェクト全体のスイートは、tests/ または非公開のテストパッケージに配置されています。
• 本番用 Rust ファイルは、レイアウト、ドキュメント、インポート、スタブ禁止のルールを満たしています。
• ソースで説明されているすべてのオブジェクト、メンバー、パラメーター、戻り値、例外、メタデータタグ、意味を持つインラインコメントに、追跡可能な Rust 側の対応箇所があります。
• いずれかの受け入れゲートを実行する前に、宣言されたバッチ全体が実装されています。
• 実装後の統合パリティ監査1回で、凍結された分母全体を対象にしています。オブジェクトごとの検証ループは使用していません。
• 重要度の高い呼び出しチェーンに、ソースへのリンクを含む意味的なマッピングがあります。
• 該当する差分、リプレイ、並行性、負荷、ファジング、ホスト、ロールバックの各ゲートについて、証拠または明示的な未解決事項があります。
• 最終報告では、構造、実装、動作、統合、本番運用への準備状況に関する主張をそれぞれ分けています。