Claude Code の Skills でライブラリアップデートの手順を体系化する

---
name: library-update
description: >
  プロジェクトの依存ライブラリを安全にアップデートする。モノレポ対応・パッケージマネージャ自動判別・リスクベースのバッチ戦略で検証を実施する。
  ライブラリの更新、依存関係のアップデート、パッケージのバージョンアップ、セキュリティ脆弱性の修正、
  pnpm update、yarn upgrade などのタスクで使用する。
disable-model-invocation: true
argument-hint: "[パッケージ名（省略時は全パッケージ対象）]"
---

# ライブラリアップデート

既存機能のデグレーションを発生させずに、依存ライブラリを安全にアップデートする。
引数でパッケージ名が指定された場合はそのパッケージのみ、省略時は全パッケージを対象とする。

「ライブラリを更新して」「パッケージをアップデートして」「依存関係を最新にして」「セキュリティ修正をして」といったリクエストにもこのスキルを使用する。

## ユーザーへのヒアリング形式

各 Phase でユーザーに確認・承認を求める際は、**番号付き選択肢**を提示して簡潔に回答できるようにする。

```
以下のいずれかを番号で選択してください:

1. この内容で進める
2. 一部変更して進める（変更内容を教えてください）
3. 全て見送る
```

**ヒアリングのルール:**

- 選択肢は番号（1, 2, 3...）で提示し、ユーザーが番号だけで回答できるようにする
- デフォルト推奨がある場合は「（推奨）」を付記する
- 複数パッケージの選択が必要な場合は、パッケージ名の横に番号を振る
- Yes/No の確認も「1: はい / 2: いいえ」の形式にする

## リファレンスファイル

以下のリファレンスファイルにサブエージェント用プロンプトテンプレートとレポート雛形を格納している。該当フェーズで必要に応じて読み込むこと。

| ファイル                             | 用途                                               | 読み込みタイミング                       |
| ------------------------------------ | -------------------------------------------------- | ---------------------------------------- |
| `references/investigation-prompt.md` | 事前調査サブエージェント用プロンプト               | Phase 2 でサブエージェントを起動する前   |
| `references/update-prompt.md`        | 高リスクパッケージ更新サブエージェント用プロンプト | Phase 4.3 でサブエージェントを起動する前 |
| `references/report-template.md`      | レポート出力の詳細テンプレート                     | Phase 7 でレポートを生成する前           |

## コンテキスト効率化の方針

パッケージ数が多い場合、全てを逐次処理するとコンテキストが溢れる。以下の戦略で効率と安全性を両立する:

- **事前調査**: Agent ツールでサブエージェントに委譲し、複数パッケージを並列調査する
- **リスク分類**: 調査結果からパッチ/マイナー（低リスク）とメジャー（高リスク）に分類する
- **バッチ実行**: 低リスクはまとめてアップデートし、高リスクのみ個別にアップデートする
- **個別更新の委譲**: 高リスクパッケージの更新は Agent ツールでサブエージェントに委譲し、メインコンテキストにはサマリーのみ返す

## Phase 0: 作業ブランチの準備

アップデート作業を開始する前に、クリーンな状態で作業ブランチを作成する。

### 0.1 作業ディレクトリの状態確認

```bash
# リモートの最新状態を取得（まだ pull しない）
git fetch origin

# 現在のブランチと未コミットの変更を確認
git status

# ローカル main がリモートより遅れていないか確認
git log HEAD..origin/main --oneline
```

以下を確認する:

- **未コミットの変更がないこと**（ある場合はユーザーに報告し、stash するか先にコミットするか相談する）
- **デフォルトブランチ（main/master）にいること**（異なるブランチにいる場合は `git checkout main` を提案する）
- **ローカルがリモートと同期していること**（遅れている場合は `git pull origin main` で同期する）

### 0.2 作業ブランチの作成

ブランチ名の候補をユーザーに提示し、**承認を得てから**作成する。

```bash
# ブランチ名の例
git checkout -b feat/library-update-YYYYMMDD
```

ブランチ名の命名規則例:

- `feat/library-update-20260324` — 日付ベース（全パッケージ対象時）
- `feat/update-react-19` — 特定パッケージ対象時
- プロジェクトに既存のブランチ命名規則がある場合はそれに従う

## Phase 1: 事前準備

### 1.1 パッケージマネージャの判別

プロジェクトルートのロックファイルから使用中のパッケージマネージャを判別する。

| ロックファイル           | パッケージマネージャ |
| ------------------------ | -------------------- |
| `pnpm-lock.yaml`         | pnpm                 |
| `package-lock.json`      | npm                  |
| `yarn.lock`              | yarn                 |
| `bun.lockb` / `bun.lock` | bun                  |

CLAUDE.md やプロジェクトルートの設定ファイルに特定のパッケージマネージャに関する制約（例: npm 使用禁止）がある場合は、その制約に従う。

### 1.2 アップデートスクリプトの確認

モノレポ内の各ディレクトリの `package.json` を走査し、アップデート用スクリプトの有無を確認する。

確認すべきスクリプト名の例:

- `update`, `upgrade`, `update:pkgs`, `update:deps`, `ncu`

**ルートの package.json にアップデートスクリプトがある場合**（例: `"update:pkgs": "ncu -u && pnpm -r run update:pkgs"`）、そのスクリプトがモノレポ全体のアップデートを一括で行う構成になっている可能性がある。スクリプトの内容を読み解き、各ワークスペースのスクリプトとの連携を把握した上で、Phase 4 のアップデートコマンドとして活用する。

