code-reviewer

code-reviewer スキルの概要

code-reviewer スキルでできること

code-reviewer スキルは、Code Review 向けに整理された PR / diff レビューのワークフローです。単に「このコードをレビューして」と一行で依頼するのではなく、変更ファイルの収集、diff の確認、ローカルなプロジェクト内パターンの把握を踏まえたうえで、正確性、セキュリティ、パフォーマンス、テスト、保守性といった具体的な観点ごとにレビューを進めるようエージェントを導きます。

code-reviewer を導入すべき人

この code-reviewer skill は、一般的なプロンプトより一貫性のあるレビューを求める開発者、テックリード、AI 支援レビュアーに向いています。とくに、日常的に pull request をレビューしている、重大度ベースで指摘を整理したい、ロジック上の問題と高リスクなセキュリティ懸念の両方を漏れなく見たい、といった用途で有効です。

本当に解決したい仕事

多くのユーザーが欲しいのは、単なる「フィードバック」ではありません。知りたいのは、何が変わったのか、どこが危険なのか、どれがマージを止めるべき問題なのか、どれは後回しにできるのか、その判断を支える根拠は何か、という点です。code-reviewer のワークフローは、この実務上のニーズに合わせて、文脈収集と分析を分けて進める設計になっています。コード断片だけを見た浅いコメントに寄りにくいのが特徴です。

このスキルが他と違う点

最大の違いは、レビューの構造化にあります。リポジトリは「コードを見てレビューせよ」という大まかな指示で終わっていません。具体的には次のものが含まれています。

• 段階的に進めるレビュー手順
• 重大度ベースの出力スタイル
• チェックリスト、コーディングパターン、セキュリティレビューのための参照資料
• Git の変更からレビュー用チェックリストを生成する scripts/review_checklist.py

そのため、code-reviewer for Code Review は単純なプロンプトより実務で使いやすく、チームごとのレビュー基準にも合わせやすい構成です。

code-reviewer が強くハマるケース

次のような状況では code-reviewer が特に有効です。

• main に対するブランチ diff がある
• 複数ファイルにまたがる PR や横断的な変更をレビューしたい
• マージを止める問題と、任意の改善提案を分けて扱いたい
• 認証、入力処理、データアクセスなどセキュリティ感度の高い変更がある
• 抽象的なベストプラクティス以上に、既存コードの流儀との整合性が重要なコードベースである

相性が弱いケース

一方で、このスキルは次のような場面では効果が落ちます。

• 確認すべき diff や変更ファイル群がない
• 欲しいのがスタイル面の細かな指摘だけ
• タスクの主眼がコードレビューではなくアーキテクチャ設計
• リポジトリ文脈にアクセスできず、既存パターンとの比較ができない
• 実際にはデバッグ、書き換え、機能計画の依頼になっている

code-reviewer スキルの使い方

code-reviewer スキルの導入方法

上流の SKILL.md には直接の install コマンドは掲載されていませんが、このスキルは zhaono1/agent-playbook の skills/code-reviewer にあります。利用している skills ランタイムが GitHub リポジトリのパスやコレクションからのスキル導入に対応しているなら、そのリポジトリを指定して code-reviewer スキルを選択してください。

よくある導入パターンは次のとおりです。

npx skills add https://github.com/zhaono1/agent-playbook --skill code-reviewer

別のインストーラを使う環境でも、重要なのはスキル slug が code-reviewer である点です。

まず読むべきファイル

最短で見極めるなら、次の順番で読むのがおすすめです。

1. skills/code-reviewer/SKILL.md
2. skills/code-reviewer/README.md
3. skills/code-reviewer/references/checklist.md
4. skills/code-reviewer/references/security.md
5. skills/code-reviewer/references/patterns.md
6. skills/code-reviewer/scripts/review_checklist.py

この順番には意味があります。SKILL.md でワークフローがどう起動するかを把握し、参照資料で適用される基準を確認し、最後にスクリプトでリポジトリからどのように根拠を集める想定なのかを見る、という流れです。

code-reviewer がうまく機能する入力条件

code-reviewer usage は、次の情報が揃っていると最も強く機能します。

• ベースブランチ。通常は main
• PR の目的、または関連チケット
• 変更ファイル一覧、または完全な diff
• 特に重視したいリスク領域
• フレームワークや言語の前提
• 軽めの確認が欲しいのか、マージ可否を判断する厳しめレビューが欲しいのか

これらがなくてもレビュー自体はできますが、内容はかなり一般論寄りになります。

このスキルがレビュー文脈を集める流れ

このリポジトリでは、想定されるレビュー手順が明示されています。

• git diff main...HEAD --name-only で変更ファイルを取得する
• git log main...HEAD --oneline でコミット履歴を確認する
• git diff main...HEAD で実際の差分を確認する
• 周辺ドキュメントや類似ファイルを読み、ローカルな慣習を把握する

