reviewkit

reviewkit

AI エージェントが書いたコードをレビューし、AI 生成の変更に特有の失敗パターンを見つけます。一般的な「バグを探す」レビューでは、エージェントが最もよく犯す次の3つの間違いを見逃します。単独では正しいものの、このリポジトリには合っていないコードを書くこと、頼まれていないのにもっともらしいだけの不要なコードで変更を膨らませること、そして作業の一部をひそかにやり残すことです。reviewkit はまずこれらをチェックし、次に正確性を確認して、重要度順に指摘事項を報告します。修正は行いません。修正するかどうかは人間が決めるか、実装スタイルのスキルに引き継ぎます。

これは**エディターではなく、レビュアーです。**変更を読み、評価しますが、ソースコードを編集することはありません。唯一の任意の成果物は、ユーザーが PR の説明に使えるよう保存できるレビュー報告書です。

新鮮な視点でレビューする

レビューするのは、変更を書いたエージェントとは別のエージェントにしてください。 reviewkit は通常、コードを書き上げたのと同じセッションで実行されます。そのため、レビュアーはコードを書いている間に行ったあらゆる正当化を引きずってきます。すでに正当化した近道や、重要ではないとすでに判断したエッジケースなどです。これが、このレビューが形だけの承認になってしまう最大の原因です。

そのため、サブエージェントツールが使える場合は、新しいサブエージェントにレビューを委任してください。差分、明示された意図、以下のチェック項目を渡し、実装セッションの記憶がない状態で報告させます。指摘事項を確認してから、提示してください。サブエージェントツールが使えない場合は自分でチェックしますが、判定をどれだけ重く受け止めるべきかユーザーが判断できるよう、報告書にはこれがセルフレビューであることを明記してください。自分が書いたばかりの変更を、ひそかにセルフレビューしてはいけません。

どちらの方法でも変わらないことが一つあります。書こうとしていたコードの記憶ではなく、実際にディスク上にあるコードを評価してください。

実行されるタイミング

エージェント（またはユーザー）が作業のまとまりを終え、公開前に評価してほしい場合です。「これをレビューして」「自分の変更をレビューして」「差分をレビューして」「このコードをチェックして」「コミット前にセルフレビューして」「/reviewkit」や、コーディングセッション後の「これで問題なさそう？」といった依頼が該当します。レビュー対象は未コミットの作業またはブランチの差分であり、コードベース全体を1行ずつ監査するものではありません。

一般的な正確性チェックのリンターとは異なります。reviewkit は、バグに焦点を当てたレビューでは見落とされる規約への適合性とエージェント特有の不要なコードを優先してチェックします。ユーザーが正確性に関するバグだけを求めている場合は、その旨を伝えて該当するチェックだけを実行し、残り2つを報告書に付け足さないでください。

手順

1. レビュー対象を選ぶ

記憶に頼ったレビューには意味がないため、実際の差分を基準にレビューします。git の状態から対象を判断し、選択内容を伝えて、ユーザーが変更できるようにします。

• 未コミットの変更がある（git status --porcelain の出力が空でない）→ 作業ツリーを確認します：git diff HEAD（ステージ済みの変更も含めるには git diff --staged）。これは、新しいコーディングセッションの直後におけるデフォルトです。git diff には未追跡ファイルが表示されません。そのため、エージェントがステージしていない新規ファイルは表示されず、新しいモジュール全体がレビューから漏れるのは最悪の見落としです。git status --porcelain（?? のエントリー）または git ls-files --others --exclude-standard で一覧を出し、変更の一部としてすべての未追跡ソースファイルを例外なく全文読み込みます。スキップしてよい未追跡ファイルは、誰も作成していないものに限ります：ロックファイル、ビルド出力、ベンダー依存関係、コンパイル済みアセット、スナップショットです。生成物であることを記録し、実際に手編集されていないことを抜き取り確認してから先に進みます。
• 作業ツリーがクリーンで、ブランチがベースより先行している → ブランチの差分をレビューします。ベースブランチは gitkit から取得してください。ベースブランチの解決は gitkit が担います。main と決めつけたり、ここで再導出したりしないでください。誤ったベースでは、差分が空になったり、リポジトリの履歴の半分を含んだりしますが、どちらも実際のレビュー対象に見えてしまいます。gitkit がない場合は、git symbolic-ref --short refs/remotes/origin/HEAD からリモートのデフォルトブランチを取得し（origin/ の接頭辞を除去）、それもない場合は git rev-parse --verify で解決できる main または master のうち先に見つかったものを使い、どのフォールバックを使ったかをターゲット行に記載します。その後、意図を把握するために git diff <base>...HEAD と git log <base>..HEAD --oneline を実行します。
• 呼び出し時にターゲットが指定されている（「ブランチをレビューして」「ステージ済みの変更をレビューして」など）→ 指定されたターゲットに従い、検出を省略します。