**重要: アップデートスクリプトが存在しても、Phase 2 の事前調査と Phase 5 の検証は省略しない。** スクリプトはあくまで「バージョンを更新する手段」として Phase 4 で使用し、リスク分類・事前調査・検証のフローは通常通り実施する。

スクリプトが存在しない場合は、パッケージマネージャのコマンドで直接アップデートする。

### 1.3 テスト用 Docker コンテナの確認

テストの実行にローカルの Docker コンテナ（データベース、キャッシュ等）が必要な場合があるため、事前に確認する。

1. **Docker Compose ファイルの検出**: プロジェクト内の `docker-compose.yml` / `docker-compose.yaml` / `compose.yml` を検索する

```bash
find . -maxdepth 3 -name 'docker-compose*.yml' -o -name 'docker-compose*.yaml' -o -name 'compose.yml' -o -name 'compose.yaml' | grep -v node_modules
```

2. **Docker Compose ファイルが見つかった場合**:
   - ファイルの内容を確認し、どのサービスが定義されているか把握する（例: DynamoDB Local, PostgreSQL, Redis 等）
   - CLAUDE.md にテスト環境に関する記述がないか確認する
   - **ユーザーに Docker コンテナの起動を確認する**:

```
テストの実行に以下の Docker サービスが必要です:
  - {サービス一覧}

1. Docker コンテナを起動する（推奨）
2. Docker なしで進める（統合テストはスキップされる可能性あり）
```

3. ユーザーが起動を選択した場合、`docker compose -f <file> up -d` を実行し、サービスが正常に起動したことを確認する

4. **Docker Compose ファイルが見つからない場合**: このステップをスキップする

**注意: テスト時に Docker コンテナが起動していないと、統合テストが `ECONNREFUSED` 等で失敗する。この失敗はアップデート起因ではないが、「全テスト Pass」の検証が不完全になるため、事前に起動しておくことが重要。**

### 1.4 対象パッケージの一覧取得

アップデート可能なパッケージの一覧を取得する。
**CLAUDE.md にパッケージマネージャの制約（例: npm 使用禁止）がある場合は、その制約に従うこと。**

```bash
# pnpm の場合
pnpm outdated --recursive

# npm の場合
npm outdated

# yarn の場合
yarn outdated

# ncu を使う場合（パッケージマネージャの制約に従い、pnpm dlx / npx / yarn dlx を選択）
pnpm dlx npm-check-updates
```

### 1.5 セキュリティ脆弱性の確認

```bash
# pnpm の場合
pnpm audit

# npm の場合
npm audit

# yarn の場合
yarn audit
```

- 脆弱性が報告されているパッケージは **深刻度に応じて優先的にアップデート** する
- 脆弱性の深刻度（critical / high / moderate / low）をレポートに含める
- **優先度の目安**:
  - **critical / high**: 最優先でアップデートする。Phase 4 の実行順序でも先に処理する
  - **moderate**: 他のアップデートと合わせて対応する。パッチ/マイナー更新で解消可能であれば積極的に対応する
  - **low**: パッチ/マイナー更新で安全に解消可能であれば対応する。メジャー更新が必要な場合は見送りも許容する
- audit 結果のパッケージ名と Phase 1.4 のアップデート対象を突合し、脆弱性情報を Phase 2 の調査に引き継ぐ

### 1.6 アップデートスコープの決定

Phase 1.4 と 1.5 の結果を元に、アップデートを **2 段階** に分けて実施する。

#### 第 1 段階（優先対応）

以下は Phase 2 の調査対象に自動的に含める:

1. **脆弱性対応（critical / high）**: 深刻度が critical または high の脆弱性を解消するために必要なアップデート（**パッチ/マイナー/メジャー問わず**）
   - **メジャー更新が必要な場合**: 破壊的変更がある旨をユーザーに説明し、実施の承認を得てから進める（ただし critical/high の解消は原則必須）
2. **低リスク更新（パッチ / マイナー）**: 破壊的変更を含まない通常のパッチ・マイナー更新

第 1 段階の対象をユーザーに提示し、番号付き選択肢で承認を得る:

```
■ 第1段階（優先対応）の対象:
  - 脆弱性対応（critical/high）: X パッケージ
    ⚠ うちメジャー更新が必要: Y パッケージ（破壊的変更の概要を記載）
  - 低リスク更新（patch/minor）: Z パッケージ

以下のいずれかを番号で選択してください:
1. この内容で Phase 2（事前調査）に進む（推奨）
2. 一部変更して進める（変更内容を教えてください）
3. 中止する
```

#### 第 2 段階（第 1 段階完了後にユーザーにヒアリング）

第 1 段階の Phase 2〜5 が完了し、ビルド・テスト・audit の結果を確認した後に、以下について改めてユーザーに方針を確認する:

3. **メジャー更新（脆弱性に関連しないもの）**: 対象パッケージの一覧を提示し、全て見送り / 一部選択 / 全て含めるのいずれかを確認する
4. **残存脆弱性（moderate / low）**: 第 1 段階で解消されなかった moderate/low の脆弱性について、追加対応するかどうかを確認する
   - パッチ/マイナーで解消可能なものは「対応推奨」として提案する
   - メジャー更新が必要なものは破壊的変更の概要を添えて提示する

