mcpField
R
runbook-writer

runbook-writer

github.com/mohitagw15856云与 DevOps1.5k41 次安装5 天前更新
代码仓库

关于 runbook-writer

runbook-writer 用于编写服务、事故、维护和部署的运维手册。它面向值班工程师组织流程，涵盖前置条件、精确命令、验证、回滚、故障排查和升级处理。

主要功能

  1. 01部署、事故、维护及灾难恢复手册
  2. 02前置条件与编号操作步骤
  3. 03含预期结果和失败路径的命令
  4. 04回滚、故障排查及升级处理章节

适用场景

  1. 01记录服务部署步骤
  2. 02指导运维事故响应
  3. 03整理维护或灾难恢复流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mohitagw15856/pm-claude-skills --skill runbook-writer

安装后在 Claude Code 中输入/runbook-writer确认已加载。

详细介绍

Runbook 编写技能

为服务、事件类型和部署流程编写操作手册，采用清晰的结构，让从未接触过该系统的值班工程师也能在压力下照章操作。

必要输入

如果未提供，请询问：

  • 操作手册的用途（例如：部署支付服务、响应数据库故障转移、轮换 API 密钥）
  • 操作手册类型（部署 / 事件响应 / 维护 / 灾难恢复）
  • 系统/服务名称及其功能（简要说明）
  • 受众（新值班工程师 / 经验丰富的 SRE / DevOps 团队）
  • 技术栈（适用时提供，例如：Kubernetes、AWS RDS、Node.js）
  • 监控工具（例如：Grafana、Datadog、CloudWatch、Splunk — 用于在步骤中指明具体的仪表板和告警链接）
  • 关键环境详情（例如：Kubernetes 集群名称、AWS 账号/区域、相关命名空间或资源名称 — 粘贴相关信息，以便提供准确命令）

输出格式

操作手册： [操作手册标题] 服务： [服务名称] 类型： [部署 / 事件响应 / 维护 / DR] 最后更新： [填写今天的日期，格式为 YYYY-MM-DD] 负责人： [团队或人员] 严重级别： [P1 / P2 / P3 — 适用于事件类型]

概述

本操作手册涵盖的内容： [用 1–2 句话说明本操作手册处理的场景]

使用本操作手册的时机：

  • [具体触发条件 1 — 例如 PagerDuty 告警：high-error-rate-payment-service]
  • [具体触发条件 2 — 例如 PR 合并到 main 后需要部署]

预计完成时间： [X 分钟 / X–Y 分钟，视结果而定]

未正确完成的影响： [例如：支付处理能力下降 / 数据丢失风险 / 用户无法登录]

先决条件

所需访问权限：

  • [系统/工具访问权限 — 例如 AWS Console：production-account]
  • [凭证 — 例如 vault read secret/payment-service]
  • [需要时提供 VPN / 堡垒机访问权限]

所需工具：

  • [工具名称和版本 — 例如 kubectl v1.28+]
  • [CLI 或仪表板名称]

开始前：

  • [先决条件检查 — 例如：在 Grafana 中确认当前部署运行正常]
  • [先决操作 — 例如：在 #ops-live 中通知大家即将开始]
操作步骤

为每个步骤编号。使用准确命令。不要改写工具名称或标志。

步骤 1：[操作名称] [说明正在执行的操作及原因 — 用一句话说明]

# Exact command
[command here]

预期输出： [成功执行后应显示的内容] 如果失败： [需要查找的确切错误消息] → [应采取的措施，或参阅故障排除]

步骤 2：[操作名称] [结构与步骤 1 相同]

步骤 3：验证 主要操作流程之后始终包含验证步骤：

[verification command]

预期状态： [本操作手册执行完毕后，系统正常运行时的状态]

回滚

如果操作出错，如何撤销此流程：

步骤 R1：[回滚操作]

[rollback command]

验证回滚： [确认回滚成功的命令]

故障排除
症状可能原因解决方法
[错误消息或可观察到的症状][发生原因][确切修复方法或后续步骤]
[另一种症状][原因][解决方法]
升级处理

如果本操作手册未能解决问题：

条件联系对象联系方式
[例如：DB 10 分钟后仍不可用][DBA 值班人员][PagerDuty 策略：db-oncall]
[例如：支付服务提供商无响应][供应商联系人][1Password 中的联系人：vendor-escalation]

升级处理前，务必先在 [工具] 中更新事件时间线。

操作后检查清单

完成操作手册中的步骤后：

  • 在 #ops-live 中公布完成情况及结果
  • 更新事件工单 / 部署日志
  • 在监控仪表板中确认告警已解除
  • 如果发现本操作手册存在不足 — 立即更新（附上编辑流程链接）

质量检查

  • 每个步骤都有精确的命令（不能写“运行部署脚本”）
  • 指定每个步骤的预期输出，让工程师知道操作是否成功
  • 明确说明每个步骤的失败处理方式（不能写“如果失败，请调查”）
  • 回滚流程完整且可独立测试
  • 升级联系表中不能有仅包含“[团队名称]”的单元格——每一行都必须填写真实联系人，或明确标记为 [填写：值班轮换链接]
  • 回滚部分至少包含一条具体命令（不能留作“[回滚命令]”占位符）
  • 没有接触过此系统的人也能按照运行手册操作

使用示例

  • “为 [服务] 部署编写运行手册”
  • “为 [告警类型] 创建事件响应运行手册”
  • “我需要一份 [流程] 的运行手册”
  • “记录 [X] 的运维流程”
  • “为 [场景] 编写运维手册”

反面模式

  • 不要将步骤写成“运行部署脚本”之类的模糊操作——每个步骤都必须包含精确的命令
  • 不要将回滚部分留作占位符——没有经过测试的回滚流程的运行手册是不完整且危险的
  • 不要省略每个步骤的预期输出——没有这些信息，值班工程师就无法判断步骤是否成功
  • 不要将升级联系人写成“[团队名称]”——每一行升级联系信息都必须包含真实联系人，或明确标记为待填写
  • 不要假设读者了解此系统——要面向从未接触过该系统的人编写

评论

支持 Markdown