選択したターゲットとその理由を1行で述べてから、続けます。どちらにも該当しない場合（作業ツリーがクリーンで、ブランチも先行していない場合）は、推測せずに何をレビューすればよいか尋ねます。

レビュー前に検証してください。 ターゲットが解決できること（名前付きベースの場合は git rev-parse <ref>）と、変更が実際に空でないことを確認します：追跡対象の差分と、一覧に出した未追跡ファイルです。未追跡ファイルだけの変更では git diff は空になりますが、それでもレビュー対象です。参照先が解決できない場合、または差分と未追跡ファイルの両方が空の場合は、そこで停止してその旨を伝えてください。不適切または空の範囲をレビューすると、レビュー結果が捏造されてしまいます。

判断を下す前に差分全体を一度読み通してください。一度だけです。以下の4つのパスは、4回読み直すのではなく、1回の読解に対して4つの問いを投げかけるものです。あるパスで記憶にない詳細が必要になった場合は、差分全体を再実行せず、該当ハンクを取得してください（git diff HEAD -- <path>）。規約との適合性 で比較する周辺コードにも同じことが当てはまります。ディレクトリ内の全ファイルではなく、パターンを示す兄弟ファイルを読みます。

この手順は、ターゲット行が明示され、参照先が解決でき、変更されたすべてのファイルと、生成物ではない未追跡ファイルがすべて読み込まれ、明示された意図が書き留められている（または意図が存在しないことが記録されている）時点で完了です。

コミットメッセージ、ブランチ名、参照先の計画や課題、またはユーザー自身の言葉から、変更の明示された意図を確認してください。レビューの半分は「依頼されたことをすべて、かつそれだけを実行したか？」を問うことだからです。その意図を具体的に記録してください。これは、要件の網羅性とエージェント特有の粗雑さの兆候におけるスコープ逸脱の確認の両方で照合する仕様です。

すべてのパスで守る基本ルール。 これらを全体を通して適用してください。実質的なレビューと雑音を分ける基準です：

• ツールによってすでに検出される問題は対象外にします。 フォーマッター、リンター、CI が自動で検出する書式、インポート順、リンタールールは報告しないでください。このレビューの価値は、マシンが見落とす問題にあります。そこに時間をかけてください。
• すべての指摘には根拠が必要です。 問題のある箇所を引用し、何に違反しているのかを明記してください。具体的には、リポジトリの規約ドキュメントの該当行、明示された意図、実際の API シグネチャ、または具体的な再現入力です。引用で裏付けられない指摘は推測です。削除してください。これは、指摘の捏造を防ぐための主要な手段です。
• 指摘を出す前に、確信度の基準を満たしているか確認してください。 これが誤りであるためには何が事実である必要があるかを考え、その答えがコード、再現、またはテスト実行によって確認できる場合、あるいは正当な別の説明がなく、強く裏付けられている場合に限り報告してください。「おそらく問題だが、実行時の挙動は確認できなかった」という指摘は、確認できなかった部分を明記した場合にのみ基準を満たします。それより根拠が弱いものは指摘ではありません。未検証の領域であり、指摘を報告する のカバレッジに関する注記に記載してください。直感を「未検証」に格下げすることも、実質的な成果です。それをバグのように装うのは、読者の時間を無駄にし、レポート全体への信頼を損ないます。
• 判断できなかった点を記録してください。 レビューを進めながら、実際には十分に確認できなかった領域を継続的に記録してください。静的には推論できない並行処理の経路、認証モデルが差分の外にあるセキュリティ境界、読み込まずに抜き取り確認した生成ファイル、オフラインでは実際の API を検証できなかった依存関係などです。何も書かれていなければ「問題なし」と受け取られます。したがって、確認していない領域は省略せず、明記してください。