```
■ 第1段階の結果:
  - アップデート済み: X パッケージ
  - 残存脆弱性: Y 件（moderate: A, low: B）

■ 残存脆弱性（moderate/low）の追加対応:
  - パッチ/マイナーで解消可能: A パッケージ（推奨）
  - メジャー更新が必要: B パッケージ（破壊的変更の概要を記載）

  1. 全て対応する
  2. パッチ/マイナーのみ対応する（推奨）
  3. 全て見送る

■ メジャー更新（脆弱性なし）: W パッケージ
  （パッケージ一覧を番号付きで列挙）

  1. 全て見送る
  2. 一部選択する（対象の番号を教えてください）
  3. 全て含める
```

第 2 段階の対象が確定したら、その分について Phase 2〜5 を再度実施する。

## Phase 2: 事前調査（並列実行）

**Phase 1.6 で確定した第 1 段階（または第 2 段階）のスコープ内のパッケージのみを調査対象とする。**
対象パッケージごとに以下の情報を収集する。
**Agent ツール（`subagent_type: Explore`）を使い、複数パッケージの調査をサブエージェントで並列実行する。**
各サブエージェントには以下の調査を依頼し、結果のサマリーを返させる。

### サブエージェントの並列制御

- **同時起動数は最大 5 つ** に制限する。対象パッケージが 6 つ以上の場合は、5 つずつバッチで実行する
- **`@types/*` パッケージ群**など、関連性の高いパッケージは 1 つのサブエージェントにまとめて調査させる
- 同一スコープのパッケージ（例: `@aws-sdk/*`）も可能な限りグルーピングする

### リポジトリ情報の取得

サブエージェントに `gh` コマンドを使わせる場合、事前にパッケージのリポジトリ情報を取得して渡す必要がある。

```bash
# Phase 1.1 で判別したパッケージマネージャに応じて選択
pnpm view <package_name> repository.url --json
npm view <package_name> repository.url --json
yarn info <package_name> repository.url
```

取得した URL から `owner/repo` を抽出し、サブエージェントへのプロンプトに含める。

### サブエージェントへの調査依頼内容

パッケージ（またはグループ）ごとに 1 つの Agent サブエージェントを起動し、以下を調査させる:

1. **CHANGELOG・リリースノートの確認**

   - GitHub Releases または CHANGELOG.md から、現行バージョン → 最新バージョンまでの変更内容を把握
   - 破壊的変更（Breaking Changes）の有無を特に注視

2. **GitHub Issues・既知の問題の確認**

   - アップデート対象バージョンに未解決の互換性問題がないか確認

3. **非推奨（deprecated）チェック**

   - アップデート先バージョンが deprecated でないか確認
   - deprecated の場合は代替パッケージ情報も収集

4. **マイグレーションガイドの調査（メジャー更新の場合）**

   - WebSearch で公式アップグレードガイド・マイグレーションガイドを検索する（公式ブログやドキュメントサイトも対象）
   - 見つかった場合は WebFetch で全文取得し、破壊的変更・codemod の有無・セキュリティ注意事項を抽出する
   - ガイドが見つからない場合は「なし」と報告する（Phase 4.3 で型定義ベースの調査に切り替える）

5. **リスク分類の提案**
   - 破壊的変更なし & パッチ/マイナー → **低リスク**（バッチ更新可能）
   - 破壊的変更あり or メジャー更新 → **高リスク**（個別更新が必要）
   - deprecated or 重大な既知問題 → **見送り**

```bash
# 調査で使用する gh コマンド（読み取り専用のみ）
gh release list --repo <owner>/<repo> --limit 10
gh release view <tag> --repo <owner>/<repo>
gh issue list --repo <owner>/<repo> --label bug --state open --limit 10
```

### gh コマンドの使用制約

- 情報収集のために `gh` コマンドを読み取り専用で使用してよい
- **Issue・PR の作成・編集・削除など、リポジトリに変更を加える操作は禁止**

### gh コマンドが使えない場合のフォールバック

`gh` が未インストールまたは未認証の場合、以下の代替手段で調査する:

1. **`<pm> view <pkg> --json`**（pnpm/npm/yarn）でパッケージのメタデータ（バージョン、deprecated 状態、リポジトリ URL）を取得する
2. **WebFetch** で GitHub Releases ページや CHANGELOG.md を取得する
3. **WebSearch** でパッケージ名 + "breaking changes" / "migration guide" を検索する

### 調査結果のまとめとユーザー確認

全サブエージェントの調査結果を集約し、以下の分類表をユーザーに提示する:

| パッケージ名 | 現行  | 更新先 | 種別  | リスク | 脆弱性   | 備考                              |
| ------------ | ----- | ------ | ----- | ------ | -------- | --------------------------------- |
| pkg-a        | 1.0.0 | 1.0.5  | patch | 低     | critical | 脆弱性修正を含む（最優先）        |
| pkg-b        | 2.1.0 | 2.3.0  | minor | 低     | -        | 新 API 追加のみ                   |
| pkg-c        | 3.0.0 | 4.0.0  | major | 高     | high     | Breaking Changes あり・脆弱性あり |
| pkg-d        | 1.2.0 | 1.3.0  | minor | 見送り | -        | deprecated                        |

ユーザーの確認・承認を得てから Phase 3 に進む。

## Phase 3: アップデート対象バージョンの判断

最新バージョンが常に最適とは限らない。以下を考慮して適切なバージョンを選択する:

- アップデート対象パッケージの依存先が、当該バージョンに追従できているか
- 事前調査で確認した既知の問題・deprecated 状態・脆弱性情報
- 依存グラフ全体の整合性が保たれるか
- モノレポ内の他ワークスペースで同一パッケージを使用している場合、バージョンを揃えられるか

