056-design-avoid-breaking-changes

破壊的変更の回避

実装またはリリースへの反映の前に、予定しているリポジトリの変更をレビューし、破壊的変更や互換性に関するリスクを確認します。これは対話型の SKILL です。

この Skill で確認する内容

• コマンドの契約との互換性：名前、入力、担当エージェント、出力、セーフガード、インストーラーへの登録、コマンド一覧
• 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 スキーマ、設定、データ契約の変更をレビューする

ワークフロー

1. 互換性に関する参照資料を読む

references/056-design-avoid-breaking-changes.md を読み、レビュー対象のソース成果物、その権威性、依頼が読み取り専用のレビューか、承認済みの実装かを特定します。

2. 互換性の対象範囲を洗い出す

予定している変更に関連するコマンド、Skill、生成物、XML／ソースの所有権、README／ドキュメント、テスト、CI／ビルドゲート、外部契約、ランタイムの動作、データ／設定契約、リリースまたは移行に関するガイダンスを確認します。

3. 指摘事項を分類する

各指摘事項を BREAKING、POTENTIALLY BREAKING、NON-BREAKING、UNKNOWN のいずれかに分類します。影響を受けるユーザー、成果物、契約、および検証の根拠、または不足している根拠を含めます。

4. 移行と検証を推奨する

確認済みまたは潜在的なリスクごとに、非推奨化、互換性を維持する期間、移行に関する注記、リリースノートの更新、ジェネレーターのチェック、対象を絞ったテスト、担当者の判断を推奨します。

5. レビュー結果を報告する

レビューしたソース、対象範囲ごとのリスク概要、重要度順の指摘事項、推奨する検証を含む簡潔な互換性レポートを作成します。破壊的変更のリスクが見つからなかった場合は、その旨を明確に記載します。

参照資料

詳しいガイダンス、例、制約については、references/056-design-avoid-breaking-changes.md を参照してください。