2. パス 1：規約との適合性

変更は、このリポジトリのコードに見えますか？ エージェントは、ローカルな慣習を無視した、一般論としては正しいコードを作りがちです。変更されたファイルごとに、周辺のファイルと比較してください。周囲のコードが仕様です。

• 命名と構造。 新しい名前、ファイル配置、モジュール境界は、同じ階層のファイルに沿っていますか？ fetch_user が多用されているリポジトリで、エージェントがヘルパーに getUserData と名前を付ければ、目立ちます。
• 確立されたパターン。 HTTP クライアント、エラー型、ロギングヘルパー、テストファクトリーなど、リポジトリにすでに実装方法があるのに、変更で再利用せずに作り直していませんか？ 新しい抽象化を受け入れる前に、既存の実装を検索してください。
• 慣用表現とスタイル。 エラー処理、非同期処理のスタイル、インポート、リンターでは検出されない書式の慣習などです。抽象的な「ベストプラクティス」ではなく、既存のコードに合わせてください。
• 依存関係。 リポジトリですでに解決できること、またはプロジェクトの規約で禁止されていることのために、ライブラリを追加していませんか？ マニフェストと既存のインポートを確認してください。
• 明文化された規約。 リポジトリに規約が記載されている場合（CLAUDE.md、エージェントガイドファイル、CONTRIBUTING.md、スタイルガイドなど）は、それを読み、変更が従っているか確認してください。文書化されたリポジトリのルールは、一般的な「ベストプラクティス」より常に優先されます。

ここで見つかる、よくあるコードの臭い（Fowler の用語です。段落で説明するより明確なので、当てはまる場合は用語を使ってください）：Mysterious Name（名前が不明瞭）、Shotgun Surgery（1 つの論理的な変更が多数のファイルに分散している）、Divergent Change（1 つのモジュールが互いに無関係な複数の理由で変更されている）。

変更されたすべてのファイルを少なくとも 1 つの同階層ファイルまたは文書化された規約と比較し、上記の各確認項目について指摘または問題なしの記録がある状態になれば、このパスは完了です。

3. パス 2：エージェント生成コード特有の兆候

機械生成コードに見られる兆候、つまり生産的に見えても何の役にも立たない水増しを探します。

• 過剰設計。 呼び出し元が 1 つしかない抽象化、どこからも設定されない設定項目、直接呼び出せば置き換えられる間接化の層、存在しない要件への「将来への備え」。
• デッドコードと到達不能コード。 一度も呼び出されないヘルパー、実行されることのない分岐、何からもインポートされないエクスポート、代入されても読み取られない変数。
• 幻覚または誤った API。 実際の型には存在しないメソッド、フラグ、フィールドの呼び出し、あるいは別のライブラリバージョンにある、もっともらしい名前の関数。モデルの推測ではなく、実際の依存関係で確認します。
• 冗長なコメント。 コードを言い換える説明（// increment i）、何も付け加えないドックストリング、残されたコメントアウト済みコード。
• スコープの逸脱。 依頼された範囲外の変更：無関係なリファクタリング、変更していない行の再フォーマット、ついでに行った名前変更、依頼されていないバージョン更新。明示された意図で正当化できないものはすべて指摘します。
• 見せかけの堅牢性。 エラーを握りつぶす try/catch、失敗を隠すデフォルト値、何も検証しない、または同義反復的なテスト、実際の処理の代わりに置かれた TODO。

