azure-architecture-autopilot

Azure Architecture Builder

自然言語を使用して Azure インフラストラクチャを設計するか、既存のリソースを分析してアーキテクチャを可視化し、変更とデプロイへ進むパイプラインです。

図表エンジンはスキル内（scripts/ フォルダー）に組み込まれています。 pip install は不要です。バンドルされた Python スクリプトを直接使用して、 605 個以上の Azure 公式アイコンを含むインタラクティブな HTML 図を生成します。 ネットワーク接続やパッケージのインストールがなくても、すぐに使用できます。

ユーザーの言語の自動検出

🚨 ユーザーの最初のメッセージの言語を検出し、それ以降のすべての応答をその言語で行ってください。これが最優先の原則です。

• ユーザーが韓国語で書いた場合 → 韓国語で応答します
• ユーザーが英語で書いた場合 → 英語で応答します（ask_user、進捗状況の更新、レポート、Bicep のコメントをすべて英語にします）
• このドキュメントの指示と例は英語で記載されており、ユーザー向けの出力はすべてユーザーの言語に合わせる必要があります

⚠️ このドキュメントの例をそのままユーザーにコピーしないでください。 構成のみを参考にし、文章はユーザーの言語に合わせて調整してください。

ツールの使用ガイド（GHCP 環境）

機能	ツール名	備考
URL のコンテンツを取得	web_fetch	MS Docs の参照など
ウェブ検索	web_search	URL の検索
ユーザーに質問	ask_user	choices は文字列の配列である必要があります
サブエージェント	task	explore/task/general-purpose
シェルコマンドの実行	powershell	Windows PowerShell

すべてのサブエージェント（explore/task/general-purpose）は web_fetch または web_search を使用できません。 MS Docs の参照が必要なファクトチェックは、メインエージェントが直接実行する必要があります。

外部ツールのパスの検出

az、python、bicep などは PATH に含まれていないことがよくあります。 Phase の開始前に一度検出して結果をキャッシュしてください。毎回再検出しないでください。

⚠️ Get-Command python は使用しないでください — Windows Store のエイリアスが返されるおそれがあります。 直接ファイルシステムを検索する方法（$env:LOCALAPPDATA\Programs\Python）を優先してください。

az CLI のパス：

$azCmd = $null
if (Get-Command az -ErrorAction SilentlyContinue) { $azCmd = 'az' }
if (-not $azCmd) {
  $azExe = Get-ChildItem -Path "$env:ProgramFiles\Microsoft SDKs\Azure\CLI2\wbin", "$env:LOCALAPPDATA\Programs\Azure CLI\wbin" -Filter "az.cmd" -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
  if ($azExe) { $azCmd = $azExe }
}

Python のパスと組み込みの図表エンジン：references/phase1-advisor.md の図表生成セクションを参照してください。

進捗状況の更新は必須

ブロック引用 + 絵文字 + 太字の形式を使用してください：

> **⏳ [Action]** — [Reason]
> **✅ [Complete]** — [Result]
> **⚠️ [Warning]** — [Details]
> **❌ [Failed]** — [Cause]

並行プリロードの原則

ask_user でユーザーの入力を待つ間に、次のステップに必要な情報を並行して事前に読み込んでください。

ask_user の質問	同時にプリロードする項目
プロジェクト名／スキャン範囲	参照ファイル、MS Docs、Python のパス検出、図表モジュールのパス確認
モデル／SKU の選択	次の質問の選択肢に関する MS Docs
アーキテクチャの確認	az account show/list、az group list
サブスクリプションの選択	az group list

---

パス分岐 — ユーザーのリクエストに基づく自動判定

パス A：新規設計（新規構築）

トリガー：「作成」、「セットアップ」、「デプロイ」、「構築」など

Phase 1 (references/phase1-advisor.md) — Interactive architecture design + diagram
    ↓
Phase 2 (references/bicep-generator.md) — Bicep code generation
    ↓
Phase 3 (references/bicep-reviewer.md) — Code review + compilation verification
    ↓
Phase 4 (references/phase4-deployer.md) — validate → what-if → deploy

パス B：既存環境の分析と変更（分析と変更）

トリガー：「分析」、「現在のリソース」、「スキャン」、「図を描く」、「自分のインフラストラクチャを表示」など

Phase 0 (references/phase0-scanner.md) — Existing resource scan + diagram
    ↓
Modification conversation — "What would you like to change here?" (natural language modification request → follow-up questions)
    ↓
Phase 1 (references/phase1-advisor.md) — Confirm modifications + update diagram
    ↓
Phase 2~4 — Same as above

パスの判定が曖昧な場合

ユーザーに直接確認してください：

ask_user({
  question: "What would you like to do?",
  choices: [
    "Design a new Azure architecture (Recommended)",
    "Analyze + modify existing Azure resources"
  ]
})

---

Phase の移行ルール

• 各 Phase では、対応する references/*.md ファイルの指示を読み、その内容に従います
• Phase を移行する際は、必ず次のステップをユーザーに知らせてください
• Phase を省略しないでください（特に Phase 3 → Phase 4 の間の what-if）
• 🚨 Phase 1 から Phase 2 への移行に必須の条件：01_arch_diagram_draft.html が組み込みの図表エンジンを使って生成され、ユーザーに表示されている必要があります。**図を生成せずに Bicep の生成へ進まないでください。**仕様の収集が完了しただけでは Phase 1 の完了とはみなされません。Phase 1 には図の生成とユーザーによる確認が含まれます。
• デプロイ後に変更を依頼された場合は、Phase 0 ではなく Phase 1 に戻ります（差分確認ルール）

サービスの対応範囲とフォールバック

最適化されたサービス

Microsoft Foundry、Azure OpenAI、AI Search、ADLS Gen2、Key Vault、Microsoft Fabric、Azure Data Factory、VNet/Private Endpoint、AML/AI Hub

その他の Azure サービス

すべてサポートされています。MS Docs が自動的に参照され、同じ品質基準で生成されます。 「対象外」や「ベストエフォート」など、ユーザーに不安を与える表現のメッセージは送信しないでください。

静的情報と動的情報の扱い

カテゴリ	扱い方	例
静的	参照ファイルを優先	isHnsEnabled: true、PE の 3 点セット
動的	必ず MS Docs を取得	API バージョン、モデルの提供状況、SKU、リージョン

クイックリファレンス

ファイル	役割
references/phase0-scanner.md	既存リソースのスキャン + 関係性の推論 + 図の作成
references/phase1-advisor.md	対話型のアーキテクチャ設計 + 事実確認
references/bicep-generator.md	Bicep コード生成ルール
references/bicep-reviewer.md	コードレビューのチェックリスト
references/phase4-deployer.md	validate → what-if → deploy
references/service-gotchas.md	必須プロパティ、PE のマッピング
references/azure-dynamic-sources.md	MS Docs の URL レジストリ
references/azure-common-patterns.md	PE/セキュリティ/命名のパターン
references/ai-data.md	AI/データサービスガイド
assets/06-architecture-diagram.png	生成されたアーキテクチャ図の例
assets/07-azure-portal-resources.png	Azure ポータルのリソース表示の例
assets/08-deployment-succeeded.png	デプロイ成功結果の例