release-notes

release-notes

将开发工作转化为项目经理能在 30 秒内浏览完的发布说明：每条都要告诉项目经理、QA 和运维人员改了什么、为什么改，以及现在有什么好处。只总结已经完成的工作——绝不规划、提交问题或审查代码（这些分别由 /feature-prompt、/qa 和 /code-review 处理）。

写作规则

每句话都必须符合以下标准：“项目经理或 QA 人员能否不问开发人员就看懂？”

1. 使用日常用语。 不用行话、企业套话或工程术语。
   • 不佳：“统一每次 RFID 查询前的扫描准备流程”
   • 良好：“应用现在会在开始扫描前检查扫描器是否已就绪”
2. 说明用户看到或执行的内容。 写清屏幕、按钮、字段或页面名称。
3. 每条要点只讲一件事，每句简短。 绝不写成段落。问题／变更／影响部分最多各写 2 条内容要点——带标签的 What changed where:、Simple logic explanation: 和 Action needed: 行不计入；超过就说明细节太多。
4. 功能名称要描述已完成的工作。 代码使用“扫描器就绪检查”，已完成的规划文档使用“登录计划文档已完成”。
5. 问题 = 用户遇到的情况（也就是症状，而不是代码缺了什么）。影响 = 现在具体有什么好处。
6. 不写填充内容或抽象表述。 删除“正式地”“为了”“需要指出的是”“这确保了”以及关于降低风险的描述。
7. 把工程细节转化为实际操作意义。 将代码层面的细节改写为用户能看到的效果（“重构了 useRfidScanner” → “应用现在会在每次扫描前以相同方式设置扫描器”）；除非用户要求技术细节，否则叙述中不要写代码标识符。
8. 叙述性要点不超过 15 个词。 用具体行为替换抽象行话。为明确 QA 应测试的内容，必要时保留准确的 UI 标签和技术名称。若缩短会造成歧义，必需的 QA 前置条件和有序步骤可以超过上限。
9. 如果逻辑有变化，在变更部分添加一句五年级学生也能看懂的话： Simple logic explanation: <句子>。
10. 像告诉同事今天做了什么那样写，不要写成正式文档。

避免使用“增强”“优化”“改进”等含糊动词，却不说明行为发生了什么变化。没有准确指标时，用基于实际观察行为的方向性描述说明影响。绝不陈述工作区、Git 历史或用户提供的上下文无法支持的内容。

生成模式

• 按日期生成（某个日期或日期范围）——按日期筛选本地 Git 历史，按项目分组，并整理相关提交。
• 会话摘要——将会话中修改的文件、笔记和差异整合为逻辑清晰的改进。
• 功能摘要——将该功能的提交整理为一个“问题 → 变更 → 影响”故事。
• 版本范围（v1.3.0..v1.4.0 或“自上次发布以来”）——使用 git tag --sort=-version:refname 查找本地标签，并查看 <from>..<to> 的日志；文件名使用 <to> 标签对应提交的日期。如果本地标签缺失 → 说明这一点；绝不执行 fetch。

证据收集

绝不要运行 git fetch、git pull 或任何会修改本地 git 状态的操作。 对于日期、功能或版本历史，加载 references/git-collection.md；该文件涵盖 仓库发现、祖先关系、交付声明和基于差异的归类。 仅限会话的工作使用会话笔记、已修改文件和相关差异； 只有在需要提交或交付证据时才加载 git 参考文档。

在所有地方都使用 Project Matrix 中完整的 PROJECT-CODE；绝不能把一个项目的约定、令牌或组件混入另一个项目。

子 Agent：对彼此独立的工作自动分派本地工作道——绝不使用云端 Agent；分派时宣布工作道数量，并在各工作道完成时逐一汇报。工作道返回哈希、文件、用户可见变更、归类和不确定性的摘要；主会话负责归类、措辞、QA 步骤和文件输出。

每次阶段转换时输出 Stage / Found / Next / Needs user——每个字段各占一行。