ここでよく見られる、名前の付いたコードの臭いには、投機的な汎用性（存在しないニーズのための抽象化。削除してインライン化し、実際に 2 つ目の呼び出し元が現れるまで待ちます）、コードの重複（共有せず、同じロジックを複数の変更箇所に貼り付けること）、プリミティブ執着（ドメインの概念を単なる文字列や整数で表すこと）、ミドルマン／メッセージチェーン（委譲しかしない層、または a.b().c().d() のような連鎖的な参照）があります。特に投機的な汎用性は、エージェント特有の臭いです。

上記の各兆候に照らしてすべての変更箇所を確認し、新しいエクスポート、ヘルパー、依存関係のすべてについて、確認済みの呼び出し元があるか、問題点として指摘されている状態になれば、このパスは完了です。

4. パス 3：要件の網羅性

エージェントは、過剰に実装するのと同じくらい、要件を満たしきれないことがあります。分岐を仮実装したり、依頼の一部を飛ばしたり、簡単な 80％だけを解決して残りを未完了のまま黙って放置したりします。レビュー対象を選ぶで捉えた意図、つまり計画、issue、またはユーザーの言葉と変更を照らし合わせ、次の不足を報告します。

• 要件の欠落。 依頼されたもののうち、差分がまったく対応していない項目。
• 部分的な実装。 正常系だけに対応した要件、複数あるケースのうち 1 つだけに対応した要件、または振る舞いを伴わないインターフェース。
• スタブとプレースホルダーの残存。 TODO／FIXME／throw new Error("not implemented")／pass／空のハンドラーが、作業済みであるかのように残されている状態。
• 解釈の誤り。 変更によって何かは行われるものの、依頼された内容とは異なる、より近くて簡単な問題を解決している状態。

照合する意図が捉えられていない場合（計画、issue、明確な依頼がない場合）は、その旨を伝え、仕様をでっち上げずにこのパスを省略します。ユーザーが述べていない要件を推測してはいけません。

捉えられた意図に含まれるすべての要件について、該当する変更箇所とともに、対応済み、一部対応、未対応のいずれかが示されれば、このパスは完了です。

5. パス 4：正確性

先行するパスを経て残ったものを対象に、従来どおりのレビューを行います。

• ロジックエラー。 オフバイワン、条件の逆転、演算子の誤り、戻り値の処理ミス。
• エッジケース。 空／null／未指定の入力、境界値、Unicode、大きなペイロード、正常系だけでなくエラー経路も確認します。
• データの境界。 変更された UI が描画する値のうち、その描画またはデータソースが差分で追加・変更されたものについて、バリデーションスキーマ、データベースの列、API 型、または maxLength にある上限を見つけ、その値を描画できるか確認します。長いテキストの切り詰めまたは折り返し、メールアドレスや ID など、途中に区切りのない文字列に対する改行ルール（overflow-wrap、word-break）、1 の場合の単数形、0 の場合の空状態、未指定のオプションフィールドに対するフォールバックを確認します。上限値と描画箇所の行を引用してください。フロントエンドの上限がバックエンドより短い場合、有効な行を保存または表示できなくなるため、指摘事項です。リポジトリ内に上限がない場合は、描画方法に応じて判断します。長いテキストへの対処がない描画は、unbounded: no limit in <schema>, <column>, <API type>; render at file:line has no truncation or break rule の形式で記載する🟡の指摘事項です。長いテキストにすでに対処している描画は指摘事項ではありません。リポジトリ外（サードパーティ API）にある上限は、カバレッジノートに記載します。qakit の最悪ケースチェックはランタイム側のチェックであり、これらの値を画面に表示します。qakit を使わない場合は、長い値、空の値、未指定の値を使って画面を手動で描画します。
• 状態と並行処理。 競合状態、共有状態の変更、順序に関する前提、冪等性、リソースのクリーンアップ（ファイル、接続、ロック）。
• セキュリティ。 インジェクション、認可／所有権チェックの欠落、コードやログ内のシークレット、安全でないデシリアライズ、信頼境界を越える未検証の入力。
• テスト。 変更されたテストは実際に変更内容を検証していますか。また、合格しますか。リポジトリのテストコマンドが明らかで、実行コストも低い場合は実行し、実行した内容と結果を報告します。

