peterwangzepeterwangze/software-project-governance/skills/stage-release/SKILL.md

stage-release

Skill2 starsChanged 5 months agoMITView on GitHub

版本发布——发布计划、changelog、回滚方案。阶段子工作流，可独立使用。

Commits and pushes

In this repository26 other files it gives its agents.
- AGENTS.mdAGENTS.md
- code-reviewSkill
- design-reviewSkill
- main-workflowSkill
- okrSkill
- pr-faqSkill
- release-checklistSkill
- release-reviewSkill
- requirement-clarificationSkill
- requirement-reviewSkill
- retro-meetingSkill
- retro-reviewSkill
- six-pagerSkill
- software-project-governanceSkill
- stage-architectureSkill
- stage-cicdSkill
- stage-developmentSkill
- stage-infraSkill
- stage-initiationSkill
- stage-maintenanceSkill
- stage-operationsSkill
- stage-researchSkill
- stage-selectionSkill
- stage-testingSkill
- tech-reviewSkill
- test-reviewSkill

The file

Create a free account to mount

Files

SKILL.md

版本发布 — 子工作流

本文件定义"版本发布"阶段的独立子工作流。用户可单独加载本文件执行版本发布阶段。

阶段目标

将已验证的软件版本安全发布到目标环境。版本发布阶段的核心产出是"发布的版本"——用户可以使用的新版本，且有明确的变更记录和回滚能力。

AI 编程场景特有风险

在 AI 辅助编程项目中，版本发布阶段存在以下特有风险：

风险	说明	缓解方向
AI 跳过发布检查	AI 倾向于"改完就发布"，跳过发布 checklist 逐项验证和回滚演练，把发布等同于 git push	强制发布 checklist 全项通过后才允许打 tag/合并到 release 分支；每项检查结果必须有记录
版本号管理混乱	AI 可能在不同文件中使用不一致的版本号、跳过语义化版本规则、或在不该升版本号的时候升了	版本号必须由单一脚本/命令统一更新；CI 检查所有声明文件中的版本号一致性
变更日志遗漏或膨胀	AI 生成的 changelog 可能遗漏关键变更（尤其是 breaking change）或包含不该发布的内容（未完成的功能）	changelog 必须与 git log 对照；breaking change 必须显式高亮；未完成功能必须排除
回滚方案形式化	AI 可能生成"看起来对"的回滚方案（步骤完整但未经实际验证），真正需要时无法执行	回滚方案必须在测试环境实际执行一次；回滚时间必须在可接受窗口内
发布后验证被忽略	AI 声称"发布完成"后不验证生产环境是否正常，等到用户反馈才发现问题	发布后必须有核心功能冒烟测试；监控指标必须在发布后观察期内确认正常

独立使用时的目标锚定

当本子工作流被独立加载时，MUST 完成以下自包含检查。本段不依赖任何其他文件。

目标确认：读取 .governance/plan-tracker.md → 提取 ## 项目配置 中的量化成功标准
偏离检查：本次发布内容是否与项目目标一致？偏离 → 记录到 .governance/decision-log.md
质量底线：发布 MUST 通过 checklist 全项 + 有可验证的回滚方案 + 版本号符合 semver

降级：.governance/plan-tracker.md 不存在 → 内联告知用户锚定不可用（单向通知，非提问——不触发 M5.1 禁令），独立模式直接开始发布流程。后续初始化 governance 后自动恢复。

进入条件

防护网已就绪（G8 通过）
CI 稳定运行
有测试报告支撑发布决策

活动清单

1. 发布准备

活动	描述	交互边界	企业实践
确认发布范围	本次发布包含哪些功能、修复、破坏性变更	需用户确认	[Amazon] 显式记录"本次不发布什么"——避免 scope creep
定义版本号	按语义化版本规则（MAJOR.MINOR.PATCH）确定版本号	自动：基于变更类型推荐 → 需用户确认	[Google] 语义化版本严格遵循；breaking change 必须 MAJOR 升级
编写变更日志	覆盖所有变更，破坏性变更显式高亮	自动：从 git log 生成 → 需用户确认	[Google] CHANGELOG 按 Added/Changed/Fixed/Removed 分类
确认未完成功能排除	检查是否有未完成的功能被错误包含	自动：diff 分析标记未完成文件 → 需用户确认	[Amazon] 只发布已完成且验证过的功能

