Thariq Skills #8 — Runbooks：從症狀到結構化報告的調查流程

凌晨三點，告警響了。誰去查？

傳統的答案是 on-call 工程師。但如果你有一個可以執行 runbook 的 agent，它可以在你起床前就把初步的調查報告準備好。

---

類別定義

三個元素缺一不可：

• 症狀觸發：不是「查一下系統狀態」，而是「這個錯誤代碼出現時，執行這個 runbook」
• 多工具調查：跨 log、metrics、database、外部 API 的系統性蒐集
• 結構化報告：輸出可以被人或其他 agent 閱讀的調查摘要，不只是 raw log dump

---

Thariq 的範例

service-debugging — 服務異常時的標準調查流程。從錯誤率上升開始，依序查：最近的 deploy、log 中的錯誤模式、相關服務的狀態、最近的 config 變更。

oncall-runner — On-call 工程師的第一線調查 skill。當告警觸發時，自動執行初步診斷：是 infra 問題（CPU / Memory）？是代碼問題（某個 endpoint 5xx）？是外部依賴問題（第三方 API 超時）？

log-correlator — 跨多個服務的 log 相關性分析。在分散式系統中，問題往往跨越多個 service 的 log——這個 skill 幫 agent 把分散的 log 事件組合成一個完整的事件時間線。

---

Runbook Skill 的結構

service-debugging/
├── SKILL.md              ← 觸發條件（什麼症狀啟動）+ 調查步驟概述
├── investigation-tree.md ← 決策樹：症狀 A → 查 X；症狀 B → 查 Y
├── queries/
│   ├── error-rate.sh     ← 查錯誤率的腳本
│   ├── recent-deploys.sh ← 查最近的部署記錄
│   └── db-health.sh      ← 查資料庫健康狀態
├── report-template.md    ← 輸出報告的標準格式
└── gotchas.md            ← 已知的 false positive + 調查陷阱

報告模板特別重要——它定義了「一次好的調查應該回答哪些問題」：

## 事件調查報告

**觸發時間**: [timestamp]
**初始症狀**: [描述]
**調查範圍**: [查了哪些系統]

## 發現

**根本原因（假設）**: [...]
**支持證據**: [log 摘要 / metrics 截圖]
**排除的可能性**: [查了但排除的原因]

## 建議行動

1. [立即行動]
2. [後續跟進]

**需要人工確認的決策**: [HITL 點]

---

SuperPortia 實戰觀點

SP 有 incident-response skill 和 SRE patrol scripts，但兩者之間有一個重要的缺口。

現有能力	狀況	問題
incident-response skill	有基本框架	主要是 HITL 決策流程，缺調查自動化
SRE patrol scripts	有，定期執行	是 daemon，不是 agent-callable skill
Cloud UB 查詢	可用	但缺跨系統的 log 相關分析

最關鍵的缺口：SRE patrol 腳本（superportia-sre 的監控腳本）目前是由 launchd 定期自動執行的 daemon，不是 agent 可以觸發的 skill。一個 agent 發現問題時，它沒有辦法主動執行「快速健康檢查」，只能等下次 patrol 自動跑。

---

與 On-demand Hooks 的結合

Runbooks 是 Thariq 技巧 #9（按需 hooks）最自然的使用場景：

# runbook skill 啟動時，自動掛載 /careful hook
# 阻擋所有可能影響生產環境的操作
hooks:
  - trigger: skill-activate
    action: /careful  # 阻擋 rm -rf, kubectl delete, DROP TABLE

調查期間，agent 有完整的讀取權限，但寫入和刪除操作被護欄阻擋——直到人工確認（HITL）才能執行修復。

---

回到總文

本文是九大類別系列的第八篇。完整框架與 SuperPortia 對照請見：

Anthropic 工程師的 Agent Skills 完全指南 — 九大類別 × 九個技巧