modernize-move

スキル：modernize-move

古くなった Move V1 の構文、パターン、API を検出し、Move V2 以降に対応させます。段階的な変換と各段階後のテスト検証により、正確性を維持します。

重要な原則

すべてのモダナイゼーションで必ず守るべき5つのルールです。

1. テストによる安全網は必須です 理由：モダナイゼーションでは動作を維持する必要があります。テストがなければ安全網がありません。テストが存在しない場合は、変更を加える前にまず generate-tests スキルを呼び出して、包括的なテストを作成してください。

2. 変更前に分析します 理由：ユーザーは何が変更されるのかを正確に確認し、対象範囲を承認する必要があります。コードを予告なく編集してはいけません。分析レポート全体を提示し、承認を待ってください。

3. 段階的な実行順序を守ります 理由：構文の変更（Tier 1）はリスクがありません。API の移行（Tier 3）は意味を変えます。常に最も安全な変更から適用し、よりリスクの高い変更を、検証済みのクリーンな基盤の上に重ねてください。

4. 各段階の後に検証します 理由：テストが失敗した場合、どの段階が原因かを正確に把握できます。その段階を元に戻してから、先に進む前に調査してください。基準となる状態でテストが失敗している場合、次の段階を適用してはいけません。

5. エラーコードの値を維持します 理由：テストでは #[expected_failure(abort_code = N)] が使われています。数値を変更すると、気づかないうちにテストが壊れます。名前付き定数を作成する場合、数値は元のリテラルと必ず一致させてください。

このスキルを使用する場面

• Move V1 のコントラクトを V2 の構文にアップグレードする
• public(friend) を package fun に移行する
• vector::borrow をインデックス表記に変換する
• カウンターを使う while ループを for 範囲ループに変換する
• 手動のベクター反復を、標準ライブラリのインライン関数（vector::for_each_ref、vector::map、vector::fold など）とラムダに置き換える
• マジックナンバーの abort 値を名前付き定数に置き換える
• レガシーな coin／TokenV1 を最新の fungible_asset／Digital Assets に移行する
• EventHandle を #[event] パターンに変換する
• カスタムの符号付き整数の代替実装を、ネイティブの i8～i256 型にアップグレードする

このスキルを使用しない場面

• コントラクトを新規に作成する場合 — write-contracts を使用してください
• バグの修正や機能の追加 — モダナイゼーションは構造を対象とし、機能は対象としません
• ガス使用量の最適化 — analyze-gas-optimization を使用してください
• セキュリティ監査 — security-audit を使用してください（モダナイゼーションの後に実行）

ワークフロー

フェーズ1：コントラクトの分析

開始条件： ユーザーがモダナイゼーション対象の Move コントラクトまたはプロジェクトを提供します。

作業内容：

1. すべてのコントラクトソースファイル（sources/ 内の .move ファイル）を読み込みます
2. detection-rules.md の検出ルールを使って V1 パターンをスキャンします：
   • Tier 1 パターン（構文）を grep で検索します — 信頼度が最も高く、最も一般的です
   • Tier 2 パターン（可視性、エラー、イベント）を grep で検索します
   • Tier 3 パターン（API の移行）を grep で検索し、手動レビューの対象としてフラグを立てます
3. 関連するパターンを相互参照します（T3-09+T3-10）
4. 各検出項目を分類します：行番号、ルール ID、パターン名、提案する変更、Tier、信頼度
5. 分析レポートを作成します

終了条件： 分析レポートを提示する準備ができています。

フェーズ2：分析の提示（ゲート1）

開始条件： 分析レポートが完成しています。

作業内容：

1. 次の形式で分析レポート全体をユーザーに提示します：

## Modernization Analysis Report

### Summary
- Tier 1 (Syntax): X findings
- Tier 2 (Visibility & Errors): X findings
- Tier 3 (API Migrations): X findings

### Findings