2. 发布前检查

活动	描述	交互边界	企业实践
执行发布 checklist	逐项检查：测试通过、门禁 green、版本声明一致、适配层状态真实、归档闭环、交叉引用无漂移	自动：候选包使用 `check-release --version X.Y.Z --require-changelog --lineage-mode candidate`；该模式明确允许 release commit/tag 尚未创建。创建并推送 tag 后，必须再运行 `check-release --version X.Y.Z --require-changelog --lineage-mode released --release-commit <commit>`，验证本地 tag、tag 指向和 remote tag。默认执行 `verify`、`check-governance --fail-on-issues`、`e2e-check` 和 unittest；需要检查本机 agent runtime 时追加 `--runtime-adapters`。	[华为 IPD] 发布门控逐项检查，不可跳过任何一项
验证 declarative release ledger	candidate commit 中 manifest 必须为 `candidate`；release commit 仅追加唯一 transition 并改为 `released`，其单一 parent 必须是 candidate commit	自动：候选执行 `release-ledger --version X.Y.Z --no-remote`；tag/push 后执行 `release-ledger --version X.Y.Z --remote origin`。`UNKNOWN`/`BLOCKED` 不得包装为 PASS。	ADR-010
同步 artifact projections	先修改 SKILL frontmatter 权威版本，再由 registry 生成全部 byte/structured/transformed projections	自动：`release-projection` 默认 check-only；需同步时显式 `release-projection --write`，随后再次 check	ADR-010
探测可选质量工具	Ruff/mypy 只作为渐进检查，不是运行时依赖	自动：运行 `quality-tools`；未安装必须记录 `NOT_RUN`，执行失败为 `FAIL`，不得把未安装包装为 PASS	ADR-010
验证回滚方案	在测试环境实际执行一次回滚，记录回滚耗时	需测试环境执行	[Amazon] 自动回滚能力——回滚必须在 N 分钟内完成
确认监控就绪	关键指标（错误率、延迟、可用性）的监控和告警已配置	需监控环境执行	[Google SRE] 发布前必须确认监控覆盖 4 大黄金信号
发布决策	基于 checklist 全部通过 + 回滚验证通过，做出 go/no-go 决策	需用户确认：Go/No-Go	[Amazon] 发布决策有 Single-Threaded Owner

3. 发布执行

3.1 发布策略选择

策略	适用场景	风险级别	用户影响	回滚难度
Big-Bang	内部工具、个人项目	低	全量	简单
金丝雀 (Canary)	用户基数大、风险敏感	中	1%→10%→50%→100% 逐步放量	中等
蓝绿 (Blue-Green)	需要瞬时切换、零 downtime	中	全量切换（流量路由）	简单（切回旧环境）
滚动 (Rolling)	多实例、持续部署	中	逐实例替换	中等
功能标记 (Feature Flag)	新功能不确定效果	低	按 flag 控制可见性	最简单（关 flag）

策略选择规则：

有数据迁移或 Schema 变更 → 金丝雀或蓝绿，禁止 Big-Bang
新功能不确定用户接受度 → 功能标记优先
基础设施变更 → 金丝雀（先 1 实例，观察 30 分钟）
安全修复 → 滚动或 Big-Bang（安全优先于渐进）

3.2 Feature Flag 管理

活动	描述	交互边界	企业实践
列出本次发布的 flags	哪些功能通过 flag 控制、哪些直接生效	自动	[Meta] 发布与启用解耦——deploy ≠ release
定义 flag 启用/关闭流程	谁可以在什么条件下启用/关闭 flag	需用户确认	[Meta] flag 变更也需要审批
定义 flag 清理计划	flag 在功能稳定后多久移除（避免 flag 债务）	自动：建议 ≥30 天后清理	[Google] flag 过期自动告警

3.3 Kill Switch 验证

活动	描述	交互边界	企业实践
定义 kill switch 触发条件	什么指标变化会触发紧急关闭？（如错误率 >2x 基线）	需用户确认	[Google SRE] 明确的回滚触发条件，不依赖人的判断
验证 kill switch 可执行	在测试环境执行一次 kill switch，记录从触发到生效的耗时	需测试环境执行	[Amazon] kill switch 必须在 N 秒内生效
确认 kill switch 负责人	谁有权限触发 kill switch？（至少 2 人，避免单点）	需用户确认	[Google SRE] 值班 rotation + 备份

