runbook
把週期性任務寫成可照做的 runbook，含排錯與 rollback
中文翻譯
--- name: runbook description: 為週期性任務或流程建立或更新營運 runbook。當要記錄 on-call 或 ops 需要反覆執行的任務、把口耳相傳的經驗變成一步一步的精確指令、替既有流程補上疑難排解與 rollback 步驟，或撰寫出事時的 escalation 路徑時使用。 argument-hint: "<process or task name>" --- # /runbook > 如果看到不認識的 placeholder，或需要確認目前連接了哪些工具，請看 [CONNECTORS.md](../../CONNECTORS.md)。 替週期性任務或流程建立一份一步一步的營運 runbook。 ## 用法 ``` /runbook $ARGUMENTS ``` ## 輸出 ```markdown ## Runbook: [任務名稱] **Owner:** [團隊/個人] | **Frequency:** [Daily/Weekly/Monthly/As Needed] **Last Updated:** [日期] | **Last Run:** [日期] ### Purpose [這份 runbook 要達成什麼，什麼時候用] ### Prerequisites - [ ] [需要的存取權或權限] - [ ] [需要的工具或系統] - [ ] [需要的資料或輸入] ### Procedure #### Step 1: [名稱] ``` [確切的指令、動作或說明] ``` **Expected result:** [應該發生什麼] **If it fails:** [該怎麼處理] #### Step 2: [名稱] ``` [確切的指令、動作或說明] ``` **Expected result:** [應該發生什麼] **If it fails:** [該怎麼處理] ### Verification - [ ] [如何確認任務成功完成] - [ ] [要檢查什麼] ### Troubleshooting | Symptom | Likely Cause | Fix | |---------|-------------|-----| | [你看到什麼] | [為什麼] | [該怎麼做] | ### Rollback [出問題時如何復原] ### Escalation | Situation | Contact | Method | |-----------|---------|--------| | [什麼時候要 escalate] | [找誰] | [怎麼聯絡] | ### History | Date | Run By | Notes | |------|--------|-------| | [日期] | [人員] | [任何問題或觀察] | ``` ## 如果有連接 Connector 如果有連接 **~~knowledge base**： - 搜尋既有的 runbook 來更新，而不是從零開始寫 - 把完成的 runbook 發布到你的 ops wiki 如果有連接 **~~ITSM**： - 把 runbook 連結到相關的事件類型和變更請求 - 從 on-call 排班表自動帶入 escalation 聯絡人 ## 小提醒 1. **要具體到讓人受不了**：「執行 script」不是一個步驟。「在 ops 伺服器上執行 `python sync.py --prod --dry-run`」才是。 2. **寫出失敗模式**：每一步可能出什麼錯，以及怎麼處理。 3. **測試這份 runbook**：找一個不熟這個流程的人照著做，卡住的地方就修掉。
英文原文
--- name: runbook description: Create or update an operational runbook for a recurring task or procedure. Use when documenting a task that on-call or ops needs to run repeatably, turning tribal knowledge into exact step-by-step commands, adding troubleshooting and rollback steps to an existing procedure, or writing escalation paths for when things go wrong. argument-hint: "<process or task name>" --- # /runbook > If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md). Create a step-by-step operational runbook for a recurring task or procedure. ## Usage ``` /runbook $ARGUMENTS ``` ## Output ```markdown ## Runbook: [Task Name] **Owner:** [Team/Person] | **Frequency:** [Daily/Weekly/Monthly/As Needed] **Last Updated:** [Date] | **Last Run:** [Date] ### Purpose [What this runbook accomplishes and when to use it] ### Prerequisites - [ ] [Access or permission needed] - [ ] [Tool or system required] - [ ] [Data or input needed] ### Procedure #### Step 1: [Name] ``` [Exact command, action, or instruction] ``` **Expected result:** [What should happen] **If it fails:** [What to do] #### Step 2: [Name] ``` [Exact command, action, or instruction] ``` **Expected result:** [What should happen] **If it fails:** [What to do] ### Verification - [ ] [How to confirm the task completed successfully] - [ ] [What to check] ### Troubleshooting | Symptom | Likely Cause | Fix | |---------|-------------|-----| | [What you see] | [Why] | [What to do] | ### Rollback [How to undo this if something goes wrong] ### Escalation | Situation | Contact | Method | |-----------|---------|--------| | [When to escalate] | [Who] | [How to reach them] | ### History | Date | Run By | Notes | |------|--------|-------| | [Date] | [Person] | [Any issues or observations] | ``` ## If Connectors Available If **~~knowledge base** is connected: - Search for existing runbooks to update rather than create from scratch - Publish the completed runbook to your ops wiki If **~~ITSM** is connected: - Link the runbook to related incident types and change requests - Auto-populate escalation contacts from on-call schedules ## Tips 1. **Be painfully specific** — "Run the script" is not a step. "Run `python sync.py --prod --dry-run` from the ops server" is. 2. **Include failure modes** — What can go wrong at each step and what to do about it. 3. **Test the runbook** — Have someone unfamiliar with the process follow it. Fix where they get stuck.