diffity-review

Diffity レビュースキル

diffity agent CLI を使用して差分をレビューし、インラインコメントを残します。

引数

• ref（任意）：レビューする Git ref（例：main..feature、HEAD~3）。デフォルトは作業ツリーの変更です。ref と focus の両方が指定されている場合は、両方を使用します（例：/diffity-review main..feature security）。
• focus（任意）：レビューで重点を置く領域です。次のいずれかを指定します：security、performance、naming、errors、types、logic。省略すると、すべてをレビューします。

CLI リファレンス

diffity agent diff
diffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"

• comment には --file、--line、--body が必須です
• --end-line のデフォルトは --line です（単一行コメント）
• --side のデフォルトは new です
• general-comment は、ファイルや行に紐付かない差分レベルのコメントを作成します
• <id> には完全な UUID または 8 文字のプレフィックスを指定できます

前提条件

1. diffity が利用可能であることを確認します：which diffity を実行します。見つからない場合は、npm install -g diffity でインストールします。

手順

ステップ 1：ブラウザーを開かずに、正しい ref で diffity が実行されていることを確認する

レビューでは、要求された ref と一致する ref の実行中セッションが必要です。ref が一致しないと、コメントの追加時に「file not in current diff」エラーが発生します。

1. diffity list --json を実行して、実行中のすべてのインスタンスを取得します。JSON 出力を解析し、repoRoot が現在のリポジトリと一致するエントリーを見つけます。
2. 一致するエントリーがある場合は、その ref フィールドと要求された ref を比較します：
   • レジストリでは、作業ツリーのセッションに "work" が、名前付き ref にはユーザーが指定した ref 文字列（例："main"、"HEAD~3"）が保存されます。
   • ref が一致する場合 → セッションを再利用し、ポートを記録してステップ 2 に進みます。
   • ref が一致しない場合 → 再起動します：diffity <ref> --no-open --new を実行します（ref がない場合は diffity --no-open --new）。--new フラグは古いセッションを終了して、新しいセッションを起動します。run_in_background: true を指定して Bash ツールを使用します。2 秒待ってから diffity list --json で確認し、ポートを記録します。
   • ref が指定されておらず、実行中セッションの ref が "work" 以外の場合 → diffity --no-open --new で再起動します（実行中セッションは名前付き ref 用ですが、作業ツリー用のセッションが必要です）。
3. このリポジトリで実行中のセッションがない場合は、バックグラウンドで起動します：
   • コマンド：diffity <ref> --no-open（ref がない場合は diffity --no-open）
   • run_in_background: true を指定して Bash ツールを使用します
   • 2 秒待ってから diffity list --json で確認し、ポートを記録します

ステップ 2：差分をレビューする

1. 統合差分を diffity から直接取得します。これにより、マージベースの解決、追跡されていないファイル、すべての ref タイプが自動的に処理されます：

   diffity agent diff
   

   これにより、現在のセッションの統合差分全体が出力されます。行番号は @@ ハンクヘッダーに記載されています。
2. 関連するすべての CLAUDE.md ファイルを見つけて読みます。ルートの CLAUDE.md と、変更されたファイルを含むディレクトリ内の CLAUDE.md ファイルが対象です。これらには、差分が従うべきプロジェクト固有のルールが定義されています。

変更規模を評価し、レビュー方法を調整する

3. 差分の規模を見積もり、進め方を計画します。差分の規模にかかわらず、すべてのファイルを徹底的にレビューします。違いは作業の整理方法だけです：
   • 小規模（変更行数約 100 行未満、ファイル数 1～3）：単純です。各ファイルを順にレビューします。
   • 中規模（変更行数 100～500 行、ファイル数 3～10）：ファイルを領域ごと（例：バックエンド、フロントエンド、テスト、設定）にまとめます。影響範囲をレビューする前に意図を把握できるよう、まず中核となるロジックファイルをレビューします。
   • 大規模（変更行数 500 行以上、またはファイル数 10 以上）：ファイルを領域ごとにまとめます。まず中核となるロジックを確認し、その後、残りのすべてのファイルをレビューします。機械的に繰り返される変更（例：同じ名前変更を 20 ファイルに適用する場合）は、最初の数件でパターンが正しいことを確認してから、残りすべての箇所でパターンから外れた部分がないか確認します。どの箇所も省略してはいけませんが、パターンを確認できた後は、より手早く確認できます。

規模にかかわらず、変更されたファイルをすべて読み、レビューしてください。ファイルを省略したり、抜き取り確認したりしてはいけません。

レビューの前に変更内容を理解する

4. まず変更内容を要約します。 問題を探す前に、差分の全体像を把握します。

   • この変更で何を実現しようとしていますか？（新機能、バグ修正、リファクタリング、設定変更）
   • どのファイルが構造上の変更で、どのファイルがコアロジックの変更ですか？
   • 作者の意図は何ですか？ コミットメッセージ（git log --oneline <args>）と、関連する課題や PR の説明を読んで背景を確認します。
   • 作者はどのような重要な判断を下し、どのような制約のもとで作業していましたか？

   意図を理解すると、意図的な動作と実際のバグを区別しやすくなります。