3.4 发布执行

活动	描述	交互边界	企业实践
按选定策略执行发布	按选择的发布策略（金丝雀/蓝绿/滚动/Big-Bang）执行	需用户确认：最终发布决策	[ByteDance] 灰度发布——先小范围验证再全量；发布过程可观测
发布后验证	核心功能冒烟测试：关键路径在生产环境可正常走通	需外部环境执行	[Google SRE] 发布后立即执行冒烟测试，不等到用户反馈
监控观察	发布后观察期（≥30 分钟）内监控指标是否正常	需监控环境执行	[Google SRE] 错误预算消耗、延迟 P99、可用性 vs 基线

4. 发布收尾

活动	描述	交互边界	企业实践
更新版本记录	版本号、发布日期、变更范围写入版本记录文件	自动	[Google] 版本记录可追溯到 commit
执行持续归档触发检查	版本 bump / 已发布状态写入后运行 `archive.py migrate --auto --dry-run`；如报告需要归档，执行 `archive.py migrate --auto` 并运行 `verify_workflow.py check-archive-integrity`	自动；失败阻断发布完成	ADR-006 版本归档边界 + ADR-007 升级迁移
通知相关人员	发布完成通知，含变更摘要和已知问题	自动	通用实践
归档发布资产	git tag、changelog、发布包	自动	[Google] 每次发布有可回溯的 immutable tag
固化 release transition	在 release commit 中把 native manifest 从 candidate 改为 released 并追加 integrity event；tag 必须 peel 到该 commit	自动；merge/repeat/wrong-parent/rename-delete-add 均阻断	ADR-010
记录发布事件	如发生事故或异常，准备 blameless postmortem 材料	自动：如有事故则创建	[Google SRE] Blameless Postmortem——聚焦流程改进而非追责

5. 影响评估（发布后数据验证）

活动	描述	交互边界	企业实践
收集发布后指标	错误率、延迟 P50/P95/P99、可用性、用户活跃度——与发布前基线对比	需监控环境执行	[ByteDance A/B Test] 不接受"感觉变好了"——必须有数据对比
核心指标对比	预设的成功标准 vs 实际数据——达标/未达标/不劣化	自动：数据 vs 基线对比	[ByteDance 数据驱动] 每个指标变化有方向（改善/恶化/持平）+ 幅度（%）
A/B 测试分析（如适用）	实验组 vs 对照组：指标差异是否达到统计显著性	自动：显著性计算 → 需用户确认结论	[ByteDance A/B Test] 结果必须达到统计显著性才能结论
无数据时的替代判定	无法 A/B 测试的功能（基础设施/安全修复/内部工具）用替代标准判定成功	自动：按替代标准逐项检查	[Google SRE] 没有 A/B 测试就用 SLO 基线对比
影响评估报告	发布对用户和系统的实际影响——改善了哪些指标、恶化了哪些、是否有意外副作用	自动：基于收集的数据生成	[Amazon Working Backwards] 回头验证 PR/FAQ 中承诺的用户价值是否通过这次发布兑现了

无数据时的替代判定标准：

变更类型	替代 A/B 测试的判定方法	来源
基础设施变更	部署后 CI 稳定运行 N 次，错误率无劣化	Google SRE
安全修复	漏洞扫描清零，安全回归测试通过	Google Security
内部工具/文档	目标用户在 X 分钟内完成目标操作	Amazon UX
小项目/早期产品	核心功能冒烟测试通过 + 48 小时内无新 bug 报告	通用实践
底线	至少要有一个可验证的成功定义——"没数据"不是跳过验证的理由	ByteDance

产出物标准

产出物	格式要求	质量标准	企业实践来源
发布计划	版本号、范围、时间窗口	完整且已确认；"不发布什么"有明确记录	[Amazon]
变更日志	覆盖所有变更，破坏性变更已高亮	与 commit 列表对照一致；按 Added/Changed/Fixed/Removed 分类	[Google]
回滚方案	具体步骤，已在测试环境验证	实际执行过；回滚时间在可接受窗口内	[Amazon]
发布后验证报告	核心功能冒烟测试结果 + 监控观察期数据	全部通过；监控指标在基线范围内	[Google SRE]
影响评估报告	核心指标基线 vs 发布后对比 + A/B 测试结论（如适用）+ 替代判定（如无数据）	每个指标有变化方向和幅度；达到预设成功标准或确认不劣化	[ByteDance A/B Test] + [Amazon Working Backwards]

