ln-711-npm-upgrader

パス： ファイルパス（shared/、references/、../ln-*）は skills リポジトリのルートからの相対パスです。CWD に見つからない場合は、この SKILL.md ディレクトリを探し、1 つ上の階層をリポジトリのルートとしてください。

ln-711-npm-upgrader

タイプ： L3 ワーカー カテゴリ： 7XX プロジェクトのブートストラップ 親： ln-710-dependency-upgrader

npm、yarn、または pnpm を使用して Node.js の依存関係をアップグレードし、破壊的変更の自動検出と移行を行います。

---

概要

項目	詳細
入力	プロジェクトパス、パッケージマネージャーの種類
出力	更新された package.json、ロックファイル、移行レポート
サポート対象	npm、yarn（classic および berry）、pnpm

---

ワークフロー

視覚的なワークフローについては、diagram.html を参照してください。

フェーズ： 事前確認 → 分析 → セキュリティ監査 → 古いバージョンの確認 → 破壊的変更の特定 → アップグレードの適用 → 移行の適用 → ビルドの検証 → レポート

---

フェーズ 0：事前確認

確認項目	必須	見つからない場合の対応
ロックファイル（package-lock.json、yarn.lock、pnpm-lock.yaml）	はい	警告し、最初に npm install を実行
package.json	はい	アップグレードをブロック

ワーカーは、コーディネーター（ln-710）がすでに Git の状態を確認し、バックアップを作成していることを前提とします。

---

フェーズ 1：依存関係の分析

package.json を読み込み、アップグレードの優先度に応じて依存関係を分類します。

依存関係のカテゴリ

