authoring-release-runbook

authoring-release-runbook — SKILL.md

**变体：**标准 · **使用时机：**编写正式投产发布操作手册，达到让不熟悉系统的值班工程师仅凭手册就能执行部署、确认部署成功并安全回滚的标准。

概述

这项技能讲解如何编写出色的发布操作手册——供部署工程师或值班工程师遵循的操作流程，帮助他们安全且可验证地将系统发布到生产环境。这是一份全面的上线操作文档，涵盖前置条件与审批、部署前的 go/no-go 检查、有序的部署流程、部署后验证、回滚流程，以及值班/升级与监控指引。这项技能传授的是编写者的判断力——一种 SRE/运维研究方法和可执行性/安全标准——而不是章节列表。它假定有两项协作能力：一个提供章节结构的发布操作手册模板工具，以及一种基于成熟实践来制定流程的深度研究能力。编写者会拿到上游文档，这些文档由计划确定为本手册的参考依据（通常是架构文档 + 技术设计 + 测试计划），并且必须从中推导出真正可执行的流程——绝不能输出通用骨架。必须达到以下标准：从未部署过该系统的工程师，仅凭操作手册就能执行发布、确认发布成功并安全回滚；每个步骤都有预期结果，每项变更都有记录在案的还原方法；不内嵌任何机密；不捏造任何内容。操作手册也是一份持续更新的文档——每次发布时都要重新验证，并通过每次事故持续改进——因此，这项技能还涵盖将其作为有版本记录、端到端重新验证的增量修改（步骤 7），而不只是首次编写。

何时启用

• 为系统或服务编写生产发布/部署/上线操作手册。
• 记录部署周边的手动操作、验证与回滚流程：前置条件、go/no-go 检查、有序部署步骤、部署后冒烟测试、回滚、升级指引和监控指引。
• 填写发布操作手册模板，提供经过研究、可执行且源自上游文档的内容。
• 修改现有操作手册，以适应上游变更（部署拓扑/渐进式发布/退出标准发生变化）或吸取事故后经验（事故暴露出缺失的回滚步骤/故障模式）——步骤 7。

以下情况不要启用：

• 编写 CI/CD 流水线自动化本身（构建、测试、部署所用的 YAML/配置）——这属于 cicd-plan。操作手册会调用流水线并记录相关操作流程，但不会编写流水线配置。
• 撰写事后事故回顾或复盘报告——操作手册记录的是预先计划好的流程（包括回滚）；复盘报告则在事故发生后撰写。
• 定义 QA 范围、级别、覆盖率或测试用例目录——这属于测试计划。操作手册会沿用测试计划中的退出标准进行部署后验证，不会重新定义 QA 策略。
• 编写操作手册所引用的架构文档/技术设计——这些是此处的上游输入。
• 审查或评估已完成的操作手册——请使用 reviewing-release-runbook（它是运行时门禁，执行相同标准）。

输入

阅读计划交给你的每一份文档——也就是你的 depends_on 集合（上游文档，是 discovery 确定会为本文档提供信息的文档）——并追溯本运行手册的内容，确保其依据这些文档编写。不要假设输入是固定的：此技能提及的典型上游文档只是方法指导，并不限制你可能收到的文档范围。

• 根据架构文档中的可部署组件／服务和部署拓扑，以及技术设计中的发布／迁移细节，推导部署步骤。
• 根据测试计划中的退出／完成标准推导验证内容——部署后冒烟测试应复用这些标准。
• 确保内容自包含且灵活应对——根据实际收到的上下文编写运行手册；如果缺少预期的上游文档（例如可观测性／监控信息，或测试计划），就基于现有信息继续，并将缺口明确标为假设——绝不可捏造命令、主机或端点来填补。
• 有研究能力时应使用该能力（deep-research），以业界成熟的 SRE／运维实践为依据编写运行手册，而不只是填充模板。

工作流

步骤 1：采用模板工具提供的结构——不要自行设计大纲

从发布运行手册模板工具（综合版）获取章节结构。此处不要重述或重新推导章节列表；本技能提供的是如何妥善填充这些章节的方法。该文档体裁的关键章节——前置条件／签核、部署前的继续／停止决策、部署流程、部署后验证、回滚、升级处理和监控信息——由模板提供；你的职责是确保填充其中的内容质量。

