dependency-management

依存関係の管理

何に依存するかを決め、依存関係を最新の状態に保ち、アドバイザリに対応し、サプライチェーンのリスクを軽減します。スタックに依存しない原則ですが、具体的な内容はパッケージマネージャーによって異なります。

---

使用する場面

• 新規または既存のプロジェクトで依存関係の健全性を整える
• セキュリティアドバイザリに対応する
• 重要な依存関係をメジャーバージョンアップする
• 新しい依存関係を追加する（評価、決定）
• 依存関係を削除する（クリーンアップ）
• インストール済みのものと、実際に使われているものを監査する
• 更新の頻度とポリシーを設定する
• 更新後にビルドが失敗した原因を診断する

使用しない場面

• 一般的なコードレビュー（code-review-web を使用）
• インフラストラクチャの脆弱性スキャン（security-baseline を使用）
• ベンダーやサービスの契約を固定する（vendor-evaluation を使用）
• 依存関係がパフォーマンスに与える影響（performance-optimization を使用）

---

必要な入力

• 使用中のパッケージマネージャーとロックファイル（npm、yarn、pnpm、pip、gem、composer など）
• 現在の依存関係一覧（本番用と開発用）
• 現在のアドバイザリ（監査を実行し、Snyk、Dependabot などのサービスを確認）
• 更新履歴（重要な依存関係を最後に更新した時期）
• リスクプロファイル（本番環境での重要度、変更への許容度）

---

フレームワーク：依存関係の4つのカテゴリー

すべての依存関係は、次のいずれかに分類されます。このカテゴリーによってポリシーが決まります。

カテゴリー1：重要なランタイム依存関係

本番環境で実行され、障害が起きるとシステムが停止するコードです。

例：フレームワーク、データベースドライバー、決済 SDK、認証ライブラリ。

ポリシー：

• 更新頻度： マイナー更新は毎月、メジャー更新は計画のうえ四半期ごと
• セキュリティ： アドバイザリの公開から24～72時間以内にパッチを適用し、重大な場合は24時間以内に適用
• バージョン固定： バージョンを厳密に固定するか、狭い範囲を指定
• 審査： 採用前に徹底的に評価

カテゴリー2：本番環境を支援するランタイム依存関係

本番環境で実行されますが、置き換え可能、または重要度の低いコードです。

例：ユーティリティライブラリ、フォーマット処理、コアではない連携機能。

ポリシー：

• 更新頻度： 重要な依存関係とあわせて毎月更新
• セキュリティ： アドバイザリの公開から1週間以内にパッチを適用
• バージョン固定： 狭い範囲の指定を許容（例：^1.2.3）
• 審査： ある程度評価し、代替案も検討

カテゴリー3：開発／ビルド用

開発中またはビルド時にのみ実行され、本番環境では実行されないコードです。

例：バンドラー、リンター、テストフレームワーク、型チェッカー。

ポリシー：

• 更新頻度： 四半期ごと
• セキュリティ： 1週間以内にパッチを適用（重要性は変わりません。サプライチェーン攻撃はビルドツールを標的にします）
• バージョン固定： 範囲指定を許容
• 審査： 簡易的に実施。開発ツールの不具合はすぐに表面化します

カテゴリー4：任意／個人用の開発ツール

個々の開発者が使用し、共有の開発環境には含まれないツールです。

プロジェクトレベルでは通常管理しません。網羅性のために記載しています。

---

フレームワーク：5つのリスク評価軸

依存関係を評価する際は、次の点を考慮してください。

評価軸1：メンテナンス状況

• 最終コミット日（数か月前の場合は懸念材料です）
• 未解決の課題の数と経過期間
• メンテナーの人数
• スポンサーシップまたは商業的な後ろ盾
• ロードマップの明確さ

1年間放置されている依存関係は、いずれ問題が表面化しかねない負債です。

評価軸2：影響範囲

• パッケージのサイズ
• 推移的依存関係の数
• バンドルに占めるサイズ（クライアント側の場合）
• 必要な権限（ファイルシステム、ネットワークなど）

推移的依存関係を50個取り込む小さな依存関係は、その50個すべてに相当する影響範囲を持ちます。

評価軸3：置き換えやすさ

• 削除するのはどれほど難しいか
• 代替案はあるか
• 機能を内製できるか
• API は標準的か、慣用的か

