关于 056-design-avoid-breaking-changes
用于在实施或发布前审查仓库变更兼容性风险的交互式技能。它检查各类契约和生成内容的归属，并以证据为依据报告问题，不修改文件。
主要功能
- 01盘点兼容性影响面
- 02分类破坏性与潜在风险
- 03审查源文件及生成内容归属
- 04建议迁移与验证步骤
- 05生成按严重程度排序的报告
适用场景
- 01审查规范中的破坏性变更
- 02评估发布前的兼容性
- 03检查生成内容与命令契约
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/056-design-avoid-breaking-changes确认已加载。
附带文件references/056-design-avoid-breaking-changes.md
详细介绍
避免破坏性变更
在实施变更或提升发布版本之前，审查计划中的仓库变更，评估破坏性变更和兼容性风险。这是一个交互式 SKILL。
此 Skill 涵盖哪些内容？
- 命令契约兼容性：名称、输入、所属 Agent、输出、安全措施、安装程序注册和命令清单
- Skill 路由兼容性：标识符、元数据、描述、触发条件、引用、生成的本地输出和验收覆盖范围
- 生成输出的所有权：XML/源文件与
.agents/skills、公共skills/、.cursor/commands、.cursor/rules和docs/之间的关系 - 源文件和生成器契约：XML、XInclude、XSLT、Maven 模块、架构预期和模块验证
- README、本地化 README、变更日志、迁移和弃用指南
- 外部和运行时契约：API、架构、数据格式、配置键、持久化、CLI 行为和 CI 预期
- 包含按严重程度排序的问题及验证指南的结构化兼容性报告
约束
除非用户明确要求实施，否则审查应以证据为依据、只读，并仅限于兼容性风险。
- 必须在提供兼容性指导前阅读
references/056-design-avoid-breaking-changes.md - 必须指出已审查的源工件和考虑过的兼容性方面
- 必须区分已确认的破坏性变更、潜在风险、非破坏性变更，以及需要维护者决策的未知事项
- 必须为有意进行的破坏性变更提供迁移、弃用、验证或发布说明方面的指导
- 必须遵守仓库的源文件所有权规定：编辑 XML 和源文档，通过文档说明的工作流重新生成生成的输出；除非仓库明确拥有该文件，否则不要直接编辑生成的输出
- 不得在审查期间修改计划、规范、源文件、生成的输出或问题描述，除非用户明确要求实施
何时使用此 Skill
- 审查此规范中的破坏性变更
- 检查兼容性风险
- 避免此 OpenSpec 变更引入破坏性变更
- 在发布前审查迁移影响
- 评估命令和 Skill 的兼容性
- 查找生成输出的兼容性风险
- 审查 API 架构、配置或数据契约变更
工作流
- 阅读兼容性参考
阅读 references/056-design-avoid-breaking-changes.md，然后确定要审查的源工件、其权威性，以及请求属于只读审查还是已获批准的实施。
- 盘点兼容性方面
检查与拟议变更相关的命令、Skill、生成的输出、XML/源文件所有权、README/文档、测试、CI/构建门禁、外部契约、运行时行为、数据/配置契约，以及发布或迁移指南。
- 对发现进行分类
将每项发现归类为 BREAKING、POTENTIALLY BREAKING、NON-BREAKING 或 UNKNOWN。说明受影响的用户、工件和契约，以及验证证据或缺失的证据。
- 提出迁移和验证建议
针对每项已确认的风险或潜在风险，建议采用弃用流程、兼容窗口、迁移说明、更新发布说明、生成器检查、针对性测试或由负责人作出决策。
- 报告审查结果
生成简洁的兼容性报告，列出已审查的源、各方面的风险摘要、按严重程度排序的发现、建议的验证措施；如果未发现破坏性变更风险，则明确声明不存在此类风险。
参考
详细指南、示例和约束请参阅 references/056-design-avoid-breaking-changes.md。