EOL対応計画の作成

フロントエンドプロジェクトのライブラリEOL（End of Life）対応計画を作成し、Markdownファイルに出力します。

引数

$ARGUMENTS: フリーワードで要件を指定できます
- 省略時: プロジェクト全体の依存関係を対象に計画を作成

引数の指定パターン

/eol-plan react@19 next@15
/eol-plan Node.jsを22系までアップデートしライブラリを可能な範囲で最新化
/eol-plan recoilをjotaiに置き換え
/eol-plan セキュリティ脆弱性のあるパッケージのみ対応

実行フロー

このコマンドは以下のフローで実行します。サブエージェントへの無駄な呼び出しを避けるため、情報収集はこのコマンド内で完結させます。

[Step 1-4] 情報収集（このコマンドで実行）
    ↓
[Step 5] サブエージェント呼び出し（調査のみ依頼）
    ↓
[Step 6-7] 戦略決定・計画書作成（このコマンドで実行）

Step 1: 初期情報の収集

以下の情報を一括で収集（並列実行可能）:

1.1 出力先の決定

# CLAUDE.mdから出力先を確認
grep -i "EOL計画出力先" CLAUDE.md

指定がない場合: プロジェクトルートに eol-plan.md を作成

1.2 パッケージマネージャーの特定

# ロックファイルの存在確認（優先順位: bun > pnpm > yarn > npm）
ls bun.lockb bun.lock pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null | head -1

1.3 プロジェクト構成の確認

# ソース/テストディレクトリの特定
ls -d src/ app/ pages/ components/ __tests__/ tests/ 2>/dev/null

1.4 Node.jsバージョンとバージョン管理ツールの確認

# バージョンファイルの確認
cat .nvmrc .node-version .tool-versions 2>/dev/null || grep '"node"' package.json

# バージョン管理ツールの特定（優先順位: プロジェクト既存ツール > mise）
ls .nvmrc .node-version .tool-versions mise.toml .mise.toml 2>/dev/null | head -1

ファイル	ツール
`.nvmrc`	nvm
`.node-version`	nodenv, fnm, mise等
`.tool-versions`	asdf, mise
`mise.toml` / `.mise.toml`	mise
なし	ユーザーに確認（推奨: mise）

Step 2: 依存関係の一括取得

2.1 npm-check-updates で最新バージョン確認

npx npm-check-updates --jsonUpgraded 2>/dev/null || npx npm-check-updates

2.2 セキュリティ監査

# パッケージマネージャーに応じて実行
npm audit --json 2>/dev/null || npm audit
yarn audit --json 2>/dev/null || yarn audit
pnpm audit --json 2>/dev/null || pnpm audit

2.3 package.json の読み込み

cat package.json

Step 3: 引数の解析と対象決定

引数の内容を解析し、対象ライブラリを決定:

パターン	例	処理
バージョン指定	`react@19`	指定バージョンへ更新
ランタイム指定	`Node.js 22系`	互換ライブラリも含めて計画
ライブラリ置換	`recoilをjotaiに置き換え`	移行計画を作成
範囲指定	`可能な範囲で最新化`	破壊的変更が少ないものから
制約条件	`React 18のまま`	指定ライブラリは現状維持
セキュリティ優先	`脆弱性のみ`	audit結果から絞り込み

引数がない場合の優先順位:

セキュリティ脆弱性があるパッケージ
EOLまたはサポート終了のパッケージ
メジャーバージョンアップが可能なパッケージ
マイナー/パッチアップデートがあるパッケージ

Step 4: ライブラリグループの構成

依存関係が自明なライブラリをグループ化（サブエージェントへの呼び出し回数を削減）:

