Claude Codeに依存更新を任せる前に：権限とテストゲートの置き方

3行まとめ

調査から始める

npm outdated、lockfile、changelogを先に確認します。

権限を分ける

確認コマンドは許可し、更新やpushは承認に残します。

ゲートを固定

npm ci、lint、typecheck、test、auditを通過条件にします。

AIに任せる範囲より先に、止める条件を決めます。

• Claude Codeに依存関係アップデートを任せるなら、最初に任せるべきは更新作業そのものではなく、npm outdated、lockfile、changelog、既存テストの調査です。
• .claude/settings.jsonでは、npm run lint、npm run typecheck、npm test、git diffのような確認コマンドを許可し、npm audit fix --force、git push、秘密情報読み取り、外部通信は承認または拒否に残します。
• 実務投入の合格ラインは「AIが更新できた」ではなく、npm ci、lint、typecheck、test、audit、差分レビュー、人間承認のログが残ることです。

本文の事実確認には、公式ドキュメント、公式ヘルプ、関連する仕様・SDKドキュメントを使っています。実リポジトリでの性能ベンチマークや更新代行は、本文で明記した場合を除き実施していません。

この記事でわかること

作業分解

調査、更新、検証、レビューを分けられます。

権限設定

.claude/settings.jsonで許可、確認、拒否を分けられます。

npm判断

update、install、audit fix、forceの危険度を分けられます。

承認条件

major updateや本番影響を人間レビューへ戻せます。

便利さではなく、レビューできる差分を作ることを目的にします。

• Claude Codeに依存関係更新を任せる前の作業分解
• npm outdated、npm update、npm audit fixの扱い分け
• .claude/settings.jsonで許可、確認、拒否に分ける例
• lint、typecheck、test、auditを必須ゲートにする考え方
• 人間承認に戻すべき更新条件
• Pro/Max/API/Team/Enterpriseで変わるデータ利用とコストの確認点

前提知識

1. 1package.json

   直接依存とdevDependencyの変更を確認します。

2. 2lockfile

   transitive dependencyとresolved registryを確認します。

3. 3検証

   npm ci、lint、typecheck、testを再実行します。

4. 4レビュー

   認証、決済、CI/CD、ライセンスへの影響を確認します。

依存関係更新は、コード差分よりも広い範囲を動かします。

依存関係アップデートは、単なるコード修正より影響範囲が広い作業です。package.jsonの1行変更に見えても、lockfile、transitive dependency、peer dependency、postinstall script、型定義、ビルド設定、テストランナー、CI/CD、脆弱性対応、ライセンス確認まで連動します。

Claude Codeは、公式ドキュメント上ではNode.js 18以上を前提にnpmからインストールして使うローカルCLIとして案内されています。コードベースを理解し、ファイル編集やコマンド実行を支援できますが、実務では「AIが作業すること」と「その作業をマージしてよいこと」を分けて考える必要があります。

依存関係更新はread-only調査から始める

最初に任せる仕事は、更新ではなく調査です。

npm outdated
npm audit --json
npm ls --depth=0
git status --short

npm公式のnpm outdatedは、依存関係をcurrent、wanted、latestの観点で見せます。実務で重要なのは、wantedとlatestを混同しないことです。wantedは現在のsemver範囲で到達できる候補、latestは公開されている最新候補として読むのが基本です。

つまり、Claude Codeに最初から「全部latestにして」と頼むより、次のように頼むほうがレビューしやすくなります。

依存関係を更新する前に調査だけしてください。
npm outdated の current / wanted / latest を表にして、
major update、runtime dependency、devDependency、peer dependency の注意点を分けてください。
まだ package.json と package-lock.json は変更しないでください。

この段階では、ファイル編集権限も外部サービス連携も要りません。read-onlyで十分です。AIに「何を変えるべきか」を考えさせる前に、「変える候補をどう分類するか」を固定します。

Claude CodeはCIの代わりではない

Claude Codeのcommon workflowsには、テスト実行やPR作成、Unix風のclaude -p利用が紹介されています。これは便利ですが、Claude CodeをCIの代替にしてよいという意味ではありません。

