System Diff
システム差分とは、変更が実行中のシステムに与える影響を示すものです。追加、削除、変更されるコンポーネントやフロー、状態が遷移できる新たな経路、変化するファクト、そして新しい障害モードを表現します。ラインディフは証拠であり、システム差分はレビュアーが必要とするストーリーです。
変更を仕様としてモデル化し、スクリプトがその仕様をビート（タイトル、各図のBefore/After、障害、クローズ）に分割した動画としてレンダリングします。以下、<script> はこのスキルのフォルダ内にある scripts/system-diff.mjs の絶対パスを指します。
1. セットアップの確認
node <script> doctor を実行します。セットアップが完了したマシンでは Ready. と表示されて終了します。
それ以外の終了メッセージの場合、または node が存在しない場合は、処理を停止し、ユーザーに /setup-system-diff を実行するよう依頼してください。これにより、このスキルに必要なすべてのツールがインストールされます。
2. 変更内容の収集
変更は、プルリクエスト、ブランチ、またはコミット範囲です。何も指定されていない場合は、現在のブランチをベースブランチに対して取得します。プルリクエストにベースブランチがある場合はそれを、それ以外はリポジトリのデフォルトブランチを使用します。どちらも明確でない場合はユーザーに確認してください。
作業は変更のHEADをチェックアウトした状態で行います。これは、ステップ4で証拠をディスク上のファイルと照合するためです。
- 差分全体（
gh pr diff <number>またはgit diff <base>...<head>）と、プルリクエストの説明（存在する場合）、またはコミットメッセージ（プルリクエストがない場合）を読み取ります。 - コール、クエリ、スケジュール、設定値、スキーマ、権限に触れるすべてのハンクについて、ベースとHEADの両方で、その周辺のコードを十分に読み、実行時に誰が誰を呼び出すかを把握します。
ベースとHEADのそれぞれについて、「何が実行されるか」「各要素が何と通信するか」「何を保存するか」「依存する各要素がダウンしたときに何が起こるか」を説明できる状態になったら完了です。
3. システム変更のモデル化
変更をクレーム（主張）のリストとして記述し、それぞれにそれを示す path:line を付けます。このクレームがステップ4の仕様の基盤となり、ステップ6でユーザーに提示されます。
- コンポーネント: サービス、ジョブ、キュー、テーブル、外部APIなど、実行またはデータを保持するもの。フローを追跡するために必要な、変更されていないコンポーネントも含めます。
- フロー: あるコンポーネントが別のコンポーネントを呼び出す、読み取る、書き込むといった関係。
- 状態と遷移: 注文、ジョブ、セッション、接続など、あるものが経由する段階と、その段階間を移動させるイベント。
- ファクト: 設定値、制限値、スキーマ、権限、処理時間など、システムに関するある事柄のBeforeとAfterの値。
- 障害モード: 最も重要な新しい障害の発生方法。通常は新しいコンポーネントや新しい依存関係が停止することですが、既存のコンポーネントの障害コストが増大する場合や、ある状態でスタックする場合も含みます。その際に何が起こるか（他の各コンポーネントの動作、またはそのものが最終的にどこに至るか）を説明します。
すべてのクレームは、それを示す行を引用します。引用する行がないクレームは推測とみなされ、動画には含まれません。
リファクタリング、フォーマット、テスト、コメント、コードからのみ参照される名前の変更など、システムを変更しない変更もあります。そのような場合は、システム差分がない旨とその変更の種類をユーザーに伝え、動画なしでここで終了します。ルート、テーブル、キュー、設定キーなど、実行中のシステムから見える名前の変更はシステム変更です。
クレームによって、動画で描画する図が決まります。
- コンポーネント図: 配線（コンポーネントやフローの追加・削除、フローが運ぶものの変更）が変わる場合。
- ステートチャート: ライフサイクル（ステータス値の増減、リトライ/キャンセルステップの出現、イベントの遷移先変更）が変わる場合。
- 配線とライフサイクルは変わらずに値だけが変わる場合（例：タイムアウトの延長）はファクトとして、文脈を提供できる側の図の下に表示します。
- 両方: 配線とライフサイクルの両方が変わり、それぞれが他方では示せない情報を持つ場合。各図は2ビート追加されるため、一方の図で完全に説明できる変更は1つの図で済ませます。
差分のすべてのハンクがクレームでカバーされるか、システムを変更しないものとして除外され、かつ図の選択が完了した時点で完了です。
4. 仕様の作成
クレームを SPEC.md に従って仕様に変換します。SPEC.md には、すべてのフィールド、レイアウトルール、キャプションとナレーションの書き方が記載されています。仕様をリポジトリ外のスクラッチフォルダに system-diff.json として保存します。
node <script> check <spec> --repo <リポジトリルート> を実行します。
The spec is valid. と警告なしで表示されたら完了です。check は各引用行が存在することを確認しますが、その行がクレームを示していることの確認はあなたの責任です。
5. シートのビルドと確認
node <script> build <spec> --repo <リポジトリルート> --out <スクラッチフォルダ> を実行します。動画のパス、警告、コンタクトシート（各ビートのフレームを1枚の画像にまとめたもの）、および同じフレームをフルサイズで保存した stills フォルダが出力されます。
コンタクトシートで全体像を確認し、スティル画像で小さなテキストを確認し、各フレームをチェックします。
- すべてのラベル、値、キャプションが完全に読めること。
- すべてのフロー線が、接続しないボックスやラベルと交差せずに描画されていること。
- 各Beforeフレームには変更前に存在したものだけが表示され、各Afterフレームには変更で追加されたすべてのものが表示されていること。
- ステートチャートの開始点は、そのものが開始する状態に配置されていること。
- 障害フレームは正しいコンポーネントまたは状態をマークし、各注釈は説明対象の下端に配置されていること。
- 各キャプションはそのフレームが示す内容を説明していること。
仕様を修正し、ビルドが No warnings. を出力し、シートがすべてのチェックに合格するまで再ビルドします。ほとんどのフレームの問題は、テキストを短くするか、ボックスを別のセルに移動することで解決します。両方で解決しないものは、引き継ぎ時に名前を付けて報告します。
6. 引き継ぎ
ユーザーに、動画のパス、動画が示す内容の一文、証拠付きのクレームのリスト、および省略した点や確信が持てなかった点を伝えます。動画の公開はユーザーの判断に委ねます。