---
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` を呼び出して手順を読み込み、次の点だけこのスキルの方針で上書きする。

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

### 5. 完了報告

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