置き換えられない依存関係は、そのメンテナーに与えてしまった交渉力です。

評価軸4：信頼性

• メンテナーや組織の評判
• コードの品質（ソースをざっと確認）
• ライセンス（GPL、MIT、BSD、プロプライエタリ、なし）
• セキュリティ問題の履歴
• サプライチェーンの運用（署名付きリリース、公開時の2FA）

ディメンション 5：コスト

• 評価、統合、保守にかかる時間
• 破壊的変更のリスク
• ロックファイルのエントロピー
• 潜在的なセキュリティ上の露出
• バンドルサイズへの影響（クライアント側の場合）

依存関係にはすべてコストがかかります。無料のパッケージも無料ではありません。

---

ワークフロー

ステップ 1：一覧を作成する

依存関係の一覧を作成します。

# npm/yarn/pnpm
npm ls --all --json

# pip
pip list

# gem  
bundle list

各トップレベル依存関係を、重要／補助／開発用に分類します。推移的依存関係については、問題が発生しない限り、通常は個別に管理する必要はありません。

ステップ 2：監査する

セキュリティ監査を実行します。

npm audit
yarn npm audit  # Yarn 2+; "yarn audit" on Yarn 1 Classic
pip-audit
bundle audit

各検出項目について、次を確認します。

• 深刻度（重大、高、中、低）
• パッケージとバージョン
• 修正が利用可能か
• 直接依存か推移的依存か

ステップ 3：分類して優先順位を付ける

深刻度	直接依存	間接依存
重大	本日中にパッチを適用	今週中にパッチを適用（修正がある場合。ない場合は追跡）
高	今週中にパッチを適用	今月中にパッチを適用
中	今月中にパッチを適用	追跡し、次回の対応でパッチを適用
低	追跡	追跡

本番コードにおける重大および高の脆弱性は緊急事態です。低および中の脆弱性は、予定を立てて対応します。

ステップ 4：修正をマージする前にテストする

パッチレベルの更新でも、問題を引き起こす可能性があります。重要な依存関係については、次を行います。

• テストスイート全体を実行する
• ステージング環境でスモークテストを実施する
• 展開後の監視状況を確認する

補助用および開発用の依存関係については、次を行います。

• テストスイートを実行する
• テスト失敗の調査は問題ありませんが、問題があると分かっている更新はマージしないでください

ステップ 5：メジャーバージョンのアップグレードを計画する

メジャーバージョンでは問題が発生します。急いで対応するのではなく、計画を立ててください。

メジャーアップグレードごとに、次を行います。

• 変更履歴と移行ガイドを読む
• 移行に必要な作業を見積もる
• 作業を予定に組み込む（締め切りに追われているときに行わない）
• ブランチを作成し、十分にテストする
• 重要な依存関係の場合は、段階的な展開を計画する

メジャーバージョンへのアップグレードをいつまでも先延ばしにしないでください。待つ期間が長くなるほど、アップグレードは大変になります。

ステップ 6：ポリシーを定める

次の内容を文書化します。

• 更新の頻度（例：毎月のレビュー、四半期ごとのアップグレード）
• セキュリティ対応の SLA（例：重大な問題には 24 時間以内に対応）
• 新しい依存関係の承認者（誰が承認するか）
• 削除の基準（どのような場合に依存関係を削除するか）
• バージョン固定の方針（完全固定、狭い範囲、広い範囲）

チームのメンバーが入れ替わっても残るのがポリシーです。ポリシーがなければ、依存関係の管理は場当たり的で混乱した作業になります。

ステップ 7：自動化する

• 自動更新 PR には Renovate または Dependabot を使用する
• すべての PR で CI による監査を実行する
• 重大な勧告がある場合はマージをブロックする（誤検出の場合の例外対応手段を用意する）
• インストール済みパッケージに関する勧告を通知する
• PR レビューでロックファイルの差分を確認する

自動化によって手作業を減らせます。手動での確認は規模の拡大に対応できません。

ステップ 8：定期的に使用状況を監査する

四半期ごとに、次を確認します。

• インストールされているものの、どこにもインポートされていない依存関係（depcheck のようなツールを実行）
• メジャーバージョンがどれだけ遅れているか（メジャーバージョンで 1～2 以上遅れている場合は、アップグレード計画が必要）
• メンテナンスされていないパッケージ（最終コミットから 1 年以上経過している場合は、置き換えを検討）
• ライセンス監査（利用条件に変更があったか）