## Phase 4: アップデート実行

### 4.1 実行順序

以下の優先度で実行する:

1. **セキュリティ脆弱性のあるパッケージを最優先** にする（critical > high > moderate > low）
2. 同一優先度内では、依存関係の**上流（共通ライブラリ・ユーティリティ）から下流（アプリケーション層）**の順に実行する
3. アップデートスクリプトが定義されている場合は、そのスクリプトの仕組みに従う

### 4.2 低リスクパッケージ（バッチ更新）

破壊的変更がないパッチ・マイナー更新はまとめてアップデートする。

1. 低リスクパッケージを一括でアップデートする
2. ビルド・型チェック・lint を実行する
3. 全テストを実行する
4. 問題があれば、以下の手順で原因パッケージを切り分ける:
   1. バッチ更新を全てロールバックする（`git restore` で変更ファイルを個別に復元し、`install` を再実行）
   2. バッチを半分に分割し、前半のみアップデートして検証する（二分探索）
   3. 問題のある半分をさらに分割し、原因パッケージを特定する
   4. 特定できた問題パッケージを高リスク扱い（Phase 4.3）に回し、残りの低リスクパッケージはバッチ更新を再実行する

### 4.2.1 低リスクバッチ成功後の中間コミット

低リスクバッチの検証（ビルド・型チェック・lint・全テスト）が全て Pass したら、**Phase 4.3 に進む前にユーザーに変更内容を提示し、承認を得てから中間コミットを作成する。**

1. `git diff` で変更されたファイルの一覧と差分サマリーをユーザーに提示する
2. ユーザーの承認を得てから `git add` → `git commit` を実行する
3. コミットメッセージ例: `chore: update low-risk packages (batch)`

- これにより、高リスク更新でロールバックが発生しても低リスクバッチの変更が保護される
- **注意: このコミットはローカルのみで、push は行わない**

### 4.3 高リスクパッケージ（個別更新・サブエージェント委譲）

メジャー更新や破壊的変更を含むパッケージは、**Agent ツール（`subagent_type: general-purpose`）でサブエージェントに委譲して個別にアップデートする。** メインコンテキストの消費を抑えるため、各サブエージェントには以下の一連の作業を任せ、結果サマリーのみを返させる。

#### 並列制御

- 高リスクパッケージのサブエージェントは**同時に 1 つずつ順次実行する**（ファイル編集を伴うため、並列実行するとコンフリクトが発生する）
- ただし、互いに依存関係がなく、影響するワークスペースが完全に異なる場合に限り、最大 2 つまで並列実行してよい

#### `@types/*` と本体パッケージの連動

- `@types/express` と `express` のように、型定義パッケージ（`@types/*`）は対応する本体パッケージと**同一のサブエージェントでまとめて更新する**
- 型定義のバージョンは本体パッケージのメジャー・マイナーバージョンに合わせる

#### 中間コミットによるセーブポイント

- 各高リスクパッケージの更新サブエージェントが成功を返したら、**メインエージェントがユーザーに変更内容を提示し、承認を得てから中間コミットを作成する**（サブエージェントはコミットしない）
  1. サブエージェントの結果サマリー（改修内容・テスト結果）をユーザーに提示する
  2. `git diff` で変更差分をユーザーに見せる
  3. ユーザーの承認を得てから `git add` → `git commit` を実行する
  4. **注意: このコミットはローカルのみで、push は行わない**
- コミットメッセージ例: `chore: update {package_name} from {old} to {new}`
- これにより、後続のパッケージでロールバックが必要になった場合に安全な復帰点として機能する
- **全パッケージの更新完了後、Phase 7 のレポート出力前に中間コミットを squash するかどうかをユーザーに確認する**

サブエージェントへの指示内容:

1. **マイグレーションガイドの調査と理解**
   - 事前調査で見つかったガイド URL を WebFetch で全文取得し、破壊的変更・推奨対応・codemod の有無・セキュリティ注意事項を整理する
   - ガイドが見つからなかった場合は WebSearch で検索し、それでもなければ Step 3 の型定義ベース調査に切り替える
   - **判断に迷う場合（複数の移行パス、プロジェクト方針に依存する選択等）は改修を進めず、相談事項として報告する**
2. パッケージをアップデートする
3. **型定義・エクスポート・API シグネチャを確認**する
   - ガイドがある場合: ガイドの破壊的変更一覧を現コードベースと照合する
   - **ガイドがない場合: `node_modules/<pkg>` 配下の型定義ファイル（`.d.ts`）を読み、エクスポートされた関数・型のシグネチャ変更を特定し、現コードの使用箇所と突合する**
4. **codemod が利用可能な場合は先に実行**し、残りの手動改修箇所を特定する
5. 現行コードベースと照合し、**破壊的変更の影響箇所を特定・改修**する（既存機能のデグレーション防止を最優先）
6. ビルド・型チェック・lint を実行し、エラーがないことを確認する
7. 全テストを実行し、Pass することを確認する
8. テスト失敗時は「原因調査 → 実装コード改修 → 再実行」を最大 3 回試行する
9. **テストコードの変更が必要と判断した場合は、変更せずにその旨と理由を返す**（ユーザー承認が必要なため）
10. 3 回試行で解決しない場合はロールバックし、その旨と理由を返す
11. 結果サマリー（成功/失敗/ロールバック、改修内容、codemod 使用有無、残課題・相談事項）を返す