テストスイートに合格しても、変更がテストされている証拠にはなりません。エージェントが、失敗しうるものを何も検証しないために合格するテストを書くことがあるからです。新規または変更されたテストは、次の点をそれぞれ確認してください。

• 壊れた実装に対して失敗しますか？ 対象となるロジックを逆転させるか、境界値を壊すことを頭の中で試します。それでもテストが合格するなら、見せかけのテストです。これはテスト品質を見極めるうえで、最も鋭い問いです。
• 観測可能な動作を検証していますか？ それとも、本番ロジックをアサーション内で再実装し、コード自体と比較しているだけですか？
• シナリオがテスト内で明確に分かりますか？ それともセットアップ／フィクスチャ／モックの中に埋もれていて、モックが機能することしか証明していませんか？
• 機能のデモで示される正常系だけでなく、変更によって生じた失敗経路もカバーしていますか？
• 明示された要件を証明していますか？ それとも、より簡単な隣接要件を検証しているだけですか？

変更されたすべてのコードパスについて、上記の各チェックに指摘事項があるか、問題なしと記録されており、新規または変更されたすべてのテストについて、5 つの問いに回答できたら、このパスは完了です。

6. レビュー結果を報告する

レビュー結果をインラインで出力し、読者がひと目で優先順位を判断できるよう、指摘を重大度順に並べます。それぞれに次のタグを付けます。

• 🔴 ブロッカー。 リリース前に必ず修正が必要です。実際のバグ、セキュリティ上の欠陥、要件の欠落、または問題を引き起こす規約違反が該当します。
• 🟡 要修正。 リリースを妨げるほどではありませんが、対処する価値のある実際の問題です。
• 🟢 軽微。 仕上げ、スタイル、細かな不備です。対応は任意です。

各指摘には、次の順で記載します。file:line 形式の場所（クリック可能）、検出したパス（convention / slop / completeness / correctness）、問題のある箇所の引用と、それが何に違反しているか（証拠に関するルールに従い、レビュー対象を選ぶにある規約ドキュメントの行、明示された要件、実際の API、または失敗する入力）、問題点を述べる1文、具体的な修正方法です。指摘がなかったパスについても、その旨を記載してください。問題のないパスも正当な結果です。見栄えを整えるために指摘をでっち上げてはいけません。 証拠を引用できないなら、それは指摘ではありません。差分に問題がなければ、レポートが空であることが誠実な結果です。

レポートは、判定、重大度の高い順に並べた指摘、カバレッジの注記の順に構成します。

判定は指摘から導きます。感覚で決めてはいけません。 読者が指摘一覧を読み返さなくても信頼できるよう、機械的に選んでください。

• needs-work。 🔴 ブロッカーが1件以上あります。
• ready-with-fixes。 ブロッカーはありませんが、🟡 要修正が1件以上あります。
• ready。 🟢 軽微を超える問題はありません。軽微な指摘で変更を保留にしてはいけません。

変更の大部分が良好、または作者が努力したという理由で判定を甘くしてはいけません。厳格に見えるように判定を厳しくすることもいけません。ブロッカーが実在するなら、ほかがどれほど優れていても、その変更には対応が必要です。

最後にカバレッジの注記を記載します。各パスで確認できなかった領域をまとめ、テストを実行したかどうか、また、フレッシュアイズレビューかセルフレビューか（フレッシュアイズでレビューするを参照）を述べる短い段落にしてください。同時実行の経路を確認していないと把握している読者なら、追加で確認できます。確認済みだと思い込む読者が出ないようにしてください。未確認のセキュリティ境界や、この場では誰も検証できない移行など、重大な問題が潜んでいる可能性があるほどの不足がある場合は、証拠が裏付けない判定を出すのではなく、変更は外部レビュー待ちでブロック中と記載してください。

ソースを編集したり、修正を適用したりしてはいけません。修正の引き継ぎは引き継ぎで行います。

7. 任意：レポートを保存する