カテゴリ	例	優先度
フレームワーク	react、vue、angular	2（ピア依存関係の後）
ビルド	vite、webpack、esbuild	3
UI	@radix-ui/*、tailwindcss	4
状態管理	@tanstack/react-query、zustand	5
ユーティリティ	lodash、date-fns	6
開発	eslint、prettier、typescript	7
ピア	@types/*、typescript	1（最初）

---

フェーズ 2：セキュリティ監査

コマンド

マネージャー	コマンド
npm	npm audit --audit-level=high
yarn	yarn audit --level high
pnpm	pnpm audit --audit-level high

対応

重大度	対応
重大	アップグレードをブロックして報告
高	警告して続行
中／低	ログに記録のみ

---

フェーズ 3：古いバージョンの確認

コマンド

マネージャー	コマンド
npm	npm outdated --json
yarn	yarn outdated --json
pnpm	pnpm outdated --json

---

フェーズ 4：破壊的変更の特定

検出

必ず読んでください： 全パターンについて、breaking_changes_patterns.md を読み込んでください。

1. 現在のメジャーバージョンと最新のメジャーバージョンを比較します
2. 既知のパターンについて breaking_changes_patterns.md を確認します
3. Context7/Ref に移行ガイドを問い合わせます

よくある破壊的変更

パッケージ	破壊的変更のあるバージョン	主な変更点
react	18 → 19	JSX Transform、prop としての ref
vite	5 → 6	ESM のみ、Node 18 以上
eslint	8 → 9	Flat config が必須
tailwindcss	3 → 4	CSS ベースの設定
typescript	5.4 → 5.5 以上	より厳密な型推論

---

フェーズ 5：アップグレードの適用

アップグレードの順序

1. ピア依存関係（TypeScript、@types/*）
2. フレームワークパッケージ（React、Vue コア）
3. ビルドツール（Vite、webpack）
4. UI ライブラリ（フレームワークの後）
5. ユーティリティ（lodash、date-fns）
6. 開発用依存関係（テスト、リンティング）

コマンド

マネージャー	コマンド
npm	npm install <package>@latest --save
yarn	yarn add <package>@latest
pnpm	pnpm add <package>@latest

ピア依存関係の競合

状況	解決方法
ERESOLVE エラー	npm install --legacy-peer-deps
それでも失敗する場合	npm install --force（最終手段）

---

移行検索用 MCP ツール

優先順位（フォールバック戦略）

優先度	ツール	使用する状況
1	mcp__context7__query-docs	ライブラリのドキュメントを調べる最初の選択肢
2	mcp__Ref__ref_search_documentation	公式ドキュメントと GitHub
3	WebSearch	最新情報、コミュニティの解決策

Context7 の使用方法

手順	ツール	パラメーター
1. ライブラリを検索	mcp__context7__resolve-library-id	libraryName: "react", query: "migration guide"
2. ドキュメントを検索	mcp__context7__query-docs	libraryId: "/facebook/react", query: "react 18 to 19 migration"

MCP Ref の使用方法

操作	ツール	クエリの例
検索	mcp__Ref__ref_search_documentation	"react 19 migration guide breaking changes"
読み取り	mcp__Ref__ref_read_url	検索結果の URL

WebSearch によるフォールバック

Context7／Ref で結果が得られない場合に使用します：

• "<package> <version> breaking changes migration {current_year}"
• "<package> <error message> fix stackoverflow"

---

フェーズ 6：移行を適用する

プロセス

1. MCP ツール（上記のセクションを参照）を使用して移行ガイドを検索します
2. Edit ツールを使用して自動コード変換を適用します
3. 手動での移行手順をユーザー向けに記録します

ハードコードされた移行は適用しないでください。必ず MCP ツールで最新のガイドを取得してください。

---

フェーズ 7：ビルドを検証する

コマンド

チェック	コマンド
TypeScript	npm run check または npx tsc --noEmit
ビルド	npm run build
テスト	npm test（利用可能な場合）

失敗した場合

1. エラーから失敗しているパッケージを特定します
2. Context7／Ref で修正方法を検索します
3. 解決できない場合は、パッケージをロールバックし、ほかのパッケージの更新を続けます

---

フェーズ 8：結果を報告する

レポートのスキーマ

フィールド	説明
project	プロジェクトのパス
packageManager	npm、yarn、または pnpm
duration	合計時間
upgrades.major[]	適用した破壊的変更
upgrades.minor[]	機能の更新
upgrades.patch[]	バグ修正
migrations[]	適用した移行
skipped[]	すでに最新
buildVerification	PASSED または FAILED
warnings[]	処理を妨げない問題

---

設定

Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Breaking changes
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true  # Use Context7/Ref

  # Security
  auditLevel: high            # none | low | moderate | high | critical
  minimumReleaseAge: 14       # days

  # Peer dependencies
  legacyPeerDeps: false
  force: false

  # Verification
  runBuild: true
  runTests: false
  runTypeCheck: true

  # Rollback
  createBackup: true
  rollbackOnFailure: true

---

エラー処理

エラー	原因	解決策
ERESOLVE	Peer dep の競合	--legacy-peer-deps
ENOENT	ロックファイルが見つからない	まず npm install を実行
ビルド失敗	破壊的変更	Context7 を使用して移行を適用
型エラー	バージョンの不一致	@types/* を更新

ロールバック

git から package.json とロックファイルを復元し、その後クリーンインストールを実行して以前の状態に戻します。

---

参考資料

• breaking_changes_patterns.md
• npm_peer_resolution.md

---

完了の定義

• ロックファイルと package.json が存在することを確認済み
• 依存関係を分類し、優先順位を設定済み（Peer dep を最優先）
• セキュリティ監査を完了済み（重大な問題がある場合は更新をブロック）
• npm/yarn/pnpm outdated で古いパッケージを特定済み
• breaking_changes_patterns.md と MCP ツールを使用して破壊的変更を検出済み
• 失敗時にロールバックしながら、優先順位に従って更新を適用済み
• 更新後にビルドと型チェックが成功
• major／minor／patch の件数、移行、ビルド状況を含むレポートを返却済み

---

バージョン： 1.1.0 最終更新日： 2026-01-10