マイナー・パッチであっても、型情報や関数の引数・戻り値が変更される可能性がある。メジャーアップデートと同等の注意を払うこと。

### 4.4 サブエージェントからの結果確認

各サブエージェントの結果を確認し、以下の場合はユーザーに相談する:

- テストコードの変更が必要と報告された場合
- 改修の影響範囲が広いと報告された場合
- ロールバックされた場合
- **マイグレーションガイドが複数の移行パスを提示し、プロジェクト方針によって最適解が変わると報告された場合**
- **セキュリティ上の理由で推奨パターンが変更されたが、対応方針の判断が必要と報告された場合**
- **マイグレーションガイドが存在せず、型定義ベースで調査したが変更の意図が不明な箇所がある場合**

## Phase 5: 検証（最終確認）

全パッケージのアップデート完了後、プロジェクト全体で最終検証を行う。

### 5.1 ロックファイルの整合性

- ロックファイルが正しく更新されていることを確認する
- **ロックファイルを手動編集しない。** パッケージマネージャ経由で更新する
- `install` コマンドを再実行し、依存解決にエラーがないことを検証する

### 5.2 ピア依存関係（peerDependencies）の確認

- peerDependencies の警告・エラーが発生していないか確認する
- 警告が発生した場合、関連するピア依存パッケージも合わせてアップデートを検討する

### 5.3 ビルド・型チェック・lint

- プロジェクトのビルドコマンドが正常に完了することを確認する
- TypeScript プロジェクトでは型チェック（`tsc --noEmit` 等）がエラーなく通ることを確認する
- lint が定義されている場合、新たな lint エラーが発生していないことも確認する
- **使用するコマンドは CLAUDE.md に記載されたプロジェクト固有のコマンドを優先する**（例: `pnpm build`, `pnpm lint`, `pnpm test` 等）

### 5.4 ワークスペース間依存の整合性

- モノレポ内の複数の `package.json` で同一パッケージを異なるバージョンで参照していないか確認する
- 共通で使用するパッケージは原則として**ワークスペース全体で同一バージョンに揃える**
- 意図的にバージョンを分けている場合は、ユーザーに確認する

### 5.5 全テストの実行

- 各ワークスペースに定義されている自動テスト（全レベル）がすべて Pass すること

### 5.6 テストコード変更の制約

- **既存のテストコードを独断で変更しない**
- テストコードの変更がやむを得ない場合は、変更の妥当性を示す理由を明示し、**ユーザーに相談・承認を得てから**変更する

### 5.7 セキュリティ監査の最終確認

- `pnpm audit`（または対応するパッケージマネージャのコマンド）を実行し、残存する脆弱性を確認する
- **critical または high の脆弱性が残存している場合**、以下の手順で継続対応する:
  1. 当該脆弱性が今回のアップデート対象パッケージの推移的依存に起因するか確認する
  2. 脆弱性を含むパッケージ自体、またはその親パッケージのマイナー/パッチ更新で解消可能か調査する
  3. 解消可能な場合はアップデートを実施し、Phase 5.1〜5.5 の検証を再実行する
  4. メジャーアップデートが必要で今回の対応範囲を超える場合は、レポートに残存脆弱性として記載し、対応の優先度と推奨アクションを明記する
- **moderate 以下の脆弱性**についても、パッチ/マイナー更新で安全に解消可能な場合は対応する:
  1. 当該パッケージのパッチ/マイナー更新で脆弱性が解消されるか確認する
  2. 解消可能かつ低リスク（破壊的変更なし）であれば、バッチ更新として対応する
  3. メジャー更新が必要、または対応のリスクが高い場合は、レポートに残存脆弱性として記載する
- **脆弱性ゼロを目指す**: 安全に対応可能な脆弱性は深刻度に関わらず積極的に解消し、対応不可能なもののみ残存としてレポートする

## Phase 6: ロールバック方針

以下のいずれかに該当する場合、当該パッケージのアップデートを中止し、元のバージョンに戻す:

- コード改修を **3 回以上試行**してもテストが Pass しない場合
- 改修の影響範囲がアップデート対象パッケージの利用箇所を大きく超える場合
- 破壊的変更の改修にテストコードの変更が不可避と判断される場合

ロールバックした場合、その旨と理由をレポートに記載する。

## Phase 7: レポート出力

全アップデート完了後、`references/report-template.md` のテンプレートに従ってレポートを出力する。

## 制約事項まとめ

