release-notes

发行说明专家

概述

将原始技术变更——工单、变更日志、Git 日志、PRD——转化为清晰、以用户收益为导向的发行说明。此技能通过一套 5 步方法，确保每次发布都能以合适的语气向合适的受众传达价值：收集输入、将每项变更归入五个类别之一、改写为用户收益、调整受众语气并汇总。

适用场景

• 产品发布 —— 向客户、合作伙伴或内部利益相关者公布新版本。
• 迭代演示 —— 为迭代评审受众总结已交付的内容。
• 维护变更日志 —— 持续记录各版本的变更。
• 客户沟通 —— 准备用于电子邮件、应用内或文档中的发布公告。

核心能力

• 五类分类 —— 新功能、改进、错误修复、重大变更、弃用，并提供明确的归类规则
• 改写为用户收益 —— 以结果为先，使用通俗语言，控制在 1-3 句话；检测以开发者视角表述的内容
• 受众语气指导 —— B2B/企业、消费者、开发者/API、内部
• 自动生成 —— release_notes_generator.py 对条目进行分组、生成 Markdown/JSON 格式，并标记需要改写的技术表述

先澄清

生成发行说明前，请确认以下信息。如果有任何信息未知或含糊不清，请提问——不要自行假设：

• 受众 —— B2B/企业、消费者、开发者/API 或内部（决定整体语气矩阵和详细程度）
• 变更来源 —— 要转换的工单/PR/变更日志，并将其归入 5 个类别（没有这些信息就无法生成内容）
• 重大变更和弃用 —— 变更内容、所需操作以及截止时间（必须包含这些字段，以维护用户信任）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“先起草再说”，就继续处理，并在文档开头列出假设。

快速开始

python scripts/release_notes_generator.py --input changes.json --product-name "Acme App" --version "2.5.0"
python scripts/release_notes_generator.py --demo --product-name "Acme App" --version "1.0.0"

仅包含有条目的类别。重大变更必须说明变更内容、用户必须采取的操作，以及截止时间。完整方法、输出模板和标记参考请参阅参考资料。

参考资料

根据任务加载相应的参考资料——保持此文件精简，按需查阅详细内容：

• references/methodology-and-tooling.md —— 完整的 5 步方法、分类表、改写前后示例、受众语气矩阵、输出模板、故障排查、成功标准，以及 release_notes_generator.py 的标记和 JSON 架构参考。编写说明或运行工具时请阅读。
• references/release-notes-guide.md —— 关于类别定义、受众指导和实例的最佳实践指南。需要深入了解其原理时请阅读。
• references/red-flags.md —— 具体的错误与正确条目示例，以及修正方法。发布草稿前请阅读。
• assets/release_notes_template.md —— 可直接使用的发行说明文档模板。

集成点

集成	方向	描述
sprint-retrospective/	接收自	迭代提交数据和类型分布有助于确定要纳入的变更
senior-pm/	互补	利益相关者沟通计划可指导发行说明的受众和语气
execution/create-prd/	接收自	PRD 功能描述（第 7 节）可转化为发行说明条目草稿
scrum-master/	接收自	迭代评审输出可确定已交付且需要记录的内容
summarize-meeting/	接收自	发布规划会议摘要可提供发行说明所需的背景信息
job-stories/ / wwas/	接收自	用户故事描述可帮助条目采用以用户收益为导向的表述

范围与限制

范围内：

• 根据 JSON 输入生成结构化发行说明，包含 5 种条目类别
• 自动检测技术语言并提供改写建议
• 按类别分组并格式化为 Markdown 和 JSON 输出
• 提供受众语气指导（B2B、消费者、开发者、内部）
• 为新功能、改进、错误修复、破坏性变更和弃用提供分类规则

范围外：

• 自动从 git 历史记录中提取变更（git 分析请参阅 sprint-retrospective/）
• 集成 Jira/Linear 工单以获取已完成的用户故事（需要手动输入 JSON）
• 跨多个发行版本维护变更日志（此工具按发行版本生成说明）
• 分发到电子邮件、应用内或文档渠道（输出为 Markdown/JSON，供后续处理）

重要注意事项：

• 改写建议基于模式启发式规则。它们可以捕捉常见的技术语言，但无法判断描述是否真正传达了用户收益。
• 语义化版本对齐由用户负责。此工具不会验证版本号是否遵循与现有变更类型相对应的 semver 约定。
• 破坏性变更需要特别谨慎。务必说明：变更内容、用户需要采取的操作，以及截止时间。含糊的破坏性变更说明会削弱用户信任。