5. 変更された各ファイルについて（上記のサイズ別の方針に応じて）、差分の該当箇所だけでなく、ファイル全体を読んで文脈を理解します。

6. 呼び出し元と依存先を相互参照します。 関数シグネチャの変更、エクスポート名の変更、戻り値の型の変更、動作の変更がある場合は、コードベース全体で使用箇所を検索します。単独では正しく見える関数でも、すべての呼び出し元を壊す可能性があります。次の点を確認します。

   • この関数を呼び出しているのはどこですか？ 新しい戻り値、エラー、null のケースに対応できますか？
   • このモジュールをインポートしているのはどこですか？ 変更後のエクスポート名を解決できますか？
   • この型の変更は、利用側にも正しく反映されていますか？

7. 以下の手法を使ってコードの変更を分析します。focus 引数が指定されている場合は、その領域に集中します。指定されていない場合は、すべての分析パスとシグナルしきい値を適用します。

分析方法

差分からは「何が」変更されたかがわかります。変更箇所の周辺コードからは、その変更が「正しいか」がわかります。以下の分析パスを適用します。

データフロー分析 — 変更されたコード内で値を追跡します。各変数の値はどこから来て、どこへ渡されますか？ 次の点を確認します。

• 変更されたコードが null／undefined ではないことを前提としている箇所に、値が null／undefined で渡される可能性はありますか？
• 変更されたコードは、上流の条件分岐のすべてのケースを処理していますか？
• 関数の戻り値の型が変更された場合、すべての呼び出し元が新しい形式に対応していますか？
• 絞り込みのチェック（例：if (x)）が、差分によって誤って外側に移動していませんか？

状態とライフサイクルの分析 — 状態を持つコード（React の状態、データベーストランザクション、ストリーム、イベントリスナーなど）について、次の点を確認します。

• この変更により、到達できない状態や、抜け出せない状態が生じていませんか？
• リソース（リスナー、サブスクリプション、ファイルハンドルなど）は、すべての経路で引き続き解放されますか？
• 並行アクセスによって共有状態が破損する可能性はありますか？
• 処理の順序は、引き続き不変条件（例：使用前の初期化）を満たしていますか？

契約分析 — 変更されたコードが満たす必要のある契約を確認します。

• 関数は呼び出し元が期待することを引き続き満たしていますか？（推測せず、呼び出し元を読みます。）
• インターフェースを実装している場合や、基底クラスのメソッドをオーバーライドしている場合、引き続きその仕様に準拠していますか？
• 事前条件と事後条件は維持されていますか？
• API エンドポイントの場合、レスポンスの形式はクライアントが送信する内容や期待する内容と一致していますか？

境界分析 — システム境界（ユーザー入力、ネットワーク、ファイル I/O、IPC）に関わるコードについて、次の点を確認します。

• ユーザーが制御できる入力は、使用前に検証されていますか？
• 不正な外部データによってプロセスがクラッシュしたり、状態が破損したりする可能性はありますか？
• インジェクションの脆弱性（SQL、シェル、XSS、パストラバーサル）はありませんか？

エッジケース分析 — 理論上のケースではなく、実際に発生するケースだけを確認します。

• 空の配列や文字列、ゼロ、負の数をコードが処理できていますか？
• ループ、スライス、インデックス計算にオフバイワンエラーはありませんか？
• 整数オーバーフローや、入力値が除数となる場合のゼロ除算はありませんか？

完全性の確認

コードの正しさを分析した後、変更が完全かどうか、つまり正しいだけでなく、仕上がっているかを確認します。

テストカバレッジ：

• 差分で新しい動作（新しい関数、エンドポイント、UI フロー、分岐）が追加されている場合、それをカバーするテストはありますか？ない場合は、[suggestion] として指摘してください。
• 差分でバグが修正されている場合、そのバグを検出できるテストはありますか？回帰テストによって再発を防止できます。
• 差分で既存の動作が変更されている場合、それに合わせて既存のテストは更新されていますか？古いままでも通ってしまうテストは、誤った安心感を与えるため、テストがないよりも悪い場合があります。
• 差分にテストが含まれている場合は、その品質を確認してください。
  • 適切な対象をテストしていますか？（実装の詳細ではなく、動作）
  • コードが処理するエッジケース（空の入力、エラーパス、境界値）をカバーしていますか？
  • 独立していますか？（テストの実行順序やグローバル状態に隠れた依存がない）
  • コードが壊れていても通ってしまう可能性はありませんか？（同語反復的なアサーション、モックでロジックを無効化しているなど）

不足している要素：

• スキーマを変更しているのに、マイグレーションがありませんか？
• 新しい環境変数に、ドキュメントやデフォルト値がありませんか？
• 新しい依存関係に対して、ロックファイルが更新されていませんか？
• API レスポンスを変更しているのに、クライアント側が更新されていませんか？
• 新しいエラー型を、呼び出し元で処理していませんか？
• 機能を削除したのに、関連コード（不要なインポート、未使用の設定、孤立したテスト）が残っていませんか？