步骤 2：加载上游文档；据此制定流程

阅读交给你的文档——这是你的输入，而不是一张白纸。从架构文档中找出每个可部署组件／服务及其部署拓扑。从技术设计中提取发布／迁移计划、变更的上线顺序以及任何向后兼容性约束。从测试计划中提取部署后验证需要检查的退出标准。如果上游文档内容不充分或缺失，请将缺口明确标为已说明的假设，绝不要默默采用默认值或捏造命令。

步骤 3：通过研究，以成熟的 SRE／运维实践为依据制定流程

通过 deep-research 研究业界成熟实践，为运行手册提供依据——而不是凭空编造。参考可靠来源，确认运维惯例（幂等性、逐步验证、回滚触发条件、通过引用方式使用机密信息）和部署策略机制。顺应上游文档所描述的架构进行设计。如果没有研究能力，切勿捏造命令、阈值或主机——应将这些内容明确标记为假设，并要求在发布前验证。

步骤 4：选择部署策略

默认采用蓝绿部署——部署到空闲环境，对其进行冒烟测试，然后切换流量；回滚 = 将流量切回。若架构文档／技术设计暗示了更适合项目的策略，或用户／系统／Agent 指定了策略，则改用该策略。部署步骤和回滚步骤会因策略而异：

策略	部署方式	回滚方式
蓝绿部署（默认）	部署到空闲环境，进行冒烟测试，切换流量	将流量切回旧环境（即时完成）
滚动部署	每次更新一部分实例，逐批验证	缩减新版本／扩容旧版本（逐步完成）
金丝雀发布	路由少量流量（1–10%），根据指标观察一段时间，再逐步扩大	将流量比例降为 0%／缩减新版本（影响范围有限）
重建部署	停止旧版本，部署并启动新版本（会造成停机）	重新部署先前的制品

针对所选策略编写部署和回滚流程，不要写通用流程。

步骤 5：按照可执行性与安全性要求编写每个步骤

按照此方法填充模板中的章节。小型发布不需要的章节可以精简；切勿为了凑篇幅而填充内容。

• 前置条件与签字确认 — 所需的访问权限／工具、要发布的不可变制品（按 ID／标签标识，并追溯到构建），以及所需审批（QA／测试签字、变更审批、值班人员确认）。记录审批人，而不只是说明需要审批。
• 部署前检查（继续／停止） — 部署前立即验证环境／配置前置条件，并为每项注明预期结果；设置明确的继续／停止关卡，任何检查失败都意味着停止并中止流程。包括识别当前线上版本，作为回滚目标。
• 部署流程 — 步骤须按顺序执行、可重复执行且可安全复制粘贴。每一步都必须是真实的命令／操作，并明确标出 <placeholders>，不能使用含糊的描述（例如“配置服务器”）。重复执行步骤必须安全（对一次性操作设置防护；使用 IF NOT EXISTS；覆盖而非追加）。每一步都要注明预期输出和验证检查，并设定明确、可衡量的标准（状态、提供服务的版本、健康值）——只有验证通过后才能进入下一步。
• 有状态变更／迁移安全（当发布会改变架构或数据时）— 优先采用向后兼容的扩展与收缩（并行变更）顺序，以确保始终可以安全回滚：扩展（在旧列／旧表旁新增列／表——绝不原地删除／重命名）、迁移（部署使用新结构的代码；新旧结构并存；必要时回填数据）、收缩（在之后单独发布的版本中移除已废弃元素）。尽可能将架构迁移与代码部署解耦。对于不可逆变更（DROP、破坏性转换、已提交的数据变更），没有干净的降级迁移——在回滚方案中注明恢复路径（见下文），不要编造不存在的回退操作。
• 部署后验证／冒烟测试 — 使用具体检查和可衡量的成功标准，沿用测试计划的退出标准；观察（稳定运行）一段明确的时间。用数字定义成功（错误率低于阈值、p99 延迟低于阈值，或 SLO 错误预算消耗率在界限内），绝不能写“感觉没问题”。
• 回滚流程 — 明确列出触发条件（可衡量：错误率／延迟／SLO 错误预算消耗率／冒烟测试失败）；按相反顺序为每项前向变更记录明确的回退操作；回退手段须与发布策略相符（蓝绿发布 = 将流量切回；金丝雀／滚动发布 = 将流量路由到 0%／缩容；重建 = 重新部署旧制品；功能开关控制 = 关闭开关——近乎即时且影响范围局部的手段）。对于不可逆的前向变更，应向前修复，不要回退——注明向前修复／遏制／补偿事务／从备份恢复的路径，而不是编造会导致数据丢失的降级迁移。回滚后，最后要重新验证并恢复到部署前基线。
• 值班／升级处理 — 提供实际可用的路径：通知谁、严重性级别、各级别的响应时限和升级策略。
• 监控／可观测性参考 — 列出要查看的仪表板／告警／日志，提供链接，并为每项说明“健康状态应是什么样”。链接到监控项；不要嵌入实时面板。
• 维护窗口／沟通（当部署会影响用户时）— 沟通计划：提前通知相关方、在状态页面发布维护窗口，并在服务恢复后发送通知；为每个渠道指定负责人（电子邮件／状态页面／应用内横幅）。按影响程度确定——内部部署／对用户无影响的部署无需沟通（留空即可；这是正确做法，不是遗漏）。

