migrate-hardhat2-to-hardhat3

このスキルでは、V2 から V3 への完全な移行を6 つの連続したフェーズで実行します。上から順に 1 つのエージェントで実行する方法がデフォルトです。小規模から中規模のプロジェクト（および 1M トークンのコンテキストウィンドウで、約 150 個までの .ts テストファイルを含む大規模プロジェクト）に対応できます。それを超える場合、またはコンテキストウィンドウが小さい環境（約 200k トークン）で単純なプロジェクトを超える場合は、移行の途中で 1 つのコンテキストがあふれないよう、ファイルを多く扱うフェーズ（4 と 5）をサブエージェントに分担させてください（references/migration-conventions.md の「Optional: sub-agent fan-out」を参照）。

開始前に

1. references/migration-conventions.md を読んでください — 各フェーズが依存するルール（VCS コマンドの禁止、パッケージマネージャーの検出、対象範囲、ゲート、変更内容の提示、任意の並列実行モデル）が記載されています。読み終えるまで先に進まないでください。
2. パッケージマネージャーを検出し（ロックファイルを確認）、移行全体を通じてその情報を保持してください。
3. 実行モードを選択してください。 コンテキストウィンドウとプロジェクトの規模（.ts テストファイルの数）を見積もり、規約ドキュメントのしきい値に基づいて、単一エージェント（デフォルト）とサブエージェントへの分担のどちらかを選んでください。どのウィンドウか判断できない場合は、小さいほうを想定してください。ほとんどのプロジェクトでは、単一エージェントで対応できます。
4. 各フェーズは必ず順番に実行してください — 各フェーズは前のフェーズの出力に依存します。各フェーズの後に停止し、ユーザー確認ポイントで承認を待ってから続行してください。確認ポイントでは、次の順に提示してください。
   • 完了したステップ — 完了したフェーズのタイトル（例：フェーズ 1 — プロジェクトのセットアップ）とその変更内容。変更したファイルを列挙し、想定外のファイルがあればそのまま提示してください（規約ドキュメントのコアルール 5 を参照）。
   • 推奨するコミットメッセージ — 完了したフェーズの確認用コミットメッセージ。
   • 次のステップ — 次のフェーズのタイトル（例：フェーズ 2 — 設定）と、実行内容を 1 行で説明してください。フェーズ 6 の後は「移行が完了しました」とします。

フェーズ

各フェーズは、対応するフェーズガイドに従って実行してください。各フェーズの最後にはゲートがあります。次のチェックリストは、先に進む前にフェーズが本当に完了したことを確認するためのものです。

フェーズ 1 — プロジェクトのセットアップ → フェーズガイド

テンプレートから .env を作成し、ESM 用に tsconfig.json を更新し、package.json を変更します（ESM フラグ、V2 から V3 への依存関係の置き換え、スクリプト）。

• フェーズですべてのゲートを通過したと報告されている
• npx hardhat --version を実行すると、3.x バージョン（例：3.9.0）が表示される
• 確認用コミット：[CHECK] HH3 project setup: env, tsconfig, package.json

フェーズ 2 — 設定 → フェーズガイド

hardhat.config.ts を、V3 の宣言型 defineConfig（プラグイン、ネットワーク、カスタムタスク、solidity、verify、テスト設定）に書き換えます。

• フェーズですべてのゲートを通過したと報告されている
• 確認用コミット：[CHECK] HH3 config: declarative defineConfig (solidity, networks, plugins, tasks, verify)

フェーズ 3 — Solidity テスト → フェーズガイド

.t.sol テストファイルを V3 の規約に合わせて移行します。config の変更が必要になる場合があります（例：Solidity テストファイルの場所を変更する paths.tests.solidity、またはテストコントラクトをソースとしてコンパイルする必要がある場合の paths.sources.solidity）。

• npx hardhat test solidity がエラー 0 件で成功する（または Solidity テストがない場合はスキップ）
• 確認用コミット：[CHECK] HH3 solidity test migration

フェーズ 4 — ソースファイル → フェーズガイド

すべての .ts ファイル（および CommonJS の .js ファイルがあればそれも）を CJS から ESM に変換し、V2 API 呼び出しを V3 に更新します（TypeChain のインポート修正を含む）。

• フェーズですべてのゲートを通過したと報告されている
• npx tsc --noEmit がエラー 0 件で成功する
• npx hardhat test solidity が引き続き成功する（回帰チェック — ソースの変更によって Solidity テストが失敗することがあります）
• 確認用コミット：[CHECK] HH3 source file migration: ESM conversion, V3 API updates, and TypeChain import fixes

フェーズ 5 — テストの修正 → フェーズガイド

V3 で .ts テストスイートが通るようにします。

• npx tsc --noEmit が引き続きエラー 0 件で通る
• 各テストファイルが個別に通る（npx hardhat test {file}）
• npx hardhat test solidity が引き続き通る（回帰チェック — テストヘルパーや設定の修正によって Solidity テストが失敗する可能性があります）
• チェックポイントのコミット：[CHECK] HH3 test suite fix-up: all tests passing under V3

フェーズ 6 — スクリプトの検証 → フェーズガイド

対話形式で、ユーザーが検証する package.json のスクリプトを選び、スキルが 1 つずつ実行して修正します。

• フェーズですべてのゲートに合格したと報告される
• npx tsc --noEmit が引き続きエラー 0 件で通る
• チェックポイントのコミット：[CHECK] HH3 script validation: all package.json scripts passing

完了

停止して、移行が完了したことをユーザーに伝えます。