dev-dependency-management

依存関係の管理

クイックリファレンス

タスク	使用するもの
エコシステムのデフォルト設定とパッケージマネージャーの選択	references/ecosystem-guides.md
ロックファイルと CI のインストールポリシー	references/lockfile-management.md
セキュリティスキャン、SBOM、来歴	references/security-scanning.md、assets/automation/template-supply-chain-security.md、assets/automation/template-sbom-vuln-triage-checklist.md
モノレポとワークスペースのポリシー	references/monorepo-patterns.md、assets/nodejs/pnpm-workspace-template.yaml
更新戦略とロールバック	references/update-strategies.md、assets/automation/template-dependency-upgrade-playbook.md
依存関係を追加するか避けるかの判断	references/dependency-selection-guide.md、references/transitive-dependencies.md
脆弱性の検出	エコシステムのネイティブな監査ツール（npm audit、pnpm audit、pip-audit、cargo audit、govulncheck、composer audit）または osv-scanner。references/security-scanning.mdを参照
脆弱性のトリアージ、VEX、EU CRA の照会	references/security-scanning.md
ポリシーマニフェストのスコアラー（脆弱性スキャナーではありません。アドバイザリーデータベースを持たず、実際のマニフェストを拒否し、未チェックの入力に対して 2 を終了コードとして返します）	python3 scripts/dep_auditor.py --help。scripts/README.mdに制限事項を記載

別のガイドを参照

• フレームワーク固有のフロントエンドまたはバックエンドの実装：該当するソフトウェアスキルを使用してください。
• 依存関係レイヤーを超える AppSec アーキテクチャ：software-security-appsecを使用してください。
• CI/CD プラットフォームの設計：ops-devops-platformを使用してください。

ワークフロー

1. すでに導入されているエコシステム、パッケージマネージャー、ロックファイル、ラッパーの規約を確認します。
2. 追加、削除、バージョン固定、更新、監査、移行のうち、最小限で安全な変更を決定します。
3. ロックファイル、セキュリティ、モノレポポリシー、更新戦略に必要なガイダンスだけを読み込みます。
4. Node のツールを移行する前に、以下の参照情報を使って対象メジャーバージョンのリリースノートとスクリプト承認設定を確認します。CI のランタイムおよび必要なネイティブビルドと比較してください。
5. 再現性の確認、ロールバックの注意事項、監査または SBOM に関する追加対応を仕上げます。

アップグレードの証明とロールバック一式

マニフェストとロックファイルは、一体の変更単位として扱います。アップグレードの前に、解決されたバージョン、整合性／ソースメタデータ、推移的依存関係の差分、インストールスクリプトの差分、および影響を受ける経路を保護するビルド／テスト／ランタイムの検証手順を正確に記録します。要求された直接依存関係に問題がなさそうに見える場合でも、新たに導入されたパッケージとライフサイクルスクリプトを確認してください。

ロールバックの手順では、マニフェストとロックファイルの両方を既知のペアに戻し、キャッシュ、生成されたクライアント、データベースの状態、または永続化されたワイヤ形式によって、コードのロールバックだけでは不十分になるかどうかを明記する必要があります。状態を保持するアップグレードやプロトコルを変更するアップグレードでは、展開前に前方互換性のある移行、またはテスト済みのダウングレード経路を必須とします。新しいバージョンがすでにデータを書き込んだり外部契約を変更したりしている場合、「依存関係のバージョン更新を元に戻す」だけでは完全なロールバック計画になりません。

基本的な判断

パッケージマネージャーのデフォルト設定

エコシステム	新規リポジトリのデフォルト	バージョンの確認方法	主な制約
Node	互換性の要件から npm が適している場合を除き、pnpm	npm view pnpm dist-tags（新しいメジャーバージョンがデフォルト以外のタグで公開される場合があります）	pnpm 11 では onlyBuiltDependencies が削除され、allowBuilds に置き換えられました。CI ポリシーを設定する前に、対象のメジャーバージョンのランタイムとインストール方法についてはリリースノートを、スクリプトの承認についてはビルド設定を確認してください
Python	uv	uv のリリースノート	API の安定性を約束する前に、uv のバージョンがまだ 0.x かどうか確認してください
Rust	Cargo	固定された rust-toolchain.toml	アプリでは Cargo.lock をコミットしてください
Go	go modules	go.mod 内の go / toolchain 行	go.mod と go.sum を正とします
Java	Maven wrapper または Gradle wrapper	wrapper のプロパティ	wrapper と BOM またはバージョンカタログを使用します
.NET	PackageReference	global.json による SDK の固定	packages.config より PackageReference を優先します
PHP	Composer	composer.json の config.platform	アプリでは composer.lock をコミットしてください

