--- name: show-changes description: 変更前と変更後の差分を、1つ以上の対象(git のリポジトリの2つのコミット、2つのフォルダやファイル、既にある unified diff)にまたがって1つの HTML のページにし、人がブラウザで変更の全体と中身を確かめられるようにする。「差分を見せて」「変更を見せて」「変更内容を表示して」「変更をページにして」「レビュー用に差分をまとめて」と頼まれたとき、レビュー・承認・マージ・差し替えの前に人へ変更を見せるとき、複数のリポジトリやフォルダにまたがる変更をまとめて見せるときに使う。エージェントがファイルを変更する作業を終えて、何を変えたかをユーザーに見せるときは、頼まれなくても使う。エージェントが自分で差分を読むだけのときと、変更の良し悪しを点検するときには使わない。 --- # スキルの目的 変更前と変更後の差分を、ブラウザで開く1つの HTML のページにする。ページを見る人(レビューや承認をする人。依頼したユーザー自身のこともある)が、何がどれだけ変わったか(全体)と、どう変わったか(中身)を、リポジトリやフォルダをまたいで1か所で確かめられるようにする。ページは変更を見せるためのもので、変更の良し悪しは判断しない。呼び出し元は、このスキルを頼んだユーザー、またはこのスキルを呼んだエージェントだ。 ページは同梱の `scripts/build.py` で作る。Python 3.9 以上(`python3` などのコマンド)がある環境では `build.py` を実行してページを作り、無い環境では、ページを作れないことを呼び出し元に伝える。ページを作る前に、呼び方と引数を記載した `references/usage.md` を読む。スキルの中のパス(`scripts/`・`references/`)は、このスキルのフォルダからの相対パスで記述してある。 ## 比較対象の指定 - 見る人が確かめたい変更に合わせて、比べる対象の種類を選ぶ。git で管理している変更なら2つのコミット、git で管理していないファイルの前後(変更前に控えた複製と今のもの、2つの版のフォルダなど)なら2つのフォルダ、ほかのツールが作った差分ならその unified diff を比べる。種類は1つのページの中で混ぜられる。 - ブランチの変更を見せるなら、取り込み先のブランチとの分岐点からブランチの先までを比べる(`--merge-base`)。取り込み先のブランチに後から入った変更が、ページに混ざらない。 - git の2つのコミットで比べられるのは、コミットされた変更だけだ。作業中の変更をコミットするかはユーザーが判断する。コミットしていない作業中の変更を見せるなら、`git diff HEAD` の出力を unified diff として渡すか(git にまだ追加していない新しいファイルは入らない)、変更前の複製と今のものを2つのフォルダとして比べる。2つのフォルダの比較は、git が無視するファイル(依存物・ビルドの出力・接続情報のファイルなど)も比べるので、比べるフォルダには見せたいファイルだけを入れる。 - unified diff の対象は差分に記載された行の範囲しか持たない。ファイルの全文を見せたいときは、ほかの種類の対象にする。 - ページの題とデータの版(`--data-version`。ページのヘッダーにそのまま出る文字列)は、見る人が何を見ているかを後から言えるように付ける。題には何の変更か、データの版には比べた状態(コミット・日付・版の名前)が分かるものを入れる。 ## 全文表示の選択 全文を入れると、見る人は変わった行の前後だけでなく、ファイル全体の流れの中で変更を読める。その代わり、ページは変わったファイルの大きさの分だけ大きくなる。依頼から、見る人が前後の流れまで読む必要があると読めるとき(文書の書き直し、設定ファイルの一部の変更など)に全文を入れ、変更の量や箇所を見るだけなら差分だけにする。どちらとも読めなければ差分だけにし、全文を入れたページも作れることを渡すときに添える。 ## 出力ファイルの提示方法 ページは、見る人がその場で開いて見られる形で渡す。HTML ファイルを作って保存先や添付を示すだけでは、見る人がファイルを取り出して開くまでページを見られない。Claude が動く環境では、ページをアーティファクトとして示すことを既定にする。 - ローカルの HTML ファイルをそのままアーティファクトとして公開できるツールがあれば、作ったファイルを公開する。Claude のアーティファクトは公開するときにページに文書の骨組み(DOCTYPE・html・head・body)を付けるので、`build.py` に `--artifact` を付けて、骨組みを省いて書き出す。ページには差分のデータがすべて入っていて大きくなることがあるので、ページの中身を書き写さずにファイルのまま公開する。 - アーティファクトを中身から作る環境(ファイルを公開するツールが無く、アーティファクトの中身をエージェントが記述する環境)では、`build.py` が書き出したページを、書き換えずにアーティファクトの中身にする。手で書き換えると、ページの差分が元の変更と合わなくなる。ページが大きく中身にしきれないときは、全文を入れないページにする。 - アーティファクトを使えない環境では、HTML ファイルを保存して、ファイルの場所を呼び出し元に伝える。保存する場所を呼び出し元が言っていなければ、比べるどのリポジトリやフォルダにも入らない場所に置く。比べる対象の中を出力先にすると、`build.py` は止まる。 - 公開先に大きさの上限があってページが上限を超えるなら、全文を入れないページにするか、HTML ファイルで渡す。 - `build.py` は、出力先に同じ名前のファイルがあっても、確かめずに上書きする。人が開いているページや、人が手を入れたページと同じ名前にしない。 - 公開したページは外部のサービスに置かれる。ユーザーが秘密として扱っている対象や、持ち主が外へ出すことを認めていない情報がページに入っていそうな対象なら、公開せずに HTML ファイルで渡し、どこに置くかは呼び出し元に任せる。差分だけのページには変わった行とその前後の数行とコミットの件名が入り、全文を入れたページには変わったファイルの変わっていない所も全部入る。 - 渡すときは、何と何を比べたか(対象、比べた2つの状態、分岐点から比べたか)と、全文を入れたかを短く添える。見る人が、ページに入っていない変更があるかを判断できるようにするため。