依存ライブラリのアップグレードは、個人開発の中で一番気が重い作業のひとつです。月初めに npm outdated を眺めて、20 行を超える更新候補のリストを見ては「来月でいいか」と先送りにする、という時期が私にもありました。半年放置するとマイナーバージョンアップでも互換性チェックの量が膨大になり、一度ハマると週末が消えていきます。
Claude Code を導入してから、この作業はだいぶ楽になりました。ただし、最初に「全部任せる」をやって痛い目を見ています。Claude が自信満々に「アップグレード完了。テストも通っています」と返してきたコードを本番に出した翌朝、ユーザーから「画像が表示されない」という報告が届いた、というのを 2 度ほど経験しました。原因はそれぞれ別の破壊的変更で、テストではカバーされていない領域でした。
私が現在運用している「Claude Code に依存アップグレードを任せつつ、破壊的変更を本番に漏らさないための検証ループ」を実例とともに整理しました。AI に任せる範囲と、人間が手放してはいけない判断を切り分ける、という観点で書いています。
なぜテストが通っているのに本番で壊れたのか
過去 2 度の事故を振り返ると、共通点がありました。どちらも「メジャーバージョンアップではなくマイナーアップ」、そして「テストはちゃんと通っていた」のです。これが厄介で、Claude Code に「依存をアップグレードしてテストを通して」と頼んだとき、AI 側からは何も問題が見えません。
最初の事故は画像最適化ライブラリのマイナーアップで、内部の WebP 変換挙動がデフォルトで変わっていました。テストでは PNG しかカバーしていなかったため検出できず、本番のユーザー画像（多くが JPEG）で初めて症状が出ました。2 度目はクライアント側のフォーム検証ライブラリで、空文字の扱いが「無効」から「未入力」に変わっていました。これも単体テストでは捕まえていましたが、E2E テストの初期化フローを通っていない領域でした。
ここから学んだのは、破壊的変更は CHANGELOG の「BREAKING CHANGES」セクションだけに書かれているとは限らない、ということです。バグ修正と書かれている項目が、こちらの実装にとっては挙動変更になっている、というケースがかなりの頻度であります。Claude Code に CHANGELOG を読ませても、こちらの利用パターンを知らなければ判定はできません。
人間が手放してはいけない 3 つの判断
検証ループの話に入る前に、AI に任せる前提として「人間が握っておくべき判断」を整理します。これを切り分けないと、Claude Code に丸投げして痛い目を見ます。
ひとつ目は アップグレード対象の選定です。マイナーアップだけにするのか、メジャーアップも含めるのか、依存の依存（lockfile レベルの更新）まで広げるのか、という意思決定は人間がします。Claude にこれを任せると、内容を吟味せずにフルアップを提案してきがちで、変更点が多すぎてレビューが破綻します。
ふたつ目は 「壊れたら一番痛い領域」の特定です。決済、認証、データ保存、画像配信など、ユーザー体験のコアにあたる部分を事前に列挙しておきます。Claude にはこの領域を特定する文脈がないので、検証ループのプロンプトで明示的に渡します。
みっつ目は ロールバック判断です。検証で疑わしい挙動が出たとき、修正を続けるか元に戻すか、という判断は AI に任せません。Claude は「直せる」と判断しがちで、結果として深い穴に潜って週末が消える、ということになります。明確な打ち切り基準を人間側で決めておきます。
この 3 点さえ握っておけば、残りの「依存を当てる」「テストを走らせる」「CHANGELOG を要約する」「修正コードを書く」といった機械的な作業は Claude Code に任せられます。
4 段階の検証ループの全体像
私が運用している検証ループは、次の 4 段階です。各段階で Claude Code に渡すプロンプトと、人間が確認するチェックポイントを分けています。
- 収集: 何をアップグレードするのか、何が変わるのかを Claude にまとめさせる
- 当て込み: 実際にバージョンを上げて、テストとビルドを走らせる
- 影響面の検査: 「壊れたら一番痛い領域」を Claude に再走査させる
- 本番投入の判断: 検証ログを見て、人間が go/no-go を決める
このうち、Claude Code が主役なのは 1 〜 3 で、4 は必ず人間が判断します。各段階を順に見ていきます。
段階 1: 収集 — 「何が変わるか」を読み解く
最初のステップは、npm outdated や pip list --outdated のようなコマンドで更新候補を取り、それぞれの CHANGELOG / Release Notes を Claude に読ませて、「自分のリポジトリにとって影響しそうな変更点」を抽出してもらうことです。ここでのプロンプトは、こちらの利用パターンを明示的に渡すのがコツです。
私のリポジトリは Next.js 16 + Tailwind + tRPC で構成されています。
以下の依存ライブラリを最新マイナー版に上げる予定です。
それぞれの CHANGELOG を読み、「私の構成で挙動が変わる可能性があるもの」を
変更内容のサマリと一緒にリストアップしてください。
注意してほしい観点:
- デフォルト値の変更（オプション省略時の挙動が変わるもの）
- 戻り値の型・形状の変更
- 例外を投げるようになった or 投げなくなった条件
- ファイル出力・ネットワーク呼び出しの挙動変更
更新候補:
- next: 16.0.4 → 16.0.7
- @trpc/server: 11.2.1 → 11.3.0
- sharp: 0.34.0 → 0.35.0
...
このプロンプトの肝は、ライブラリの作者が「破壊的変更ではない」と判定した変更点まで、こちら視点で再評価させるところです。私の経験上、CHANGELOG の Bug Fix セクションに紛れている挙動変更が一番怖いので、ここを Claude に拾わせます。
出力としては、ライブラリごとに「影響しそうな変更点 0〜3 個」と「特に検証が必要な領域」を返してくれます。これを次の段階の入力として保存します。
段階 2: 当て込み — テストとビルドを走らせる
ここからは Claude Code に直接コードを触らせます。プロジェクトのパッケージマネージャに合わせてアップグレードを実行し、テストとビルドを走らせます。私の運用では、この段階だけは「失敗してもいいから一気にやる」というスタンスで進めます。
段階 1 で抽出した依存をすべて当て込んでください。
1. package.json のバージョンを更新
2. npm install --no-audit --no-fund
3. npm run lint, npm run typecheck, npm run test, npm run build を順に実行
4. 失敗があれば、原因の概略と該当ファイルだけまとめて報告してください
※ この段階では修正しないでください
報告フォーマット:
- 失敗ステップ:
- 失敗したテスト / ファイル:
- エラーメッセージの要約:
- 推測される原因（CHANGELOG との対応）:
「この段階では修正しないでください」と明示しているのは、Claude Code がエラーを見ると修正に走り出してしまうためです。私はここで一度立ち止まり、報告を読んで「修正方針を決める」フェーズを挟みます。
修正方針が決まったら、改めて Claude にコードを直させます。このとき、修正コミットを 1 ライブラリ 1 コミットに分割するように指示しておくと、後でレビューと部分ロールバックがしやすくなります。
報告された失敗のうち、以下を順番に修正してください。
各修正は 1 コミットに分け、コミットメッセージに対応するライブラリ名と
変更点を明記してください:
1. sharp 0.35 の WebP デフォルト挙動変更への対応
2. @trpc/server 11.3 の zod 入力エラー型変更への対応
修正前に、各ファイルで影響範囲を grep で確認し、変更が漏れないようにしてください。
段階 3: 影響面の検査 — 「テストでは見えない領域」を当てる
ここが、私が事故の経験から増やした段階です。テストとビルドが通っただけでは、本番投入はしません。「壊れたら一番痛い領域」を Claude に再走査させ、テストでカバーできていない動作確認を手動 or 半自動で行います。
リポジトリのルートに docs/critical-paths.md というファイルを置いて、決済・認証・画像配信などの「触れたら本番に影響が大きい経路」を列挙しています。このファイルを Claude に読み込ませた上で、「今回のアップグレードがこの経路のどこに触れたか」を再走査させます。
docs/critical-paths.md を読み、今回のアップグレード差分が
記載された経路のどこに影響する可能性があるかを判定してください。
判定の出力は、経路ごとに次のフォーマットでお願いします:
- 経路名:
- 触れた依存ライブラリ:
- 影響しそうな関数 / コンポーネント:
- 推奨する手動検証手順（ローカル or staging で再現できる手順）:
ここで「画像配信経路に sharp の WebP 挙動変更が影響しうる」という出力が出れば、人間側で staging 環境にデプロイして、実ユーザーが上げる代表的な JPEG / PNG / HEIC で目視確認をします。テストにはなくても、目視で 5 分かければ前回事故った種類のバグはほぼ防げます。
この段階で、新たに自動テストを追加すべき領域も浮かび上がります。次回以降は人間の目視を減らしたいので、その場で Claude にテストの追加もお願いします。
段階 3 で見つかった未カバー領域のうち、自動テスト化できるものを
リストアップし、優先度順にテストを追加してください。
テストは tests/regression/upgrade/ 以下に配置し、
ファイル名に対応する依存ライブラリ名を含めてください。
段階 4: 本番投入の判断 — 人間がログを読む
最後の段階は、Claude には任せません。各段階のログ（CHANGELOG サマリ、修正コミット一覧、影響面検査結果、追加した回帰テスト一覧）を 1 つの Markdown にまとめさせ、それを読んで go/no-go を決めます。
私の判定基準はシンプルで、次のいずれかに該当したら「保留してもう一段検証」を行います。
- 段階 3 で「決済 / 認証 / データ保存」のいずれかに影響ありと判定された
- 修正コミットが 5 つを超えた（変更面が広すぎるサイン）
- Claude の説明文の中に「おそらく」「たぶん」が 2 つ以上出てきた
特に最後の項目は感覚的ですが、Claude Code が確信を持てていない領域はだいたい後で問題になる、というのが個人開発で得た経験則です。曖昧さが残ったら、その依存だけアップグレードを次回送りにします。
go と判断したら、修正コミットを順番に main にマージし、staging で 24 時間放置してから本番に反映します。この「24 時間 staging 放置」が地味に効いていて、cron 系や非同期処理が絡む不具合を 2 度ほど捕まえています。
月一アップグレードを「儀式」にしないための運用ルール
検証ループだけ整えても、運用に乗らなければ意味がありません。私が個人開発で守っているルールを 3 つ書いておきます。
第一に、月初の最初の平日にカレンダー予約を入れる。アップグレード作業は気が重いので、作業日を曖昧にすると簡単に先延ばしになります。「毎月 1 日に 2 時間だけブロックして必ずやる」と決めると、間隔が空きすぎて壊れる、ということが起きにくくなります。
第二に、CHANGELOG が読みづらい依存は、別タイミングでメジャーアップする。月一の機械的なマイナーアップとは別に、「この依存はメジャーアップを通して整理したい」という意思決定が必要なものを年に 2〜3 個ピックアップして、専用の枠を取って取り組みます。Claude Code は単純な機械的更新が得意なので、月一はその得意分野に絞って任せます。
第三に、Claude にやってもらった検証ログを毎回 docs/upgrade-history/ に残す。次回のアップグレード時に、前回どの依存で何が起きたかを Claude に読み込ませると、注意点を覚えていてくれます。これは個人開発の中で「組織の記憶」を AI に肩代わりしてもらう、ささやかな工夫です。
依存アップグレードは、サボると確実に技術的負債として返ってくる作業です。完全自動化は難しいですが、「人間が判断するところ」と「AI に機械的に動いてもらうところ」を切り分ければ、月一の儀式が「2 時間で終わる定型作業」になります。次回のアップグレードでは、まず段階 1 のプロンプトを書くところから始めてみてください。