requesting-code-review

requesting-code-review スキルの概要

requesting-code-review スキルは、適切なタイミングで、適切な diff を対象に、レビュー担当エージェントが有用なフィードバックを返せるだけの実装コンテキストを添えて、焦点の定まったコードレビューを依頼するための軽量ワークフローです。単に「コードをレビューしてください」と曖昧に頼むのではなく、コミット範囲、変更内容の要約、意図した要件をセットで渡すことを前提にしている点が特徴です。

requesting-code-review スキルが実際にやること

requesting-code-review の中核は、code-reviewer.md にあるテンプレートを使って superpowers:code-reviewer サブエージェントを呼び出すことです。差別化ポイントは、凝った自動化ではなくレビューのフレーミングにあります。レビュー担当にはセッション履歴全体ではなく、作業成果物と計画が渡されるため、レビュー対象が絞られ、指摘も実際に対応しやすくなります。

requesting-code-review を導入すべき人

このスキルは、次のような開発者や AI エージェント利用者に向いています。

• コミットベースのワークフローで作業している
• 機能を段階的にリリースする
• 「先へ進む前にレビューする」チェックポイントを再現可能な形で持ちたい
• サブエージェントを使っていて、汎用プロンプトより明確な引き継ぎ方法がほしい

特に、複数のタスクが積み上がって大きな diff になってから、遅すぎるタイミングでレビューを頼みがちな場合に有効です。

実際に解決したい課題

ユーザーが requesting-code-review を入れる理由は、単に「レビューを受けるため」ではありません。避けられる手戻りを減らすためです。

• マージ前に問題を見つける
• 元の計画どおりかを検証する
• 重要度付きのフィードバックを得る
• レビュー担当エージェントにコードを別系統で見てもらいつつ、メインタスクの文脈を保つ

単なるレビュー依頼プロンプトより実用的な理由

requesting-code-review skill には、場当たり的な依頼では抜けがちな実務向けの構造があります。

• レビューのタイミング指針: 各タスク後、主要機能の実装後、マージ前
• BASE_SHA と HEAD_SHA を明示的に渡す前提
• コード品質、アーキテクチャ、テスト、要件、運用投入可否を確認するレビュー用テンプレート
• 後続対応をしやすくする重要度区分

そのため、「最新の変更をざっと見てください」よりも、はるかにアクションにつながる出力になりやすいです。

導入前に最も重要な判断ポイント

導入判断で最大の論点は相性です。このスキルが最も力を発揮するのは、作業内容をきれいな git の範囲として表せて、意図した振る舞いを簡潔に説明できるときです。ブランチが散らかっている、計画が曖昧、無関係な変更が混ざっている、といった状態ではレビュー品質は下がります。

先に知っておくべき重要な制約

requesting-code-review for Code Review は、それ単体で完結するフル機能のレビューシステムではありません。スクリプト、強制ルール、リポジトリ固有のチェッカーは含まれていません。あくまで、規律あるプロンプト設計と引き継ぎパターンです。そこに価値はありますが、レビュー品質はコミット範囲の切り方と要件の明瞭さに大きく左右される、と理解しておくべきです。

requesting-code-review スキルの使い方

skills 環境に requesting-code-review をインストールする

このリポジトリ全体で使われている Skills CLI パターンを使っている場合は、次のコマンドでインストールできます。

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

すでに環境内で obra/superpowers コレクションが利用可能なら、そのパックから requesting-code-review スキルを有効化するか参照するだけで使えます。

まず読むべきファイル

手早く見極めたいなら、まず次の 2 ファイルを確認してください。

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

SKILL.md には、どのタイミングでレビューを呼ぶべきかが書かれています。出力品質を重視するなら、より重要なのは code-reviewer.md です。レビュー担当に何を評価させるのかが、そこに具体的に示されています。

想定されている実行タイミングを理解する

このスキルは、次のタイミングで使う設計です。

• サブエージェント主導の開発で各タスクを終えた後
• 主要機能を実装した後
• main へマージする前

任意ですが、使う価値が高いタイミングとしては次もあります。

• 行き詰まっていて別視点のレビューがほしいとき
• リスクの高いリファクタリング前
• 複雑なバグ修正の後

大きなブランチの最後に一度だけ使う運用だと、このスキルの利点をかなり失います。

呼び出し前に最低限そろえるべき入力

このスキルは、次の情報を渡したときに最も機能します。

• 何を実装したか
• 計画または要件
• BASE_SHA
• HEAD_SHA
• 変更の簡潔な説明

よく使う git コマンドは以下です。

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

feature branch では、より広いレビュー範囲を見たいなら HEAD~1 より origin/main をベースにしたほうが適切な場合があります。

曖昧な「最新の作業」ではなく、きれいな diff 範囲を使う

ここが requesting-code-review usage パターンの中で最も効果が大きいポイントです。BASE_SHA..HEAD_SHA に結び付いたレビューは、作業ツリーや会話履歴から「何が変わったか」をエージェントに推測させるより、はるかに精度が上がります。

