Agent-almanac write-incident-runbook

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/write-incident-runbook" ~/.claude/skills/pjt222-agent-almanac-write-incident-runbook-f0be5a && rm -rf "$T"

manifest: i18n/zh-CN/skills/write-incident-runbook/SKILL.md

source content

Write Incident Runbook

创建可操作的运行手册，引导响应人员完成事故诊断和解决。

适用场景

为反复出现的告警或事故记录响应流程
在值班轮换成员中标准化事故响应
通过清晰的诊断步骤缩短平均修复时间（MTTR）
为新团队成员创建事故处理培训材料
建立升级路径和通信协议
将部落知识迁移到书面文档
将告警链接到解决流程（告警注解）

输入

必填：事故或告警名称/描述
必填：历史事故数据和解决模式
可选：诊断查询（Prometheus、日志、追踪）
可选：升级联系人和通信渠道
可选：以前的事故复盘

步骤

第 1 步：选择运行手册模板结构

完整模板文件请参阅 Extended Examples。

根据事故类型和复杂程度选择合适的模板。

基础运行手册模板结构：

# [Alert/Incident Name] Runbook
## Overview | Severity | Symptoms
## Diagnostic Steps | Resolution Steps
## Escalation | Communication | Prevention | Related

高级 SRE 运行手册模板（摘录）：

# [Service Name] - [Incident Type] Runbook

## Metadata
- Service, Owner, Severity, On-Call, Last Updated

## Diagnostic Phase
### Quick Health Check (< 5 min): Dashboard, error rate, deployments
### Detailed Investigation (5-20 min): Metrics, logs, traces, failure patterns
# ... (see EXAMPLES.md for complete template)

关键模板组件：

元数据：服务所有权、严重程度、值班轮换
诊断阶段：快速检查 → 详细调查 → 故障模式
解决阶段：立即缓解 → 根因修复 → 验证
升级：标准和联系路径
通信：内部/外部模板
预防：短期/长期行动

预期结果： 所选模板与事故复杂程度匹配，章节适合服务类型。

失败处理：

从基础模板开始，根据事故模式迭代
查阅行业示例（Google SRE 书籍、供应商运行手册）
根据首次使用后的团队反馈调整模板

第 2 步：记录诊断流程

完整的诊断查询和决策树请参阅 Extended Examples。

创建带有具体查询的逐步调查流程。

六步诊断清单：

验证服务健康状态：健康端点检查和正常运行时间指标

curl -I https://api.example.com/health  # Expected: HTTP 200 OK

up{job="api-service"}  # Expected: 1 for all instances

检查错误率：当前错误百分比及按端点分解

sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m])) * 100  # Expected: < 1%

分析日志：来自 Loki 的近期错误和主要错误消息

{job="api-service"} |= "error" | json | level="error"

检查资源利用率：CPU、内存和连接池状态

avg(rate(container_cpu_usage_seconds_total{pod=~"api-service.*"}[5m])) * 100
# Expected: < 70%

审查近期变更：部署、git 提交、基础设施变更
检查依赖项：下游服务健康状态、数据库/API 延迟

故障模式决策树（摘录）：

服务下线？→ 检查所有 Pod/实例
错误率升高？→ 检查特定错误类型（5xx、网关、数据库、超时）
何时开始？→ 部署后（回滚）、逐渐增加（资源泄漏）、突然发生（流量/依赖）

预期结果： 诊断流程具体，包含预期值与实际值对比，引导响应人员完成调查。

失败处理：

在记录前在实际监控系统中测试查询
为视觉参考添加仪表板截图
为频繁遗漏的步骤添加"常见错误"部分
根据事故响应人员的反馈迭代

第 3 步：定义解决流程

完整命令和回滚流程的所有 5 个解决选项请参阅 Extended Examples。

记录带有回滚选项的逐步修复流程。

五种解决选项（简要摘要）：

回滚部署（最快）：针对部署后的错误

kubectl rollout undo deployment/api-service

验证 → 监控 → 确认解决（错误率 < 1%、延迟正常、无告警）

扩容资源：针对高 CPU/内存、连接池耗尽

kubectl scale deployment/api-service --replicas=$((current * 3/2))

重启服务：针对内存泄漏、连接卡死、缓存损坏

kubectl rollout restart deployment/api-service

功能标志/熔断器：针对特定功能错误或外部依赖故障

kubectl set env deployment/api-service FEATURE_NAME=false

数据库修复：针对数据库连接、慢查询、连接池耗尽

-- Kill long-running queries, restart connection pool, increase pool size

通用验证清单：

回滚流程：如果解决措施使情况恶化 → 暂停/取消 → 还原 → 重新评估

预期结果： 解决步骤清晰，包含验证检查，为每个操作提供回滚选项。

失败处理：

为复杂流程添加更细粒度的步骤
为多步骤流程添加截图或图表
记录命令输出（预期值与实际值）
为复杂解决流程创建单独的运行手册

第 4 步：建立升级路径

完整升级级别和联系目录模板请参阅 Extended Examples。

定义何时以及如何升级事故。

立即升级的情况：

