runbook-generator

runbook-generator skill 概览

runbook-generator 的作用

runbook-generator 是一个面向工程团队的技能，用于为服务生成运维 runbook 草稿，覆盖部署、故障响应、维护、健康检查和回滚等文档场景。它包含一个 Python 辅助脚本 scripts/runbook_generator.py，可以根据服务名称、负责人和环境生成结构化的 Markdown runbook；同时还提供 references/runbook-templates.md，用于补充更完整的部署、故障处理、数据库维护、过期检测和验证模式。

适合 DevOps、SRE 和技术写作团队

runbook-generator skill 非常适合平台团队、SRE、DevOps 工程师，以及需要为服务运维文档建立统一起点的技术写作者。尤其在新服务准备上线、on-call 工程师需要基础操作手册，或多个团队正在用不一致格式编写 runbook 时，它的价值更明显。

对 Technical Writing 来说，它的价值不只是快速生成一页文档。这个技能还能为写作者提供一套实用结构，用来向工程师追问关键问题：归属负责人、访问权限、部署检查、回滚触发条件、升级路径、验证步骤和评审节奏。

它和通用 prompt 的区别

通用 AI prompt 可能会生成一份看起来很完整、但缺少关键运维细节的 runbook。runbook-generator 更扎实：它提供可重复使用的 CLI 骨架，包含标准运维章节，并通过参考文件提示真实 runbook 中需要关注的问题，例如 staging dry-run、明确的回滚触发条件、smoke tests、季度验证，以及当部署配置或 CI 文件发生变化时的过期检测。

采用前需要考虑的事项

这个技能不会自动检查你的基础设施、服务依赖图、CI/CD 系统、监控 dashboard 或 secret manager。生成结果只是脚手架，不是已经获批的生产操作规程。发布给 on-call 使用前，需要替换示例命令，补充真实 dashboard 和告警，验证回滚步骤，并在 staging 环境中测试文档。

如何使用 runbook-generator skill

runbook-generator 安装方式和优先查看的文件

在你的 Claude skills 环境中安装该技能：

npx skills add alirezarezvani/claude-skills --skill runbook-generator

然后在依赖它之前，先查看源文件：

• SKILL.md — 能力概览、快速开始和推荐工作流。
• scripts/runbook_generator.py — 实际的 CLI 生成器和默认 Markdown 章节。
• references/runbook-templates.md — 用于部署、故障响应、数据库维护、过期检测和季度验证的额外模板。

由于该仓库似乎没有为这个技能单独提供 README 或 metadata 文件，以上三个文件是最重要的阅读路径。

runbook-generator 的基础用法

脚本可以把 runbook 输出到 stdout，也可以写入文件：

python3 scripts/runbook_generator.py payments-api
python3 scripts/runbook_generator.py payments-api --owner platform --output docs/runbooks/payments-api.md

如果你安装的版本支持环境参数，建议使用它，避免对 “production/staging” 做模糊假设。如果不支持，请立即编辑生成的 Markdown，并手动设置环境。生成的章节通常包括概览、前置条件、启动和停止流程、健康检查、部署 checklist、回滚、故障响应、升级路径和验证元数据。

用具体运维信息提示该技能

一个较弱的请求是：

Generate a runbook for payments-api.

更好的 runbook-generator 使用 prompt 是：

Use runbook-generator to create a production runbook for payments-api. Owner is Platform Payments. Runtime is Kubernetes on EKS. Deployment is via GitHub Actions and Helm. Health endpoint is /healthz. Logs are in Datadog, traces in Honeycomb, alerts in PagerDuty service payments-api-prod. Include rollback triggers for elevated 5xx rate, p95 latency over 800 ms, failed migrations, or payment authorization errors. Add placeholders where I need to confirm exact commands.

这样能提升输出质量，因为技能可以把脚手架映射到真实的运维决策，而不是编造泛泛的命令。

生成后的推荐工作流