演练／彩排（辅助措施，而非关卡）。 正式运行前，在类生产的预发布环境中执行完整流程，注入故障以验证回滚确实有效，并安排一位团队外的工程师按流程操作（以实测达到“陌生工程师”标准）。在模板的 Last validated 字段中记录日期，作为运行手册仍与系统相符的时效性信号。首次编写的运行手册尚未经过演练；这是质量信号，绝不是前置条件。

第 6 步：交付前依据可执行性与安全标准进行自检

确认以下各项均成立（这是运行时 reviewing-release-runbook 门禁所采用的标准——作者和审阅者使用并评判相同的 11 项条件标准，以免标准偏移；编号与审阅者的条件编号一致）。每个按比例适用的项目在不适用时均可归为 n/a——这是适当的范围界定，不是遗漏。

1. 不熟悉项目的工程师也能执行 — 每个部署／回滚步骤都具体且可安全复制粘贴，并标明占位符；没有含糊的描述；重复执行某一步是安全的（幂等）。
2. 逐步验证 — 每一步都说明预期结果和可量化的验证检查（原始阈值或 SLO 错误预算消耗率）；未经验证不得进入下一步。
3. 设有继续／停止门禁 — 部署前检查是部署的门槛；任何检查失败都必须明确判定为 NO-GO 并停止流程。
4. 完整且安全的回滚，并包含触发条件 — 设有可量化的触发条件（包括错误预算消耗率）；每项正向变更都应按相反顺序回滚，并使用与策略匹配的控制手段（包括对已标记项切换标志位）；不可逆变更应通过向前修复回滚，并说明恢复路径；重新验证至基线状态。
5. 部署后验证复用具体检查项 — 冒烟测试应在明确的观察期内使用可量化的成功标准；如已提供测试计划，则复用其中的退出标准。
6. 明确的升级处理流程与监控 — 提供真实的值班／升级处理路径和真实的监控入口（附链接，并说明“健康状态应是什么样”），而非占位符。
7. 不内嵌机密信息 — 操作手册中不得包含真实令牌／密码／密钥；机密信息应通过其存储库／密钥库／环境变量名称引用。
8. 不捏造信息 — 每条命令、每台主机和每个端点都能追溯到已提供的上游资料，或明确标注为假设。
9. 有状态变更安全性*（按比例适用 — 无架构／数据变更时为 n/a）* — 架构／数据正向变更应可逆／向后兼容（按扩展－收缩顺序执行），或说明向前修复／遏制／恢复的处理路径。
10. 沟通／维护窗口*（按比例适用 — 部署不会影响用户时为 n/a）* — 会影响用户的部署应说明沟通／维护窗口计划。