| # | File:Line | Rule | Pattern | Proposed Change | Tier | Confidence |
|---|-----------|------|---------|-----------------|------|------------|
| 1 | src/mod.move:15 | T1-01 | vector::borrow | → index notation | 1 | High |
| ... | ... | ... | ... | ... | ... | ... |

### Tier 3 Warnings (if any)
- T3-03: coin → fungible_asset migration is a major rewrite (X locations)

2. 対象範囲を選ぶようユーザーに尋ねます：
   • syntax-only（Tier 1 のみ） — リスクなしで、構文を整理します
   • standard（Tier 1 + Tier 2） — 推奨されるデフォルト。構文、可視性、エラー定数が対象です
   • full（すべての Tier） — API の移行を含み、リスクが高くなります
3. 大規模な書き換えが必要な Tier 3 の項目があれば、強調して伝えます
4. 対象範囲に Tier 3 が含まれる場合、デプロイの状況をユーザーに尋ねます：
   • 互換性あり — デプロイ済みのコントラクトをアップグレードします。対象範囲に含まれていても、破壊的変更は除外します。⚠ Breaking のマークが付いたルールはスキップされます。
   • 新規デプロイ — 新たにデプロイするか、再デプロイが可能です。破壊的変更を含め、選択した対象範囲内のすべての変更が適用されます。

終了条件： ユーザーが対象範囲（Tier 3 が含まれる場合はデプロイ状況も）を確認しています。確認されるまで先に進んではいけません。

フェーズ 3：テストのセーフティネットを確立する

開始条件： ユーザーがスコープを確認済みです。

作業内容：

1. 既存のテストを検索します。
   • ソースファイル内の #[test_only] モジュール
   • *_tests.move ファイル
   • tests/ ディレクトリ
2. テストが見つからない場合：作業を止め、generate-tests スキルを実行して包括的なテストを先に作成してから、ここに戻ります。
3. aptos move test を実行し、合格するベースラインを確立します。
4. ベースラインを記録します：テスト数、すべて合格していること。

終了条件： すべてのテストが合格しています。ベースラインが記録されています。モダナイズ前にテストが失敗する場合は、いったん停止して、まずテストの失敗に対処します。壊れたテストスイートの状態でモダナイズしてはいけません。

フェーズ 4：変換を適用する（フィードバックループあり）

開始条件： テストのベースラインが確立されています。

作業内容 — ティア順に適用します：

ティア 1（スコープに含まれる場合 — 常に適用）：

1. transformation-guide.md に従って、ティア 1 の構文変更をすべて適用します。
2. aptos move test を実行します。
3. テストが失敗した場合 → ティア 1 の変更をすべて元に戻し、失敗の原因となった変更を特定して修正し、再試行します。

ティア 2（スコープが standard または full の場合）： 4. 変換ガイドに従って、ティア 2 の変更をすべて適用します。5. aptos move test を実行します。6. テストが失敗した場合 → ティア 2 の変更をすべて元に戻し、原因を調査して修正します。

ティア 3（スコープが full の場合のみ）： 7. ティア 3 の変更を一度に 1 つずつ適用します（一括では適用しません）。

• デプロイコンテキストが compatible の場合：⚠ 破壊的変更 とマークされたルールはスキップします。スキップしたリストに、理由「破壊的変更のため、compatible モードでは除外」と記録します。
• デプロイコンテキストが fresh deploy の場合：スコープ内のすべてのルールを通常どおり適用します。

8. ティア 3 の変更を個別に適用するたびに、aptos move test を実行します。
9. テストが失敗した場合 → その変更を元に戻し、スキップとして記録してから、次のティア 3 項目に進みます。

終了条件： 承認された変更がすべて適用され、すべてのテストが合格しています。

フェーズ 5：最終検証

開始条件： すべての変換が適用されています。

作業内容：