退出条件

发布范围明确（有版本号和变更清单）
变更日志覆盖所有变更，破坏性变更已高亮
回滚方案已在测试环境验证（实际执行过）
发布后验证通过（冒烟测试 + 监控观察期无异常）
影响评估已完成（核心指标 vs 基线对比；无数据时有替代判定且通过）
发布脚本检查已通过：候选态 check-release --version X.Y.Z --require-changelog --lineage-mode candidate PASS；创建并推送 tag 后，完成态 check-release --version X.Y.Z --require-changelog --lineage-mode released --release-commit <commit> PASS；两者默认包含 verify、check-governance --fail-on-issues、e2e-check、unittest
0.66.0+ declarative manifest 已闭环：candidate commit 保持 candidate；release commit 是唯一单父 transition；本地/remote tag peel 一致；release-ledger --version X.Y.Z PASS
release-projection check-only PASS；若执行过 --write，rollback journal/原子写入测试证据存在
quality-tools 结构化结果已记录；Ruff/mypy 未安装时为 NOT_RUN，没有虚构 PASS
持续归档触发检查已通过：archive.py migrate --auto --dry-run 无待归档数据，或已执行归档且 check-archive-integrity PASS

Gate 映射

本阶段对应 G9 — 发布就绪。

Gate 检查项	对应活动	判定标准	自动化判定
发布范围是否明确？	发布准备	有版本号（符合 semver 格式）、发布范围、时间窗口	可自动：正则匹配版本号格式 + 检查范围列表非空
变更日志是否完整？	变更日志	覆盖所有变更，与 commit 列表对照一致，破坏性变更已高亮	可自动：git log diff 对照 commit 列表 + 关键词匹配"BREAKING"
回滚方案是否已验证？	发布前检查	有具体步骤且已在测试环境实际执行	半自动：方案文档存在可自动；验证执行记录需人工确认
发布后验证是否已定义？	发布前检查	验证 checklist 存在且包含核心功能冒烟测试项	可自动：检查 checklist 文件存在 + 核心功能项非空
监控是否已就绪？	发布前检查	关键指标（错误率/延迟/可用性）监控和告警已配置	半自动：监控配置存在可自动；告警有效性需人工确认
发布后冒烟测试是否通过？	发布执行	核心功能路径在生产环境正常走通	可自动：解析冒烟测试结果
观察期指标是否正常？	发布执行	错误率/延迟/可用性在基线范围内	可自动：监控数据 vs 基线阈值对比
治理归档是否闭环？	发布收尾	版本发布后无待归档历史 task；归档索引与归档文件一致	可自动：`archive.py migrate --auto --dry-run` + `verify_workflow.py check-archive-integrity`
影响评估是否已完成？	影响评估	核心指标基线 vs 发布后对比存在；A/B 测试结论明确（如适用）；无数据时有替代判定	可自动：检查报告文件存在 + 指标对比字段完整

企业实践溯源

本子工作流的设计参考了以下企业实践，每条实践已映射到具体活动步骤：

企业	核心实践	映射到本工作流
Google	语义化版本 + Changelog 分类	发布准备→版本号按 semver 规则；变更日志→Added/Changed/Fixed/Removed
Google SRE	4 大黄金信号监控 + Blameless Postmortem	发布前检查→确认监控覆盖；发布执行→冒烟测试+观察期；发布收尾→事故记录
Amazon	显式记录"不发布什么" + 自动回滚	发布准备→排除未完成功能；发布前检查→回滚方案实际验证
Amazon	Single-Threaded Owner	发布前检查→Go/No-Go 决策有明确负责人
Amazon	Working Backwards (PR/FAQ 验证)	影响评估→回头验证 PR/FAQ 承诺的用户价值是否通过发布兑现
华为	IPD 发布门控逐项检查	发布前检查→checklist 不可跳过任何一项
字节跳动	灰度发布 + 数据驱动验证	发布执行→逐步放量；发布后验证→数据 vs 基线对比
字节跳动	A/B Test 一切 + 无数字不接受	影响评估→核心指标对比 + A/B 测试分析 + 无数据替代判定——不接受"感觉变好了"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free