CIは、同じ入力に対して同じコマンドを走らせるための場所です。Claude Codeは、調査、差分作成、ログ読解、修正案の反復に向いています。依存関係更新では、次の分担にすると事故が減ります。

役割	任せる対象	合格条件
Claude Code	調査、差分作成、失敗ログ読解、修正案	実行コマンドと未検証範囲を報告する
ローカル/CI	npm ci、lint、typecheck、test、audit	exit codeとログが残る
人間レビュー	major update、認証、決済、CI/CD、ライセンス	差分の意味を説明できる

まずread-onlyで調査させる

項目	内容	見方
npm outdated		current、wanted、latestの差を整理します。
npm audit		既知脆弱性とseverityを確認します。
依存種別		runtime dependencyとdevDependencyを分けます。
changelog		major updateやbreaking changeを確認します。

read-only調査だけなら、作業範囲を広げずに判断材料を作れます。

依存関係更新をAIに任せるとき、最初の失敗は「更新対象の粒度が粗すぎる」ことです。dependenciesとdevDependenciesを一緒に上げ、major/minor/patchも混ぜ、失敗したテストをAIが別方向に直し始めると、レビューは急に難しくなります。

npm outdatedを先に読ませる

調査プロンプトは、更新対象を分ける形にします。

このリポジトリのnpm依存関係更新候補を調査してください。
実行してよいコマンドは npm outdated、npm audit --json、npm ls --depth=0、git status --short だけです。
package.json、package-lock.json、ソースコードは変更しないでください。

出力は次の観点で整理してください。
- patch/minorで更新できるもの
- major updateになるもの
- runtime dependency
- devDependency
- peer dependencyの注意があるもの
- changelog確認が必要なもの

ここでnpm updateまで許可しないのがポイントです。npm公式ドキュメントでは、npm updateはプロジェクトの依存関係を更新するコマンドです。現在のsemver範囲内で済む場合もありますが、lockfileが変わります。調査フェーズでlockfileを変えると、どの判断で差分が発生したのか追いにくくなります。

changelogと差分範囲を確認する

AIに調査を任せるときは、changelog確認も作業に含めます。ただし、全パッケージの全履歴を読ませる必要はありません。まずは次の条件で絞ります。

確認項目

条件	人間レビューの優先度
major update	高い
runtime dependency	高い
build tool、test runner、TypeScript、framework	高い
security fix	高い
devDependencyのpatch/minor	中
lockfileのみのtransitive update	中

Claude Codeには、更新対象ごとに「なぜ安全そうか」ではなく「何をまだ確認していないか」を出させます。依存関係更新で危ないのは、成功ログがあることより、未確認範囲が見えないことです。

.claude/settings.jsonで許可と拒否を分ける

項目	内容	見方
allow		git diff、npm outdated、lint、typecheck、testなどの確認コマンド。
ask		npm update、npm install、npm audit fixなど差分を作る操作。
deny		秘密情報読み取り、git push、破壊的削除、本番影響のある操作。
managed policy		法人では上位ポリシーで個人設定より強い境界を置きます。

自然言語の禁止だけではなく、設定でも実行境界を作ります。

Claude Code公式のsettingsドキュメントでは、設定ファイルにpermissions.allow、permissions.ask、permissions.denyを置けます。ユーザー設定、プロジェクト設定、ローカルプロジェクト設定、企業管理ポリシーには優先順位があり、企業管理ポリシーが最も強い層として扱われます。

依存関係更新では、自然言語の「危ない操作はしないでください」だけに頼らず、設定でも境界を置きます。

allowに入れる最小コマンド

