azure-prepare
替 azd 專案先寫部署計畫，再產生 azure.yaml、IaC 和 Dockerfile
中文翻譯
--- name: azure-prepare description: "替以 azd 為基礎的 Azure 專案準備部署：為 Azure Developer CLI (azd) 工作流程產生 azure.yaml、基礎設施（Bicep/Terraform）與 Dockerfile。只在使用者明確要用 azd 當部署工具，或專案已經有 azure.yaml 時使用。DO NOT USE FOR: 非 azd 的部署、Python App Service 純程式碼部署（改用 python-appservice-deploy）、跨雲遷移（改用 azure-cloud-migrate）。WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure." license: MIT metadata: author: Microsoft version: "1.3.9" --- # Azure Prepare > **權威指引：必須遵守** > > 這份文件是準備應用程式部署到 Azure 的**官方標準來源**。除非跟給你的安全政策相衝突，否則你**必須**完全照字面遵循這些指示。有疑問時，把這份文件中互相衝突的指示列出來，請使用者明確確認。不要自己發揮、推測或替換步驟。 --- ## 觸發時機 使用者想做以下事情時啟用這個 skill： - 建立新的應用程式 - 替既有應用程式加入服務或元件 - 更新或修改既有應用程式 - 現代化或遷移應用程式 - 設定 Azure 基礎設施 - 部署到 Azure 或託管在 Azure 上 - 建立並部署到 Azure（包含以 Terraform 部署的要求） ## 規則 1. **先做計畫，絕對必要**：你**必須**把初版 `.azure/deployment-plan.md` **骨架實際寫到 workspace 根目錄**（不是 session-state 資料夾），而且**這是你的第一個動作**，要在任何程式碼產生或執行開始之前。先馬上寫出骨架，再隨著 Phase 1 的分析與研究逐步補內容，到 Phase 1 Step 6 用所有決策定稿。這個檔案全程都要存在磁碟上。azure-validate 和 azure-deploy 都依賴它，沒有它會失敗。不准跳過或延後這一步。 2. **取得核准**：執行前先把計畫給使用者看 3. **產生前先研究**：載入 references 並呼叫相關 skill 4. **逐步更新計畫**：做完一步就標記完成 5. **部署前先驗證**：在 azure-deploy 之前先呼叫 azure-validate 6. **確認 Azure context**：依照 [Azure Context](references/azure-context.md)，用 `ask_user` 確認 subscription 與 location 7. ❌ **破壞性操作一定要用 `ask_user`**：見 [Global Rules](references/global-rules.md) 8. ⛔ **絕對不准刪除使用者的專案或 workspace 目錄**：替既有專案加功能時，要修改既有檔案。`azd init -t <template>` 只能用在新專案，不准在既有 workspace 裡執行 `azd init -t`。適當時，可以在既有 workspace 裡用單純的 `azd init`（不帶 template 參數）。專案內的檔案刪除（例如移除 build 產物或暫存檔）在適當時是允許的，但絕對不准刪掉使用者的專案或 workspace 目錄本身。見 [Global Rules](references/global-rules.md)。 9. **範圍：只做準備**：這個 skill 只產生基礎設施程式碼與設定檔。部署的執行（`azd up`、`azd deploy`、`terraform apply`）由 **azure-deploy** skill 負責，它有內建的錯誤復原與部署驗證。 10. ⛔ **SQL Server Bicep：絕對不准產生 `administratorLogin` 或 `administratorLoginPassword`**，不管是直接屬性、條件式／三元運算的分支，還是檔案裡任何地方都不行。一律無條件使用僅限 Entra 的驗證（`azureADOnlyAuthentication: true`）。見 [references/services/sql-database/bicep.md](references/services/sql-database/bicep.md)。 11. **轉換後移除過時的 template IaC**：如果你把選定的 `azd` template 裡的 Bicep template 轉成了 Terraform template，就要移除那些由該 `azd` template 帶進來、現在已被 Terraform 版本完全取代的 Bicep template。不准移除使用者自己寫的 Bicep 檔。只有在 Terraform IaC 完成、而且已選定 Terraform 作為部署路徑之後，才能移除這些 template 提供的 Bicep 檔。交給 azure-validate skill 之前，只保留所選部署路徑需要的 IaC template。 --- ## ❌ 先做計畫的工作流程：必須遵守 > **做任何事之前，你必須先建立計畫** > > 1. **停下來**：先不要產生任何程式碼、基礎設施或設定檔 > 2. **建立骨架**：**立刻**把初版 `.azure/deployment-plan.md` 骨架寫到磁碟上（在任何程式碼產生或執行開始之前），再隨著 Phase 1 的 1-5 步揭露細節逐步補內容；到 Step 6 定稿 > 3. **確認**：把完成的計畫呈現給使用者並取得核准 > 4. **執行**：核准之後，才一步一步執行計畫 > > `.azure/deployment-plan.md` 是這個工作流程，以及 azure-validate 與 azure-deploy 這兩個 skill 的**唯一事實來源**。沒有它，那些 skill 都會失敗。 > > ⚠️ **關鍵：`.azure/deployment-plan.md` 必須寫到 workspace 根目錄內的磁碟上**（例如 `<workspace-root>/.azure/deployment-plan.md`），不是寫在 session-state 資料夾。用寫檔工具建立這個檔案。這是 azure-validate 和 azure-deploy 會讀取的部署計畫產物。**你必須建立這個檔案，沒有它不准往下做。** > ⚠️ **關鍵：檔案名稱必須原封不動是 `.azure/deployment-plan.md`**。不准用 `.azure/plan.md` 之類的其他名稱。 > > ⛔ **關鍵：** 沒有建立計畫檔，azure-validate 和 azure-deploy 就會失敗。這個要求沒有例外。 --- ## ❌ STEP 0：特定技術檢查，必須是第一個動作 **在開始 Phase 1 之前**，先檢查使用者的 prompt 或 workspace 程式碼是否符合某個有專屬 skill 與已測試 template 的特定技術。如果符合，**先呼叫那個 skill**，再回到 azure-prepare 做驗證與部署。 ### 檢查 1：Prompt 關鍵字 | Prompt 關鍵字 | 先呼叫 | |----------------|-------------| | Python + App Service（例如 "deploy Python to App Service"、"Flask on Azure App Service"、"publish Python web app to App Service"） | **python-appservice-deploy** | | Lambda, AWS Lambda, migrate AWS, migrate GCP, Lambda to Functions, migrate from AWS, migrate from GCP | **azure-cloud-migrate** | | Azure Functions, function app, serverless function, timer trigger, HTTP trigger, func new | 留在 **azure-prepare**：Step 4 優先用 Azure Functions template；方案選擇與 cold start 請看 [hosting-plans.md](references/services/functions/hosting-plans.md) 和 [cold-start.md](references/services/functions/cold-start.md) | | APIM, API Management, API gateway, deploy APIM | 留在 **azure-prepare**：請看 [APIM Deployment Guide](references/apim.md) | | AI gateway, AI gateway policy, AI gateway backend, AI gateway configuration | **azure-aigateway** | | workflow, orchestration, multi-step, pipeline, fan-out/fan-in, saga, long-running process, durable, order processing | 留在 **azure-prepare**：在 Step 4 選 **durable** recipe。**必須**載入 [durable.md](references/services/functions/durable.md)、[DTS reference](references/services/durable-task-scheduler/README.md) 和 [DTS Bicep patterns](references/services/durable-task-scheduler/bicep.md)。 | > ⚠️ 要檢查使用者的 **prompt 文字**，不只是既有程式碼。這對沒有程式碼可掃描的 greenfield 專案特別重要。見[完整路由表](references/specialized-routing.md)。 特定技術的 skill 完成後，**回到 azure-prepare**，從 Phase 1 Step 4（Select Recipe）繼續處理剩下的基礎設施、驗證與部署。 --- ## Phase 1：規劃（BLOCKING，在任何執行之前必須完成） 依序完成這些步驟來建立 `.azure/deployment-plan.md`。計畫核准之前，不准產生任何產物。 | # | 動作 | 參考 | |---|--------|-----------| | 0 | 如果 prompt 符合有專屬 skill 的特定技術，先呼叫那個 skill | [specialized-routing.md](references/specialized-routing.md) | | 1 | **分析 Workspace**：判斷模式是 NEW、MODIFY 還是 MODERNIZE | [analyze.md](references/analyze.md) | | 2 | **收集需求**：分類、規模、預算 | [requirements.md](references/requirements.md) | | 3 | **掃描程式碼**：找出元件、技術、相依套件 | [scan.md](references/scan.md) | | 4 | **選擇 Recipe**：選 AZD（預設）、AZCLI、Bicep 或 Terraform | [recipe-selection.md](references/recipe-selection.md) | | 5 | **規劃架構**：選定技術堆疊，並把元件對應到 Azure 服務 | [architecture.md](references/architecture.md) | | 6 | **定稿計畫（必做）**：用寫檔工具，把步驟 1-5 的所有決策定稿到 `.azure/deployment-plan.md`。用完整內容更新 Phase 1 開頭寫下的骨架。在把計畫呈現給使用者之前，檔案必須完整填好。 | [plan-template.md](references/plan-template.md) | | 7 | **呈現計畫**：把計畫給使用者看並請求核准 | `.azure/deployment-plan.md` | | 8 | **破壞性操作一定要用 `ask_user`** | [Global Rules](references/global-rules.md) | --- > **❌ 到此為止**：使用者核准計畫之前，不准進入 Phase 2。 --- ## Phase 2：執行（只在計畫核准之後） 執行已核准的計畫。每做完一步，就更新 `.azure/deployment-plan.md` 的狀態。 | # | 動作 | 參考 | |---|--------|-----------| | 1 | **研究元件**：載入服務 references 並呼叫相關 skill | [research.md](references/research.md) | | 2 | **確認 Azure Context**：偵測並確認 subscription 與 location，並檢查資源佈建上限 | [Azure Context](references/azure-context.md) | | 3 | **產生產物**：建立基礎設施與設定檔 | [generate.md](references/generate.md) | | 4 | **強化安全性**：套用安全最佳實務 | [security.md](references/security.md) | | 5 | **功能驗證**：確認應用程式能運作（UI + 後端），可以的話在本機驗證 | [functional-verification.md](references/functional-verification.md) | | 6 | **⛔ 更新計畫（交接前必做）**：用 `edit` 工具把 `.azure/deployment-plan.md` 的 Status 改成 `Ready for Validation`。你**必須**在呼叫 azure-validate **之前**完成這個修改。不准跳過這一步。 | `.azure/deployment-plan.md` | | 7 | **⛔ 必須交接**：呼叫 **azure-validate** skill。你的準備工作到此結束。不准直接執行 `azd up`、`azd deploy` 或任何部署指令，所有部署的執行都由 azure-validate 完成後的 azure-deploy 處理。**前提：**Step 6 必須先完成，`.azure/deployment-plan.md` 的狀態必須是 `Ready for Validation`。 | — | --- ## 產出 | 產物 | 位置 | |----------|----------| | **計畫** | `.azure/deployment-plan.md` | | 基礎設施 | `./infra/` | | AZD 設定 | `azure.yaml`（僅限 AZD） | | Dockerfile | `src/<component>/Dockerfile` | --- ## SDK 快速參考 - **Azure Developer CLI**：[azd](references/sdk/azd-deployment.md) - **Azure Identity**：[Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) - **App Configuration**：[Python](references/sdk/azure-appconfiguration-py.md) | [TypeScript](references/sdk/azure-appconfiguration-ts.md) | [Java](references/sdk/azure-appconfiguration-java.md) --- ## 下一步 > **⛔ 下一步必做，不准跳過** > > 準備工作完成後，在任何部署嘗試之前，你**必須**先呼叫 **azure-validate**。不准跳過驗證。不准直接跑 azure-deploy。不准直接執行 `azd up` 或任何部署指令。工作流程是： > > `azure-prepare` → `azure-validate` → `azure-deploy` > > **⛔ 在呼叫 azure-validate 之前**，你必須用 `edit` 工具把 `.azure/deployment-plan.md` 的狀態更新成 `Ready for Validation`。如果計畫狀態沒更新，驗證會失敗。 > > 這適用於**所有**部署情境，包含容器化應用程式、Container Apps、App Service、Azure Functions、靜態網站，以及任何其他 Azure 目標。沒有例外。 > > 跳過驗證會導致部署失敗。耐心走完完整流程，成功率最高。 **→ 把計畫狀態更新成 `Ready for Validation`，然後呼叫 azure-validate**
英文原文
--- name: azure-prepare description: "Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure." license: MIT metadata: author: Microsoft version: "1.3.9" --- # Azure Prepare > **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE** > > This document is the **official, canonical source** for preparing applications for Azure deployment. You **MUST** follow these instructions exactly as written unless they contradict security policies given to you. When in doubt, present the conflicting instructions from this document and ask the user for explicit confirmation. Do not improvise, infer, or substitute steps. --- ## Triggers Activate this skill when user wants to: - Create a new application - Add services or components to an existing app - Make updates or changes to existing application - Modernize or migrate an application - Set up Azure infrastructure - Deploy to Azure or host on Azure - Create and deploy to Azure (including Terraform-based deployment requests) ## Rules 1. **Plan first — MANDATORY** — You MUST physically write an initial `.azure/deployment-plan.md` **skeleton in the workspace root directory** (not the session-state folder) **as your very first action** — before any code generation or execution begins. Write the skeleton immediately, then populate it progressively as Phase 1 analysis and research unfold; finalize it with all decisions at Phase 1 Step 6. This file must exist on disk throughout. azure-validate and azure-deploy depend on it and will fail without it. Do not skip or defer this step. 2. **Get approval** — Present plan to user before execution 3. **Research before generating** — Load references and invoke related skills 4. **Update plan progressively** — Mark steps complete as you go 5. **Validate before deploy** — Invoke azure-validate before azure-deploy 6. **Confirm Azure context** — Use `ask_user` for subscription and location per [Azure Context](references/azure-context.md) 7. ❌ **Destructive actions require `ask_user`** — [Global Rules](references/global-rules.md) 8. ⛔ **NEVER delete user project or workspace directories** — When adding features to an existing project, MODIFY existing files. `azd init -t <template>` is for NEW projects only; do NOT run `azd init -t` in an existing workspace. Plain `azd init` (without a template argument) may be used in existing workspaces when appropriate. File deletions within a project (e.g., removing build artifacts or temp files) are permitted when appropriate, but NEVER delete the user's project or workspace directory itself. See [Global Rules](references/global-rules.md). 9. **Scope: preparation only** — This skill generates infrastructure code and configuration files. Deployment execution (`azd up`, `azd deploy`, `terraform apply`) is handled by the **azure-deploy** skill, which provides built-in error recovery and deployment verification. 10. ⛔ **SQL Server Bicep: NEVER generate `administratorLogin` or `administratorLoginPassword`** — not in direct properties, not in conditional/ternary branches, not anywhere in the file. Always use Entra-only authentication (`azureADOnlyAuthentication: true`) unconditionally. See [references/services/sql-database/bicep.md](references/services/sql-database/bicep.md). 11. **Remove stale template IaC after conversion** — If you converted Bicep templates from the selected `azd` template into Terraform templates, remove the Bicep templates that were introduced by that `azd` template and are now fully replaced by Terraform equivalents. Do not remove user-authored Bicep files. Only remove those template-provided Bicep files after the Terraform IaC is complete and Terraform has been selected as the deployment path. Before handing off to azure-validate skill, keep only the IaC templates required by the chosen deployment path. --- ## ❌ PLAN-FIRST WORKFLOW — MANDATORY > **YOU MUST CREATE A PLAN BEFORE DOING ANY WORK** > > 1. **STOP** — Do not generate any code, infrastructure, or configuration yet > 2. **CREATE SKELETON** - Write an initial `.azure/deployment-plan.md` skeleton to disk **immediately** (before any code generation or execution begins), then populate it progressively as Phase 1 steps 1-5 reveal details; finalize it at Step 6 > 3. **CONFIRM** — Present the completed plan to the user and get approval > 4. **EXECUTE** — Only after approval, execute the plan step by step > > The `.azure/deployment-plan.md` file is the **source of truth** for this workflow and for azure-validate and azure-deploy skills. Without it, those skills will fail. > > ⚠️ **CRITICAL: `.azure/deployment-plan.md` must be WRITTEN TO DISK inside the workspace root** (e.g., `<workspace-root>/.azure/deployment-plan.md`), not in the session-state folder. Use a file-write tool to create this file. This is the deployment plan artifact read by azure-validate and azure-deploy. **You MUST create this file — do not proceed without it.** > ⚠️ **CRITICAL: You must create the file with the name `.azure/deployment-plan.md` as is**. You must not use other names such as `.azure/plan.md`. > > ⛔ **Critical:** Skipping the plan file creation will cause azure-validate and azure-deploy to fail. This requirement has no exceptions. --- ## ❌ STEP 0: Specialized Technology Check — MANDATORY FIRST ACTION **BEFORE starting Phase 1**, check if the user's prompt OR workspace codebase matches a specialized technology that has a dedicated skill with tested templates. If matched, **invoke that skill FIRST** — then resume azure-prepare for validation and deployment. ### Check 1: Prompt keywords | Prompt keywords | Invoke FIRST | |----------------|-------------| | Python + App Service (e.g., "deploy Python to App Service", "Flask on Azure App Service", "publish Python web app to App Service") | **python-appservice-deploy** | | Lambda, AWS Lambda, migrate AWS, migrate GCP, Lambda to Functions, migrate from AWS, migrate from GCP | **azure-cloud-migrate** | | Azure Functions, function app, serverless function, timer trigger, HTTP trigger, func new | Stay in **azure-prepare** — prefer Azure Functions templates in Step 4; for plan choice/cold starts see [hosting-plans.md](references/services/functions/hosting-plans.md) and [cold-start.md](references/services/functions/cold-start.md) | | APIM, API Management, API gateway, deploy APIM | Stay in **azure-prepare** — see [APIM Deployment Guide](references/apim.md) | | AI gateway, AI gateway policy, AI gateway backend, AI gateway configuration | **azure-aigateway** | | workflow, orchestration, multi-step, pipeline, fan-out/fan-in, saga, long-running process, durable, order processing | Stay in **azure-prepare** — select **durable** recipe in Step 4. **MUST** load [durable.md](references/services/functions/durable.md), [DTS reference](references/services/durable-task-scheduler/README.md), and [DTS Bicep patterns](references/services/durable-task-scheduler/bicep.md). | > ⚠️ Check the user's **prompt text** — not just existing code. Critical for greenfield projects with no codebase to scan. See [full routing table](references/specialized-routing.md). After the specialized skill completes, **resume azure-prepare** at Phase 1 Step 4 (Select Recipe) for remaining infrastructure, validation, and deployment. --- ## Phase 1: Planning (BLOCKING — Complete Before Any Execution) Create `.azure/deployment-plan.md` by completing these steps. Do NOT generate any artifacts until the plan is approved. | # | Action | Reference | |---|--------|-----------| | 0 | If the prompt matches a specialized technology with a dedicated skill, invoke that skill first | [specialized-routing.md](references/specialized-routing.md) | | 1 | **Analyze Workspace** — Determine mode: NEW, MODIFY, or MODERNIZE | [analyze.md](references/analyze.md) | | 2 | **Gather Requirements** — Classification, scale, budget | [requirements.md](references/requirements.md) | | 3 | **Scan Codebase** — Identify components, technologies, dependencies | [scan.md](references/scan.md) | | 4 | **Select Recipe** — Choose AZD (default), AZCLI, Bicep, or Terraform | [recipe-selection.md](references/recipe-selection.md) | | 5 | **Plan Architecture** — Select stack + map components to Azure services | [architecture.md](references/architecture.md) | | 6 | **Finalize Plan (MANDATORY)** - Use a file-write tool to finalize `.azure/deployment-plan.md` with all decisions from steps 1-5. Update the skeleton written at the start of Phase 1 with the complete content. The file must be fully populated before you present the plan to the user. | [plan-template.md](references/plan-template.md) | | 7 | **Present Plan** — Show plan to user and ask for approval | `.azure/deployment-plan.md` | | 8 | **Destructive actions require `ask_user`** | [Global Rules](references/global-rules.md) | --- > **❌ STOP HERE** — Do NOT proceed to Phase 2 until the user approves the plan. --- ## Phase 2: Execution (Only After Plan Approval) Execute the approved plan. Update `.azure/deployment-plan.md` status after each step. | # | Action | Reference | |---|--------|-----------| | 1 | **Research Components** — Load service references + invoke related skills | [research.md](references/research.md) | | 2 | **Confirm Azure Context** — Detect and confirm subscription + location and check the resource provisioning limit | [Azure Context](references/azure-context.md) | | 3 | **Generate Artifacts** — Create infrastructure and configuration files | [generate.md](references/generate.md) | | 4 | **Harden Security** — Apply security best practices | [security.md](references/security.md) | | 5 | **Functional Verification** — Verify the app works (UI + backend), locally if possible | [functional-verification.md](references/functional-verification.md) | | 6 | **⛔ Update Plan (MANDATORY before hand-off)** — Use the `edit` tool to change the Status in `.azure/deployment-plan.md` to `Ready for Validation`. You **MUST** complete this edit **BEFORE** invoking azure-validate. Do NOT skip this step. | `.azure/deployment-plan.md` | | 7 | **⛔ MANDATORY Hand Off** — Invoke **azure-validate** skill. Your preparation work is done. Do NOT run `azd up`, `azd deploy`, or any deployment command directly — all deployment execution is handled by azure-deploy after azure-validate completes. **PREREQUISITE:** Step 6 must be completed first — `.azure/deployment-plan.md` status must say `Ready for Validation`. | — | --- ## Outputs | Artifact | Location | |----------|----------| | **Plan** | `.azure/deployment-plan.md` | | Infrastructure | `./infra/` | | AZD Config | `azure.yaml` (AZD only) | | Dockerfiles | `src/<component>/Dockerfile` | --- ## SDK Quick References - **Azure Developer CLI**: [azd](references/sdk/azd-deployment.md) - **Azure Identity**: [Python](references/sdk/azure-identity-py.md) | [.NET](references/sdk/azure-identity-dotnet.md) | [TypeScript](references/sdk/azure-identity-ts.md) | [Java](references/sdk/azure-identity-java.md) - **App Configuration**: [Python](references/sdk/azure-appconfiguration-py.md) | [TypeScript](references/sdk/azure-appconfiguration-ts.md) | [Java](references/sdk/azure-appconfiguration-java.md) --- ## Next > **⛔ MANDATORY NEXT STEP — DO NOT SKIP** > > After completing preparation, you **MUST** invoke **azure-validate** before any deployment attempt. Do NOT skip validation. Do NOT go directly to azure-deploy. Do NOT run `azd up` or any deployment command directly. The workflow is: > > `azure-prepare` → `azure-validate` → `azure-deploy` > > **⛔ BEFORE invoking azure-validate**, you MUST use the `edit` tool to update `.azure/deployment-plan.md` status to `Ready for Validation`. If the plan status has not been updated, the validation will fail. > > This applies to ALL deployment scenarios including containerized apps, Container Apps, App Service, Azure Functions, static sites, and any other Azure target. No exceptions. > > Skipping validation leads to deployment failures. Be patient and follow the complete workflow for the highest success outcome. **→ Update plan status to `Ready for Validation`, then invoke azure-validate**