（条件 9 — 按差异范围进行修订 — 仅适用于你正在修订现有操作手册的情况；相应的自检步骤是第 7 步。在发布压力下仍可使用 — 操作手册从上到下应是一套值班工程师凌晨 3 点无需询问作者也能遵循的流程；这是贯穿整个操作手册的整体评估视角，不是编号条目。）

输入不足门禁：如果无法根据现有信息或合理假设可信地描述部署，应将其列为阻碍项（“操作手册信息不足 — 需要部署拓扑／发布决策”），而不是用捏造的命令敷衍了事。

步骤 7：修订现有运行手册（持续更新路径）

发布运行手册会在每次发布时重新执行，并通过每次事故不断完善。当你收到现有运行手册和变更请求时，应修订，而非重新生成：

1. 限定变更范围，仅涉及受影响的单元——部署步骤／回滚步骤和触发条件／发布准入检查／部署后检查／部署策略／有状态变更步骤／升级或监控指引／沟通计划。
2. 识别触发原因（两种情况）：上游变更（架构文档中的拓扑、技术设计中的发布流程或测试计划中的退出标准发生变更 → 重新推导受影响的步骤），或事后复盘所得经验（故障暴露出缺失的回滚步骤、未经验证的故障模式或过慢／缺失的触发条件 → 补充事故所要求的回滚触发条件／验证关卡／修正步骤）。
3. 编辑，不要重写——仅修订受影响的步骤。
4. 端到端重新验证——运行手册是一个有顺序要求的流程，因此某个步骤的变更可能会悄然破坏后续步骤的前置条件（环境变量被重命名、迁移顺序调整、健康检查端点变更）。检查整个流程是否存在被破坏的下游前置条件；在可行时重新进行干运行，并更新“上次验证”日期，或明确标记待重新验证（重新演练只是辅助措施，绝不强制）。
5. 确认变更符合要求——变更或新增的步骤满足适用的约束条件：可执行且已验证（cond-1/2）；任何新的前向变更都有回退方案和可衡量的触发条件，不可逆变更则有向前修复路径（cond-4/cond-10）；未内联任何密钥（cond-7）；未捏造任何内容（cond-8）。
6. 更新版本、变更日志并标记旧版——递增运行手册自身的文档版本（与已部署的发布版本不同），添加注明触发原因的变更日志条目，并将上一版本标记为已取代。

这就是审核者 cond-9（按变更范围修订）要求的标准；对于从零开始的首次构建，cond-9 不适用。

规则

硬性规则（绝不违反）：

• 步骤必须幂等且可安全复制粘贴。 无法安全复制粘贴并重复运行的操作不算步骤。需要输入命令的地方，不得使用含糊的描述。
• 每个步骤都必须有预期结果。 没有验证关卡的步骤就不算完成——不得在未验证的步骤上开始下一步。
• 每项前向变更都必须有注明触发条件的回退方案。 回滚必须说明何时（可衡量的触发条件）以及如何操作（每项变更对应一个回退步骤，按相反顺序执行，并采用与策略匹配的手段），重新验证是否恢复至基线，并指出任何不可逆变更及其缓解措施。
• 有状态变更必须向后兼容，或明确标记为不可逆。 架构或数据变更应按扩展-收缩模式排序，以便干净回滚；不可逆变更必须说明前向修复、遏制或恢复路径，不得虚构会导致数据丢失的降级迁移。
• 修改，而非重新生成。 收到针对现有运行手册的变更请求时，应编辑受影响的步骤，端到端重新验证整个流程，并为运行手册更新版本和变更日志——绝不能悄悄重写（第 7 步）。
• 绝不在文档中直接写入机密。 引用机密存储库、保险库或环境变量名称。运行手册中出现真实令牌、密码或密钥即属缺陷——机密绝不能存在于已提交、已部署或已记录日志的文件中。
• 绝不捏造命令、主机或端点。 追溯每一项的上游来源；无法追溯时，应明确标记为发布前需要验证的假设。
• 组合，而非重复大纲。 从模板工具获取章节结构；此技能用于填充内容。不得粘贴一份与之竞争的大纲。
• 验证时沿用测试计划的退出标准。 不要重新定义 QA 策略；应断言其已有的标准。
• 围绕流水线编写流程，而非编写流水线。 运行手册调用 CI/CD 自动化，并记录手动操作、验证和回滚步骤；不得编写流水线配置（那属于 cicd-plan）。
• 必须可执行、安全且完整，否则就不算完成。 不得交付一份让不熟悉情况的工程师无法据此完成部署和回滚的运行手册。