| 項目                   | ルール                                                                                                                                                               |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 最優先原則             | 既存機能のデグレーションを起こさない                                                                                                                                 |
| 作業ブランチ           | main から最新状態で作業ブランチを作成してから開始する。ブランチ名はユーザーに確認する                                                                                |
| デフォルトスコープ     | 第 1 段階: 脆弱性対応（critical/high、メジャーでも必須）+ 低リスク（patch/minor）。第 2 段階: 完了後にメジャー更新と残存脆弱性（moderate/low）をユーザーにヒアリング |
| パッケージマネージャ   | プロジェクトに応じて自動判別する                                                                                                                                     |
| アップデートスクリプト | package.json に定義があれば Phase 4 のコマンドとして活用する。Phase 2 の調査と Phase 5 の検証は省略しない                                                            |
| 最新版への更新         | 必須ではない。依存関係・既知問題・deprecated 状態を考慮して判断                                                                                                      |
| 実行戦略               | 低リスクはバッチ、高リスクは個別（サブエージェント委譲）                                                                                                             |
| メジャー更新           | ガイド WebSearch/WebFetch → codemod 確認 → 型定義ベース照合 → コード改修。ガイドがない場合は node_modules の型定義から変更を特定                                     |
| マイナー・パッチ更新   | メジャーと同等の注意を払う                                                                                                                                           |
| ロックファイル         | 手動編集禁止。パッケージマネージャ経由で更新                                                                                                                         |
| overrides              | 原則禁止。推移的依存の脆弱性は親パッケージの更新で解消する。やむを得ない場合はユーザーに相談の上使用する                                                             |
| ビルド・型チェック     | アップデート後にエラーがないことを確認                                                                                                                               |
| ワークスペース間依存   | 同一パッケージは原則同一バージョンに揃える                                                                                                                           |
| テスト                 | 全テスト Pass が必須                                                                                                                                                 |
| Docker コンテナ        | テスト実行前に docker-compose ファイルを検出し、必要なサービスの起動をユーザーに確認する                                                                             |
| テストコード変更       | 原則禁止。変更時はユーザーに相談・承認必須                                                                                                                           |
| git 操作               | `git add` / `git commit` の前にユーザーに変更内容を提示し承認を得る。push は行わない                                                                                 |
| ロールバック           | 3 回試行で未解決、影響範囲過大、テスト変更不可避の場合は中止                                                                                                         |
| gh コマンド            | 読み取り専用のみ許可。編集・削除は禁止                                                                                                                               |
| deprecated パッケージ  | アップデート先として選択しない                                                                                                                                       |
| セキュリティ監査       | 完了後に audit を実行。脆弱性ゼロを目指し、安全に対応可能なものは深刻度に関わらず解消する                                                                            |
| レポート               | アップデート完了後に必ず出力する                                                                                                                                     |

# 事前調査サブエージェント プロンプトテンプレート

このファイルは Phase 2 の事前調査で Agent ツールを使う際のプロンプトテンプレート。
パッケージごとに以下の内容でサブエージェントを起動する。

## テンプレート

```
以下のパッケージについて事前調査を行い、結果をサマリーとして返してください。

## 調査対象
- パッケージ名: {package_name}
- 現行バージョン: {current_version}
- 最新バージョン: {latest_version}
- 更新種別: {patch|minor|major}
- リポジトリ: {owner}/{repo}（パッケージマネージャの view コマンドで取得済み。取得できなかった場合は WebSearch で特定する）
- 既知の脆弱性: {vulnerability_info|なし}（Phase 1.4 の audit 結果から引き継ぎ）

## 調査項目

### 1. CHANGELOG・リリースノートの確認
- GitHub Releases または CHANGELOG.md を確認する
- 現行バージョンから最新バージョンまでの変更内容を把握する
- 破壊的変更（Breaking Changes）の有無を特定する

使用コマンド（読み取り専用）:
  gh release list --repo {owner}/{repo} --limit 20
  gh release view {tag} --repo {owner}/{repo}

### 2. GitHub Issues・既知の問題の確認
- 最新バージョンに関する未解決の互換性問題がないか確認する
- 重大なバグ報告がないか確認する

使用コマンド（読み取り専用）:
  gh issue list --repo {owner}/{repo} --label bug --state open --limit 10
  gh search issues --repo {owner}/{repo} "{latest_version}" --limit 5

### 3. 非推奨（deprecated）チェック
- アップデート先バージョンが deprecated でないか確認する
- deprecated の場合、推奨される代替パッケージ情報を収集する

使用コマンド（プロジェクトのパッケージマネージャに応じて選択。CLAUDE.md に特定パッケージマネージャの使用禁止がある場合はそれに従う）:
  pnpm view {package_name}@{latest_version} deprecated
  npm view {package_name}@{latest_version} deprecated
  yarn info {package_name}@{latest_version}

### 4. マイグレーションガイドの調査（メジャー更新の場合）

以下の手順で公式のアップグレードガイド・マイグレーションガイドを探す:

1. **WebSearch** で `{package_name} v{latest_version} upgrade guide` / `{package_name} v{latest_version} migration guide` を検索する
2. 見つかった場合は **WebFetch** でガイドの全文を取得し、以下を抽出する:
   - 破壊的変更の一覧と対応方法
   - 推奨される移行手順・移行パスの選択肢
   - codemod（自動移行ツール）の提供有無と実行コマンド
   - セキュリティに関する注意事項（非推奨 API がセキュリティ理由で削除された等）
3. ガイドが見つからない場合は「なし」と報告する（Phase 4.3 で型定義ベースの調査に切り替える）

**注意**: ガイドは GitHub Releases だけでなく、公式ブログや公式ドキュメントサイトに掲載されることが多い（例: React のアップグレードガイドは react.dev のブログ記事）。`gh` コマンドだけでは見つからないため、必ず WebSearch を併用する。

## 出力フォーマット

以下の形式でサマリーを返してください:

パッケージ: {package_name}
現行: {current_version} → 更新先: {recommended_version}
更新種別: {patch|minor|major}
リスク: {低|高|見送り}

### 破壊的変更
- （あれば具体的に列挙、なければ「なし」）

### 既知の問題
- （あれば具体的に列挙、なければ「なし」）

### deprecated 状態
- （deprecated でなければ「なし」、deprecated なら代替パッケージ情報）

### マイグレーションガイド
- （あれば URL と主要な移行手順の要約。なければ「なし」）

### codemod の有無
- （公式 codemod があれば実行コマンドと対象範囲。なければ「なし」）

### セキュリティに関する移行注意事項
- （アップグレードガイドやリリースノートにセキュリティ関連の記載があれば要約。なければ「なし」）

### 脆弱性
- （audit で報告されている場合は深刻度と概要、なければ「なし」）

### 推奨アクション
- （「バッチ更新可能」「個別更新推奨」「見送り推奨」のいずれかと理由）
```