エコシステムとしての理論上の純粋さより、リポジトリ内での一貫性を重視してください。

ロックファイルとツールチェーンのポリシー

最低限のルール：

• アプリケーションのロックファイルをコミットする
• CI ではロックファイルを厳密に使用してインストールする
• ロックファイルを手作業で編集しない
• 1 つのパッケージグラフに複数のロックファイルを持たせない
• バージョンが固定されていないグローバルインストールより、リポジトリ内の wrapper またはツールチェーンファイルを優先する

ルール：rules/deps/lockfiles.md は、Claude が該当するファイルを編集する際に、この不変条件を読み込みます。

更新戦略

デフォルトの更新頻度：

• パッチ：小規模かつ頻繁に更新する
• マイナー：まとめて更新し、テストする
• メジャー：リリースノートを確認し、ロールバック計画を立てて個別に更新する
• セキュリティ：到達可能性と悪用の証拠に基づいて優先順位を付け（まず KEV リストへの掲載を確認し、EPSS は悪用可能性の指標として、CVSS は深刻度の指標としてのみ使用する）、not_affected の判定結果は根拠を添えて VEX ステートメントとして記録してください。脆弱性のトリアージを参照してください

サプライチェーン管理

次を使用します。

• 可能な場合は公式レジストリを使用します
• サポートされている場合は、プロベナンスまたは署名を検証します
• リリース成果物の SBOM を生成し、顧客または規制当局が求める最小限の要素を含めます（確認手順はreferences/security-scanning.mdを参照）
• インストールスクリプトまたはビルドスクリプトを明示的にレビューします
• ソースコードだけでなく、出荷するすべての成果物に対してビルド時の静的ゲートを設けます。このゲートでは、パッケージまたはバイナリと、それにバンドルされるすべてのもの（ベンダー管理および静的リンクされた依存関係、プラグイン、拡張機能またはレシピのマニフェスト、テンプレート）を対象にします。公開前に、ライセンスが許可リストに含まれているか、既知のアドバイザリがないか、許可されたソースから取得されているか（ロックファイルを回避する git またはパス依存関係がないか）を確認し、バンドルされたマニフェストのスキーマを検証します。検査に失敗した成果物はリリースチャネルに到達しません。cargo-deny の deny.toml のようなポリシーファイルでこれを表現できます
• オーバーライド、解決、臨時のバージョン固定に有効期限を設けます
• リリースから一定期間を置いてから利用するようにします（pnpm の minimumReleaseAge、Renovate の minimumReleaseAge、Dependabot の cooldown）。公開直後のパッケージを利用しないための対策です。過去には、削除されるまで数時間しか公開されていなかった npm の侵害事例も複数あるため、これは対策の一層であり、根本的な解決策ではありません（references/security-scanning.mdのインシデントのパターンを参照）
• 依存関係の混同を防ぐ対策を講じます。内部パッケージにはすべてスコープを指定し、組織スコープのパッケージはすべて使用前に監査します
• EU 市場：EU でデジタル要素を含む製品を出荷する場合、トリアージのワークフローを設計する前に、サイバーレジリエンス法（規則（EU）2024/2847）の脆弱性報告義務のうち、自社に適用されるものを確認してください。EU サイバーレジリエンス法の確認を参照してください
• npm のメジャーバージョンを採用する前に、依存関係のライフサイクルスクリプトの承認と git／リモート依存関係のデフォルト設定について、バージョン別の設定ドキュメントと変更履歴を確認します。CI で必要なネイティブビルドとソースを確認し、すべてのスクリプトを有効にするのではなく、承認項目を個別にレビューします。

AI 生成の依存関係によるリスク

AI が提案したパッケージを受け入れる前に、次を確認します。

• 実在すること
• タイポスクワッティングのリスクがないこと
• メンテナンス状況とリリース頻度
• 実現可能な場合は、標準ライブラリまたは既存の依存関係を優先すること
• 新しいパッケージと同じ監査およびレビューのワークフローを実施すること

ルール：rules/common/dependencies.md は、すべてのコーディングセッションでこの不変条件を読み込みます。

