sop-writing
核心哲學
標準作業程序（SOP）不是一篇理論論文或一份理想的政策文件。SOP 是一份可執行的演算法手冊，供人類或代理操作員使用。一個好的 SOP 應設計成讓合格的操作員在凌晨 3 點極度壓力下，也能以零模糊、零猜測、零災難性錯誤的方式執行流程。每一步都必須有確定性的輸入、編號的實際操作、可觀察的驗收標準以及明確的升級路徑。
4 步驟標準作業程序（SOP）架構
步驟 1：範圍、治理與執行前準備
- 元資料與所有權標頭：
- SOP ID、版本號（SemVer）、生效日期、審查頻率（每年/每半年）、負責的流程擁有者。
- 嚴格的目標與範圍界定：
- 此程序涵蓋的內容，以及不涵蓋的內容。
- 先決條件與存取權限：
- 在執行第一步驟之前，列出所需的憑證、VPN 存取權限、軟體套件和環境變數。
步驟 2：確定性編號步驟序列
- 命令式、無歧義的動作動詞：
- 每個步驟都以主動動詞開頭：按一下、執行、驗證、複製、匯出、檢查。
- 絕不寫被動式指導方針：「確保已檢查日誌。」
- 請寫：「1. 開啟 Datadog 儀表板
Prod-Ingestion。2. 檢查圖表p99 Latency。3. 驗證數值低於 200ms。」
- 複製貼上命令衛生：
- 在圍欄程式碼區塊中提供確切的 CLI 命令或程式碼片段。切勿讓操作員猜測旗標名稱或參數。
步驟 3：可觀察的驗證與驗收閘門
- 「我怎麼知道它成功了？」檢查：
- 每個主要步驟都必須指定其預期輸出：
- 「預期輸出：終端機顯示
Deployment Complete: 12/12 pods healthy。」
- 「預期輸出：終端機顯示
- 每個主要步驟都必須指定其預期輸出：
- 決策樹與分支邏輯：
- 清楚格式化條件邏輯：
- 如果 status == 200：繼續執行步驟 4。
- 如果 status == 500：跳至故障排除章節 5.1。
- 清楚格式化條件邏輯：
步驟 4：失敗處理、回滾與升級路徑
- 回滾手冊：
- 如果程序在中途失敗，提供確切的回滾命令以將系統還原至安全的基準狀態。
- 升級 SLA 與聯絡人矩陣：
- 如果無法在 15 分鐘內完成程序，應傳呼誰、透過哪個管道、以及何種嚴重性等級。
交付物格式：生產級標準作業程序（SOP-TEMPLATE.md）
# 標準作業程序：生產環境 Hotfix 部署
*SOP ID: SOP-ENG-042 | 版本號: v2.1.0 | 擁有者: 平台工程主管*
*生效日期：[YYYY-MM-DD] | 審查頻率：每季*
## 1. 目標與範圍
此程序規範在標準每週 CI/CD 發布週期之外，將緊急 hotfix 部署至生產環境叢集的行為。
## 2. 先決條件與存取需求
- 生產 AWS IAM 角色 `arn:aws:iam::123456789012:role/EmergencyDeployer`
- GitHub CLI (`gh`) 已通過儲存庫寫入權限驗證
- 已在本機設定 AWS CLI v2 與 `kubectl`
## 3. 逐步執行順序
### 步驟 1：分支隔離與驗證
1. 從 `main` 分支檢出 hotfix 分支：
```bash
git checkout main && git pull origin main
git checkout -b hotfix/SEC-[IssueNum]
- 在本機執行完整測試套件：
npm run test:ci- 驗收檢查：退出代碼為 0；所有測試套件通過。
步驟 2：建置與標記容器映像
- 觸發自動化 hotfix 建置管道：
gh workflow run hotfix-build.yml -f branch=hotfix/SEC-[IssueNum]- 預期輸出：GitHub Actions 發出映像摘要
sha256:...。
- 預期輸出：GitHub Actions 發出映像摘要
步驟 3：生產環境部署與 Canary 驗證
- 將部署套用至 Canary Pod 池（10% 流量）：
kubectl set image deployment/api-gateway api=ecr.internal/api:[Digest] -n production - 監控錯誤率 5 分鐘：
- 檢查 Grafana 儀表板
https://grafana.internal/d/canary-health。 - 驗收閘門：5xx 錯誤率必須維持 < 0.01%。
- 檢查 Grafana 儀表板
4. 回滾與應變計畫
如果 Canary 錯誤率超過 0.05%：
- 立即回滾部署：
kubectl rollout undo deployment/api-gateway -n production - 在 Slack
#incident-war-room通知事件指揮官。
5. 升級聯絡人
- 主要待命 SRE：PagerDuty 排班表
sre-tier-1 - 工程副總裁：電話：[號碼]（如果中斷時間超過 15 分鐘則傳呼）
---
## 實際範例：資料庫還原 SOP
- **情境**：加密 PostgreSQL 資料庫快照還原的復原手冊。
- **影響**：逐步 SOP 讓一位夜間輪值的初級工程師在 11 分鐘內還原了意外刪除的客戶資料表，且零資料損毀。
---
## 驗證檢查清單
- [ ] 每個程序步驟都以主動命令式動詞開頭。
- [ ] 命令與程式碼片段可 100% 複製貼上，語法精確無誤。
- [ ] 每個關鍵步驟都指定了預期的可觀察輸出。
- [ ] 已記錄執行失敗時的明確回滾程序。
- [ ] 升級聯絡人矩陣包含指定角色與傳呼管道。
---
## 反模式
- **模糊的指令**：撰寫「正確設定網路」，而不是提供確切的 IP tables 或 YAML 設定。
- **缺少回滾手冊**：說明如何推送變更，卻未說明如何在變更造成問題時復原。
- **未經測試的手冊**：撰寫緊急災難復原 SOP，但從未在暫存環境中進行過乾執行。