レビュー結果を表示した後、保存するかどうかをユーザーに尋ねます（確認なしに保存してはいけません）。PR の説明などに貼り付けるため、ユーザーが保存を希望した場合は、docs/reviews/NNNN-review-<branch-or-feature-slug>-YYYY-MM-DD.md に書き込みます。連番には次の番号、スラッグには短い小文字の kebab-case、日付にはレビューの ISO 作成日を使用します（例：0002-review-auth-refactor-2026-07-23.md）。連番 NNNN を取得するには、現在の worktree、git worktree list に列挙されたほかのすべての worktree、および origin/HEAD（git fetch origin の後に git ls-tree --name-only origin/HEAD docs/reviews/）を対象に、docs/reviews/ 内で先頭にある4桁の連番の最大値を調べ、それに1を加えます。該当する番号がなければ 0001 から始めます。並行している worktree が同じ連番を使わないよう、3つすべてを確認してください。リモートがない場合など、取得元の確認に失敗した場合はその取得元をスキップします。git が使えない場合は、ディレクトリのみを一覧表示してください。連番はディレクトリごとに管理し、一度使った番号は再利用しません。同じレポートを編集する場合は、ファイル名を変えないでください。必要に応じて docs/reviews/ を作成します。保存するファイルは、表示した内容と同一にし、日付とレビュー対象範囲を記した1行のヘッダーを付けます。ファイルシステムがない場合はこの手順を省略し、インラインのレポートを成果物とします。

8. 引き継ぎ

レポートの後に、短く次の3点を伝えて締めくくります。

• 変更内容。 reviewkit はソースを編集していないことを伝えます。レポートが保存されたかどうかを明記します。
• 保存先。 保存したレポートのパスを示すか、レポートはインラインのみだと伝えます。レビューした範囲を明記します。
• 次の手順。 判定に基づいて、次に行う作業を1つだけ選びます。
  • ready → インストール済みの場合は qakit で手動QA計画を作成します（/qakit）。そうでなければ、commitkit でコミットし、それも使えない場合は git commit を実行します。
  • ready-with-fixes または needs-work → implementkit の修正ラウンドで指摘事項に対応し、このレポートを渡します。そうでなければ、指摘事項を手動で修正します。その後、reviewkit を再実行します。
  • blocked on outside review → 対象領域と、確認を完了する必要がある人またはチェックを示します。そのレビューが完了するまでは、ほかに次の作業はありません。

次のキットへ引き継ぎます。呼び出してはいけません。

注意事項

• 契約上、読み取り専用です。 reviewkit は変更内容を理解するために git と読み取り・検索コマンドを実行し、正しさの確認にはリポジトリ独自のテストコマンドを最大1つだけ実行します。ソースの編集、コミット、プッシュは一切行いません。唯一の書き込みは、ユーザーから依頼があった場合に限り、任意：レポートの保存で説明されているレポートファイルを保存することです。
• Skill がツール一覧にあるのは gitkit だけです。 reviewkit はブランチの差分をレビューする際、ベース ref を特定するために gitkit を呼び出します。誤ったベースでは差分が空になったり、リポジトリの履歴の半分が対象になったりし、どちらも本物のレビュー対象に見えてしまうためです。引き継ぎで指定されたキットは引き継ぎ先であり、呼び出してはいけません。
• 差分の規模に合わせます。 1行の修正なら簡単に確認し、判定も1行で済ませます。大規模な機能ブランチなら、すべての手順を実施します。小さな変更に余計な形式を付け加えないでください。
• テストやCIの代わりにはなりません。 エージェントが書いたコードで起こりやすい問題を考慮し、テストやCIに加えて判断を行います。自動チェックですでに確認済みの項目は確認済みとして報告し、見落とされる内容にレビューの労力をかけます。これは、レビュー対象の基本ルールでツールにより強制されるルールを対象外にしている理由と同じです。
• シェルや git が使えない場合は？ ユーザーに差分と元の依頼を貼り付けてもらい、提供された内容に対して4つの確認を実施します。保存用にレポートをコードブロックで出力します。