建立 GitHub Actions 工作流程規格
為 GitHub Actions 工作流程 ${input:WorkflowFile} 建立一份完整的規格。
這份規格作為工作流程行為、需求與限制的說明文件。它必須與實作無關，專注於工作流程達成什麼，而非如何實作。
AI 最佳化需求
- Token 效率：使用簡潔語言，不犧牲清晰度
- 結構化資料：利用表格、清單與圖表呈現密集資訊
- 語意清晰：全篇一致使用精確術語
- 實作抽象化：避免特定語法、指令或工具版本
- 可維護性：設計便於隨工作流程演進而更新
規格範本
儲存為：/spec/spec-process-cicd-[workflow-name].md
---
title: CI/CD 工作流程規格 - [工作流程名稱]
version: 1.0
date_created: [YYYY-MM-DD]
last_updated: [YYYY-MM-DD]
owner: DevOps 團隊
tags: [process, cicd, github-actions, automation, [領域特定標籤]]
---
## 工作流程概述
**目的**：[一句話描述工作流程的主要目標]
**觸發事件**：[列出觸發條件]
**目標環境**：[環境範圍]
## 執行流程圖
```mermaid
graph TD
A[觸發事件] --> B[工作 1]
B --> C[工作 2]
C --> D[工作 3]
D --> E[結束]
B --> F[並行工作]
F --> D
style A fill:#e1f5fe
style E fill:#e8f5e8
工作與相依性
| 工作名稱 |
目的 |
相依性 |
執行環境 |
| job-1 |
[目的] |
[前置條件] |
[執行器/環境] |
| job-2 |
[目的] |
job-1 |
[執行器/環境] |
需求矩陣
功能需求
| 編號 |
需求 |
優先級 |
驗收標準 |
| REQ-001 |
[需求] |
高 |
[可測試標準] |
| REQ-002 |
[需求] |
中 |
[可測試標準] |
安全需求
| 編號 |
需求 |
實作限制 |
| SEC-001 |
[安全需求] |
[限制說明] |
效能需求
| 編號 |
指標 |
目標 |
測量方式 |
| PERF-001 |
[指標] |
[目標值] |
[如何測量] |
輸入/輸出合約
輸入
## 環境變數
ENV_VAR_1: string # 用途：[說明]
ENV_VAR_2: secret # 用途：[說明]
## 儲存庫觸發
paths: [路徑過濾器清單]
branches: [分支模式清單]
輸出
## 工作輸出
job_1_output: string # 說明：[用途]
build_artifact: file # 說明：[內容類型]
機密與變數
| 類型 |
名稱 |
用途 |
範圍 |
| 機密 |
SECRET_1 |
[用途] |
工作流程 |
| 變數 |
VAR_1 |
[用途] |
儲存庫 |
執行限制
執行時期限制
- 超時：[最大執行時間]
- 並行：[平行執行限制]
- 資源限制：[記憶體/CPU 限制]
環境限制
- 執行器需求：[作業系統/硬體需求]
- 網路存取：[外部連線需求]
- 權限：[所需存取層級]
錯誤處理策略
| 錯誤類型 |
回應 |
復原動作 |
| 建置失敗 |
[回應] |
[復原步驟] |
| 測試失敗 |
[回應] |
[復原步驟] |
| 部署失敗 |
[回應] |
[復原步驟] |
品質閘門
閘門定義
| 閘門 |
標準 |
繞過條件 |
| 程式碼品質 |
[標準] |
[何時允許] |
| 安全掃描 |
[門檻] |
[何時允許] |
| 測試覆蓋率 |
[百分比] |
[何時允許] |
監控與可觀測性
關鍵指標
- 成功率：[目標百分比]
- 執行時間：[目標持續時間]
- 資源使用：[監控方式]
警示
| 條件 |
嚴重性 |
通知對象 |
| [條件] |
[等級] |
[誰/哪裡] |
整合點
外部系統
| 系統 |
整合類型 |
資料交換 |
SLA 需求 |
| [系統] |
[類型] |
[資料格式] |
[需求] |
相依工作流程
| 工作流程 |
關係 |
觸發機制 |
| [工作流程] |
[類型] |
[如何觸發] |
合規與治理
稽核需求
- 執行日誌：[保留政策]
- 核准閘門：[所需核准]
- 變更控制：[更新流程]
安全控制
- 存取控制：[權限模型]
- 機密管理：[輪替政策]
- 弱點掃描：[掃描頻率]
邊界案例與例外
情境矩陣
| 情境 |
預期行為 |
驗證方式 |
| [邊界案例] |
[行為] |
[如何驗證] |
驗證標準
工作流程驗證
- VLD-001：[驗證規則]
- VLD-002：[驗證規則]
效能基準
- PERF-001：[基準標準]
- PERF-002：[基準標準]
變更管理
更新流程
- 規格更新：先修改此文件
- 審查與核准：[核准流程]
- 實作：將變更套用到工作流程
- 測試：[驗證方式]
- 部署：[發布流程]
版本歷史
| 版本 |
日期 |
變更內容 |
作者 |
| 1.0 |
[日期] |
初始規格 |
[作者] |
相關規格
- [相關工作流程規格連結]
- [基礎設施規格連結]
- [部署規格連結]
### 分析說明
分析工作流程檔案時：
1. **提取核心目的**：識別主要業務目標
2. **繪製工作流程**：建立顯示執行順序的相依圖
3. **識別合約**：記錄輸入、輸出與介面
4. **擷取限制**：提取超時、權限與限制
5. **定義品質閘門**：識別驗證與核准點
6. **記錄錯誤路徑**：繪製失敗情境與復原
7. **抽象化實作**：專注於行為，而非語法
### Mermaid 圖表指南
#### 流程類型
- **循序**：`A --> B --> C`
- **平行**：`A --> B & A --> C; B --> D & C --> D`
- **條件**：`A --> B{Decision}; B -->|Yes| C; B -->|No| D`
#### 樣式
```mermaid
style TriggerNode fill:#e1f5fe
style SuccessNode fill:#e8f5e8
style FailureNode fill:#ffebee
style ProcessNode fill:#f3e5f5
複雜工作流程
對於 5 個以上工作的工作流程，使用子圖：
graph TD
subgraph "建置階段"
A[Lint] --> B[Test] --> C[Build]
end
subgraph "部署階段"
D[Staging] --> E[Production]
end
C --> D
Token 最佳化策略
- 使用表格：以結構化格式呈現密集資訊
- 一致縮寫：定義一次，全文使用
- 項目符號：避免散文段落
- 程式碼區塊：結構化資料勝於敘述
- 交叉引用：連結而非重複資訊
專注於建立一份既可作為文件，也可作為工作流程更新範本的規格。
