AIコーディングエージェント（ClaudeやCursorなど、自然言語の指示からコードを生成・修正するツール）を本番システムの改修に使い始めたインフラ担当者やSREに向けた内容です。生成されたコードが動くかどうかより、変更が3ステップ先の別サービスをどう壊すかを、どう検知する仕組みにするかを整理します。
単一のマイクロサービスで新規コンポーネントを書かせる分には、AIエージェントは数秒で動くコードを出します。問題は、決済APIのフィールド1つを変えたときに、どのサービスがそれを参照しているかをエージェント自身が把握できない点です。
たとえば注文金額を表すtotalというフィールドがあるとします。型定義の名前をtotalCentsに変えれば、TypeScriptの型チェックが呼び出し元のエラーを検出してくれます。ですが名前はそのままに、単位だけをドルからセントに変えるとどうなるでしょうか。コンパイルは通ります。しかしチェックアウト画面が12.99を$12.99と表示すべきところ、1299を受け取って$1,299.00と表示してしまいます。型エラーゼロのまま、本番で金額表示が壊れる典型パターンです。
この手のバグは、リポジトリのソースコードだけを見ていては検知できません。エージェントに渡すコンテキストが「ファイルツリー」なのか「依存関係グラフ」なのかで、事故の発見タイミングが大きく変わります。
どんな場面でこの判断が必要になるか
AIエージェントにコード修正を任せる範囲を広げようとした瞬間に、この判断が必要になります。
単一リポジトリの小さな機能追加なら、既存のCIとレビューで十分にカバーできます。問題は、共有ライブラリ・社内API・複数チームが依存するコンポーネントにエージェントが手を入れ始めたときです。
オンプレ時代の運用では、変更の影響範囲は担当者の頭の中にある「暗黙知」に依存していました。クラウド移行でマイクロサービス化が進み、依存先がチームや契約範囲をまたぐようになると、この暗黙知はもう機能しません。AIエージェントが人間の代わりにコードを書く時代には、その暗黙知を明示的なグラフとして持たせる必要が出てきます。
判断軸
依存関係の可視化範囲
変更の影響が単一リポジトリ内で完結するか、複数リポジトリ・複数ワークスペースにまたがるかを確認します。
社内でnpm workspacesやモノレポ構成（1つのリポジトリで複数パッケージを管理する方式）を使っているなら、Nxのaffected機能やTurborepoのタスクグラフだけでも影響範囲の把握は可能です。逆に、決済APIをフロントエンド・モバイル・パートナー企業のWebhookなど複数リポジトリが個別に参照している構成なら、リポジトリ横断の依存グラフが必要になります。
障害検知のタイミング
型エラーで検知できるか、実行時にしか壊れないかを切り分けます。
先のtotalフィールドの例のように、型は合っているのに意味が変わるケースは、静的解析では拾えません。契約テスト（Contract Test、APIの入出力形式を保証するテスト）やステージング環境でのプレビュー実行が必要になります。この検知タイミングが「デプロイ前」か「デプロイ後の障害対応」かで、事故対応のコストは桁違いに変わります。
運用コストと導入の手間
依存グラフを構築・維持するためのツール導入や運用工数を、既存のCI/CD運用と比較します。
Bitのようなコンポーネントグラフ管理ツールを導入する場合、コンポーネント単位でのバージョン管理・公開・依存追跡の仕組みを新たに設計する必要があります。既存のCIをそのまま使う場合に比べて、初期の学習コストと移行作業が発生する点は見込んでおくべきです。
チーム・組織の境界
影響を受けるコンポーネントの所有者が同じチームか、別チーム・別組織かを確認します。
同一チーム内であれば、Slackなどでの一声で済むこともあります。ですが決済API・在庫API・パートナー向けWebhookのように所有チームが分かれている場合、エージェントが自動で影響範囲を洗い出し、該当チームへの通知やレビュー依頼まで組み込める仕組みがないと、変更の見落としが起きやすくなります。
選択肢の比較
| アプローチ | 依存関係の可視化 | 向いている構成 | 運用コスト |
|---|---|---|---|
| リポジトリツリーのみ | なし（ファイル探索頼み） | 小規模・単一サービス | 低い |
| モノレポ + Nx/Turborepo | ワークスペース内で高い | 単一リポジトリの複数パッケージ | 中程度 |
| コンポーネントグラフ（Bit等） | リポジトリ横断で高い | 複数リポジトリ・複数チーム | やや高い（初期構築が必要） |
リポジトリツリーのみの運用は、エージェントに渡すコンテキストがソースコードのテキストだけになります。差分は生成できても、そのコンポーネントを誰がどこで使っているかはエージェントにはわかりません。
NxやTurborepoのaffectedビルド（変更の影響を受けるパッケージだけを再ビルド・再テストする機能）は、モノレポ内であれば強力です。ただし対象はあくまで同じリポジトリ内のワークスペースに限られます。
コンポーネントグラフ型のアプローチは、公開されたコンポーネントを別のリポジトリやワークスペースが取り込んで使う構成でも、依存関係を追跡できる点が異なります。バージョン管理された単位でコンポーネントを公開・消費する設計を前提にしている点は押さえておく必要があります。
ケース別の推奨
- 単一リポジトリで完結するチーム開発なら、既存のCIとコードレビューにAIエージェントを組み込むだけで十分です。無理にグラフ構築ツールを導入する必要はありません
- モノレポで複数パッケージを管理しているなら、NxやTurborepoのaffectedビルドをCIに組み込み、エージェントが生成した差分の影響範囲だけをテスト対象にする構成が現実的です
- 決済・認証・共通API基盤など複数チーム・複数リポジトリが依存する基盤コンポーネントを扱うなら、コンポーネント単位の依存グラフとステージング環境での自動プレビューを検討する価値があります
- パートナー企業向けAPIやWebhookのように、社外の依存者が存在する契約がある場合は、契約テストを依存グラフの検知ロジックに組み込み、エージェントの変更提案がその契約テストを通過するまでマージしない運用が安全です
あえて見送るべき条件
依存関係グラフの構築は万能ではありません。以下の条件に当てはまる場合は、導入を急がず既存の運用を維持したほうが合理的です。
チーム規模が小さく、コンポーネントの利用状況を数人が把握しきれている場合は、グラフ構築の運用コストが見合わないことがあります。まずは既存のCIログとコードレビューのコメント履歴を振り返り、実際に「型エラーでは検知できなかった障害」がどれだけ発生しているかを確認するところから始めるとよいでしょう。
またリポジトリ構成そのものが流動的で、頻繁にサービス分割・統合を繰り返しているフェーズでは、グラフの定義が追いつかず、かえってメンテナンスコストが増える可能性があります。アーキテクチャがある程度安定してから導入を検討するのが無難です。
まとめ
AIエージェントに任せる変更範囲が広がるほど、リポジトリのソースコードだけでは見えない依存関係が事故の原因になります。
判断のポイントは、依存関係の可視化範囲・障害検知のタイミング・運用コスト・チームの境界という4つの軸です。
まずは自分のプロジェクトで、直近の障害対応ログを振り返ってみてください。型エラーでは検知できず、ステージングや本番で初めて発覚した変更がどれだけあったかを数えるだけでも、依存グラフが必要かどうかの判断材料になります。
単一リポジトリならモノレポツールのaffected機能から試し、複数リポジトリ・複数チームにまたがる基盤コンポーネントがあるなら、コンポーネントグラフとステージング検証の組み合わせを段階的に検討していくのが現実的な進め方です。