はじめに
これまでの記事で、Backstageが持つコンテキストは3層に分かれることを扱ってきました。構造化メタデータ（カタログのComponent/API/Resourceなど）、AIエージェント向けの静的コンテキスト（ルール・スキル）、そして非構造化ドキュメント（TechDocs配下のMarkdown文書群）です。前々回はカタログ設計、前回はそれをMCP経由で安全に公開する実務を扱いました。
今回は3層目、TechDocsに何を、どう置くべきかを扱います。ここが整理されていないと、いくらカタログとMCPを整えても、AIエージェントは「なぜこの構成にしたのか」「障害が起きたときにどう対応すべきか」といった、コードやメタデータだけでは分からない情報にたどり着けません。
TechDocsの4カテゴリ
Backstage実務でのTechDocsの使われ方は、大きく4つのカテゴリに整理できます。アーキテクチャチームはADR、システム図、統合パターン、ドメインレベルのドキュメントにTechDocsを使い、運用チームはインシデント対応手順、アラートの意味、復旧手順、ロールバック手順、エスカレーション経路といったランブックを記録し、プラットフォームチームは新規サービスの作り方、可観測性の設定、Kubernetes連携、APIのセキュリティ、CI/CDテンプレートの使い方といったゴールデンパス・標準のドキュメントを扱います。これに加えて、新規参画者向けのオンボーディング資料も一般的な用途です。
このうち「アーキテクチャ関連」は、ADRと図・統合パターンをまとめて1カテゴリとして扱われていますが、AIエージェントにとっての価値はこの2つで大きく異なります。ADRは文章として明確な判断根拠を含む一方、図はそのままでは検索対象として機能しにくいためです。そこで本記事では、この2つを分けて5項目として優先度を整理し直します。
| ドキュメント種別 | 具体例 | AIエージェントにとっての価値 | 優先度の考え方 |
|---|---|---|---|
| ADR（アーキテクチャ決定記録） | なぜこの技術を選んだか、なぜこの構成にしたかの記録 | コード生成・レビュー時に、過去の決定を覆さない判断ができる | 高：決定の背景は人間の頭の中にしかないことが多く、最も欠落しやすい情報 |
| ランブック | インシデント対応手順、アラートの意味、復旧・ロールバック手順、エスカレーション経路 | 障害対応エージェントが一次対応を行う際の直接的な参照先になる | 高：手順が明文化されていないと自動化のしようがない領域 |
| ゴールデンパス・標準ドキュメント | サービスの作り方、CI/CDテンプレートの使い方、APIセキュリティの標準 | Scaffolder経由でのプロジェクト生成や、コード生成時の標準準拠チェックに使える | 高：カタログ設計・MCP実装と直接つながる領域 |
| システム図・統合パターン | サービス間の連携図、ドメインモデル図 | 依存関係の把握、影響範囲の推定に使える。ただし図単体では扱いにくい | 中：テキストでの補足説明の有無で価値が大きく変わる |
| オンボーディング資料 | 環境構築手順、ローカル実行方法 | 新規参画者向けが主眼で、AIエージェントにとっての優先度は相対的に低い | 低〜中：人間向けの色合いが強い |
以下、優先度が高い3つのカテゴリと、扱いに注意が必要な図解について、それぞれもう少し掘り下げます。
ADR：最も欠落しやすい「なぜ」の情報
コードそのものやカタログのメタデータからは、「なぜその技術を選んだか」「なぜ以前の設計を変更したか」といった経緯は読み取れません。AIエージェントがコード生成やレビューを行う際、この経緯を知らないまま作業すると、過去に意図的に避けた選択を無自覚に繰り返してしまうことがあります。
Backstage自体のプロジェクトでも、こうした重要なアーキテクチャ決定はADRとして記録され、決定が上書きされた場合も削除せず「supersededされた」という形で残す運用がとられています。この「消さずに、上書きされた経緯ごと残す」という発想は、AIエージェントに履歴ごと参照させる上でも重要です。最新の決定だけでなく、過去にどう変遷してきたかが分かることで、エージェントは「なぜ今この形なのか」まで踏まえた提案ができるようになります。
ランブック：自動化の土台になる手順書
障害対応をAIエージェントに一部任せる、というシナリオを考えたとき、最初に必要になるのがランブックです。アラートが何を意味するか、どう切り分けるか、どう復旧するか、どこまで自分で対応してよくどこから人間にエスカレーションすべきか、といった情報が明文化されていなければ、エージェントは何もできません。
ここでのポイントは、ランブックを「人間が読んで理解できる文章」として書くだけでなく、「エージェントが手順として実行できる粒度」まで分解して書いておくことです。「ログを確認する」ではなく「どのログを、どのクエリで確認するか」まで踏み込んで書かれているランブックほど、AIエージェントにとっての価値が高くなります。
ゴールデンパス・標準ドキュメント：既存の仕組みとの接続点
ゴールデンパスや標準のドキュメントは、これまでの記事で扱ってきたScaffolderやカタログの設計と直接つながる領域です。「新しいサービスをどう作るか」という標準ドキュメントがTechDocsに整備されていれば、AIエージェントがScaffolderのテンプレートを呼び出す際に、その背景にある標準（なぜこの構成が推奨されるか）まで踏まえた提案ができるようになります。
逆に言えば、ここが手薄なままMCP経由でScaffolderを呼び出せるようにしても、エージェントは「テンプレートを実行できる」だけで、「なぜそのテンプレートが適切か」を判断できません。前回扱った書き込みツールの権限設計とあわせて、その背景にある標準ドキュメントの整備もセットで進める必要があります。
システム図・統合パターン：図だけでは価値を持たない
システム図やドメインモデル図は、人間が全体像をつかむには有用ですが、AIエージェントがそのまま活用できる情報ではありません。画像として置かれているだけの図は、RAGの検索対象としてはほとんど機能しないためです。
図の周辺に、「なぜこの構成なのか」「何が変わったらこの図を更新すべきか」といったテキストでの説明を添えておくことで、初めて検索・参照の対象になります。図を描くこと自体をゴールにせず、図を説明する文章とセットで管理する、という意識が必要です。
構造化するうえでの注意点
カタログとの紐付けを前提に設計する
TechDocsは、各Markdownドキュメントが属するソフトウェアコンポーネントを、カタログのメタデータをもとに判定する仕組みになっています。つまり、ドキュメントがどのサービス・ドメインに属するかをカタログ側で正しく紐付けておくことが、後の検索精度に直結します。前々回扱ったカタログ設計の話が、ここでも前提になります。
「取得可能な情報源」がまだ限定的であることを踏まえる
代表的なRAGプラグインが対応している情報源は、現状カタログとTechDocsに限られています。任意のドキュメント形式を自由に投入できるわけではなく、「TechDocsに書く」という前提を置くこと自体が、実務上は現実的な制約になります。
埋め込み生成のタイミングを設計する
TechDocsの文章をAIエージェントが検索できるようにするには、あらかじめ文章を埋め込み（embedding、文章の意味をベクトルに変換したもの）に変換して保存しておく必要があります。ドキュメント量が多い場合、この埋め込みをすべて一括・定期的に再生成する方式は、対象データが大きくなるほどコストがかさみます。新しい情報が追加されたタイミングでのみ埋め込みを生成するイベント駆動の方式が推奨されており、「何を、いつ、再インデックスするか」の設計もあわせて必要になります。
制約・注意点
- 本記事の優先度づけは、一般的なAIエージェントの利用シーン（コード生成、障害対応、標準準拠チェック）を前提にした整理であり、組織によって重視すべきドキュメント種別は変わります。
- RAGプラグイン自体、埋め込み対象として明確にサポートされている情報源が限られているなど、まだ発展途上の領域です。今後のアップデートで扱える情報源が広がる可能性があります。
- 既存のドキュメントをどう移行・再構成するかという実務手順は、本記事では扱っていません。
まとめ
- Backstageが持つコンテキストは、構造化メタデータ・AIエージェント向け静的コンテキスト・非構造化ドキュメント（TechDocs）の3層に分かれます。
- TechDocsの中でも、ADR、ランブック、ゴールデンパス・標準ドキュメントは、AIエージェントにとって特に価値が高い情報です。
- システム図は単体では検索対象として機能しにくく、説明テキストとセットで管理する必要があります。
- ドキュメントの構造化は、カタログとの紐付け、対応情報源の制約、埋め込み生成のタイミング設計とあわせて検討する必要があります。
参考リンク
- Alok Rahul「Day 186 — TechDocs in Backstage: Bringing Documentation Closer to Engineering Workflows」（Medium、2026年7月）
- Backstage公式ドキュメント「Architecture Decision Records (ADR)」
- Roadie.io「Backstage AI Assistant - RAG AI Plugin」
注意事項
本ブログに掲載している内容は、私個人の見解であり、
所属する組織の立場や戦略、意見を代表するものではありません。
あくまでエンジニアとしての経験や考えを発信していますので、ご了承ください。