良い例:

• 「signup フロー要件に照らして、feature 開始時点から current head までのコミットをレビューしてください。」

弱い例:

• 「最近の auth 変更をレビューしてくれる？」

前者は対象範囲が明確で、レビュー担当の推測に頼る部分が減ります。

ざっくりした依頼を、強いレビュー依頼に変える

次のような依頼は情報が薄すぎます。

Please review my new feature.

スキルの想定に沿った、より強い依頼はこうです。

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

これならレビュー担当は、スタイルだけでなく、実装の正しさまで判断できます。

スキルが想定する形で reviewer サブエージェントを呼び出す

リポジトリ上の案内では、Task ツールで superpowers:code-reviewer タイプを使い、code-reviewer.md のテンプレートを埋めるよう求めています。このテンプレートでは、レビュー担当に次のことを依頼します。

• 実装と計画を比較する
• git diff を確認する
• 品質、アーキテクチャ、テスト、運用投入可否をチェックする
• 重要度ごとに所見を返す

エージェント基盤がサブエージェントに対応しているなら、実装作業中の会話に混ぜず、レビューを独立して走らせたほうが効果的です。

reviewer テンプレートが特に見つけやすいもの

組み込みのチェックリストが強いのは、主に次の論点です。

• 要件の取りこぼし
• 明らかな運用投入上の抜け
• テストカバレッジの問題
• アーキテクチャ上の懸念
• 危険なエッジケース
• 後方互換性や移行手順の漏れ

一方で、ドメイン固有のコンプライアンス、リポジトリ固有の慣習、深い実行時検証などは、明示的に足さない限り得意分野ではありません。

実案件でのおすすめ workflow

実践的な requesting-code-review guide は、たとえば次の流れです。

1. ひとまとまりのタスクを完了する
2. 正確な diff 範囲を特定する
3. 意図と受け入れ条件を要約する
4. テンプレート付きで reviewer を呼び出す
5. critical と important の指摘を修正する
6. 修正が大きければ再度レビューを回す
7. 開発を続けるかマージする

このスキルは、最終ゲートとしてだけではなく、実装ステップの合間に置くチェックポイントとして使うと最も効果的です。

出力品質を目に見えて改善するコツ

レビュー結果を良くしたいなら、次を意識してください。

• 1 つの論理的変更に収まる diff 範囲を使う
• 機能名だけでなく受け入れ条件も添える
• migration、auth、concurrency、caching、API contracts のような高リスク領域を明記する
• テストを追加したか、どの種類のテストかを書く
• breaking changes が想定内か禁止かを伝える

こうした情報があると、レビュー担当は意図したトレードオフと単なる見落としを区別しやすくなります。

価値を下げがちなよくある誤用

次のようなチーム運用なら、requesting-code-review install の判断はやや慎重に考えるべきです。

• 無関係な変更を 1 つの範囲にまとめてコミットする
• 書かれた要件がない
• git 上の意味ある区切りを使っていない
• このスキルに human approval や CI の代替を期待している

こうした場合は、先にワークフローを整えるか、レビュー結果がノイジーになりやすいことを織り込んでおく必要があります。

requesting-code-review スキル FAQ

requesting-code-review は初心者にも向いていますか？

はい。ただし、コミットや SHA といった基本的な git の概念を理解していることが前提です。スキル自体はシンプルですが、「何が変わったのか」「本来どうあるべきか」を定義できることを求めます。そこを省く初心者でもフィードバック自体は得られますが、信頼性は下がります。

このスキルは未コミットの変更もレビューできますか？

設計上はその用途ではありません。ワークフローは BASE_SHA と HEAD_SHA を軸にしているため、コミット済みの作業に対して最も強く機能します。staged / unstaged や未コミット変更に流用することはできますが、それはスキル本来の構造から外れるため、再現性が落ち、レビュー品質も下がりやすくなります。

AI に普通にコードレビューを頼むのと、requesting-code-review は何が違いますか？

通常のプロンプトだと、モデル側が対象範囲、意図、受け入れ条件を推測しなければならず、汎用的なレビューになりがちです。requesting-code-review は次を必須にすることで、そこを改善します。

• 明示的な diff
• 実装内容の明確な要約
• 元の計画または要件
• 重要度ベースの出力形式

その結果、出力は信頼しやすく、次のアクションにも移しやすくなります。

requesting-code-review を使わないほうがよいのはどんなときですか？

次の状況では見送ったほうがよいです。

• 変更がまだ評価できる完成度に達していない
• diff に無関係な複数機能が混ざっている
• 期待する振る舞いがまだ定まっていない
• 判断型レビューより、リポジトリ固有の static checks のほうが必要

また、チームがそもそも git のコミット範囲を単位に作業しないなら、相性は良くありません。

human code review の代わりになりますか？

なりません。最適な使い方は、事前レビューやステップ間の品質ゲートです。早い段階で問題を拾い、その後の人間によるレビューをスムーズにする効果はありますが、ドメイン知識、チーム規約、組織上の承認要件を置き換えるものではありません。

