Upgrade Strategies

概要

このスキルは、依存関係を安全かつ効率的にアップグレードするための 戦略と手法を提供します。

適切なアップグレード戦略を選択することで、 破壊的変更のリスクを最小化しながら、セキュリティと機能の恩恵を受けられます。

主要な価値:

• セキュリティパッチの迅速な適用
• 新機能へのタイムリーなアクセス
• 技術的負債の蓄積防止

対象ユーザー:

• 依存関係を管理するエージェント（.claude/agents/dep-mgr.md）
• テクニカルリード
• DevOps エンジニア

リソース構造

upgrade-strategies/
├── SKILL.md                                    # 本ファイル（概要とワークフロー）
├── resources/
│   ├── strategy-selection-guide.md             # 戦略選択ガイド
│   ├── tdd-integration.md                      # TDD統合パターン
│   ├── rollback-procedures.md                  # ロールバック手順
│   └── automation-patterns.md                  # 自動化パターン
├── scripts/
│   └── check-upgrades.mjs                      # アップグレード候補チェック
└── templates/
    └── upgrade-plan-template.md                # アップグレード計画テンプレート

コマンドリファレンス

このスキルで使用可能なリソース、スクリプト、テンプレートへのアクセスコマンド:

リソース読み取り

# 戦略選択ガイド
cat .claude/skills/upgrade-strategies/resources/strategy-selection-guide.md

# TDD統合パターン
cat .claude/skills/upgrade-strategies/resources/tdd-integration.md

# ロールバック手順
cat .claude/skills/upgrade-strategies/resources/rollback-procedures.md

# 自動化パターン
cat .claude/skills/upgrade-strategies/resources/automation-patterns.md

スクリプト実行

# アップグレード候補チェック
node .claude/skills/upgrade-strategies/scripts/check-upgrades.mjs

# 例: セキュリティアップデートのみ
node .claude/skills/upgrade-strategies/scripts/check-upgrades.mjs --security-only

テンプレート参照

# アップグレード計画テンプレート
cat .claude/skills/upgrade-strategies/templates/upgrade-plan-template.md

いつ使うか

シナリオ 1: 定期的なアップグレード

状況: 定期的な依存関係メンテナンスサイクルでのアップグレード

適用条件:

• 定期的なメンテナンスウィンドウが設定されている
• 複数のパッケージを同時に更新する必要がある
• テストカバレッジが十分（>60%）

期待される成果: 安全に更新された依存関係と検証済みのシステム

シナリオ 2: セキュリティパッチの緊急適用

状況: 重大なセキュリティ脆弱性の修正が必要

適用条件:

• Critical/High の脆弱性が検出された
• パッチが利用可能
• 迅速な対応が必要

期待される成果: 脆弱性が解消された状態

シナリオ 3: メジャーバージョンアップ

状況: フレームワークやライブラリのメジャーバージョンアップ

適用条件:

• Major バージョンが変更される
• 破壊的変更が含まれる可能性がある
• 移行ガイドが提供されている

期待される成果: 新バージョンへの完全な移行

アップグレード戦略の種類

1. 段階的アップグレード（推奨デフォルト）

概要: 小さな更新を頻繁に行う

適用条件:

• 定期的なメンテナンスが可能
• テストカバレッジが十分
• CI/CD パイプラインが整備されている

メリット:

• リスクの分散
• 問題の早期発見
• ロールバックが容易

手順:

# 1. 更新可能なパッケージを確認
pnpm outdated

# 2. Patchバージョンから更新
pnpm update --latest

# 3. テスト実行
pnpm test

# 4. コミット
git add . && git commit -m "chore: update patch dependencies"

2. 一括アップグレード

概要: 多数のパッケージを一度に更新

適用条件:

• 長期間更新されていない
• 大規模なリファクタリングの一環
• 十分なテスト時間が確保できる

リスク:

• 問題の切り分けが困難
• 複数の破壊的変更が同時に発生

手順:

# 1. 現状をバックアップ
git checkout -b upgrade/bulk-update

# 2. 全パッケージを最新に
pnpm update --latest

# 3. ビルドエラーを修正
pnpm build

# 4. テストを修正・実行
pnpm test

# 5. E2Eテスト
pnpm test:e2e

3. セキュリティファーストアップグレード

概要: セキュリティパッチを最優先で適用

適用条件:

• セキュリティ脆弱性が検出された
• パッチが利用可能
• 迅速な対応が必要

手順:

# 1. 脆弱性を確認
pnpm audit

# 2. セキュリティパッチのみ適用
pnpm audit --fix

# 3. 検証
pnpm test

# 4. 即座にデプロイ

4. フィーチャーフラグ型アップグレード

概要: フィーチャーフラグで新バージョンの使用を制御

適用条件:

• 段階的なロールアウトが必要
• A/B テストを行いたい
• リスクを最小化したい

実装例:

// feature-flags.js
const flags = {
  USE_NEW_LIBRARY_VERSION: process.env.NEW_LIB === "true",
};

// usage.js
const lib = flags.USE_NEW_LIBRARY_VERSION
  ? require("lib@2.0.0")
  : require("lib@1.0.0");

TDD 統合