ここは重要です。弱い AI レビューは文脈収集を飛ばして、いきなり抽象的なベストプラクティスを語りがちです。code-reviewer は、まず「何が実際に変わったのか」に足場を置くことで、その問題を避けやすくしています。

実務で使いやすい code-reviewer プロンプト例

プロンプトは、次のように書くほうが効果的です。

Review this branch with the code-reviewer skill.

Base branch: main
Goal: add password reset flow for users
Priority areas: security, correctness, test gaps
Constraints: keep current API shape, do not request large refactors
Please classify findings by severity: critical, high, medium, low.
For each finding, cite the file, explain the risk, and suggest the smallest safe fix.

これは「review my code」とだけ依頼するより優れています。ブランチの比較先、変更の業務上の意図、レビュー優先度、返答フォーマットまで明示されるためです。

弱い入力と強い入力の違い

弱い入力:

Review this PR

より強い入力:

Use code-reviewer on the diff against main.
Focus on auth flows, input validation, and regression risk.
Check whether tests cover unhappy paths and whether any existing project patterns were broken.
Flag only issues that are actionable before merge unless clearly marked as low severity.

強いほうの書き方は、レビュー対象の範囲を絞り、リスク領域を明示し、どこまで踏み込んだ指摘を求めるかも伝えるため、出力品質がはっきり改善します。

実際の PR レビュー向けおすすめ手順

実務向けの code-reviewer guide としては、次の流れが扱いやすいです。

1. 変更ファイルと diff を集める
2. PR 説明またはチケットを読む
3. 隣接するファイルを少し見て慣習をつかむ
4. 正確性、セキュリティ、パフォーマンス、コード品質、テスト、ドキュメント、保守性の順でレビューする
5. 指摘を重大度別にまとめる
6. 初回レビューで重大な問題が見つかったら、高リスクなファイルだけを対象に 2 回目の確認を行う

この 2 パス構成は、1 回目で広くリスクを拾い、2 回目で精度を上げられるため、実運用で相性が良いです。

参照資料を使ってレビューを一般論化させない

通常のプロンプトではなくこのスキルを選ぶ理由として大きいのが、補助ファイルの存在です。

• references/checklist.md はレビューを体系的に保つ
• references/security.md は OWASP 寄りの確認観点を追加する
• references/patterns.md は良い実装 / 悪い実装の具体例を示す

レビューが曖昧だと感じたら、diff を分析する際にこれらの参照を明示的に適用するようエージェントに指示すると改善しやすいです。

レビューの土台を作りたいなら補助スクリプトを使う

このリポジトリには次のスクリプトが含まれています。

python scripts/review_checklist.py

エージェントに文章ベースの指摘を書かせる前に、現在の Git 状態から機械的にチェックリストを作りたいときに便利です。生の diff 確認と、完成度の高いレビュー文の中間を埋める実用的な手段になっています。

実務で使いやすい出力形式

スキルには、次の形で返すよう求めるのが実践的です。

• 何が変わったかの短い要約
• 最初にマージブロッカー
• 重大度ごとに整理した指摘
• ファイル単位の参照
• 結論だけでなく理由の説明
• 最後に注意点つきの「safe to merge?」評価

この出力スタイルは、リポジトリの重大度モデルと噛み合っており、実際のチームレビューにも流し込みやすくなります。

code-reviewer スキル FAQ

code-reviewer は普通のレビュー用プロンプトより優れているか

多くの場合、実リポジトリの文脈があるなら yes です。code-reviewer の価値は、魔法のように分析が深くなることそのものではありません。起動のきっかけ、段階的ワークフロー、チェックリストの網羅性、参照資料が組み合わさることで、レビューをより完全で一貫したものに寄せられる点にあります。

code-reviewer は初心者にも使いやすいか

はい。ただし注意点が 1 つあります。初心者であっても、最低限の文脈は渡す必要があります。このスキルは強いレビュー構造を提供しますが、要件、期待される振る舞い、チームの慣習をゼロから推測できるわけではありません。初めて使う場合でも、PR の目的とベースブランチは最初に入れておくほうが結果が安定します。

code-reviewer は pull request でしか使えないか

いいえ。code-reviewer usage は、ローカルブランチの diff、変更ファイルのまとまり、あるいは「src/auth/ のコードをレビューして」のようなフォルダ単位の依頼にも使えます。ただし、既知のベースブランチに対する明確な diff があるときが最も力を発揮します。

code-reviewer スキルはどんな問題を見に行くのか

リポジトリ上の情報を見る限り、次の観点をカバーしています。

• 正確性と境界ケース
• OWASP 系の観点を含むセキュリティ問題
• 不要なクエリや呼び出しなどのパフォーマンス問題
• コード品質と保守性
• テスト不足
• ドキュメント不足