使用していないものは削除します。メンテナンスされていないものは置き換えます。

---

新しい依存関係の評価

新しい依存関係を追加する前に、次の質問に答えます。

• これはどのような問題を解決しますか？
• 依存関係を追加せずに解決できますか？（小さな問題なら、多くの場合可能です。）
• どのような代替手段がありますか？
• パッケージは積極的にメンテナンスされていますか？
• インストールサイズとバンドルへの影響はどの程度ですか？
• 推移的依存関係は何ですか？（簡単に確認しておく価値があります。）
• ライセンスは何ですか？
• セキュリティ上の履歴はどうなっていますか？
• どの程度置き換えやすいですか？

原則として、追加しないでください。価値がコストを明らかに上回る場合にのみ追加します。コストには、インストールだけでなく、その後のメンテナンスも含まれます。

---

依存関係の削除

依存関係を削除するときは、次の手順に従います。

• 使用箇所をすべて特定する（コードベースを検索する）
• 使用箇所をそれぞれ置き換える（ネイティブコード、別の依存関係、または何もしない処理を使う）
• package.json または同等のファイルから削除する
• ロックファイルを更新する（インストールを実行する）
• テストが成功することを確認する
• ビルドサイズが小さくなった（または同じまま）ことを確認する
• 変更履歴に削除を記録する

依存関係を削除しても、設定ファイル、CI フック、インポートが残っていることがあります。幅広く検索してください。

---

失敗パターン

更新の周期がない。 依存関係が古くなります。いざアップグレードすると、大変な作業になります。定期的な更新スケジュールを設定してください。

CI で監査が無効になっている。 「警告が多すぎる」という理由で無効にするのではなく、監査を調整してください。既知の誤検知は明示的にホワイトリストに登録してください。

すべてを厳密なバージョンに固定する。 自動パッチ適用が止まり、セキュリティ修正を取り逃します。ロックファイルと併せて、範囲を狭く指定してください。

浮動バージョンを固定せずに使う。 本番環境で latest を使うと、ビルドを再現できません。ロックファイルは必須です。

レビューせずに依存関係を追加する。 「ちょっとしたユーティリティが必要だっただけ」のつもりが、使われていない依存関係が50個も増えてしまいます。新しい依存関係は必ずレビューしてください。

推移的依存関係を無視する。 直接依存するパッケージが、間接依存を50個取り込むことがあります。それぞれがサプライチェーンの攻撃対象になります。トップレベルだけでなく、依存関係ツリー全体を監査してください。

メジャーバージョンを上げてパッチを適用する。 「バグ修正のための更新」のつもりが、メジャーバージョンの更新だったということがあります。無関係な破壊的変更まで発生してしまいます。修正に使うバージョンは慎重に選んでください。

ベンダー同梱ライブラリ。 依存関係の中には、別の依存関係のコピーを同梱するものがあります。監査では検出されません。定期的に確認してください。

ビルド時の依存関係をリスクゼロとして扱う。 ビルドツールは、コードや認証情報にアクセスできます。サプライチェーン攻撃の標的になるため、適切に注意して扱ってください。

リベース計画のないフォーク。 依存関係をフォークして修正すると、その後は自分たちで保守することになります。上流の変更をリベースまたはマージする方法を計画するか、フォークの保守を継続することを決めてください。

ライセンス監査がない。 GPL ライセンスの依存関係を含むプロジェクトを商用製品として出荷すると、コンプライアンス上の問題になります。追加時と四半期ごとにライセンスを監査してください。

更新 PR が積み上がる。 Dependabot の PR が何か月もマージされずに残っています。PR の数を減らすように設定を調整するか、マージのための時間を確保してください。

---

出力形式

依存関係ポリシー文書には、次の内容を含めます。

• 一覧： カテゴリ別の現在の依存関係
• 監査状況： 未解決のアドバイザリ、深刻度、対応計画
• ポリシー： 更新頻度、SLA、バージョン固定、承認
• ツール： 自動化されている項目（Renovate、Dependabot、CI での監査）
• ライセンス監査： 懸念事項の有無
• 四半期レビューのスケジュール： 見直しの時期

---

参考ファイル

• references/upgrade-checklist.md：変更履歴の確認から段階的なロールアウトまで、重要な依存関係をメジャーバージョンにアップグレードするための手順をまとめたチェックリストです。