変更が正しく機能するために明らかに必要な不足要素だけを指摘してください。将来的な改善案は指摘しないでください。

指摘する内容

正しさ、セキュリティ、信頼性に影響する実際の問題を指摘してください。

• コンパイル、解析、実行に失敗するコード（構文エラー、型エラー、インポート漏れ、未解決の参照）
• 誤った結果を生むロジックエラー（明らかなバグ、オフバイワンエラー、条件式の不具合）
• 変更されたコードにおけるセキュリティの脆弱性（インジェクション、XSS、認証バイパス、データ漏えい）
• 具体的な状況を示して説明できる競合状態やデータ損失のリスク
• 違反している正確なルールを引用できる、CLAUDE.md の規則違反
• 呼び出し元が期待する内容を満たさなくなった変更済み関数など、契約の破綻
• 新規または変更された動作に対するテストの不足（プロジェクトの CLAUDE.md でテストが必須とされている場合を除き、[must-fix] ではなく [suggestion] として指摘）
• 変更が正しく機能するために明らかに必要な要素の不足（マイグレーション、設定、クライアント側の更新など）

スタイル上の懸念、リンターで検出できる問題、変更されていないコードに既存する問題は指摘しないでください。ファイル全体ではなく、差分に注目してください。

コメントする前に検証する

指摘ごとに、投稿する前に問題が実在することを確認してください。

• 周辺のコードを読み直してください。全体の文脈を見ると、バグに見えたものが問題でなくなることがあります。
• 「インポート漏れ」や「未定義変数」の指摘は、grep で確認してください。
• 呼び出し元の不具合については、実際の呼び出し箇所を読んでください。
• CLAUDE.md 違反については、そのルールがこのファイルにも適用されることを確認してください。
• テスト不足については、別のファイルに該当パスをカバーするテストがないことを確認してください。

同じパターンが複数のファイルに見られる場合は、最初に見つかった箇所にコメントし、全体の概要でそのパターンについて説明してください。コメントを重複させないでください。

ステップ 3：コメントを残す

1. コメントは重要度の高い順に並べます。 まずすべての [must-fix] コメントを投稿し、次に [suggestion]、最後に [question] を投稿します。同じ重要度の中では、ファイル順に並べます。これにより、作成者がざっと目を通す場合でも、最も重要な問題が先に目に入ります。

2. 各指摘には、コメント本文の先頭に重要度のプレフィックスを付けて分類します。

   • [must-fix] — バグ、セキュリティ上の問題、データ損失のリスク。コードが動作しなくなったり、誤った結果を生成したりする問題です。
   • [suggestion] — 明確な理由がある具体的な改善案です。スタイルの好みではなく、実質的な改善に限ります。テストの不足、変更の不完全さ、より良い方法などが該当します。
   • [question] — 不明瞭で、作成者に確認が必要な内容です。

3. 各指摘について、次のコマンドを使ってインラインコメントを残します。

   diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
   

   • 追加・変更されたコードへのコメントには --side new（デフォルト）を使用します。
   • 削除されたコードへのコメントには --side old を使用します。
   • 問題が複数行にわたる場合は --end-line を使用します。
   • 背景ではなく、問題点から書き始めます。 具体的で、対応方法がわかる内容にします。
   • 小さく、単独で修正できる問題には、修正例を示すコードを含めます。
   • 大規模な修正（構造の変更、複数箇所にまたがる変更）の場合は、コードブロック全体を示すのではなく、問題と推奨する対応方法を説明します。
   • CLAUDE.md 違反を指摘する場合は、違反しているルールを正確に引用します。

4. すべてのインラインコメントを残した後、全体コメントが必要かどうかを判断します。

   • 指摘がない場合 → 全体コメントを残します： "No issues found. Checked for bugs and CLAUDE.md compliance."
   • 指摘が 1～2 件の場合 → インラインコメントで触れられていない横断的な懸念がない限り、全体コメントは省略します。
   • 指摘が 3 件以上の場合 → 指摘のテーマをまとめた全体コメントを残します。
   • 差分が大きい場合 → レビューの対象範囲を示し、指摘を分野ごとにまとめた全体コメントを必ず残します。
   • 全体コメントに重要度のプレフィックスは付けません。プレフィックスはインラインの指摘にのみ使用します。
   • 判定を先に述べ、率直かつ簡潔に書きます。褒め言葉や余計な文言、コードの内容を逐一説明する記述は避けます。

   diffity agent general-comment --body "<overall review summary>"
   

ステップ 4：ブラウザーを開く

1. コメントの準備ができたら、ブラウザーを開きます。

   diffity open <ref>
   

   ref が指定されている場合は引数として渡します（例：diffity open HEAD~3）。デフォルトのビューを開く場合は省略します。

2. レビューが完了し、ブラウザーで確認できることをユーザーに伝えます。例：

   レビューが完了しました。ブラウザーを確認してください。

   指摘：must-fix 2 件、suggestion 1 件

   準備ができたら、/diffity-resolve を実行して修正してください。