输出格式

一个 Markdown 文件，按模式对应的资源骨架填写—— 骨架是唯一的格式来源：

• 基于日期／日期范围／版本范围／功能模式 → assets/release-notes-template.md
• 会话摘要 → assets/session-summary-template.md

示例见 references/examples.md； 不确定条目的写法时加载该文件。

填写规则：

• Stakeholder Summary 用于 30 秒快速浏览：每个 PROJECT-CODE 单独占一行，使用纯文本（不使用标题语法）；每项功能用一个项目符号，将 Summary + Change 合并为一句话；未标注日期的会话摘要省略 Date: 行。
• 同一项目下有多项功能时重复功能区块； 功能区块放在对应的项目标题下。
• Manual QA Steps：每项功能提供 3–5 个实用步骤，每个步骤采用 操作 -> 预期结果 的格式，涵盖主要的正常流程和一个边界情况。先说明本地设置、角色和测试数据；区分建议执行的检查和已运行的测试。对于仅涉及文档／工具的变更，注明要检查的实际文件或命令。绝不虚构界面或观察到的结果。
• 只包含所选范围内至少有一项已确认变更的项目。
• 用户可见的详情只有在提交／差异中能确认时，才写在 Change 下可选的 What changed where: 行中——注明设置、页面／屏幕、元素或路由；否则省略该行。
• Impact 下可选的 Action needed: 行用于说明用户或运营团队必须执行的操作——重新登录、新设置、迁移或环境密钥。差异中未显示任何此类操作时，省略该行。
• 提交哈希只放在 Commits Included 下，每条项目符号列出一个；无提交的会话使用会话骨架中的 (uncommitted session work) 作为后备内容。

文件输出

保存到 <artifacts-root>/specs/release-notes/。

零署名：绝不要在提交、PR、问题评论、发行说明、生成的文档、设置或代码注释中添加或保留共同作者、AI 或工具署名。

解析 <artifacts-root>：如果存在 *.code-workspace 文件，则使用其所在目录；否则使用每个上下文的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版 CONTEXT-MAP.md）；否则使用仓库根目录。 如果既没有工作区文件，也没有映射的上下文根目录，则分别解析每个范围内的仓库，并为每个仓库写入一个文件。映射的上下文使用其解析出的根目录；不要将其替换为单仓库回退路径。

文件名 — D-Month-YYYY，日期不补前导零，英文月份首字母大写： 10-March-2026.md；日期范围：10-March-2026-to-12-March-2026.md。

• 功能摘要使用发行日期，而不是功能名称；如果未提供日期，且用户没有明确指当前会话，则应询问；如果用户不在线，则使用当前本地日期，并在顶部注明此假设。
• “Today” / “current session” → 当前本地日期。
• 不要在文件名中添加 NNNN、-release-notes 或功能标识；发行说明不使用 ADR/提示词的 NNNN 序列。

冲突处理：保留现有内容。在不删除无关条目的前提下执行获准的更新；如果替换需要用户作出尚未解决的决定，则创建下一个未使用的 (2) 格式的同级文件，并说明其路径。绝不要覆盖未经确认的手动编辑，也不要删除无关文件。

完成标准

• 保存的文件符合叙述性要点和章节数量上限；QA 步骤保留必要的设置和顺序。
• 每个文件均位于已解析的日期、日期范围或未使用的编号同级路径，并重新打开核对，确保其结构与加载的骨架一致，且只包含已更改的项目。
• 每个集群都有依据充分的交付状态；“已发布”须引用发行证据，未合并的工作须标记为进行中。
• 至少有一个要点指出受影响的工作流或团队。
• 每个手动 QA 步骤均采用“操作 -> 预期结果”的格式，并注明真实的 UI 位置、文件或命令；影响部分须区分已完成的工作与预期收益。
• 回复须列出每个已保存文件的路径，并以 Suggested next skills (optional) 结尾 — 提供 1–3 条建议，不设为前置条件。