出力モード

次のいずれかをデフォルトとして使用します。

• 依存関係ポリシーの概要： マネージャーの選択、ロックファイルのルール、更新頻度、セキュリティ管理。
• アップグレード計画： 対象範囲、バッチ化、テスト、ロールバック、監査のフォローアップ。
• 依存関係の監査： 健全性のリスク、メンテナンスされていないパッケージ、グラフの複雑さ、修正の優先順位。
• モノレポの依存関係戦略： ワークスペースモデル、共有ポリシー、更新の自動化ルール。

よくある落とし穴

• 推移的依存関係やセキュリティ上重要なパッケージをアップグレードする際、修正が本番環境の成果物に実際に反映されるか確認しないこと。

• ラッパー、ロックファイル、パッケージマネージャーのアップグレードを一度に行うこと。これにより、ロールバックや原因の特定がはるかに難しくなります。

• postinstall スクリプト、peer deps、ネイティブビルドが関わる場合に、モノレポのホイスティングやワークスペースの重複排除は無害だと思い込むこと。

• 削除の担当者、有効期限、再テストのトリガーを定めずに、臨時のバージョン固定やオーバーライドを受け入れること。

• プロベナンス、インストールスクリプト、リリースプロセスが未レビューのまま、SBOM の生成だけでサプライチェーン管理が完了したとみなすこと。

• dep_auditor.py の実行結果がクリーンであることを監査とみなすこと。このツールが読み取るのは、自己申告されたフラグのみです。入力には、明示的な依存関係リスト（依存関係のないエコシステムには [] を使用）、ブール値のポリシーフラグ、指定する場合は 0 以上の整数の経過日数、そして未来の日付ではないスキャン日が必要です。不正な宣言がある場合は、終了コード 2 で終了します。

参考資料

ファイル	内容
references/ecosystem-guides.md	Node、Python、Rust、Go、Java、.NET、PHP 向けのエコシステム別パッケージマネージャーの既定値、CI インストールコマンド、注意点
references/lockfile-management.md	ロックファイルの一覧、基本原則、エコシステム別の厳密なインストールコマンド、CI のルール、差異の解消方法
references/security-scanning.md	ネイティブの監査コマンド、SBOM の生成、プロベナンス制御、Dependabot/Renovate の使用方法、トリアージのワークフロー
references/monorepo-patterns.md	JS/TS ワークスペースの既定値、pnpm のサプライチェーン設定、ポリグロット構成、バージョン管理
references/dependency-selection-guide.md	追加・回避の判断基準、依存関係グラフの調査コマンド、AI が提案したパッケージのチェックリスト
references/update-strategies.md	更新頻度の表、リスク別の一括処理ワークフロー、ボットのポリシー、ロールバックのルール
references/transitive-dependencies.md	依存関係ツリーの調査、オーバーライドのパターン、重複排除、解決判断ツリー
references/license-compliance.md	ライセンスリスクの表、GPL の判断ツリー、自動化ツール、CI 統合、SBOM 生成コマンド
references/version-conflict-resolution.md	競合の種類、パッケージマネージャー別の診断コマンド、強制解決の構文、pnpm カタログ
references/container-dependency-patterns.md	マルチステージビルドのパターン、レイヤーキャッシュ、脆弱性スキャン（Trivy/Grype）、再現可能なベースイメージの固定
references/semver-guide.md	npm、Python、Cargo の SemVer 制約構文とよくある落とし穴
references/anti-patterns.md	重大度が高いアンチパターンおよび中程度のアンチパターンと、その修正例

厳選したソースリンクは data/sources.json にあります。

ナビゲーション

• アセット： assets/nodejs/package-json-template.json、assets/nodejs/npmrc-template.txt、assets/nodejs/pnpm-workspace-template.yaml、assets/python/pyproject-toml-template.toml、assets/automation/dependabot-config.yml、assets/automation/renovate-config.json、assets/automation/audit-checklist.md、assets/automation/template-dependency-upgrade-playbook.md、assets/automation/template-supply-chain-security.md、assets/automation/template-sbom-vuln-triage-checklist.md
• スクリプトとサンプル： scripts/dep_auditor.py、scripts/README.md、data/sample-dependency-manifest.example.json

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または代替として利用できるファイルがそれだけの場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に値するパターン、再発を防ぐべき誤り、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを 1 つ追記してください。SKILL.md 自体は変更しないでください。