面向客户的中断超过 15 分钟
SLO 错误预算消耗 > 10%
疑似数据丢失/损坏或安全漏洞
20 分钟内无法识别根因
缓解尝试失败或使情况恶化

五个升级级别：

主要值班人员（5 分钟响应）：部署修复、回滚、扩容（单独处理最多 30 分钟）
次要值班人员（15 分钟后自动）：额外的调查支持
团队负责人（架构决策）：数据库变更、供应商升级、超过 1 小时的事故
事故指挥官（跨团队协调）：多团队、客户沟通、超过 2 小时的事故
高管（C 级）：重大影响（>50% 用户）、SLA 违约、媒体/PR、超过 4 小时的中断

升级流程：

通知目标并提供：当前状态、影响、已采取的行动、需要的帮助、仪表板链接
如有需要交接：共享时间线、行动、访问权限、保持可用
不要沉默：每 15 分钟更新一次，提问，提供反馈

联系目录：维护包含角色、Slack、电话、PagerDuty 的表格，涵盖：

平台/数据库/安全/网络团队
事故指挥官
外部供应商（AWS、数据库供应商、CDN 提供商）

预期结果： 升级标准清晰，联系信息易于获取，升级路径与组织结构一致。

失败处理：

验证联系信息是最新的（每季度测试）
为何时升级添加决策树
包含升级消息示例
记录每个级别的响应时间期望

第 5 步：创建通信模板

包含完整格式的所有内部和外部模板请参阅 Extended Examples。

提供预先编写的事故更新消息。

内部模板（Slack #incident-response）：

初始声明：

🚨 INCIDENT: [Title] | Severity: [Critical/High/Medium]
Impact: [users/services] | Owner: @username | Dashboard: [link]
Quick Summary: [1-2 sentences] | Next update: 15 min

进展更新（每 15-30 分钟）：

📊 UPDATE #N | Status: [Investigating/Mitigating/Monitoring]
Actions: [what we tried and outcomes]
Theory: [what we think is happening]
Next: [planned actions]

缓解完成：

✅ MITIGATION | Metrics: Error [before→after], Latency [before→after]
Root Cause: [brief or "investigating"] | Monitoring 30min before resolved

解决：

🎉 RESOLVED | Duration: [time] | Root Cause + Impact + Follow-up actions

误报：无影响，无需跟进

外部模板（状态页面）：

初始：正在调查，开始时间，15 分钟后下次更新
进展：已识别原因（面向客户的语言），正在实施修复，预计解决时间
解决：解决时间、根因（简单语言）、持续时间、预防措施

客户邮件模板：时间线、影响描述、解决方案、预防措施、赔偿（如适用）

预期结果： 模板在事故期间节省时间，确保通信一致，减少响应人员的认知负担。

失败处理：

根据公司通信风格定制模板
用常见事故类型预填充模板
创建 Slack 工作流/机器人自动填充模板
在事故回顾期间审查模板

第 6 步：将运行手册链接到监控

完整的 Prometheus 告警配置和 Grafana 仪表板 JSON 请参阅 Extended Examples。

将运行手册与告警和仪表板集成。

向 Prometheus 告警添加运行手册链接：

- alert: HighErrorRate
  annotations:
    runbook_url: "https://wiki.example.com/runbooks/high-error-rate"
    dashboard_url: "https://grafana.example.com/d/service-overview"
    incident_channel: "#incident-platform"

在运行手册中嵌入快速诊断链接：

服务概览仪表板
过去 1 小时错误率（Prometheus 直接链接）
近期错误日志（Loki/Grafana Explore）
近期部署（GitHub/CI）
PagerDuty 事故

创建 Grafana 仪表板面板，包含运行手册链接（markdown 面板，列出所有事故运行手册及值班和升级信息）

预期结果： 响应人员可直接从告警或仪表板访问运行手册，诊断查询预填充，一键访问相关工具。

失败处理：

验证运行手册 URL 无需 VPN/登录即可访问
为复杂的 Grafana/Prometheus 链接使用短链接
每季度测试链接确保不失效
为常用运行手册创建浏览器书签

验证清单

常见问题

过于笼统：包含"检查日志"等模糊步骤但没有具体查询的运行手册不可操作。要具体。
信息过时：引用旧系统或命令的运行手册变得无用。每季度审查。
没有验证步骤：没有验证的解决方案会导致误报。始终包含"如何确认已修复"。
缺少回滚流程：每个操作都应有回滚计划。不要让响应人员陷入更糟糕的状态。
假设知识：只面向专家的运行手册排除了初级工程师。为轮换中经验最少的人编写。
没有所有者：没有所有者的运行手册会变得陈旧。分配负责更新的团队/人员。
隐藏在认证后面：在 VPN/SSO 问题期间无法访问的运行手册在危机期间无用。缓存副本或使用公共 wiki。

Agent-almanac write-incident-runbook

Write Incident Runbook

适用场景

输入

步骤

第 1 步：选择运行手册模板结构

第 2 步：记录诊断流程

第 3 步：定义解决流程

第 4 步：建立升级路径

第 5 步：创建通信模板

第 6 步：将运行手册链接到监控

验证清单

常见问题

相关技能