## gh コマンドの制約（サブエージェントにも適用）

- 情報収集のための読み取り専用コマンドのみ使用可能
- Issue・PR の作成・編集・削除など、リポジトリに変更を加える操作は禁止

## gh コマンドが使えない場合のフォールバック

`gh` が未インストールまたは未認証の場合、以下の代替手段で調査する:

1. **`<pm> view <pkg> --json`**（pnpm/npm/yarn）でパッケージのメタデータ（バージョン、deprecated 状態、リポジトリ URL）を取得する
2. **WebFetch** で GitHub Releases ページや CHANGELOG.md を取得する
3. **WebSearch** でパッケージ名 + "breaking changes" / "migration guide" を検索する

# 高リスクパッケージ更新サブエージェント プロンプトテンプレート

このファイルは Phase 4.3 の高リスクパッケージ更新で Agent ツールを使う際のプロンプトテンプレート。
パッケージごとに以下の内容でサブエージェントを起動する。

## テンプレート

```
以下のパッケージのアップデートを実施してください。

## アップデート対象
- パッケージ名: {package_name}
- 現行バージョン: {current_version}
- 更新先バージョン: {target_version}
- 更新種別: {patch|minor|major}
- パッケージマネージャ: {package_manager}
- プロジェクトルート: {project_root}

## 事前調査結果
{investigation_summary}

## プロジェクト制約

- **CLAUDE.md を必ず確認し、記載されている制約に従うこと**（例: 特定パッケージマネージャの使用禁止、コードスタイル等）
- 使用するビルド・テスト・lint コマンドは CLAUDE.md に記載されたプロジェクト固有のコマンドを優先する

## 作業手順

### Step 1: マイグレーションガイドの調査と理解

**ガイドが事前調査で見つかっている場合:**

1. 事前調査結果に記載されたマイグレーションガイドの URL を **WebFetch** で全文取得する
2. ガイドの内容を精読し、以下を整理する:
   - 破壊的変更の一覧（削除された API、変更されたデフォルト値、型の変更等）
   - 各破壊的変更の推奨対応方法
   - 移行パスが複数ある場合は、各パスのメリット・デメリットを整理する
   - セキュリティに関する注意事項（非推奨 API がセキュリティ理由で削除された等）
3. **codemod が提供されている場合**は、手動改修の前に codemod の適用を検討する:
   - codemod の対象範囲と限界を確認する
   - codemod 実行後に手動対応が必要な箇所を把握する

**ガイドが見つからなかった場合:**

1. **WebSearch** で `{package_name} v{target_version} breaking changes` / `{package_name} v{target_version} changelog` を検索する
2. それでも十分な情報が得られない場合は、Step 3 の型定義ベースの調査で破壊的変更を特定する（ガイドがないこと自体は作業を中止する理由にならない）

**判断に迷うケース:**

以下の場合は改修を進めず、結果サマリーに記載してメインエージェント経由でユーザーに相談する:
- ガイドが複数の移行パスを提示しており、プロジェクトの方針によって最適解が変わる場合
- セキュリティ上の理由で推奨パターンが変更されたが、既存コードの書き換え範囲が広い場合
- 新旧 API 両方が使えるが、どちらを選ぶべきかプロジェクトコンテキストに依存する場合

### Step 2: アップデート実行
- パッケージをアップデートする:
  {update_command}
- install コマンドを再実行し、依存解決にエラーがないことを検証する

### Step 3: 型定義・API の変更確認

アップデート後のパッケージの型定義・エクスポートを確認し、現行コードとの差分を特定する。

**マイグレーションガイドがある場合:**
- ガイドに記載された破壊的変更を、現行コードベースで使用しているか grep/検索で確認する
- ガイドの対応方法に従って改修箇所を特定する

**マイグレーションガイドがない場合（型定義ベースの調査）:**
1. `node_modules/{package_name}` 配下の型定義ファイル（`.d.ts`）またはエントリポイントを読む
2. パッケージのエクスポートされた関数・クラス・型を確認する
3. 現行コードベースで当該パッケージを import している全箇所を検索する
4. 使用している API が引き続きエクスポートされているか、シグネチャ（引数・戻り値・ジェネリクス）が変更されていないかを照合する
5. 削除・変更された API を使用している箇所を改修対象として特定する

**共通:**
- 既存の機能がデグレーションしないことを最優先とする
- 不明な変更点がある場合は、推測で改修せず、結果サマリーに疑問点として記載する

### Step 4: コード改修
- codemod が利用可能な場合は先に実行し、差分を確認する
- 手動改修は最小限にとどめ、アップデート対象パッケージの利用箇所に限定する
- 改修の各箇所に対して「何を」「なぜ」変更したかを記録する（結果サマリーに含めるため）

### Step 5: ビルド・型チェック・lint
- ビルドコマンドを実行する
- 型チェック（tsc --noEmit 等）を実行する
- lint を実行する
- エラーがあれば改修する

### Step 6: テスト実行
- 全テストを実行する
- 失敗した場合は「原因調査 → 実装コード改修 → 再実行」を行う

## 重要な制約

- **テストコードは変更しない。** テストコードの変更が必要と判断した場合は、変更せずにその旨と理由を結果に含めて返す
- テスト失敗の改修は最大 **3回まで** 試行する。3回で解決しない場合はロールバックする
- 改修の影響範囲がアップデート対象パッケージの利用箇所を大きく超える場合はロールバックする
- ロールバック時は元のバージョンに戻し、ロックファイルも復元する

## ロールバック手順

ロールバックが必要な場合:
1. `git diff` で変更されたファイルを確認し、影響範囲を把握する
2. 改修したソースファイルを `git restore <file>` で個別に元に戻す（他の変更を巻き込まないよう、ファイル単位で指定する）
3. **package.json は `git restore` せず、対象パッケージのバージョンのみを編集で元に戻す**（他のパッケージの変更を巻き込まないため）
4. パッケージマネージャの install を再実行し、ロックファイルを復元する

## 出力フォーマット

以下の形式で結果サマリーを返してください:

パッケージ: {package_name}
結果: {成功|ロールバック}
旧バージョン: {current_version}
新バージョン: {target_version}（ロールバック時は「元に戻した」）

### コード改修内容
- （改修があれば、ファイルパス・改修内容・改修理由を列挙）

### ビルド・型チェック結果
- ビルド: {OK|NG}
- 型チェック: {OK|NG}
- lint: {OK|NG}

### テスト結果
- {OK|NG}（NG の場合は失敗内容）

### テストコード変更の要否
- {不要|要（理由を記載）}

### ロールバック理由（該当時のみ）
- （ロールバックした場合の理由）

### codemod の使用
- {未使用|使用（コマンドと適用結果を記載）}

### 残課題・相談事項
- （ユーザーに確認すべき事項があれば記載）
- （移行パスの選択、セキュリティ関連の判断、プロジェクト方針に依存する判断など）
```