1. aptos move test --coverage を実行します。
2. テストカバレッジがベースライン以上であることを確認します（同等以上である必要があります）。
3. モダナイズ概要レポートを生成します。

## Modernization Summary

### Changes Applied
- Tier 1: X changes (syntax)
- Tier 2: X changes (visibility & errors)
- Tier 3: X changes (API migrations)

### Changes Skipped
- [List any skipped items with reasons]

### Test Results
- Tests: X passing (baseline: Y)
- Coverage: X% (baseline: Y%)

### Files Modified
- [List of modified files]

終了条件： レポートをユーザーに提示します。

モダナイズスコープのクイックリファレンス

スコープ	ティア	リスク	使用するタイミング
syntax-only	ティア 1	なし	構文のみを整理し、セマンティックな変更は行いません
standard	ティア 1+2	低	デフォルト。 構文 + 可視性 + エラー定数
full	ティア 1+2+3	中〜高	API の変更を含む完全な移行

ティア早見表

ティア	変更内容	リスク	例
1 — 構文	コードの読み方は変わりますが、コンパイル結果は同じです	なし	vector::borrow(&v, i) → v[i]、x = x + 1 → x += 1、while (i < n) { ... i += 1 } → for (i in 0..n) { ... }
2 — 可視性とエラー	セマンティクスは同じまま、宣言がより明確になります	低	public(friend) → package fun、マジックナンバー → E_* 定数
3 — API 移行	API は異なりますが、意図された動作は同じです。多くは破壊的変更です。	中〜高	coin → fungible_asset、SmartTable → BigOrderedMap、EventHandle → #[event]、手動ループ → ラムダを使った標準ライブラリの v.for_each_ref()／v.map()／v.fold()

ルールの完全な一覧（3 つのティアにわたる 22 個のルール）については、detection-rules.md を参照してください。

避けるべき誤った正当化

誤った正当化	間違っている理由
「テストに通ったので、モダナイゼーションは正しい」	テストで検証できるのは動作であり、コード品質ではありません。変更内容も手動で確認してください。
「このコントラクトは単純なので、分析は省略しましょう」	単純なコントラクトにも、見落としやすいパターンが含まれることがあります。必ず最初に分析してください。
「時間を節約するため、すべてのティアを一度に適用しましょう」	テストが失敗した場合、どの変更が原因か切り分けられません。必ずティアごとに進めてください。
「レシーバースタイルの呼び出しで問題なさそうです」	対象の関数で self が宣言されていることを確認する必要があります。誤検知はよくあります。
「エラー定数の名前や値を変更しても問題ありません」	既存のテストは正確な数値に依存しています。値を維持してください。
「テストはありませんが、変更は安全です」	テストがなければ安全網がありません。まずテストを生成してください。
「ティア 3 の変更は任意なので、テスト実行は省略しましょう」	すべての変更で検証が必要です。ティア 3 は最もリスクが高いため、テストは減らすのではなく、増やしてください。

成功基準

• 変更を加える前に分析レポートを提示している
• ユーザーがモダナイゼーションの範囲を確認している
• 変更前にテストのベースラインを確立している
• 各ティアの変更後にテストが通っている
• すべてのエラーコードの数値が維持されている
• full スコープの確認なしにティア 3 の変更を適用していない
• ユーザーが互換モードを選択した場合、破壊的変更を除外している
• モダナイゼーション概要レポートを生成している
• テストカバレッジをベースライン以上に維持している

リファレンス一覧

ファイル	内容
detection-rules.md	V1 パターン検出の完全なカタログ（3 つの階層にわたる 22 のルール）
transformation-guide.md	各ルールの変換前後のコード、安全性チェック、エッジケース
MOVE_V2_SYNTAX.md	V2 構文の完全なリファレンス
OBJECTS.md	最新のオブジェクトモデルパターン
ADVANCED_TYPES.md	列挙型、符号付き整数、ファントム型

関連スキル： generate-tests、write-contracts、security-audit