偏好（可覆盖）：

• “全面”决定输出的目标；但应保持适度——关注关键运维步骤的完整性，而非字数。小型服务应省去不需要的章节。
• 默认采用蓝绿部署策略；若上游设计表明应采用滚动、金丝雀或重建策略，或策略已被固定，则应覆盖此默认值。
• 每个步骤都应以围栏命令代码块和预期输出块表示；验证应以包含可衡量通过标准的检查表呈现。
• 通信/维护窗口计划应与用户影响相称（内部部署无需此计划）；试运行/演练和“上次验证时间”是保持信息时效性的辅助措施，绝不是编写第一份运行手册的前提。

注意事项

• 命令该出现的地方却用了含糊的描述。“配置服务并重启”在凌晨 3 点时无法执行——请给出带有明确占位符的确切命令和预期输出。
• **步骤没有预期结果。**没有验证关卡，操作人员就无法判断操作是成功了，还是悄无声息地失败了；后续步骤会在错误状态下继续。请说明预期输出和检查方法。
• **回滚只写“回滚”。**安全保障应包括：按相反顺序为每项前向变更提供回退方法，并给出触发回退的可量化条件，同时指出不可逆变更；“回滚部署”并不够。
• **在步骤中直接写入机密。**将真实令牌／连接字符串粘贴到步骤中，会导致它泄露到操作手册的所有存放位置。请引用存储／保险库／环境变量名称；只显示是否存在，绝不显示其值。
• **回滚策略与部署策略不匹配。**蓝绿部署通过切换流量回滚；重建部署则通过重新部署旧制品回滚。针对错误策略编写的回滚方案无法奏效——回滚方案必须与所选策略匹配。
• **捏造主机名／命令。**为了显得完整而编造主机名或 CLI 标志，会导致操作手册首次使用就失败。请追溯到上游来源，或将其标记为假设。
• **大爆炸式架构变更没有安全的回滚方案。**在同一次发布中删除／重命名列，并发布不再使用该列的代码，会导致无法安全回退。请采用扩展—收缩流程（新增列并保留旧列；迁移；之后再收缩），确保每一步都能独立回滚。
• **不可逆变更却虚构向下迁移。**对于已经销毁数据的 DROP，写上“回滚：运行向下迁移”只是假安全保障——这会丢失数据。应改为说明前向修复／遏制／从备份恢复。
• **小改动却重新生成整份操作手册。**只修正一行拓扑结构不需要重写——修改受影响的步骤，端到端重新验证（变更步骤可能破坏后续步骤的前置条件），并更新版本和变更日志（步骤 7）。
• **给内部部署硬加沟通计划。**沟通安排应与用户影响相称；内部／零用户部署不需要沟通计划——强行加入状态页面章节只是凑内容，并非安全措施。
• **重复列出模板大纲。**在内容中（或此技能中）重新推导章节列表会重复模板工具的功能，还会导致内容偏离——应根据实际判断填写相应章节。

反模式