最初に許可してよいのは、状態確認と検証コマンドです。例としては次のような設定になります。

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm outdated:*)",
      "Bash(npm ls:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test)",
      "Bash(npm ci)"
    ],
    "ask": [
      "Bash(npm update:*)",
      "Bash(npm install:*)",
      "Bash(npm audit fix:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

これはそのまま全リポジトリに貼る設定ではありません。リポジトリによってnpm testではなくnpm run test:unitが正しい場合もあります。重要なのは、許可するコマンドを「確認」と「変更」に分けることです。

askまたはdenyに残す操作

依存関係更新では、次の操作を自動許可にしないほうが安全です。

注意点

操作	推奨
npm update	初期はask
npm install <pkg>	ask
npm audit fix	ask
npm audit fix --force	原則denyまたは人間実行
git push	denyまたは人間実行
.env、秘密情報、credentials	deny
本番環境へ触るコマンド	deny
外部から任意スクリプトを取得して実行	deny

Anthropicのsecurityドキュメントでは、Claude Codeはread-onlyを基本にし、追加操作には明示的な許可を求める設計が説明されています。設定で境界を置く理由は、AIを信用しないためだけではありません。人間側の疲れを減らすためでもあります。毎回すべてのコマンドを目視承認する運用は、すぐに形骸化します。

依存関係更新のコマンドを4段階に分ける

項目	内容	見方
調査		npm outdated、npm audit –json、npm lsは差分を作らない段階です。
lockfile更新		npm updateやaudit fix –package-lock-onlyはCI再現性を確認します。
直接依存更新		npm install <pkg>@versionはpackage.jsonもレビュー対象にします。
force		npm audit fix –forceはmajor updateを含み得るため人間承認に戻します。

同じ更新でも、作る差分とレビュー負荷は大きく違います。

Claude Codeに渡す前に、npmコマンドを危険度で分けます。ここが曖昧だと、AIは「更新」という言葉を広く解釈します。

1. 調査コマンド

npm outdated
npm audit --json
npm ls --depth=0

この段階では差分を作りません。npm auditは既知の脆弱性レポートを取得しますが、公式ドキュメント上、auditでは依存関係情報がレジストリ側へ送られます。非公開パッケージ名や社内パッケージ名をどう扱うかは、チームの方針に合わせて確認してください。

2. lockfileを変える更新

npm update
npm audit fix --package-lock-only

npm updateは、依存関係ツリーを更新し、lockfileに差分が出る可能性があります。npm audit fix --package-lock-onlyは、node_modulesを直接変えずにlockfile更新だけを狙うときに候補になります。ただし、lockfileだけなら安全という意味ではありません。CIのnpm ciで再現できるかを必ず確認します。

3. package.jsonも変える更新

npm install react@latest
npm install typescript@latest --save-dev

直接依存を上げる場合、package.jsonとlockfileの両方が変わります。Claude Codeに任せるなら、1回のタスクでは対象パッケージを絞るのがおすすめです。

typescript だけを更新してください。
package.json と package-lock.json の差分を作成したあと、
npm ci、npm run typecheck、npm test を実行してください。
失敗した場合は、修正する前に原因と選択肢を報告してください。

4. 危険度が高い更新

npm audit fix --forceは、SemVer-majorの更新を含む可能性があります。公式ドキュメントでも、--forceによってトップレベル依存関係のmajor updateが入り得ることが示されています。これはAIに自動実行させるコマンドではなく、人間が影響範囲を読んでから使うコマンドです。

postinstall scriptを伴うパッケージ、native buildを伴うパッケージ、認証、決済、暗号、DB、ビルドパイプライン、デプロイに関わるパッケージも同じ扱いです。AIに差分作成を任せるとしても、承認は人間に戻します。

lint・typecheck・testゲートの設計

項目	内容	見方
npm ci		lockfileからclean installできるか確認します。
lint		静的規約やformatterの差分を確認します。
typecheck		型定義やAPI変更を検出します。
test/audit		既存挙動と既知脆弱性の増減を確認します。

テスト失敗時は、すぐ修正せず原因分類を先に出させます。

依存関係更新のゴールは「更新できた」ではなく「更新後も同じ品質ゲートを通った」です。最低限、次のコマンドをチームの実情に合わせて固定します。

npm ci
npm run lint
npm run typecheck
npm test
npm audit --audit-level=high

最小ゲート

ゲート	目的	失敗時の扱い
npm ci	lockfileから再現可能にインストールできるか	lockfile差分またはnpm設定を確認
npm run lint	フォーマット/静的規約が壊れていないか	自動修正前に差分方針を確認
npm run typecheck	型定義やAPI変更を検出する	依存先のbreaking changeを確認
npm test	既存の振る舞いが壊れていないか	テスト修正か実装修正かを切り分ける
npm audit	既知脆弱性の増減を見る	severityと修正方針を人間レビュー

npm公式のnpm ciは、CIやテスト環境などclean installが必要な状況向けのコマンドです。依存関係更新では、ローカルのnode_modulesがたまたま動いている状態を避けるため、npm ciを最初のゲートにします。

変更範囲別ゲート

変更対象によって、追加ゲートを決めます。

評価基準

変更対象	追加ゲート例
React/Next.jsなどUIフレームワーク	component test、Playwright、build
TypeScript	npm run typecheck、型生成、API型テスト
ESLint/Prettier	lint結果差分、設定ファイル差分レビュー
test runner	unit test、watch設定、CI設定
bundler/build tool	production build、bundle差分、環境変数確認
認証/決済/DB周辺	integration test、人間レビュー必須

Claude Codeに修正まで任せる場合も、失敗したテストを無断で書き換えさせないほうが安全です。テストが古いのか、実装が壊れたのか、依存先の仕様変更なのかを分けて報告させます。

テストが失敗した場合、すぐに修正しないでください。
失敗ログを読み、原因候補を3つ以内に整理してください。
テスト期待値を変更する案がある場合は、実装が正しい根拠と合わせて人間承認を求めてください。

人間承認へ戻す境界

1. 1patch/minor

   devDependency中心なら差分作成と検証まで任せやすいです。

2. 2ゲート通過

   npm ci、lint、typecheck、test、auditの結果を確認します。

3. 3人間レビュー

   差分説明、未検証範囲、changelogを確認します。

4. 4停止条件

   major、force、認証、決済、CI/CD、本番影響は承認に戻します。

AIの作業完了と、マージしてよい判断は分けます。

AIに依存関係更新を任せるときは、「どこまで自動で進めてよいか」を先に決めます。ここがないと、AIは親切心で作業範囲を広げます。

自動で進めてよい候補

次の条件なら、Claude Codeに差分作成と検証まで任せやすいです。

• devDependencyのpatch/minor update
• wanted範囲内の更新
• lockfileのみの更新
• 既存のlint、typecheck、testが通る
• changelog上のbreaking changeがない
• postinstall scriptやnative buildの追加がない
• 認証、決済、DB、CI/CD、本番設定に触れない

それでも、最終マージはCIとレビューを通します。AIの自己報告だけでマージしないのが基本です。

止めるべき更新

次の条件では、人間承認へ戻します。

条件	理由
major update	仕様変更が入りやすい
runtime dependency	本番挙動に直結しやすい
peer dependency警告	実行時に壊れることがある
npm audit fix --force	major updateを含む可能性がある
postinstall script追加	supply chainリスクが増える
CI/CD設定変更	検証ゲート自体が変わる
認証/決済/DB/暗号	事故時の影響が大きい
ライセンス未確認	法務・配布条件に関わる

人間承認の条件は、CLAUDE.mdやAGENTS.mdにも書く価値があります。ただし、実行を止める必要がある操作は、Claude Code settings、CI required checks、branch protection、CODEOWNERSなどでも支えます。

セキュリティ・コスト注意

データ利用

個人プランと商用条件で扱いが変わる点を確認します。

秘密情報

.env、credentials、顧客データはdenyで除外します。

外部通信

npm registryや公式リポジトリへの通信範囲を確認します。

利用上限

長いログや複数更新は使用量とレビュー時間を増やします。

依存関係更新はネットワークとログを使うため、情報管理も作業条件に入れます。

Claude Codeのdata usageドキュメントでは、コンシューマー向けFree/Pro/Maxと、Team、Enterprise、APIなどの商用条件でデータ利用の扱いが分かれます。2026年5月31日時点の確認では、コンシューマー利用ではデータ改善設定の選択が関係し、商用条件では顧客が明示的に選択しない限り、Claude Codeに送信されたコードやプロンプトを生成モデルの学習に使わないという説明があります。

保持期間やローカルキャッシュ、テレメトリ、エラー報告の設定も確認対象です。特に法人利用では、個人のPro/Maxで社内コードを扱ってよいかを、契約、社内規程、情報分類、監査要件と合わせて判断してください。

秘密情報を読ませない

.env、秘密鍵、credentials、社内URL、顧客データ、非公開リポジトリ情報は、記事やプロンプトに載せません。Claude Code settingsでは、permissions.denyで秘密情報ファイルを見えないようにする例が示されています。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

依存関係更新では、auditやinstallのためにネットワーク通信が発生します。外部通信を完全に禁止した環境では更新自体が進みません。許可するなら、npm registry、GitHub release、対象パッケージの公式リポジトリなど、目的に合う範囲へ絞ります。

利用上限と料金を作業単位で見る

Anthropic Help Centerでは、Claude Codeの利用がPro/Maxの利用上限と共有されること、Maxには5x/20xの利用枠があること、API利用は標準APIレートで別に課金されることが説明されています。依存関係更新は、長いログ、changelog、複数回のテスト失敗、lockfile差分の読解でコンテキストを使いがちです。

コストを抑えるなら、1セッションで「全部更新」しないことです。次のように分けます。

1. 調査だけ
2. devDependencyのpatch/minorだけ
3. 1パッケージだけ
4. テスト失敗の原因調査だけ
5. major updateは別Issue

この分け方は、AIの使用量だけでなく、レビュー時間も減らします。

失敗点とハマりどころ

lockfile誤読

package.jsonが小さくてもtransitive dependencyが大きく変わります。

force乱用

audit fix –forceで互換性が壊れることがあります。

テスト書き換え

失敗原因を見ずに期待値を変えると不具合を隠します。

途中停止

長い更新は使用量上限やレビュー不能な大差分につながります。

失敗条件を先に知ると、Issueの粒度を小さくできます。

依存関係更新で起きやすい失敗は、AI固有の問題だけではありません。人間が手作業でやっても起きます。ただ、AIに任せると作業が速いぶん、失敗も速く広がります。

lockfile差分を読まずに通す

package.jsonの差分が小さくても、package-lock.jsonでは多くのtransitive dependencyが変わることがあります。レビューでは、差分量だけでなく、runtime dependencyの増減、install script、resolved registry、package managerのバージョン差を見ます。

npm audit fix --forceを便利コマンドとして使う

これは避けます。--forceは、脆弱性対応のために大きな更新を入れる可能性があります。AIに自動で走らせると、脆弱性は減っても互換性が壊れることがあります。

テスト失敗をテスト変更で隠す

依存関係更新後のテスト失敗は、依存先の仕様変更を教えてくれる重要なシグナルです。Claude Codeには、最初からテスト期待値を書き換えさせず、原因分類を先に出させます。

peer dependency警告を軽く見る

peer dependencyは、インストール時に警告で済んでも実行時に壊れることがあります。UIフレームワーク、test runner、plugin ecosystemでは特に注意します。

使用量上限で途中停止する

Claude Codeの利用上限は作業の途中で効くことがあります。長い依存関係更新を1セッションに詰め込むより、Issueを分け、各Issueに入力、実行コマンド、期待結果、承認条件を書くほうが安定します。

実務で使うなら

1. 対象を1つに絞る

   devDependencyのpatch/minorから始めます。

2. Issueに条件を書く

   許可コマンド、承認条件、完了条件を固定します。

3. settingsを置く

   allow、ask、denyでコマンドと秘密情報を分けます。

4. PRで検証

   実行ログ、差分説明、未検証範囲をレビューします。

最初の成功条件は、更新量ではなくレビュー可能性です。

最初の導入単位は、1つのリポジトリ、1つのパッケージ、1つの更新種別にします。おすすめは、devDependencyのpatch/minor更新です。

Issueテンプレート

目的

対象パッケージを安全に更新する。

対象

- package: <package-name>
- update range: patch/minor only
- files expected to change: package.json, package-lock.json

Claude Codeに許可する作業

- npm outdated
- npm audit --json
- npm update <package-name>
- npm ci
- npm run lint
- npm run typecheck
- npm test
- git diff

人間承認が必要な条件

- major updateになる
- npm audit fix --force が必要
- runtime dependencyが増える
- postinstall scriptが増える
- CI/CD、認証、決済、DB、環境変数に触る
- テスト期待値を書き換える

完了条件

- 実行コマンドと結果がPR本文にある
- package.json / lockfile差分の説明がある
- 未検証範囲が明記されている

このテンプレートをAGENTS.mdやCLAUDE.mdの運用ルールと合わせると、エージェントが毎回同じ粒度で作業しやすくなります。チームのAI開発運用全体を整える場合は、AI開発ワークフローカテゴリも導線になります。

レビュー観点

PRレビューでは、次の表を使います。

観点	確認すること
更新理由	脆弱性対応、互換性維持、開発環境更新のどれか
変更範囲	package.json、lockfile、設定、ソース、テスト
コマンド	npm ci、lint、typecheck、test、audit
失敗ログ	失敗したコマンドと再実行結果
互換性	major update、peer dependency、Node/npm version
セキュリティ	install script、外部通信、秘密情報、audit結果
コスト	Claude Code使用量、レビュー時間、CI時間

ベンチマークとしてAIコーディングツールを比較したい場合は、検証・ベンチマークの固定ページに評価設計を集約するのがよいです。料金や機能を横並びで見たい場合は比較表を使います。

FAQ

完結させるか

Claude Codeだけで完結させず、CIと人間レビューを残します。

Proで足りるか

小さな更新なら足りる場合がありますが、長いログは使用量を増やします。

npm以外

pnpmやYarnは公式ドキュメントに合わせてゲートを置き換えます。

audit通過

既知脆弱性以外の互換性、ライセンス、運用影響は別途確認します。

迷ったら、権限、ゲート、承認境界へ戻ります。

Claude Codeだけで依存関係更新を完結してよいですか

完結させないほうが安全です。Claude Codeには調査、差分作成、ログ読解を任せ、CIと人間レビューでマージ可否を決めます。

Proプランで足りますか

小さなリポジトリの短い更新なら足りることがあります。ただし、長いログ、複数パッケージ、E2E失敗、changelog確認を含むと使用量を消費します。公式ヘルプではPro/Max/APIで利用上限や課金前提が分かれるため、作業量が大きいチームはMax、API、Team/Enterpriseの条件を確認してください。

npm以外のpnpmやYarnでも同じですか

考え方は近いですが、コマンド、lockfile、workspace、auditの挙動は違います。この記事の具体例はnpm向けです。pnpmやYarnでは、それぞれの公式ドキュメントに合わせてゲートを置き換えてください。

MCPを使って依存関係更新を自動化すべきですか

最初からMCPで広げる必要はありません。MCPを使うなら、read-onlyの情報取得から始め、書き込みTool、外部API、チケット更新、PR作成は人間承認を挟みます。MCP全般の論点はMCPカテゴリで追う想定です。

npm auditが通れば安全ですか

安全とは言い切れません。npm auditは既知の脆弱性を検出する助けになりますが、悪意ある新規パッケージ、ライセンス、互換性、運用上の影響までは別途確認が必要です。

次に読むなら

参照した主な情報源

• Claude Code overview
• Claude Code settings
• Claude Code common workflows
• Claude Code CLI reference
• Claude Code security
• Claude Code データ使用
• Using Claude Code with your Pro or Max plan
• About Claude's Max Plan Usage
• npm outdated
• npm update
• npm ci
• npm audit

更新履歴

1. 2026年5月31日

   Claude Code 2.1.138、Node.js v25.9.0、npm 11.12.1と公式情報を確認して初版を作成しました。

導入時には、Claude Codeとnpmの公式情報を再確認してください。

• 2026年5月31日: Claude Code 2.1.138、Node.js v25.9.0、npm 11.12.1のローカル確認と、Anthropic/npm公式情報の確認にもとづいて初版を作成しました。