由基礎架構程式碼產生文件
基礎架構程式碼一向出了名地缺乏充分的文件記錄。 Bicep 範本可以正確部署複雜且多層級的架構。 但如果沒有人記錄它部署了什麼、每個資源為何存在，或參數控制了什麼，這個範本就變成了部落知識。 只有寫這封信的人才能安全地更改。
這個缺口之所以存在，是因為文件寫起來繁瑣且容易被跳過。 完成並驗證一個 400 行的 Bicep 範本後，撰寫相符的架構描述感覺像是另一個專案。
GitHub Copilot 改變了這個等式。 給定範本後，Copilot 能在幾秒內產生文件的初稿。 工程師的工作從撰寫文件轉為檢閱與潤飾文件。 文件撰寫不再是可有可無，而是成為日常工作流程的一部分。
產生純語言架構描述
文件方面最迫切的需求，是針對範本會部署哪些內容提供一份便於人閱讀的說明。 這種層級的文件是專案經理、資安審查員或新團隊成員在理解或操作基礎架構前所需要的。
Explain what this Bicep template deploys in plain language.
Structure your explanation as follows:
1. A one-paragraph summary of the overall architecture
2. A section for each major resource group or logical component,
describing what it does and why it exists
3. A description of how the components connect to each other
4. Any security controls that are configured
Use language that a technical project manager could understand.
Avoid Bicep-specific syntax in the explanation.
[paste template here]
結構教學很重要。 沒有這個，Copilot 只會產生一份扁平的資源清單，而非能傳達架構意圖的說明。
輸出結構範例
對於樞紐輻射網路範本，結構良好的說明可能如下：
## Architecture Overview
This template deploys a hub-and-spoke network topology for Azure, a standard
pattern for enterprise environments that need centralized security controls
alongside segmented workload networks.
## Hub Network
The hub virtual network (10.0.0.0/16) is the central connection point for all
network traffic. It hosts the Azure Firewall, which inspects and filters all
traffic entering and leaving the environment. It also contains an Azure Bastion
host, which provides secure browser-based access to virtual machines without
exposing RDP or SSH ports to the internet.
## Spoke Network
The spoke virtual network (10.1.0.0/16) is where application workloads run.
It connects to the hub through VNet peering, a low-latency, private connection
within the Azure backbone. Traffic from the spoke to the internet is routed
through the hub firewall, ensuring all outbound connections are inspected.
## Observability
A Log Analytics workspace collects diagnostic logs from the Azure Firewall.
This enables security monitoring, threat detection, and compliance auditing
from a single location.
## Security Controls
- All internet-bound traffic from workloads is inspected by Azure Firewall
- No management ports (SSH, RDP) are exposed directly to the internet
- Network access to VMs is restricted to Azure Bastion sessions only
產生參數參考文件
參數繁多的範本在沒有文件的情況下很難使用。 參數參考表告訴使用者每個參數的功能、哪些值有效，以及預設值。
Generate a markdown parameter reference table for this Bicep template.
Include these columns:
| Parameter | Type | Default | Allowed Values | Description |
Cover all parameters. For parameters with @allowed() decorators,
list the allowed values. For parameters with no default, mark the
Default column as "Required". Write descriptions in plain language,
not a repeat of the parameter name.
Copilot 能準確產生此表格，因為它直接從模板讀取 @description()、@allowed() 和 @minLength() 裝飾器。 如果你的範本缺少裝飾器，Copilot 會從參數名稱推斷描述。 這也是產生範本時使用描述性參數名稱的另一個原因。
產生輸出的參考資料
Add a second table below the parameters table documenting all outputs
from this template. Include: Output Name | Type | Description.
Describe what each output contains and when you would use it.
此範例對供其他範本使用的模組輸出非常有用。 輸出說明文件會告訴呼叫端其會收到什麼，以及其格式為何。
用美人魚製作架構圖
Mermaid 是一種基於文字的圖表語言，原生支援於 GitHub Markdown、Azure DevOps Wiki 及 VS Code。 它能從純文字渲染圖表。 這表示圖表可以與基礎架構程式碼同存於同一儲存庫，與範本同時有版本控制與更新。
Represent the network topology deployed by this Bicep template as a Mermaid diagram.
Use flowchart LR (left to right) direction.
Show:
- Each VNet as a subgraph
- Subnets as nodes inside their VNet subgraph
- Resources (Firewall, Bastion, VMs) as nodes in the appropriate subnet
- VNet peering as a double-headed arrow between VNets
- The Log Analytics workspace outside the VNets, with a log collection arrow
from the Firewall
- Use descriptive labels on each node showing the resource name and type
Wrap the Mermaid code in a markdown code block with the mermaid language tag.
第一代美人魚圖並不總是像素般完美。 請 Copilot 調整版面配置、新增或移除元件，或根據最適合的呈現效果變更圖表類型。
圖解驗證
在 VS Code 中使用 Markdown 預覽功能（Ctrl+Shift+V）預覽圖表。 如果 GitHub 在你倉庫的 README 裡渲染了 Mermaid，請推送該檔案並查看渲染出來的結果。 GitHub 的渲染器行為和 VS Code 略有不同。
如果圖表太複雜無法清晰渲染，請 Copilot 簡化：
Simplify this Mermaid diagram to show only the major components and their
connections. Remove subnet-level detail and focus on the resource relationships
at the VNet level.
產生變更摘要
當基礎設施改變時，需要有人檢視哪些改變了。 像「更新的 Bicep 範本」這類 pull request 描述對審查者毫無幫助。 Copilot 可以透過比較兩個版本的範本來產生有意義的變更摘要。
Compare these two Bicep templates (v1 and v2) and generate a change summary
in markdown format.
For each change, include:
- What changed (resource added, modified, or removed)
- Why it likely changed (e.g., added for security, added for observability,
fixed a misconfiguration)
- Impact on existing deployments (e.g., requires redeployment, causes downtime,
is additive only)
Group changes by category: Security, Observability, Networking, Compute, Cost.
--- v1 template ---
[paste old template]
--- v2 template ---
[paste new template]
此變更摘要可立即用作提取要求的描述、給利害關係人的溝通內容，或部署操作手冊中的章節。
變更摘要輸出的範例
## Infrastructure Change Summary — v1 to v2
### Security
- **Added:** AzureFirewallSubnet resized from /27 to /26
- *Why:* Azure Firewall requires a minimum /26 subnet. The /27 caused deployment failures.
- *Impact:* Requires redeployment of the hub VNet. Existing peering will need to be re-established.
- **Added:** CostCenter tag on all resources
- *Why:* Azure Policy requires a CostCenter tag. Missing tag caused policy denial.
- *Impact:* Additive only. No resource changes.
### Observability
- **Added:** Azure Bastion host in AzureBastionSubnet
- *Why:* Provides browser-based secure access to VMs without exposing management ports.
- *Impact:* Additive. New resource. Costs approximately $140/month per Bastion instance.
- **Added:** Log Analytics Workspace and Firewall diagnostic settings
- *Why:* Required for security monitoring and compliance auditing.
- *Impact:* Additive. Data ingestion costs depend on log volume.
保持文件同步
最常見的文件失敗是陳舊。 一份在範本為版本 1 時撰寫的文件，到了版本 5 就會變得具有誤導性。
有幾種做法能長期維持準確度。
在公關流程中產生文件。 在 CI 管線中新增一個步驟，當範本大幅變更時標幟 PR 以進行文件檢閱。
使用 @description() 裝飾項目作為真實資料來源。 透過裝飾工具嵌入範本的文件會與程式碼同步，因為它們存在同一個檔案。 外部的 Markdown 文件可能會逐漸與實際情況脫節。
為每個主要版本產生文件。 每次重大合併至 main 後，使用變更摘要提示詞。 將更新後的文件與範本變更一併提交到同一個 PR 中。
README 更新提示詞：
The following changes were made to our infrastructure template in this release:
[paste change summary]
Update the Infrastructure README to reflect these changes. Specifically:
- Update the Architecture Overview section to mention Azure Bastion
- Add the new CostCenter parameter to the parameter reference table
- Update the "Resources Deployed" list