关于 engineering-change-descriptions
一项编写工程变更说明的技能，涵盖改动内容、原因、测试方式和相关风险，帮助作者留下便于评审和长期查阅的记录。
主要功能
- 01变更说明编写指南
- 02提交标题与正文结构
- 03常见变更的 PR 模板
- 04说明重写检查清单
- 05记录风险与测试背景
适用场景
- 01撰写标准 PR 说明
- 02记录小型改动的原因
- 03描述重构或生成式修改
- 04评审后更新过时的说明
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/engineering-change-descriptions确认已加载。
详细介绍
工程变更描述
变更描述是永久的工程历史记录。它应帮助评审者现在理解变更，也帮助未来的维护者找到并理解它。
改编自 Google Engineering Practices Documentation，尤其是“Writing good CL descriptions”。来源：https://google.github.io/eng-practices/review/developer/cl-descriptions.html。许可证：CC-BY 3.0。
一份好的描述应回答哪些问题
- 改了什么？
- 为什么要改？
- 有哪些代码中不明显的背景、约束或权衡？
- 如何测试？
- 评审者需要了解哪些风险、迁移、回滚或后续工作？
即使是小改动，只要原因不明显，也值得说明背景。
第一行
第一行应：
- 在版本控制历史中独立成句。
- 简短、具体，并聚焦于变更的作用。
- 撰写提交或 CL 标题时使用祈使句式。
- 避免使用“修复 bug”“清理”“第 1 阶段”“杂项”或“添加辅助工具”等含糊标签。
- 如果后面有正文，应在第一行之后空一行。
正文
只包含有用的背景信息：
- 要解决的问题。
- 选择这种方案的原因。
- 用户或开发者可见的行为变化。
- 重要的实现说明。
- 已知的限制或后续工作。
- Bug ID、问题链接、基准测试结果、设计文档、迁移文档或发布计划。
- 为链接补充足够的背景信息，以防链接日后无法访问。
- 适当时，列出测试命令和结果。
提交前，在评审修改后重新阅读描述，并确保其仍与最终差异相符。
模板
标准 PR
[Imperative one-line summary]
## Why
[Problem, user need, production issue, maintainability reason, or design context.]
## What Changed
- ...
- ...
## Testing
- ...
## Risk / Rollback
- Risk:
- Rollback:
小改动
[Imperative one-line summary]
[One paragraph explaining why this change exists and any non-obvious context.]
Testing: [command or manual check]
重构
[Describe the structural change and what it replaces]
This prepares for [future change] by [specific reason], without intentionally changing behavior.
Testing: [existing or new tests that protect behavior]
生成或机械式变更
[Describe the mechanical rewrite]
Generated by [tool/version/command] to [reason]. Manual edits: [none/list].
Verification: [format/test/build command]
改写检查清单
改进现有描述时：
- 从差异中提取实际行为。
- 将含糊的第一行改为具体的操作描述。
- 补上缺失的原因。
- 保留有用的问题链接和测试证据。
- 删除对评审者或未来维护者没有帮助的流程性杂音。
常见错误
- 只描述实现方式，却不说明原因。
- 标题无法让未来搜索者将其与类似变更区分开来。
- 完全依赖外部链接来提供关键背景信息。
- 评审导致差异发生重大变化后，描述仍未更新。
- 因为觉得不便而隐瞒风险、限制或发布要求。
评论
支持 Markdown