概觀
什麼是 azure-validate？
azure-validate 是一個用來在部署前，對你的 Azure 應用程式與基礎架構執行深入預檢（preflight checks）的部署驗證技能。它會讀取由 azure-prepare 建立並核准的部署計畫，接著驗證設定、基礎架構即程式碼（Bicep 或 Terraform）、Azure Developer CLI (azd) 工作流程、Azure CLI (azcli) 指令碼、原則、區域，以及所需的權限。
此技能位於工作流程的部署階段，但行為上更像是一套針對 Azure 環境的自動化測試。它協助你確認計畫執行起來是安全的，並確保你的 App 已真正做好部署準備。
什麼時候應該使用這個技能？
在下列情境，你都適合使用 azure-validate：
- 想確認應用程式與基礎架構是否已準備好部署
- 想在執行
azd provision或azd deploy之前驗證azure.yaml或 Bicep 範本 - 想對 Terraform 或原生 Azure CLI 指令碼執行部署前檢查
- 想再次確認 Azure 訂用帳戶、區域與額度選擇是否合適
- 想驗證預計建立的資源是否符合 Azure Policy
- 想及早攔截常見 Azure CLI 與 IaC 驗證錯誤
- 想排查在 CI/CD pipeline 中重複發生的部署失敗
它最適合放在這個順序中：
azure-prepare → azure-validate → azure-deploy
azure-validate 適合哪些人？
azure-validate 主要適用於：
- 在 Azure 上開發應用程式的後端與雲端開發者
- 負責穩定部署的 DevOps 與平台工程師
- 在基礎架構上標準化使用 Bicep、Terraform、azd 或 azcli 的團隊
- 需要一致、自動化部署前檢查的 CI/CD 負責人
如果你經常管理多環境部署（dev/test/prod），或需要遵循公司層級的原則與區域規範，這個技能可以提供一個可重複的驗證層。
它解決哪些問題？
azure-validate 能透過提前抓出以下問題，降低部署失敗或部分部署的風險：
azure.yaml或 IaC 檔案缺少或包含無效設定- 針對特定服務設定錯誤或不支援的 Azure 區域
- 將會阻擋部署的 Azure Policy 違規情況
- 驗證與權限相關問題（例如缺少必要角色）
- Bicep 與範本常見的 Azure CLI 驗證錯誤
- 在 azd、azcli、Bicep 與 Terraform 之間不一致的基礎架構設計
你不必等到上線或 pipeline 後段才發現這些問題，而是可以在驗證階段就及早浮現，並附上清楚的參考與修正做法。
什麼情況下不適合使用 azure-validate？
這個技能不適用於：
- 非 Azure 的部署（其他雲端或純 on-prem）
- 部署後的監控、健康檢查或可觀測性
- 應用程式層級的測試（unit、integration 或 UI 測試）
- 未透過
azure-prepare產生部署計畫的一次性手動部署
如果你沒有使用基礎架構即程式碼，或沒有使用結構化的計畫檔（例如由 azure-prepare 產生的 .azure/plan.md），就無法完全發揮 azure-validate 的價值。
使用方法
1. 安裝與基本設定
將 azure-validate 加入你的 skills
從 microsoft/azure-skills repository 安裝此技能：
npx skills add https://github.com/microsoft/azure-skills --skill azure-validate
這會讓 azure-validate 的工作流程可以在你的 agent 或工具環境中使用。
必須遵守的工作流程順序
在執行 azure-validate 之前，你必須已經：
- 成功呼叫過
azure-prepare，且 - 存在一個
.azure/plan.md檔案，其狀態為Approved或更後階段
支援且建議的工作流程順序為：
azure-prepare → azure-validate → azure-deploy
如果找不到 .azure/plan.md 或其狀態尚未核准，請先停止並重新執行 azure-prepare。
2. 瞭解核心觸發條件與規則
主要觸發情境
在下列需求時使用 azure-validate：
- 想確認某個 App 是否已準備好部署
- 想驗證
azure.yaml或 Bicep 範本 - 想在建立資源前執行預檢（preflight checks）
- 想排查來自 IaC 或 CLI 步驟的 Azure 部署錯誤
必須遵守的核心規則
根據此技能的使用說明與共用的 global-rules 參考：
- 只在
azure-prepare之後、任何實際部署之前執行 azure-validate。 - 將驗證失敗視為阻擋性結果；在問題解決前不要繼續執行
azure-deploy。 - 對於任何具破壞性或高度影響的操作（刪除、覆寫、大幅成本或安全性變更），一律依照
references/global-rules.md的說明，以ask_user提示使用者確認。 - 切勿自行假設 Azure 訂用帳戶或區域；當有關聯時必須向使用者確認。
3. 依基礎架構類型使用對應驗證指南
此技能在 references/recipes/ 底下提供多種針對不同基礎架構方式的驗證 recipes。
適用於 Azure Developer CLI (azd) 專案
- 從
references/recipes/azd/README.md開始。 - 使用
references/recipes/azd/environment.md驗證環境設定。 - 使用
references/recipes/azd/errors.md解讀與修正常見的azd驗證與部署問題。 - 若是 .NET Aspire 架構的專案，請參考
references/recipes/azd/aspire.md進行額外檢查。
這些指南會協助你在使用 azd 建立資源前，先確認 azure.yaml、應用程式 wiring 與環境設定皆正確無誤。
適用於 Azure CLI (azcli) + Bicep 工作流程
- 從
references/recipes/azcli/README.md開始，裡面提供完整的 AZCLI 驗證清單，包括：- 確認 Azure CLI 安裝狀態（
az version） - 登入並設定訂用帳戶
- 編譯 Bicep（
az bicep build） - 執行範本驗證與 what-if 預覽
- 確認 Azure CLI 安裝狀態（
- 使用
references/recipes/azcli/errors.md快速處理常見az錯誤訊息（token 問題、多重驗證、授權問題、範本驗證失敗等）。
這樣的搭配能提供具體、可實作的步驟，讓你在使用 Azure CLI 驅動 Bicep 部署前先完成完整驗證。
專注於 Bicep 的基礎架構
- 請看
references/recipes/bicep/README.md了解 Bicep 專用驗證流程。 - 使用
references/recipes/bicep/errors.md取得常見 Bicep 驗證問題及對應解法的指引。
你可以將這些檢查整合進本機開發流程或 CI pipeline，確保範本與參數在正式部署前已通過驗證。
使用 Terraform 進行部署
- 使用
references/recipes/terraform/README.md，將 azure-validate 與 Terraform plan 與 apply 步驟對齊。 - 參考
references/recipes/terraform/errors.md了解常見 Terraform 驗證與 Azure 授權錯誤以及如何修正。
這些 recipes 能幫助你在任何環境中執行 terraform apply 前，先確認 Terraform 基礎架構與 Azure 帳戶設定皆已就緒。
4. 驗證原則、區域與額度是否足夠
Azure Policy 驗證
請依 references/policy-validation.md 的指引，確認預計部署的內容符合訂用帳戶上的 Azure Policy 設定。
典型流程如下：
-
取得目前的訂用帳戶 ID：
az account show --query id -o tsv -
依照參考文件中的說明，使用 Azure policy MCP integration 列出並檢視該訂用帳戶的原則。
-
在繼續之前，先解決所有原則違規問題（不允許的 SKU、缺少 tags、受限制的資源類型、禁止的區域、網路安全規則等）。
只有在確認已符合原則後，才應進入部署階段。
區域可用性與額度檢查
使用 references/region-availability.md 交叉檢查架構中的所有服務，是否皆支援在指定區域中執行，且額度是否充足。
這對於區域受限較多的服務尤其重要，例如：
- Azure Static Web Apps
- Azure OpenAI（不同模型可用區域也可能不同）
請遵循參考文件中的建議，以及任何列出的 MCP 工具（用於查詢額度與區域可用性），避免因不支援的區域或容量不足而造成部署失敗。
5. 應用程式與 Functions 驗證範例
Aspire + Azure Functions 機密儲存設定
如果你同時使用 .NET Aspire 與 Azure Functions，請參考 references/aspire-functions-secrets.md：
- 確認你的 app host 是否包含以身分識別為基礎儲存的
AddAzureFunctionsProject。 - 確保
AzureWebJobsSecretStorageType設定正確。 - 依指示套用建議修正（包含在指定位置加入
.WithEnvironment("AzureWebJobsSecretStorageType", "Files")）。
在執行 azd provision 之前做好這一步，可避免常見的 Functions 機密儲存問題，避免阻擋無伺服器部署。
6. 在 CI/CD pipeline 中使用 azure-validate
雖然 azure-validate 是以 agent skill 的形式撰寫，但其中的步驟與參考內容非常適合用在自動化 pipeline：
- 將 recipes 中的步驟對應成 pipeline stages（例如在部署工作前先執行 Bicep 驗證與 what-if）。
- 只要 recipes 或原則檢查出任何驗證錯誤，就讓 pipeline 失敗。
- 在 pipeline log 中輸出來自
references/*檔案的連結或片段，協助開發者了解如何修正問題。
這樣就能讓 azure-validate 成為所有環境共用的一致部署前閘道。
7. 進階客製化時建議檢視的檔案
若你想將 azure-validate 更貼近自己的工作流程，請在 repository 中開啟以下關鍵檔案：
SKILL.md– 此技能的權威說明，包含指示、觸發條件、規則與執行步驟順序。references/global-rules.md– 關於破壞性操作、訂用帳戶與區域處理的強制性全域規則。references/policy-validation.md– 詳細的原則驗證使用方式。references/region-availability.md– 對於受限服務的區域與額度規劃指引。references/aspire-functions-secrets.md– Aspire + Azure Functions 機密儲存驗證。references/recipes/README.md– azd、azcli、Bicep 與 Terraform 驗證 recipes 的索引。
建議你以這些檔案為組合元件來設計流程，而不是直接照搬整套工作流程。
常見問題（FAQ）
azure-validate 是必需的嗎？我可以不跑它就直接部署嗎？
此技能是設計用在 azure-prepare 與 azure-deploy 之間。技術上你可以省略 azure-validate 直接部署，但官方建議是將它視為必經的驗證閘道。若跳過，部署失敗、原則阻擋，或區域與權限相關問題的風險都會提高。
我一定要先執行 azure-prepare 嗎？
是的。azure-validate 假設你已執行過 azure-prepare，並且 .azure/plan.md 存在且狀態為 Approved 或更後階段。如果該檔案不存在或尚未核准，你應該先停止，並先執行 azure-prepare 之後再使用 azure-validate。
azure-validate 支援哪些基礎架構工具？
azure-validate 目前提供以下工具的 recipes 與操作指引：
- Azure Developer CLI (azd)
- 搭配 Bicep 範本的 Azure CLI (azcli)
- 以 Bicep 為主的基礎架構
- Terraform
你可以在 references/recipes/ 下選擇與你技術堆疊相符的 recipe。
可以在 CI/CD pipeline 中使用 azure-validate 嗎？
可以。雖然它是以 agent skill 撰寫，但其中的驗證步驟、錯誤說明與原則/區域檢查都很適合放入 CI/CD。你可以在 pipeline（例如 GitHub Actions、Azure DevOps）中鏡像這些 recipes 與檢查，讓部署只在驗證成功時才繼續。
azure-validate 會直接變更我的 Azure 資源嗎？
azure-validate 的重點在於驗證與預檢。使用說明中也強調，任何具破壞性或高度影響的操作都必須透過 ask_user 並依 global-rules 檔案明確取得使用者同意。在一般情境下，你會用這個技能來檢視、驗證與規劃，而不是直接執行不可逆的變更。
azure-validate 對 Azure Policy 與治理有什麼幫助？
此技能包含 references/policy-validation.md，示範如何檢視訂用帳戶上的原則並在部署前確認是否符合。依照這份指引操作，你可以事先找出不被允許的資源類型、SKU、tags 或區域，確保部署符合組織的治理規範。
它如何處理像 Azure Static Web Apps 或 Azure OpenAI 這類區域受限服務？
references/region-availability.md 列出區域支援度較有限的服務，並提供指向官方 Azure 文件與 MCP 工具的連結，以便查詢額度與可用性。azure-validate 的預期做法是，請你先參考這份文件，只在所有必要服務都有支援的區域提供或使用這些服務。
azure-validate 適合用在本機開發環境嗎？
適合，只要你的目標是部署到 Azure，並且透過 azure-prepare 產生部署計畫，就可以針對 dev 與 test 環境執行 azure-validate。這是一種在推到 staging 或 production 前及早發現問題的好方法。
第一次安裝 azure-validate 時該從哪裡開始？
安裝技能之後，先閱讀 SKILL.md 了解整體規則與執行順序，接著打開 references/recipes/README.md，選擇符合你基礎架構工具（azd、azcli、Bicep、Terraform）的 recipe。之後再搭配原則與區域相關的指引，將 azure-validate 串接進你的工作流程中。