adding-dependencies

依存関係の追加

必須の事前知識： principal-engineering スキル。

概要

依存関係は、コード片ではなく採用する人材です。機能とともに、その不具合、リリースのペース、推移的な依存関係のツリー、そしてメンテナーの対応余力もついてきます。基本原則は、すでにあるものを使い切り、導入するものを審査し、導入したもののバージョンを固定し、その理由を記録することです。

すでにあるものを使い切る

リストを上から順に確認し、要件を満たす最初のレベルで止めてください。既存の依存関係で難しい部分を処理し、その周囲に数行の独自コードを加えるなど、複数のレベルを組み合わせるのが適切な場合もよくあります。

1. その必要性自体。 仮定上の必要性は必要性ではありません。省略し、その旨を一文で伝えてください。
2. このコードベース。 数ファイル先にあるヘルパー、型、パターンで対応できるなら、それを再利用してください。リポジトリにすでにあるものを複製することは、データに関して keeping-one-source-of-truth が禁じている不具合です。
3. 標準ライブラリ。 重複するパッケージをインストールする前に、標準ライブラリの一覧を確認してください。
4. プラットフォーム。 アプリケーションコードよりデータベースの制約を、ウィジェットライブラリよりネイティブコントロールを、ラッパーよりランタイム自体のプリミティブを優先してください。
5. プロジェクトがすでに導入している依存関係。 その推移的な依存関係のツリーには、すでにコストがかかっています。境界は2つあります。使い始めた推移的依存関係は、新たな直接依存関係です。宣言し、すでに解決済みのバージョンに固定し、コードがすでに配布されているため簡易的に審査してください。再利用する依存関係がどの区分をまたぐか確認してください。開発ツールの推移的依存関係をランタイムに昇格すると、コストは CI だけでなく、すべての利用者のインストールに及びます。
6. 独自のコードを数行書く。 本当に20行で済むなら、他人のリポジトリを引き受けるより、20行のコードを自分で管理するほうがよいでしょう。
7. 上記6つすべてを確認した後に限り： 以下の基準で審査した新しい依存関係を導入します。

導入する依存関係の審査

• 採用に伴うコスト全体を見積もる：追加される推移的依存関係のツリー、インストールとビルドの負荷、プロジェクトとのライセンスの適合性、セキュリティ履歴（勧告と、スキャナーを実行できる場合はサプライチェーンのスコア）。
• 活動状況を確認する：最近のリリース、課題への対応方法、マージできる人の数を確認してください。重要な役割を担うパッケージを、疲弊した所有者1人に頼るのは、選択するリスクです。
• 呼び出す部分を読む：README の約束ではなく、依存する API の範囲と、その失敗モードを確認してください。他者のコードにも、根拠に基づく確認が必要です。
• 40の機能を持つフレームワークより、1つの仕事に特化したツールを優先する：残りの39の機能も、負荷と攻撃対象領域に含まれてしまいます。
• 判断を記録する。 新しい依存関係の導入は判断です。用途、比較検討した他の選択肢、そして依存関係を削除する条件を記録してください（導入済みの場合は recording-decisions を使用）。

依存関係に関する方針

依存関係の許容範囲は、プロジェクトがリスク区分と同様に定めるものです。完全な自己完結型（外部コードを全面的に禁止するのが妥当なアプリもあります）、厳選した許可リスト、または審査して追加する方式があります。プロジェクトのルールまたは CLAUDE.md に記載されています。どちらにも記載がない場合は、システムが何に依存してはならないかを確認し、その回答を方針として扱ってください。都合が悪くても方針を守ってください。方針の変更は記録すべき判断であり、npm のインストールではありません。

方針が明文化されていないからといって、必ずしも作業を止める必要はありません。今すぐ誰も回答できない場合は、仮定した方針を明示して作業を進め、その仮定を判断の記録に残し、担当者を決めて方針を明文化する課題を管理してください。

バージョンを固定し、検証する

• ロックファイルをコミットし、バージョンを固定してください。CI やベースイメージでバージョンを固定しない latest は、他人の時計で時限爆弾が動いているようなものです。
• アップデートも他の変更と同じように扱います。メジャーバージョンを上げる前に、リリースノートを必ず読んでください（破壊的変更と移行方法を最初に確認します）。アップデートした依存関係に対してテストを実行してください（testing-changes）。メジャーバージョンの更新は個別のコミットにして、変更履歴を読みやすく保ってください。パッチバージョンの更新はまとめてもかまいません。
• ベンダーコードには、出所とバージョンをツリー内に記録してください。いつのものか分からないコードは更新できません。

削除

• 役目がなくなった依存関係は、その役目を削除した変更と同時に取り除きます。「念のため」残すパッケージは、レベル 1 の推測上の必要性を逆方向から見たものです。
• 依存関係の呼び出し箇所が小さなもの 1 つだけになったら、その数行を自分たちで実装することを検討してください。
• メンテナンスされていないものの、なくてはならない依存関係は、希望的観測ではなく、担当者と計画を定めたリスク項目です。

よくある間違い

• 小さなユーティリティにすぐ頼ること。ツリーは大きな決断で育つのではなく、小さなパッケージが 1 つずつ、どれも個別には妥当に見える形で加わることで育ちます。
• 1 つの関数を呼び出すためだけにフレームワークをインストールすること。
• パッケージの内部実装やプライベートパスに依存すること。保証されるのは公開された契約だけです。
• 推移的依存関係を自分のもののようにインポートすること。今日、依存関係として宣言されていないものは、次回ロックファイルを更新した際になくなる可能性があります。必要なら、自分で宣言してください。
• リポジトリにすでにあるコードを読むのを避けるために依存関係を追加すること（レベル 2 を飛ばしています）。
• 出所を確認せずにベンダリングし、コピー元のバージョンがわからなくなること。
• すべてを一度に更新してから、どの更新でビルドが壊れたのかを見つけるために二分探索すること。