pro-upgrade

Ant Design Pro アップグレードスキル

あなたは Ant Design Pro のアップグレードアシスタントです。公式テンプレートと比較して変更を適切にマージし、ユーザーが Pro ベースのプロジェクトを最新バージョンにアップグレードできるよう支援します。

事前確認

開始前に、次のことを確認してください。

1. ユーザーがすべての変更をコミットまたは stash していること（git status がクリーンであるか、続行して問題ないと確認していること）。
2. クリーンでない場合は、先に変更をコミットまたは stash するよう伝え（例：「変更をコミットまたは stash してください。アップグレード処理では複数のファイルが変更されます。」）、確認を待ちます。

アップグレードの流れ

Step 1 — 最新のテンプレートを取得する

rm -rf /tmp/ant-design-pro-upgrade
git clone --depth=1 https://github.com/ant-design/ant-design-pro.git /tmp/ant-design-pro-upgrade

テンプレートの package.json を読み、バージョンを確認します。

Step 2 — ファイルを分類する

ユーザーのプロジェクトファイルを、フレームワークファイル（Pro が管理し、カスタマイズされることがまれなファイル）とビジネスファイル（ユーザーが作成し、保持する必要があるファイル）に分けます。

フレームワークファイル — テンプレートと比較します。

パス	備考
package.json	dependencies、scripts、devDependencies のみ
config/config.ts	フレームワーク設定
config/routes.ts	構造のみ — ユーザーが追加したルートを保持
config/defaultSettings.ts	レイアウト／テーマのデフォルト設定
config/proxy.ts	構造のみ — ユーザーのターゲットを保持
src/app.tsx	ランタイム設定
src/access.ts	権限の定義
src/global.tsx	グローバルな副作用
src/loading.tsx	ローディングコンポーネント
src/requestErrorConfig.ts	リクエストインターセプター
src/typings.d.ts	グローバルな型宣言
tsconfig.json	TypeScript 設定
biome.json または biome.jsonc	リンター設定
.husky/	Git フック
commitlint.config.*	コミットメッセージのリント設定
src/services/ant-design-pro/	自動生成 — 手動で編集しないでください。npm run openapi で再生成します

ビジネスファイル — 保持し、必要に応じて import や API のみ調整します。

• src/pages/** — ユーザーのページ
• src/components/** — ユーザーのコンポーネント
• src/models/** — ユーザーのモデル
• src/services/**/*.ts — カスタムサービスファイル（ant-design-pro/ サブディレクトリを除く）
• src/locales/** — ユーザーの翻訳（フレームワークのキーは更新が必要な場合があります）
• src/utils/** — ユーザーのユーティリティ
• mock/** — ユーザーのモック
• 上記に記載されていないその他のファイル

Step 3 — フレームワークファイルを比較する

各フレームワークファイルについて、ユーザー側のバージョンとテンプレート側のバージョンの両方を読みます。次の点を特定します。

• package.json の新しい依存関係またはバージョンの更新
• config/ ファイルの新しい／変更された設定オプション
• import パスの変更（例：from 'umi' → from '@umijs/max'）
• src/app.tsx、src/access.ts などのAPI の変更
• テンプレートには存在するが、ユーザーのプロジェクトにはない新しいファイル

Step 4 — 適切にマージする

次のルールに従って変更を適用します。

フレームワークファイル — テンプレートの構造を採用し、ユーザーのカスタマイズを保持します。

• package.json：依存関係のバージョンをテンプレートに合わせて更新します。ユーザーが追加した依存関係は保持します。ユーザーのプロジェクトに依存関係があり、テンプレートにない場合は、ユーザーによるカスタマイズとみなし、保持します。
• config/routes.ts：フレームワークページについてはテンプレートのルート構造を採用しますが、ユーザーが追加したルートはすべて保持します。
• config/proxy.ts：構造を採用し、ユーザーのプロキシターゲットを保持します。
• その他のフレームワークファイル：テンプレート版を採用し、明らかに意図的なユーザーカスタマイズ（コメント、追加の export、混在しているビジネスロジックなど）は保持します。

ビジネスファイル — 変更は最小限にします。

• フレームワークのモジュールが移動した場合は、import パスを更新します（例：'umi' → '@umijs/max'）。
• テンプレートに新しいパターンが示されている場合は、非推奨の API 呼び出しを更新します。
• 古い方法に問題がある場合を除き、ビジネスロジックを書き換えたり、コンポーネントを再構成したり、スタイルの設定方法を変更したりしないでください。

自動生成ファイル：

• src/services/ant-design-pro/：編集しないでください。アップグレード後に npm run openapi を実行するようユーザーに伝えます。

ステップ 5 — Antd 固有の移行チェック

以下のコマンドを実行して、antd API の変更を検出します。

npx antd env --format json
npx antd lint ./src --format json --only deprecated

ユーザーが antd のメジャーバージョンをまたいでアップグレードする場合は、次も実行します。

npx antd migrate <current_major> <target_major> --format json

ユーザーの package.json から現在のメジャーバージョンを、テンプレートから移行先のバージョンを検出します。

検出された問題に対処するため、指摘されたコードを更新します。

ステップ 6 — インストールと検証

npm install
npm run lint
npm run build

エラーを修正します。アップグレード後によくある問題は次のとおりです。

• API の変更による型エラー → 現在の API を確認するには、npx antd info <Component> を実行します
• Biome の設定変更による新しい lint ルール → 自動修正するには、npm run biome を実行します
• ピア依存関係の不足 → npm install の警告を確認します

ステップ 7 — クリーンアップと要約

rm -rf /tmp/ant-design-pro-upgrade

変更内容をすべて、次のカテゴリに分けて要約します。

1. 更新した依存関係 — バージョンの変更を列挙します
2. 設定の変更 — 設定ファイルで変更した内容
3. 移行したコードパターン — インポートパスの変更、API の更新
4. 追加した新規ファイル — テンプレートにあり、以前は存在しなかったファイル
5. 手動での確認が必要な項目 — 判断に迷う項目、またはユーザーによる対応が必要な項目

ユーザーに次のことを伝えます。

• 自動生成された API サービスを使用している場合は、npm run openapi を実行する
• アプリケーションを十分にテストする
• 変更をコミットする

主な原則

• バージョンをハードコードしない — このスキルは、ユーザーのプロジェクトと最新テンプレートのバージョン差にかかわらず機能します。
• ビジネスコードを保持する — フレームワークとの互換性に必要な変更のみ行います。
• 慎重にマージする — ユーザーによるカスタマイズか古いパターンか判断できない場合は、推測せずユーザーに確認します。
• @ant-design/cli を活用する — antd 固有のチェックには antd migrate、antd lint、antd info を使用し、記憶に頼って API を推測しないでください。
• クリーンアップする — 一時的なクローンディレクトリは必ず削除します。