• “部署人员知道命令，我会写得概括一些。” 标准是让一位在压力下工作的陌生工程师也能执行——每个步骤都必须具体且可安全复制粘贴，否则操作手册会在最需要时失效。
• “回滚就是反向部署。” 每项正向变更都需要有对应的回退操作和可衡量的触发条件；不可逆变更则需要说明缓解措施。对回滚含糊其辞，往往会延长故障时间。
• “我把令牌直接写进去，这样步骤就能直接执行。” 这会泄露密钥。请引用密钥的存储位置；操作手册要写出密钥名称，绝不能写它的值。
• “没人给我监控链接，我就写个看起来合理的仪表板 URL。” 虚构端点会在事故发生时留下失效链接。应将缺少的链接作为假设指出，而不是编造。
• “我也把流水线 YAML 写在这里。” 这属于 cicd-plan。操作手册应记录围绕流水线的操作流程，而不是自动化配置。
• “我自己来写大纲。” 这会重复模板工具的内容——从模板工具获取结构。
• “迁移只需一行，我直接删掉列就行。” 没有向后兼容步骤的破坏性架构变更，是最常见的无法回滚的部署问题——应采用扩展-收缩策略，或明确指出这是不可逆变更并向前推进。
• “改动很小，我直接重写操作手册就行。” 修改受影响的步骤，并端到端重新验证；无声重写会丢失变更历史，还可能破坏下游前置条件。
• “跳过调研吧，我知道怎么部署。” 调研能让这份操作手册以经过验证的 SRE 惯例为依据（幂等性、验证关卡、回滚触发条件、策略机制），而非依赖关于部署的道听途说。

输出

一份满足 第 6 步可执行性 + 安全性标准的完整发布操作手册（11 项标准：陌生工程师能够执行；每个步骤都有验证关卡；有继续/停止关卡；回滚完整且安全，并包含触发条件；不可逆变更有向前推进方案；部署后验证复用测试计划的退出标准；提供具体的升级处理渠道和监控链接；不内嵌密钥；不编造内容；在适用时确保有状态变更安全性和沟通计划；在发布压力下仍可用）——或者，对于修订，提供经过端到端重新验证的版本化差异（第 7 步）。以 Markdown 文本形式编写——包含编号操作步骤、围栏命令/检查片段、预期输出块、验证/检查表，以及指向仪表板/监控工具的链接（而非嵌入实时面板）；具体方法和标准不受媒介限制。抽象使用者是执行发布的部署/值班工程师，以及运行时 reviewing-release-runbook 关卡（该关卡检查相同标准）。操作手册依赖于已提交的上游文档（通常是 architecture-doc + technical-design + test-plan），并将其作为输入。其结构来自模板工具；此技能提供内容质量。

相关内容

• 发布操作手册模板工具（例如内容/模板网关）——提供此技能要填充的章节结构。应与之组合使用；切勿重新陈述其大纲。
• 深度研究能力——以既定的 SRE/运维实践为操作手册提供依据（幂等性、验证关卡、回滚触发条件、部署策略机制、通过引用而非明文提供密钥）。
• 上游 architecture-doc + technical-design + test-plan（如有）——操作手册据此推导可部署组件、发布流程和退出标准（作为输入，切勿在此处重新编写）。
• reviewing-release-runbook——运行时关卡，用于检查成品操作手册是否符合相同的可执行性 + 安全性标准；编写者和审核者遵循同一标准，以免标准偏移。
• cicd-plan（单独使用，不在此组合中）——操作手册会调用的流水线自动化；操作手册应记录围绕它的操作流程，而非其配置。

渐进式披露

• references/stateful-and-rollback.md — 深入介绍有状态变更的安全性和回滚手段：扩展-收缩／并行变更迁移阶段划分、不可逆变更的继续向前修复还是回滚决策及遏制措施、SLO 错误预算消耗速率的依据，以及功能标志／自动化金丝雀回滚手段。发布涉及架构或数据变更，或采用渐进式交付时加载。
• references/amend-and-rehearsal.md — 深入介绍第 7 步的修订流程（双重触发条件和端到端重新验证的连锁影响）、生产前演练，以及维护窗口／利益相关方沟通计划。修订现有运行手册或规划会影响用户的部署时加载。
• references/sources.md — SRE／运维方法及可执行性／安全标准的研究出处（AWS Well-Architected 运行手册指南、Google SRE 金丝雀发布／可靠发布及基于 SLO 的告警、OneUptime／Upstat 运行手册实践、扩展-收缩迁移及继续向前修复相关来源、部署策略比较、功能标志／暗发布、密钥管理指南）。仅在审核指导内容的出处时加载。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。Claude 会在技能列表中将 description 和 when_to_use 合计截断至 1,536 个字符。
• 正文 ≤ 约 500 行／5,000 个 token。
• 大篇幅内容放在 references/ 中，按需加载。