この広さがあるため、セキュリティ専用レビューやスタイルレビュー専用ではなく、一般的な PR レビュー全般に向いています。

どんなときに code-reviewer を使うべきではないか

次のようなタスクが主目的なら、code-reviewer は外したほうがよいです。

• 新しいコードの生成
• 実行時エラーのデバッグ
• 大規模なアーキテクチャ設計
• フォーマットや lint の一括調整だけ
• 変更文脈にアクセスできない状態でのレビュー

こうしたケースでは、より専用のスキルや、タスク特化の直接的なプロンプトのほうが適しています。

1 つのコーディングスタイルを強制するか

いいえ。このリポジトリは、変更を評価する前に類似ファイルの既存パターンを確認することを勧めています。これは導入しやすさの面で良い兆候です。ローカルな慣習とぶつかるような一般論ベースの助言が減るためです。

code-reviewer スキルを改善する方法

変更の意図を code-reviewer に渡す

もっとも効きやすい改善策は、「この変更で何を実現したいのか」を説明することです。エージェントが実装しか見えない状態だと、レビュー品質はすぐ落ちます。チケット要約、受け入れ条件、あるいは 1 段落程度の意図説明を添えて、スタイルや構文だけでなく正しさまで判断できるようにしてください。

最重要のリスク領域を絞る

認証、課金、migration、並行処理など、特に重視したい領域があるなら明示しましょう。スキル自体は複数カテゴリを見ますが、優先度を絞ることで本当に重要な箇所の深さが増します。特に PR が大きい場合、広く見てほしいとだけ伝えると浅くなりがちです。

パターン比較に足るリポジトリ文脈を渡す

このリポジトリは、既存の慣習を見ることを明確に促しています。比較対象になるファイルやモジュールを指定すると、さらに精度が上がります。

Compare the new handler to the existing patterns in src/api/users/ and src/api/sessions/.
Prefer consistency with those files unless there is a clear bug.

こうすると誤検知が減り、提案も採用しやすいものになりやすいです。

根拠のある指摘だけを求める

AI レビューでよくある失敗は、推測ベースの批判です。code-reviewer の出力を改善したいなら、次のようなルールを加えると効果があります。

Only report an issue if you can point to a specific file change, missing case, or concrete risk. Avoid hypothetical style advice unless it affects maintainability or correctness.

これで、ノイズの少ない高シグナルなレビューに寄せやすくなります。

大きなレビューは分割して回す

大規模 PR では、最初から全部を一度に求めないほうが賢明です。段階的に進めてください。

1. 正確性とセキュリティ
2. パフォーマンスと保守性
3. テストとドキュメント

これはスキルのカテゴリ構造とも一致しており、過負荷な 1 回の依頼より良い指摘が出やすいです。

修正案は「最小の安全策」で求める

最初の出力が抽象的すぎる場合は、指摘を最小限の安全な修正案に書き換えさせると実用度が上がります。

Revise the review. For each high or critical issue, suggest the smallest code change or test addition that would reduce the risk before merge.

忙しいチームでも扱いやすいレビューに変わります。

典型的な失敗パターンを把握する

code-reviewer skill の出力が弱くなる典型例は次のとおりです。

• ベースブランチが指定されていない
• diff が渡されていない
• 意図した振る舞いの説明がない
• 優先度のない巨大 PR
• プロジェクト内パターンへの参照がない
• 「全部見て」と依頼して一般論が返ってくる

これらの多くは、スキルの問題というより入力設計の問題です。

チェックリストとセキュリティ参照を明示的に使う

1 回目のレビューが広すぎると感じたら、特定のリポジトリ参照を使った 2 回目の確認を依頼してください。

• references/checklist.md で網羅性を確認する
• references/security.md でセンシティブな変更を精査する
• references/patterns.md で一貫性やアンチパターンを確認する

これは日常運用で code-reviewer guide を改善する、もっとも手軽な方法の 1 つです。

1 回目のレビュー後に再レビューする

2 回目のプロンプトとしては、次のような形が有効です。

Now re-review only the files with high-severity findings.
Assume the author wants merge-blocking issues only.
Double-check whether each finding is a real defect, a security exposure, or a missing test that hides regression risk.

この追加入力によって、価値の低いコメントが減り、最終的な推奨内容が引き締まることがよくあります。

code-reviewer をチームの運用に合わせて調整する

code-reviewer を継続利用するなら、自チームのマージ運用に合わせて整えるのが重要です。

• blocker と suggestion の境界を定義する
• ベースブランチの慣例を明示する
• テスト期待値を含める
• チーム固有のセキュリティ確認項目を追加する
• ローカルなスタイルの代表例となるファイルを示す

そうして初めて、code-reviewer install は単なるプロンプト短縮ではなく、実際のワークフロー改善として機能します。