グループ	メインライブラリ	関連ライブラリ
React コア	react	react-dom, @types/react, @types/react-dom
Next.js	next	react, react-dom, eslint-config-next
Vue コア	vue	@vue/compiler-sfc, vue-router, pinia
ESLint	eslint	eslint-config-, eslint-plugin-
TypeScript	typescript	@types/*, ts-node

グルーピング結果の作成

グループ1: Next.js
  - next: 14.0.4 → 15.0.0
  - react: 18.2.0 → 19.0.0
  - react-dom: 18.2.0 → 19.0.0
  - eslint-config-next: 14.0.4 → 15.0.0

グループ2: ESLint
  - eslint: 8.x → 9.x
  - eslint-plugin-react: x.x → y.y
  ...

単体: lodash 4.17.20 → 4.17.21

Step 5: サブエージェント呼び出し（library-update-analyzer）

各グループに対して1回ずつサブエージェントを呼び出す。 収集済みの情報を渡し、調査のみを依頼する。

呼び出しフォーマット

調査対象:
  メインライブラリ: next
  現在バージョン: 14.0.4
  目標バージョン: 15.0.0
  関連ライブラリ: [react@18.2.0→19.0.0, react-dom@18.2.0→19.0.0, eslint-config-next@14.0.4→15.0.0]

プロジェクト情報:
  パッケージマネージャー: pnpm
  Node.jsバージョン: 20.10.0
  ソースディレクトリ: src/, app/
  テストディレクトリ: __tests__/, *.test.tsx

サブエージェントからの戻り値（JSON）

{
  "library": "next",
  "breakingChanges": [...],
  "deprecations": [...],
  "packagesToRemove": [...],
  "packagesToUpdate": [...],
  "testCoverage": {...},
  "summary": {
    "affectedFileCount": 5,
    "breakingChangeCount": 3,
    "estimatedEffort": "medium",
    "riskLevel": "medium"
  },
  "references": {...}
}

並列呼び出しの判断

グループ間に依存関係がない場合: 並列で呼び出し可能
依存関係がある場合（例: Next.js → React）: 順次呼び出し

Step 6: アップグレード戦略の決定

サブエージェントの結果を集約し、戦略を決定:

一括アップグレード（すべて満たす場合）

破壊的変更が合計3件以下
影響ファイルが合計10件以下
依存関係の競合がない

段階的アップグレード（1つでも該当する場合は必須）

🔴 破壊的変更が多い（4件以上）
🔴 影響ファイルが多い（11件以上）
🔴 複数のメジャーバージョンアップを含む
🔴 ライブラリの置換を含む
🔴 Node.jsのアップグレードを含む

段階的アップグレードの計画

Phase 0: 事前準備 - アップデート前の品質担保
- 破壊的変更が入る箇所をリストアップ
- 該当箇所のテストを追加（変更前の挙動を保証）
- lint/testが通ることを確認（ベースライン確立）
Phase 1: ランタイム・言語基盤 - Node.js, TypeScript
Phase 2: 品質担保ツール - ESLint, Prettier, Jest/Vitest, Testing Library等
Phase 3: 主要フレームワーク - Next.js, React, Vue等
Phase 4: UIライブラリ - MUI, Chakra, Tailwind, Radix等
Phase 5: 状態管理・データ取得・その他 - TanStack Query, Jotai, Zustand, SWR, ユーティリティ等
Phase 6: ライブラリ置換 - 別ライブラリへの移行（該当する場合）

重要: 各Phaseの完了時に必ずlint/testを実行し、問題がないことを確認してから次のPhaseに進む

バージョンアップの粒度

以下の場合は、1バージョンずつ段階的にアップデートし、各バージョンで挙動を確認する:

ケース	例	対応
メジャーバージョンが2つ以上離れている	React 16 → 18	16 → 17 → 18 と順次アップ
マイナーバージョンに破壊的変更がある	Next.js 14.1 → 14.2 (App Router変更等)	1マイナーずつ確認
非推奨警告が大量に出ている	警告を解消してから次へ	警告対応 → アップデート

# 悪い例: 一気にアップデート
react: 16.8.0 → 19.0.0  ❌

# 良い例: 段階的にアップデート
react: 16.8.0 → 17.0.0 (確認) → 18.0.0 (確認) → 19.0.0 (確認)  ✅

複数サイクルでのアップグレード

複数ライブラリで段階的アップデートが必要な場合、Phase 1〜6を複数サイクル繰り返す:

例: Node.js 20系、React 17系、TanStack Query 3系 を最新化

■ サイクル1（1メジャーずつ上げる）
  Phase 1: Node.js 20 → 22
  Phase 2: ESLint等を互換バージョンへ
  Phase 3: React 17 → 18
  Phase 4: UIライブラリを互換バージョンへ
  Phase 5: TanStack Query 3 → 4
  → lint/test確認 ✅

■ サイクル2（さらに1メジャー上げる）
  Phase 1: Node.js 22 → 24
  Phase 2: ESLint等を互換バージョンへ
  Phase 3: React 18 → 19
  Phase 4: UIライブラリを互換バージョンへ
  Phase 5: TanStack Query 4 → 5
  → lint/test確認 ✅

サイクルの組み方:

全Phase（1〜6）を繰り返す: ランタイムも含めて段階的に上げる場合
Phase 3〜6のみ繰り返す: ランタイム・lint系は先に最新化済みの場合

アップグレード順序の考え方

順序	カテゴリ	理由
1	ランタイム・言語基盤	他のすべてのライブラリの動作基盤となるため最初に
2	品質担保ツール	以降のアップデートで問題を正しく検知するため
3	主要フレームワーク	アプリケーションの中核。周辺ライブラリより先に安定させる
4	UIライブラリ	フレームワークのバージョンに依存することが多いため、フレームワーク更新後に
5	状態管理・データ取得・その他	UIと連携するため、UIライブラリ更新後に。影響範囲も限定的
6	ライブラリ置換	既存コードの大幅な変更を伴うため最後に

Step 7: 計画書の作成

サブエージェントの結果を統合し、以下のフォーマットでMDファイルを出力:

# EOL対応計画

作成日: {日付}
対象プロジェクト: {プロジェクト名}
パッケージマネージャー: {npm/yarn/pnpm/bun}

## 概要

| 項目 | 内容 |
|------|------|
| 対象ライブラリ数 | X件 |
| セキュリティ脆弱性 | X件 |
| リスクレベル | {低/中/高} |
| 推奨戦略 | {一括/段階的} |

## セキュリティ監査結果

| パッケージ | 脆弱性レベル | 説明 | 修正バージョン |
|-----------|------------|------|--------------|

## ライブラリグループ

| グループ | メインライブラリ | 関連ライブラリ | 一括アップグレード |
|---------|----------------|---------------|------------------|

## 削除対象パッケージ

| パッケージ | 理由 | 削除タイミング |
|-----------|------|--------------|

## アップグレード戦略

### 推奨アプローチ: {一括/段階的}

{選択理由}

## 段階的アップグレード計画

### Phase 0: 事前準備

**目的**: 破壊的変更が入る箇所を特定し、変更前の挙動を保証するテストを追加する

**破壊的変更の影響箇所**:
| ファイル | 影響を受ける変更 | 現在のテスト有無 |
|---------|----------------|----------------|

**テスト追加が必要な箇所**:
| ファイル | 追加すべきテスト | 理由 |
|---------|----------------|------|

**確認項目**:
- [ ] 破壊的変更の影響箇所をすべてリストアップ
- [ ] 影響箇所のテストを追加（変更前の挙動を保証）
- [ ] `{pm} run lint:fix` 成功
- [ ] `{pm} run test` 成功
- [ ] 現状のテストカバレッジを記録

⚠️ **Phase 0が完了するまで、ライブラリのアップデートは行わない**
💡 テストがあることで、アップデート後に挙動が変わった箇所を検知できる

**lint:fixコマンドがない場合は追加**:
```json
{
  "scripts": {
    "lint:fix": "eslint src --ext .js,.jsx,.ts,.tsx --fix && tsc --noEmit"
  }
}

Phase 1: {フェーズ名}

対象:

{ライブラリ}: {現在} → {目標}

破壊的変更への対応:

変更内容	影響ファイル	対応方法

アップデートコマンド:

{コマンド}

確認項目:

{pm} run lint:fix 成功
{pm} run test 成功
ビルド成功
動作確認

Phase 2: ...

ライブラリ置換計画

（ライブラリ置換が指定された場合のみ）

{旧ライブラリ} → {新ライブラリ}

API対応表

旧API	新API	備考

移行手順

新ライブラリをインストール
コード修正
テスト更新
旧ライブラリを削除

リスクと対策

リスク	発生確率	影響度	対策

ロールバック計画

各フェーズでの問題発生時:

{手順}

参考リンク


---

## 注意事項

- **情報収集はこのコマンド内で完結**: サブエージェントにはプロジェクト情報を渡す
- **サブエージェントはグループ単位で呼び出し**: 個別ライブラリごとに呼び出さない
- **並列呼び出しを活用**: 依存関係がないグループは並列で調査
- **破壊的変更が多い場合は必ず段階的アップグレード**
- **アップグレードの実行順序を厳守**:
  1. Phase 0で不足テストを追加し、lint/testが通ることを確認（ベースライン確立）
  2. 各Phaseでアップデート実施後、必ずlint/testを実行して問題がないことを確認
  3. 問題があれば解決してから次のPhaseに進む
- **Node.jsのアップデートにはプロジェクトのバージョン管理ツールを使用**:
  - プロジェクトに既存のバージョン管理ツール（nvm, nodenv, asdf等）があればそれを使用
  - バージョン管理ツールが特定できない場合は、**ユーザーに確認する**（デフォルト推奨: [mise](https://mise.jdx.dev/getting-started.html)）
  - 計画書にはバージョン管理ツールを使ったアップデート手順を記載すること