| 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に貼り付ければ修正を続けられることを伝える
