difit-explain

name	difit-explain
description	実装した差分に、変更意図・設計上の注意点などの説明コメントを付けてdifitで表示する。AIが書いたコードを人間が理解・判断するためのレビュー支援。「差分を説明コメント付きでdifitで表示して」「変更内容の説明をdifitに表示して」「今回の実装の解説をdifitで見せて」などのリクエストで使用。問題点の指摘を主目的とする通常のコードレビューには使わない。
argument-hint	["diff対象（省略時は未コミット差分、なければブランチ差分）"]
user-invocable	true

Difit Explain

目的

AIが生成したコードの差分を、人間が理解して判断できるようにするためのスキル。差分の該当行に説明コメントを付けたdifit画面を開く。

通常のコードレビュー（問題点の指摘が中心）ではない。人間が次を理解できるようにすることが目的。

• なぜこの変更が必要なのか
• この処理が何をしているのか
• 変更前と比べて何が変わったのか
• どこが設計上の重要ポイントなのか
• どこに不具合や影響範囲のリスクがあるのか

手順

1. diff対象を特定する

• ユーザーが対象を指定した場合はそれに従う
• 未指定の場合は、未コミットの変更があればそれを対象にする（gitro status で確認）。なければ origin/main...HEAD（または origin/master...HEAD）のブランチ差分を対象にする

2. 差分を読んで理解する

• 差分全体を読む。差分だけで意図が分からない箇所は、周辺コードや呼び出し元も読んで理解する
• 複数ファイルにまたがる変更のつながり、既存実装との設計の違いを把握する
• このセッション内で自分が実装した差分であれば、実装時の意図や経緯をコメントに反映する

3. 説明コメントを作成する

すべての行にコメントする必要はない。差分だけでは意図を読み取りづらい、次のような箇所に付ける。

• 処理の入口や中心となる箇所
• 複数ファイルの変更をつなぐ箇所
• 既存実装から設計を変えた箇所
• 暗黙の前提がある箇所
• エラー処理、整合性、認可、並行処理など注意が必要な箇所
• テストが何を保証しているか分かりづらい箇所

コメントの書き方:

• 冒頭に種類を付けて区別する
  • 説明: 変更意図や処理内容
  • 注意: 人間が確認すべき設計上のポイント
  • 問題: バグや修正が必要な可能性が高い箇所
• 簡潔にする。コードをそのまま言い換えるだけの説明は書かない
• 問題: は明らかなものを見つけた場合のみ付ける。一般的なAIコードレビューのように細かな指摘を大量に並べない

例:

説明: この関数でリクエスト単位の冪等性を保証している。同じキーの再実行時には、外部APIを再度呼ばず前回結果を返す。

注意: DB更新とイベント送信を分離すると送信漏れが起きるため、ここではTransactional Outboxとして同一トランザクション内に記録している。

4. コメント付きでdifitを起動する

difitの起動方法・コメントの渡し方は difit-review スキルに従う。Skillツールで difit-review を呼び出して手順を読み込み、次の点だけこのスキルの方針で上書きする。

• --comment の body には手順3で作成した説明コメントを渡す（レビュー指摘中心にしない）
• コメントJSONの形式・position.side の使い分け・range指定・--include-untracked などは difit-review の記載どおりに行う

5. 完了報告

• difitのURLを共有する
• 人間がdifit上で追加コメントを書き、それをClaude Codeに貼り付ければ修正を続けられることを伝える