# レポートテンプレート

Phase 7 でアップデート完了後に出力するレポートのテンプレート。
このテンプレートに沿ってレポートを生成する。

## テンプレート

```markdown
# ライブラリアップデートレポート

実施日: {date}
プロジェクト: {project_name}
パッケージマネージャ: {package_manager}

## サマリー

- アップデート済み: {updated_count} パッケージ
- 見送り: {skipped_count} パッケージ
- ロールバック: {rollback_count} パッケージ

## アップデート済みパッケージ

| パッケージ名 | 旧バージョン | 新バージョン | 種別   | 更新方法           | ワークスペース |
| ------------ | ------------ | ------------ | ------ | ------------------ | -------------- |
| {name}       | {old}        | {new}        | {type} | {batch/individual} | {workspace}    |

## アップデート見送りパッケージ

| パッケージ名 | 現バージョン | 最新バージョン | 見送り理由 |
| ------------ | ------------ | -------------- | ---------- |
| {name}       | {current}    | {latest}       | {reason}   |

見送り理由の分類:

- deprecated: パッケージまたはバージョンが非推奨
- known-issue: 既知の互換性問題あり
- rollback: アップデート試行後にロールバック
- dependency-conflict: 依存関係の競合
- user-decision: ユーザー判断により見送り

## ロールバックしたパッケージ

| パッケージ名 | 試行バージョン | ロールバック理由 | 試行回数 |
| ------------ | -------------- | ---------------- | -------- |
| {name}       | {attempted}    | {reason}         | {count}  |

## コード改修の概要

### {package_name} の改修

- **ファイル**: {file_path}:{line_number}
- **改修内容**: {description}
- **改修理由**: {reason}

## テスト結果

| ワークスペース | テスト数 | Pass   | Fail   | 結果        |
| -------------- | -------- | ------ | ------ | ----------- |
| {workspace}    | {total}  | {pass} | {fail} | {Pass/Fail} |

## ビルド・型チェック結果

| ワークスペース | ビルド  | 型チェック | lint    |
| -------------- | ------- | ---------- | ------- |
| {workspace}    | {OK/NG} | {OK/NG}    | {OK/NG} |

## セキュリティ脆弱性

### アップデート前

| パッケージ名 | 脆弱性 | 深刻度                       | 対応状況             |
| ------------ | ------ | ---------------------------- | -------------------- |
| {name}       | {vuln} | {critical/high/moderate/low} | {resolved/remaining} |

### アップデート後

- 残存する脆弱性: {count} 件
- 新たに検出された脆弱性: {count} 件

## ワークスペース間依存の整合性

| パッケージ名 | ワークスペース間で統一 | 備考   |
| ------------ | ---------------------- | ------ |
| {name}       | {Yes/No}               | {note} |

## ユーザーへの相談・確認事項

- {item}
```

Claude Code Skill - ライブラリアップデート対応

* 基本的に、安全に、機能のデグレーションが発生しないように、アップデートを行う
* プロジェクトによって、パッケージマネージャツールが違うので、npm や pnpm
* package.json のスクリプトでライブラリupdateコマンドスクリプトがあればそれを用いてアップデートする
* 概ねモノレポ構成のとなっている、モノレポの各ディレクトリごとに、package.jsonファイルが格納されているので、そちらを確認する
* セマンティックバージョン管理となっている
* メジャーバージョンを上げると破壊的変更が含まれる可能性があるため、CHANGELOGの確認、GitHubのIssueの確認、
  deprecatedの確認をしてからアップデートする
* マイナー・パッチでも型情報や引数・戻り値が変わる可能性がある。メジャーと同等の注意を払う
* テストは全てPassすること
* テストコードは勝手に変更しない。変更が必要な場合は相談する
* 3回試行してダメならロールバック
* gh コマンドは読み取り専用のみ（編集・削除は一切禁止）