はじめに
「AIがコードを書く時代に、IDP(Internal Developer Portal)を作る意味はあるのか」という問いから始めて、Backstageを題材に、7本の記事を書いてきました。結論を先に言うと、ポータルを人間が開く頻度は減っていきますが、組織固有のコンテキスト、アーキテクチャ標準、ガードレールとしての役割は残り、むしろAIエージェントが参照する基盤として重要になる、というのがシリーズ全体の主張です。
記事が7本に増えたため、どの順で読めばよいか、どこから手をつければよいかが分かりにくくなってきました。この記事はその入口として、シリーズ全体を1枚の地図に整理します。各論点の詳細は個別の記事に任せ、ここでは「どの層に何を置くか」「どの順で着手するか」に絞ります。
なお、このシリーズは設計原則と業界の公開情報にもとづく整理であり、実装コードを伴う検証ではありません。この点は、記事の最後にも改めて触れます。
前提：IDPの価値は「開く頻度」では測れない
シリーズの出発点は、次の整理でした(①AIが開発する時代にIDPを作る意味はあるのか？)。
IDPの価値は、大きく2つの側面に分けられます。1つはUIとしての側面(画面を開いてクリックする体験)、もう1つは組織固有のコンテキスト・標準・ガードレールとしての側面です。AIがUIを作れるようになり、人間がポータルを開く機会が減っても、後者の価値はなくなりません。AIエージェントが正しく動くには、「このサービスは誰が持っているのか」「どの標準に従うべきか」「どこまで自動でやってよいか」といった情報をどこかから読み取る必要があるからです。
以降の6本は、この「後者の価値」を実際にどう作り込むか、という話です。
全体像：4つの層で整理する
7本の記事は、次の4つの層に整理できます。
| 層 | 何を扱うか | 記事 |
|---|---|---|
| コンテキスト層 | AIエージェントに読ませる情報そのもの | ②④ |
| 経路層 | エージェントがその情報にアクセスする入口 | ③ |
| 実行・権限層 | エージェントが実際に操作を行う部分と、その権限 | ⑤⑥ |
| 統制層 | 上記すべての判断ロジックを一箇所に集約する仕組み | ⑦ |
各層の要点
コンテキスト層：エージェントに何を読ませるか
カタログ設計(②AI Ready な IDP の設計とは？)
AIエージェント向けのルールやスキルは、デプロイされるわけでも稼働するわけでもない静的なコンテキストです。既存のComponentなどの種別に混在させるとカタログの検索性が落ちるため、専用の種別として独立させつつ、ガバナンスの仕組みは既存のカタログ基盤に乗せる、という設計判断を整理しました。annotation namespaceを用途ごとに区切る、公開範囲は既存の権限モデルの延長で管理する、といった点も扱っています。
TechDocs(④Backstageのドキュメントを「AIエージェントが読める形」に構造化する)
カタログ(構造化データ)では表現しきれない「なぜこの構成にしたのか」「障害時にどう対応するか」といった情報は、TechDocsに置きます。ADR、ランブック、ゴールデンパス・標準ドキュメントはAIエージェントにとって価値が高く、システム図は説明テキストとセットで管理しないと検索対象として機能しにくい、という優先度づけを整理しました。
経路層：どう公開するか
MCP(③BackstageをMCPサーバーとして公開する際に何を考慮すべきか？)
MCPは接続の規約であり、認証・レート制限・監査ログといった運用上の安全対策は仕様の範囲外です。静的トークンでの検証からサービスアカウントベースの運用へ移ること、読み取りツールと書き込みツールを最初から分けること、エージェント特有のリトライ挙動を前提にレート制限を設計すること、MCP標準のログに頼らず監査ログを別途整えること、を扱いました。
実行・権限層：エージェントに何をさせるか
Scaffolder(⑤ScaffolderをAIエージェント向けのアクションゲートウェイにする)
人間向けのフォーム入力ツールだったScaffolderが、Actions RegistryとMCPを通じて、エージェントが呼び出せるアクションとして再解釈されつつあります。人間向けのバリデーションをそのまま流用せず、エラーメッセージの扱い、承認フローの明示、dry-runの活用、標準ドキュメントとの接続を見直す、という論点を整理しました。
GitHub操作の権限(⑥AIエージェントのGitHub操作をどう安全に設計するか)
Scaffolderはもともとリポジトリ作成などの強い権限を前提にした設計です。個人アクセストークンから用途別のGitHub Appへ移ること、認証情報をエージェント固定ではなく実行者本人の権限に紐づけること、RBACを有効にしただけでは権限が絞られているとは限らないこと、読み込みと書き込みのフローを分離することを扱いました。
統制層：判断ロジックをどこに置くか
OPA(⑦カタログデータを動的なポリシーソースとしてOPAと連携させる)
③〜⑥で個別に扱ってきた「読み書き分離」「承認フロー」「権限の絞り込み」を、個々の実装に埋め込まず、OPAという一元的なポリシーエンジンに集約する設計です。カタログのオーナー情報、ライフサイクル、annotation namespaceをそのままポリシー判断の入力として再利用できる点が、BackstageとOPAを組み合わせる利点です。
シリーズを貫く3つの設計原則
7本を通して、繰り返し出てきた考え方が3つあります。
読み取りと書き込みを分ける
MCPのツール設計(③)、Scaffolderの実行(⑤)、GitHubの権限(⑥)のいずれでも、読み取り系は広く、書き込み系は厳格に、という線引きが出てきました。権限を絞ることは、セキュリティのためであると同時に、エージェントに渡す情報を絞って挙動を安定させるためでもあります。
段階導入する
開発環境限定・読み取り専用から始め、本番の読み取り、書き込み解禁へと広げる、という順序は、③⑤⑥で形を変えながら繰り返し登場しました。一足飛びに書き込み権限まで開放しないことで、問題が起きたときの影響範囲を小さく保てます。
判断ロジックを個々の実装に埋め込まず、集約する
どのエージェントがどの情報にどこまでアクセスできるかを、エージェントやツールの実装側ではなく、カタログ(②)とポリシー(⑦)の側に置く、という考え方です。複数チームがそれぞれ独自にエージェントを作っても、統制が効く状態を保つための土台になります。
どこから着手するか
4層すべてを同時に始める必要はありません。シリーズの内容を踏まえると、次の順序が収まりがよいと考えています。
-
annotation namespaceとカタログ種別の設計(②)
コストが小さく、他のすべての層の土台になります。判断ロジックをカタログ側に置く、という原則の最初の一歩でもあります。 -
TechDocsの整備(④)
まずADRとランブックから。エージェントが「なぜ」を参照できる状態を作ります。 -
読み取り専用・開発環境限定でのMCP公開(③)
本番にはMCPサーバー自体を存在させない構成から始め、認証・レート制限・監査ログの運用を確かめます。 -
書き込み系(⑤⑥)は、権限設計と承認フローが固まってから
GitHub Appへの移行、実行者本人の権限への紐づけ、RBACの既定ポリシーの見直しを先に済ませます。 -
OPAによる統制(⑦)は、判断ロジックが複数箇所に散らばってきた段階で
最初から導入する必要はありません。ガードレールがプラグインやアクションごとに個別実装され、管理しきれなくなってきた時点で集約を検討するのが現実的です。
これはあくまで本シリーズの整理にもとづく案であり、組織のAIエージェント活用の成熟度やBackstageの運用状況によって、適切な順序は変わります。
このシリーズの限界
最後に、このシリーズの限界を明記しておきます。
- 各記事は、設計原則と業界の公開情報(コミュニティの議論、ベンダーのブログ、公式ドキュメントなど)にもとづく整理であり、実際のBackstage環境で実装・検証した結果ではありません。実装コードも扱っていません。
- 扱った機能の多く(Actions Registry、MCP統合、Dynamic Client Registration、AIContext種別のRFCなど)は、2026年時点でまだ発展途上です。今後のアップデートで、設計の前提が変わる可能性があります。
- 組織ごとに状況は異なるため、記事で挙げた判断軸がそのまま当てはまるとは限りません。
実際に手を動かした結果は、別の記事として改めてまとめる予定です。
まとめ
- IDPの価値は「人が開く頻度」ではなく、組織のコンテキスト・標準・ガードレールを、人とAIエージェントの双方に提供する基盤としての役割に移っていきます。
- シリーズ7本は、コンテキスト層(②④)、経路層(③)、実行・権限層(⑤⑥)、統制層(⑦)の4層に整理できます。
- 全体を貫く設計原則は、読み取りと書き込みを分けること、段階導入すること、判断ロジックを集約することの3つです。
- 着手は、annotation namespaceとカタログ種別の設計から始め、書き込み系とOPAによる統制は後から、という順序が収まりがよいと考えています。
シリーズ一覧
- AIが開発する時代にIDPを作る意味はあるのか？
- AI Ready な IDP の設計とは？
- BackstageをMCPサーバーとして公開する際に何を考慮すべきか？
- Backstageのドキュメントを「AIエージェントが読める形」に構造化する
- ScaffolderをAIエージェント向けのアクションゲートウェイにする
- AIエージェントのGitHub操作をどう安全に設計するか
- カタログデータを動的なポリシーソースとしてOPAと連携させる
注意事項
本ブログに掲載している内容は、私個人の見解であり、
所属する組織の立場や戦略、意見を代表するものではありません。
あくまでエンジニアとしての経験や考えを発信していますので、ご了承ください。