先生成第一版草稿，然后和服务负责人一起编辑。把每一条示例命令都替换为经过测试的命令，补充预期输出，链接 dashboard 和告警名称，并明确升级联系人。接着在 staging 中 dry-run 这套流程：启动、停止、部署、健康检查和回滚。最后添加 Last verified 日期，并使用 references/runbook-templates.md 中的 checklist 安排季度评审。

runbook-generator skill 常见问题

runbook-generator 足够生成生产 runbook 吗？

单独使用还不够。runbook-generator 会创建结构化基线，但生产就绪程度取决于是否验证过服务特定细节。一份生产 runbook 应包含真实命令、访问前置条件、已知故障模式、回滚决策点、dashboard 链接、告警路由、升级负责人，以及经过测试的预期输出。

什么时候不应该使用这个技能？

不要把它作为安全关键、强合规或高风险数据库操作的唯一依据。它可以帮助搭建数据库维护说明的框架，但迁移顺序、锁风险、备份验证和恢复流程都需要工程评审。对于无法在 staging 中测试的系统，也不要直接发布生成的 runbook。

它和 incident template 有什么区别？

incident template 通常聚焦于分诊、缓解、沟通和事后复盘。runbook-generator skill 覆盖范围更广：它包含日常运维流程，例如启动、停止、健康检查、部署、回滚和升级路径。对于故障频发的服务，可以把生成的 runbook 与 references/runbook-templates.md 中的 incident response template 结合使用。

它适合新手吗？

适合，前提是使用者了解目标服务，或能访谈了解该服务的人。新手可以从清晰结构中受益，但在填写部署命令、可观测性链接、严重级别规则和回滚标准时，可能仍需要帮助。这个技能最适合作为带引导的 checklist，而不是一个自主判断基础设施的专家。

如何改进 runbook-generator skill

在请求输出前改进 runbook-generator 的输入

质量提升最大的地方，是提供更好的源事实。在调用 runbook-generator 之前，先收集：

• 服务名称、负责人、Slack channel 和升级路径。
• 环境、运行时、部署工具和 CI/CD workflow。
• 健康检查端点、smoke tests、dashboard 和告警名称。
• 依赖清单：数据库、队列、API、缓存和第三方服务。
• 回滚方式、last-known-good release 来源和回滚触发条件。
• 近期故障或已知故障模式。

这些细节可以避免草稿变成一页泛泛的运维说明。

用可验证流程替换占位内容

常见失败模式包括“check logs”“monitor metrics”或“rollback if needed”这类模糊步骤。把它们改成可执行的指令：

• 不要写 “check logs”，而是写出确切的 log query 或 dashboard link。
• 不要写 “run smoke tests”，而是列出命令和预期响应。
• 不要写 “rollback if errors occur”，而是定义阈值和时间窗口。
• 不要写 “contact owner”，而是写明 PagerDuty service、Slack channel 和 backup team。

当 on-call 工程师能在高压下不靠猜测地照着执行时，runbook 才真正有用。

使用模板扩展默认脚手架

完成第一版草稿后，使用 references/runbook-templates.md 在服务需要的地方增加深度。对于部署频繁的服务，补充部署前检查、artifact verification、smoke tests 和沟通说明。对于故障响应，补充前五分钟分诊、诊断来源、缓解选项和事后复盘动作。对于数据库工作，补充备份验证、锁风险说明、执行顺序和恢复检查。

在 staging 和真实故障后持续迭代

最好的 runbook 都是在使用中改进出来的。完成 staging dry-run 后，更新失效命令、缺失权限、不清晰的预期输出和时间假设。真实故障后，把响应人员实际需要的内容补进去：更快的诊断链接、更清晰的严重级别映射、更安全的缓解步骤，或更合理的回滚阈值。保持 Last verified 字段为最新，并在部署配置、CI pipeline、schema 或运行时环境文件变化时重新评审 runbook。