requesting-code-review は大きな機能にしか向いていませんか？

いいえ。むしろ小さな diff でこそ真価を発揮します。このスキルは、最後に大きくまとめて見るより、早く・頻繁にレビューすることを明確に勧めています。そのほうが実際には効果的なことが多いです。

どんなエコシステムとの相性を想定すべきですか？

このスキルは obra/superpowers のワークフロー内で最も自然に機能し、とくにサブエージェントをすでに使っている場合に相性が良いです。フル機能のレビュー基盤より軽く、独自のレビュー自動化を組むより導入しやすい反面、ガードレールは少なめです。

requesting-code-review スキルを改善するには

コードより先に、reviewer に渡す要件を良くする

最も多い失敗パターンは、計画コンテキストが弱いことです。たとえば「notifications を実装した」とだけ伝えても、retry path がないのがバグなのか、スコープ外なのかをレビュー担当は判断できません。次のような具体的期待値を足してください。

• 発火条件
• エラー時の振る舞い
• 後方互換性の期待
• パフォーマンスやセキュリティ要件

要件の質が上がれば、レビュー判断の質も上がります。

意味のある最小単位でレビューする

requesting-code-review skill は、単一タスクか、密接に関連した変更セットに対して最も性能を発揮します。schema 変更、API 変更、UI 更新、無関係な cleanup が 1 つの diff に入っていると、指摘は広く浅くなり、実行可能性が下がります。できる限り、レビュー可能な単位に分割してください。

ベースコミットを正しく選ぶ

不適切な BASE_SHA は、誤解を招くフィードバックにつながります。feature が 6 コミットにまたがるのに HEAD~1 を使えば、レビュー担当には見える範囲が狭すぎます。逆に古すぎるベースを使うと、ノイズが増えすぎます。評価してほしい作業単位に合うベースを選んでください。

reviewer が頭の中で検証できるよう、プレースホルダーを具体化する

テンプレートには、次のようなプレースホルダーがあります。

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

変更にリスクがあるなら、これらを 1 行要約で埋めて済ませないでください。期待する実際の振る舞いまで書くべきです。たとえば「added password reset」より、「prevents user enumeration and invalidates token after first successful reset」のほうが、はるかに強い情報になります。

リスクがある箇所を reviewer に伝える

リスクの高い面が分かっているなら、明示してください。

• 「Please pay special attention to race conditions around token reuse.」
• 「Check backward compatibility for existing API consumers.」
• 「Focus on whether tests cover the error path and expiry boundary.」

見るべき場所を絞ることで、有益な指摘が返る確率が上がります。

1 回目のレビュー後に、レビュー自体を強化する

最初の出力を受けたら、次の流れを取ると効果的です。

1. 明らかに正しい critical issues を修正する
2. 誤っていそうな指摘には異議を出す
3. 足りない要件を補足する
4. 変更が大きいなら、更新後の diff でもう一度レビューする

このスキル自体、reviewer が間違っているときは押し返してよいという前提です。これは良い設計です。判断を支援するものであって、判断そのものを置き換えるものではありません。

必要に応じて、リポジトリ固有のレビュー観点を追加する

標準の code-reviewer.md は、一般的なレビュー観点をかなりうまくカバーしていますが、多くのチームではそれだけでは足りません。requesting-code-review for Code Review を改善するなら、次のようなプロジェクト固有チェックを追加するのが有効です。

• migration rollout rules
• observability requirements
• accessibility expectations
• security review points
• language or framework conventions

出力を汎用論から一段引き上げたいなら、ここが最も効果の大きい改善ポイントです。

繰り返し起きやすい失敗パターンに注意する

品質低下の原因として多いのは、次のようなものです。

• 要件がない、または曖昧
• コミット範囲がノイジー
• 非機能要件への言及がない
• タスクを溜めすぎてからレビューしている
• 軽微な提案を必須扱いする一方で、重大な設計問題を見落としている

出力が浅いと感じたら、まず入力条件を見直してください。

欠陥の指摘だけでなく、判断も求めることで出力を改善する

より強い requesting-code-review usage パターンは、不具合指摘だけでなく、トレードオフの妥当性もレビュー担当に評価させることです。たとえば次のように頼めます。

• 「Flag any unnecessary complexity.」
• 「Call out if this should be split before merge.」
• 「Assess whether current tests justify production readiness.」

こうした依頼を加えると、lint 的なコメントに留まらず、リリース可否に近い評価へとレビューの質が上がります。

自分の環境でこのスキルを育てる実践的な進め方

このスキルを本格的に使うなら、まず次の 3 点を自分たち向けに決めるのがおすすめです。

1. ベースコミットの選び方の標準ルール
2. 要件と受け入れ条件の標準フォーマット
3. 利用技術スタックとリリース手順に合わせた追加チェック項目

これらを足しても requesting-code-review のシンプルさは保てますし、日々の開発での実用性は大きく上がります。