テスト駆動アップグレードの流れ

1. 既存テストの実行（Green）
   ↓
2. パッケージを更新
   ↓
3. テストを実行（Red/Green）
   ↓
4. 失敗したテストを修正
   ↓
5. 全テスト通過（Green）
   ↓
6. コミット

推奨テストカバレッジ

レベル	カバレッジ	適用範囲
最小	60%以上	段階的アップグレード
推奨	80%以上	一括アップグレード
理想	90%以上	メジャーバージョンアップ

静的テスト（100%必須）

# TypeScript型チェック
pnpm tsc --noEmit

# ESLintチェック
pnpm eslint .

# Prettierチェック
pnpm prettier --check .

ワークフロー

Phase 1: 計画

目的: アップグレードの範囲と戦略を決定

ステップ:

1. 更新可能なパッケージを確認
2. 各パッケージの変更内容を調査
3. 影響範囲を評価
4. 戦略を選択
5. タイムラインを策定

判断基準:

• 更新対象を特定したか？
• 破壊的変更を確認したか？
• 戦略を選択したか？
• ロールバック計画があるか？

Phase 2: 準備

目的: アップグレードに必要な準備を完了

ステップ:

1. テストカバレッジを確認・改善
2. ベースラインのテスト結果を記録
3. フィーチャーブランチを作成
4. 依存関係の現状を文書化

判断基準:

• テストカバレッジは十分か？
• ベースラインを記録したか？
• ブランチを作成したか？

Phase 3: 実施

目的: アップグレードを安全に実行

ステップ:

1. パッケージを更新
2. ビルドエラーを修正
3. テストを実行・修正
4. 静的解析を実行
5. 手動テストを実施

判断基準:

• ビルドが成功するか？
• 全テストが通過するか？
• 静的解析をパスするか？

Phase 4: 検証

目的: アップグレードが正しく完了したことを確認

ステップ:

1. 全テストスイートを実行
2. パフォーマンスを測定
3. セキュリティ監査を実行
4. ステージング環境でテスト
5. コードレビューを実施

判断基準:

• 回帰がないか？
• パフォーマンス低下がないか？
• 新しい脆弱性が導入されていないか？

Phase 5: 本番適用

目的: 安全に本番環境へデプロイ

ステップ:

1. 本番デプロイを実行
2. スモークテストを実施
3. モニタリングを強化
4. 問題発生時はロールバック
5. 成功を確認・文書化

判断基準:

• デプロイが成功したか？
• エラー率が正常か？
• パフォーマンスが正常か？

ベストプラクティス

すべきこと

1. 小さく頻繁に更新:

   • 週次または隔週でのパッチ更新
   • 月次でのマイナー更新
   • 四半期でのメジャー更新検討

2. 自動化を活用:

   • Dependabot の活用
   • Renovate の活用
   • CI/CD での自動テスト

3. 文書化:

   • 変更内容の記録
   • 問題と解決策の記録
   • 次回への学びの記録

避けるべきこと

1. 長期間の放置:

   • ❌ 6 ヶ月以上更新しない
   • ✅ 定期的なメンテナンスサイクル

2. テストなしの更新:

   • ❌ テストをスキップして更新
   • ✅ テストで検証してから更新

3. 一括大量更新:

   • ❌ 全パッケージを同時に最新化
   • ✅ 段階的に更新して問題を切り分け

トラブルシューティング

問題 1: 型エラーの大量発生

症状: TypeScript の型エラーが大量に発生

対応:

1. まず@types/*パッケージを更新
2. 型定義の変更点を確認
3. 一つずつ修正、またはanyで一時回避
4. 根本的な修正を後で実施

問題 2: 推移的依存の競合

症状: ピア依存の競合でインストールが失敗

対応:

# overridesで強制解決
# package.json
{
  "pnpm": {
    "overrides": {
      "conflicting-package": "^1.0.0"
    }
  }
}

問題 3: テストの大量失敗

症状: アップグレード後にテストが大量に失敗

対応:

1. 一旦ロールバック
2. 段階的なアップグレードに切り替え
3. 一つのパッケージずつ更新

関連スキル

• .claude/skills/semantic-versioning/SKILL.md (.claude/skills/semantic-versioning/SKILL.md): バージョン変更の影響評価
• .claude/skills/dependency-auditing/SKILL.md (.claude/skills/dependency-auditing/SKILL.md): セキュリティ監査
• .claude/skills/lock-file-management/SKILL.md (.claude/skills/lock-file-management/SKILL.md): ロックファイルの管理

メトリクス

アップグレードの効果測定

測定指標:

• アップグレード成功率
• ロールバック発生率
• 平均アップグレード時間
• 技術的負債スコアの推移

目標値:

• 成功率: >95%
• ロールバック率: <5%
• Patch 更新時間: <30 分
• Minor 更新時間: <2 時間

変更履歴

バージョン	日付	変更内容
1.0.0	2025-11-27	初版作成 - アップグレード戦略フレームワーク

参考文献

• Dependabot: https://docs.github.com/en/code-security/dependabot
• Renovate: https://docs.renovatebot.com/
• pnpm update: https://docs.npmjs.com/cli/v10/commands/pnpm-update