explain-diff について
explain-diffは、Gitの変更内容を把握したい開発者向けのスキルです。変更をテーマ別に説明し、根拠を示すクイズ付きHTML学習ページを生成して、入力元と出力を検証します。
主な機能
- 01ブランチ、PR、ステージ済み・未ステージ差分の説明
- 02変更パスの機能別分類
- 03コードとクイズを含むHTMLページの生成
- 04再開可能な台帳による進捗管理
- 05根拠、ページ構造、入力元の変更確認
活用シーン
- 01mainとの差分のレビュー
- 02ステージ済みまたは作業ツリーの変更説明
- 03Pull Requestの学習ページ作成
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/explain-diffを入力して読み込まれたか確認します。
同梱ファイルREFERENCE.md
詳細
diff の解説
フラグ
| フラグ | デフォルト | 効果 |
|---|---|---|
--target <branch> | main | <branch>...HEAD を解説します |
--pr <n|url> | オフ | 1 件の PR の diff とメタデータを解説します |
--staged | オフ | インデックスを解説します |
--unstaged | オフ | ワークツリーの変更を解説します |
--output <path> | /tmp/YYYY-MM-DD-explain-<slug>.html | HTML の出力先を設定します |
4 つのソース指定は相互に排他的です。競合するフラグや値のないフラグは
BLOCKED になります。値を省略できる唯一の例外は単独の --pr で、現在のブランチの
PR を解決する場合があります。ソースフラグがない場合は、--target main と同等の指定を
使用します。PR の diff を取得できない場合はブロックします。PR の任意のメタデータが
見つからない場合、動機に関する主張を含まない diff のみのページを作成できます。
1. ソースと出力を固定する
ソースの識別情報、head SHA、正確な diff、ソート済みパス、diff の SHA-256
ハッシュを取得します。diff が空の場合は NO_CHANGES です。ブランチ名、PR 番号、
または change-<head8> からスラッグを導出し、40 文字以内に収めます。
出力先をリポジトリ外の絶対パスとして解決します。リポジトリ内のパスが明示された
場合は BLOCKED とし、別の場所へ移動してはいけません。存在しない親ディレクトリを
作成します。ユーザーが指定した既存ファイルを上書きする前にブロックします。デフォルトの
出力先で置き換えられるのは、このスキルのジェネレーターマーカーを含む既存の成果物のみです。
次の情報を記録します。
source/hash | theme(name/paths/path-hash/gate) | evidence | output | gate | verification | terminal。
各ゲートの完了後とテーマの完了後に、出力先の隣へ <output>.ledger として保存します。
出力先とソースのハッシュが一致する場合に限り、進行中の台帳を再開します。一致しない
場合は BLOCKED です。成功したら削除します。
ソースと安全な出力先が変更されない状態になったら完了です。
2. 分類して調査する
周辺コードを読む前に、変更されたすべてのパスを機能テーマに割り当てます。パスが
50 件を超える場合は、代表的なハンクを使ってテーマを解説し、ソート済みのすべての
パスを省略せずに含めます。リネームは old → new として表します。生成ファイルや
バイナリファイルは該当するテーマの下に列挙し、テキストのハンクがない場合は動作に
関する主張を行いません。パスのみの一覧行には data-hunk="<path>:inventory" を指定します。
テーマは最大 12 件、テーマごとの周辺ファイルは最大 3 件、周辺ファイルの合計は
最大 30 件とします。計画中の主張に必要な場合に限り、直接の定義、呼び出し元、契約、
テスト、設定を読みます。
すべてのパスがテーマに割り当てられ、計画中の各主張にハンクまたは読み込んだファイルの 参照先が付いたら完了です。
3. 学習用ページを作成する
./REFERENCE.md を読み込みます。次の順序で 1 つの HTML ファイルを作成します。
背景、直感、コード、クイズです。目次、インライン CSS と JavaScript、レスポンシブな
レイアウト、HTML またはインライン SVG の図のみを含めます。コードセクションはテーマごとに
まとめ、大規模な diff では完全な一覧を含めます。
変更に関する事実を述べるすべての文には、対応するハンクを紐付けます。システムに関する 主張はすべて周辺ファイルに紐付けます。裏付けのない意図、動機、PR に関する主張は 削除します。
4 つのセクションすべてに内容があり、根拠に基づくクイズの質問が 5 件ある状態で ファイルが存在したら完了です。
4. 検証して報告する
参照チェックリストを適用します。外部アセットの URL がないこと、すべてのアンカー、ジェネレーターマーカー、コードの空白、エビデンスポインター、クイズの回答フィードバックを確認します。
ブラウザツールがある場合は、ファイルを読み込み、各問題で正解と不正解を1つずつ試します。それ以外の場合は、JavaScript と HTML を解析し、verification: static-only を明記します。ブラウザーで実行した場合は、verification: browser と報告します。
SUCCESS の前に、最新のソースフィンガープリントを再計算します。差異がある場合は BLOCKED とし、ページに異なるスナップショットが混在しないようにします。
中断後は、ソースハッシュと台帳を比較します。テーマに変更があれば最初からやり直し、それ以外の場合は最初の未完了ゲートから続行します。
絶対パス、ソース、テーマとファイルの数、クイズの数、検証レベルを報告します。HTML を貼り付けないでください。最終ステータスは SUCCESS、NO_CHANGES、BLOCKED のいずれかです。PR をコミット、プッシュ、変更しないでください。