依存パッケージの更新をClaude Codeに任せる：範囲の切り方と確認ポイント
AIを使いこなすClaudeで執筆し、GPTで自動校閲・修正しています。
依存パッケージの更新はClaude Codeに任せられます。ただし「全部最新にして」と頼むのは避けてください。テストが落ちたとき、どの更新が原因なのか分からなくなるからです。 おすすめは、調査・更新・確認を分け、更新は1グループずつGitのコミットで区切る進め方です。Claude Codeには、更新できるものの一覧づくりと、1グループ分の更新、確認コマンドの実行を任せます。人は、どのグループをどの順で更新するかと、各段階の結果の判断を担当します。 この記事では、更新対象を絞る指示文と、更新ごとの確認項目表を使える形で示します。例のコマンドはnpmを前提にした「説明用の例」で、私が実行して検証したものではありません。別のエコシステムでは、同じ役割のコマンドに読み替えてください。
1. 先に「何も変更しない調査」だけを頼む
最初の依頼では、ファイルを一切変更させません。Claude Codeには、編集を止めたまま調べて計画を出す「Plan」モードがあります。公式ドキュメントでは、Shift+Tabでモードを切り替えるか、プロンプトの先頭に/planを付けて入るとされています。通常は計画を承認するまでソースの編集がブロックされます。ただし、権限チェックを省略するbypassPermissionsを選択可能にして起動した対話型CLIでは例外があります（Permission modesで確認）。現在のモードは画面の表示で確かめてください。
説明用の依頼文です。
/plan 依存パッケージの更新計画を作ってください。まだ何も変更しないでください。
1. 古くなっているパッケージを一覧にする（現在版・最新版・メジャー/マイナー/パッチの区別）
2. 各パッケージのリリースノートや変更履歴を読み、破壊的変更の有無を書く
3. 「パッチ」「マイナー」「メジャー」に分け、各項目に「開発ツール系」「ランタイムに直結するもの」などの用途を併記する
4. 更新の推奨順と、各グループで実行すべき確認コマンドを提案する
読むだけで、package.jsonやlockファイルは編集しないでください。出てきた一覧は鵜呑みにせず、次の2点を人が見ます。
- 変更履歴の要約が、実際のリリースノートに書かれている内容か（気になる項目は自分で原典を開く）
- 分類が自分のプロジェクトの感覚と合っているか（たとえば、普段は開発用でも本番ビルドに入るものはリスクが高い）
2. 更新対象を絞る指示文
調査結果から、今回やるグループを1つだけ決めて依頼します。次のテンプレートの{ }を埋めて使えます。
今回の更新対象は次の{件数}件だけです。
- {パッケージA} {現在版} → {目標版}
- {パッケージB} {現在版} → {目標版}
ルール:
- 上記以外の直接依存の版指定は変えない。更新対象が必要とする間接依存の変更は理由を報告し、無関係なlockファイルの差分が出たら止まる
- 目標版は私が指定したものに固定し、勝手に最新版へ上げない
- 更新後に {インストール、ビルド、型チェック、テスト、lintの各コマンド} を順に実行し、結果をそのまま報告する
- 失敗したら自分で原因を広く探し回らず、失敗内容と推測を報告して止まる
- コミットはしない。差分の要約だけ出すポイントは3つです。
- 件数を固定する: 1グループは同種のものを数件までにします。何件までが適切かはプロジェクト次第なので、原因を追える大きさで決めてください。
- 目標版を明示する: 「最新に」と書くと、範囲外の更新が混ざります。
- 失敗時は止める: 止めないと、テストを通すために別のコードやテストを書き換えることがあります。差分の確認で、更新と無関係な変更が入っていないかを見ます。
3. 更新ごとの確認項目表
1グループの更新が終わるたびに、同じ表で確認します。下の表は編集上の提案で、公式の必須手順ではありません。
- 差分の範囲、誰が：人、見るもの：変更ファイルが、マニフェスト・lockファイル・必要な修正だけか、止める条件：無関係なファイルが変わっている
- 対象外の版、誰が：人、見るもの：lockファイルの差分に、指定外パッケージの大きな版変更がないか、止める条件：想定外のメジャー更新がある
- インストール、誰が：Claude→人が結果を読む、見るもの：警告、非推奨の表示、依存の競合、止める条件：エラー、または警告の急増
- ビルド・型チェック・lint、誰が：Claude→人が結果を読む、見るもの：成功/失敗と、エラーの出た箇所、止める条件：失敗（原因が更新由来か切り分ける）
- テスト、誰が：Claude→人が結果を読む、見るもの：失敗の数と内容。更新前に同じテストが通っていたか、止める条件：更新前に通っていたテストが落ちた
- テストの改変、誰が：人、見るもの：テストや設定ファイルが書き換えられていないか、止める条件：通すための書き換えがある
- 実際の挙動、誰が：人、見るもの：主要画面や主要APIを手で一度動かす、止める条件：自動テストで拾えない表示や動作の崩れ
- 脆弱性・ライセンス、誰が：人、見るもの：脆弱性監査の結果、新規・更新した依存のライセンス情報、止める条件：新規の高リスク指摘、利用条件が未確認の依存
「更新前に通っていたか」は重要です。最初に更新前の状態でテストを一度走らせ、結果を控えておくと、既存の失敗と更新由来の失敗を混同しません。この基準取りは、手順1の直後にClaude Codeへ頼めます。
全項目が問題なければ、人がコミットします。コミットメッセージにはグループ名と版の変化を書くと、後でgit bisectなどで原因を探しやすくなります。
4. 壊れたときの戻し方と切り分け
更新で失敗したときの基本は、直前のコミットに戻して、グループを小さく分け直すことです。
ここで注意したいのは、Claude Codeの/rewind（入力欄が空ならEsc2回でも開けます）だけに頼らないことです。公式のCheckpointingには、次の制限が書かれています。
- Bashコマンドだけで変更されたファイルは追跡されない。パッケージの更新コマンドが書き換えるlockファイルが、この例に当たる可能性がある
- サブエージェントによる編集は、基本的に復元されない場合がある
- チェックポイントは、Gitのようなバージョン管理の代わりではない
つまり、更新前にはGitで作業ツリーをきれいにしておき（未コミットの変更は先にコミットかstashします）、git diffで変更を確認し、git restoreで更新対象の追跡ファイルを戻せる状態にしておきます。ファイルを戻した後は、復元したlockファイルに合わせて依存パッケージを再インストールし、確認をやり直してください。
失敗したときの切り分け依頼の例です。
このグループの更新でテストが落ちました。コードは変更しないでください。
1. 落ちたテストと、エラーメッセージの最初の原因らしき行を示す
2. 更新した{件数}件のうち、どれが原因として疑わしいか、根拠つきで順位をつける
3. 1件ずつ版を戻して確認する手順を提案する（実行はまだしない）原因候補が絞れたら、疑わしい1件だけを外して残りを更新し直します。外した1件は、別の作業として移行手順を読んでから扱います。
5. 任せないほうがよいもの
- メジャー更新: 移行ガイドを人が先に読み、コード修正を伴う作業として独立に扱います
- 認証情報を含む設定: .envなどの中身は渡しません。調査に必要なら、値を伏せた説明用の設定に置き換えます
- プライベートレジストリの認証設定: 設定の中身ではなく、「社内レジストリを使っている」という事実だけを伝えます
コマンドの自動承認を許す範囲も、更新の段階に合わせて見直してください。Claude Codeの権限モードには、編集を自動承認するacceptEditsや、事前に許可したものだけを実行するdontAskなどがあります（Permission modes）。初めての更新では、Manual（default）モードを選び、パッケージのインストールや削除を伴うコマンドを自動承認する設定がないか確認して、承認を自分で毎回見るほうが安全です。慣れてから、実行内容を確認したテストやビルドのコマンドごとに許可を広げます。テストやビルドもスクリプトを実行するため、読み取り専用とは限りません。
