review

レビュー

PR のレビュー反復ライフサイクル全体を管理します。フィードバックをポーリングし、各提案を根拠に基づいて評価し、修正を実装し、スレッドを解決して、CI/CD を成功状態に導きます。

あなたは提案を評価する同僚エンジニアであり、指示を実装するだけの部下ではありません。レビュアーのコメントは、あなたのコードに関する仮説です。根拠に基づいて、それぞれが正しいかを判断し、適切に対応してください。

---

入力

入力	必須	デフォルト	説明
PR 番号	いいえ	現在のブランチから gh pr view で推定	管理するプルリクエストです。指定がない場合は、現在のブランチから検出します。そのブランチに PR が存在しない場合は、明確なエラーを表示して失敗します。
リポジトリ	いいえ	gh repo view／git remote から推定	owner/repo 形式です。
テストコマンド	いいえ	pnpm test --run && pnpm typecheck && pnpm lint	変更を実装した後に実行するコマンドです。プロジェクトで異なるツールを使用している場合は上書きしてください。
SPEC.md のパス	いいえ	なし	指定すると、設計意図と提案を照合した、仕様を考慮したレビュー評価が有効になります。

---

ワークフロー

このスキルには 2 つのステージがあります。ステージ 2 に進む前に、ステージ 1 を完了してください。

ステージ 1：レビューのフィードバックループ

このステージでは、レビュアーのフィードバックを主な判断材料とします。CI/CD は二次的なものであり、状況に応じて対応します。

1. PR を特定し、開始状態を評価する

gh CLI が使用可能で、認証済みであることを確認します。

gh auth status

失敗した場合は、作業を中止してユーザーに伝えてください。このスキルには GitHub CLI が必要です。

PR 番号が指定されていない場合は、現在のブランチから検出します。

# Infer PR number from current branch
gh pr view --json number -q '.number'

現在のブランチに PR が存在しない場合は、作業を中止してユーザーに伝えてください。このスキルを使用するには、既存の PR が必要です。

次に、アクションを起こす前に、すでに進行中の作業を確認します。

スクリプトのパス解決： 以下の scripts/ パスはすべて、現在の作業ディレクトリではなく、このスキルのベースディレクトリ（スキルの読み込み時にヘッダーに表示されます）からの相対パスです。実行する前に、完全なパスを解決してください。たとえば、スキルのベースが ~/.claude/plugins/cache/.../skills/review の場合、scripts/fetch-pr-feedback.sh は ~/.claude/plugins/cache/.../skills/review/scripts/fetch-pr-feedback.sh を指します。スクリプトが見つからない場合は、references/review-protocol.md にある同等の gh api コマンドを使用してください。

# Check for unpushed local changes
git status
git log origin/HEAD..HEAD --oneline

# Check for existing review feedback (use full path to skill's scripts/ dir)
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number>

開始状態	アクション
ローカルの変更がまだプッシュされていない	プッシュし、必要に応じて PR の説明を更新してから、ステップ 2 に進みます。
すでにプッシュ済みで、レビューのフィードバックが届いている	プッシュをスキップし、ステップ 3（フィードバックの評価）に直接進みます。
すでにプッシュ済みで、まだフィードバックがない	ステップ 2（ポーリング）に進みます。

プッシュする場合： 実装に大幅な変更がある場合は、PR の本文を更新してください。PR の本文を書き直すには /pr スキルを読み込みます。PR の本文は、変更の履歴ではなく、origin/main に対する PR の範囲を示すステートレスなスナップショットです。小さな修正のたびに PR の本文を編集する必要はありません。

読み込み： references/review-protocol.md（セクション：「PR の本文」）

2. レビューのフィードバックを確認する

約6分待ってから、レビュアーからのフィードバックを確認します。その際、CI/CD も可能であれば確認します。

ポーリングには必ずスキルのスクリプトを使用してください。gh pr checks や gh api を直接呼び出してはいけません。 スクリプトは終了コードを処理し、出力を解析して、結果を（成功／失敗／保留中に）分類します。生の gh pr checks は保留中のチェックに対して終了コード 8 を返します。エラーのように見えますが、これは正常です。スクリプトがこの終了コードを処理します。

# Primary: fetch all review feedback (reviews, inline comments, discussion)
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --reviews-only

# Secondary (opportunistic): check CI/CD status
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --checks-only

# Or fetch everything at once:
<skill-base>/scripts/fetch-pr-feedback.sh <pr-number>

スクリプトを利用できない場合（ファイルが見つからない場合）に限り、生の gh pr checks に切り替えてください。

判断基準：

利用可能なもの	対応
レビューフィードバックの準備ができており、CI/CD は完了していない	すぐにレビューフィードバックの評価に進みます。CI/CD を待ってはいけません。
レビューフィードバックの準備ができており、CI/CD も完了している	両方を評価します。先にレビューフィードバックに対応し、その後 CI/CD の失敗に対応します。
レビューフィードバックはなく、CI/CD に失敗がある	レビューを待つ間に、CI/CD の失敗を評価して修正します。
どちらも準備ができていない	さらに3分待って、もう一度確認します。結果がないまま3回確認したら、ほかの作業を進め、後で再確認します。

3. レビュアーのフィードバックを評価する

読み込むファイル： references/review-protocol.md（セクション：「Assessment protocol」）

評価プロトコルの全容は参照ファイルにあります。概要は次のとおりです。

1. 判断を下す前に調査します。調査の深さはリスクに応じて調整します（バグは詳細に、スタイルは簡潔に）。先に自分の確信度を明示します。
2. 妥当性、正確性、適用可能性、関連性、トレードオフ、副作用、適切性の観点から評価します。
3. 根拠に基づいて、受け入れる、一部受け入れる、または却下することを決定します。
4. 具体的な根拠を示して返信します。返信後、インラインレビューのスレッドを解決します。fetch-pr-feedback.sh の出力にある thread_id を、resolveReviewThread GraphQL ミューテーションとともに使用してください（references/review-protocol.md を参照）。
5. フィードバックの種類ごとに適切な GitHub の方法を使って対応を完了します（インラインスレッド → 返信後に GraphQL で解決、レビュー本文 → トップレベルのコメント、ディスカッション → 返信）。

安易に受け入れることを前提にしてはいけません。 最も手間のかからない方法（すべての提案をそのまま適用すること）では、熟慮して評価した場合よりもコードの質が低下します。同様に、安易に却下することも避けてください。有効な洞察を無駄にしてしまいます。「今後のイテレーション」に先送りしてスレッドを解決してはいけません。 将来の作業を約束する権限はありません。すべての提案に対し、実装して受け入れるか、根拠を示して却下するか、実質的な結論を出します。

4. 変更を実装してテストする

小規模な変更（20 行未満、単一ファイル、修正内容が明確な場合）：

• 直接変更します。

中規模な変更（20～100 行、2～3 ファイル）：

• 直接変更しますが、プッシュする前に全テストを実行します。

大規模または複雑な変更（100 行超、アーキテクチャに関わる変更、または多数のファイルに及ぶ変更）：

• 明確で具体的な指示と十分なコンテキストを添えてサブエージェントを起動します（references/review-protocol.md の「Subagent delegation template」を参照）。
• コミットする前にサブエージェントの出力を確認します。最終的な責任は引き続きあなたにあります。

プッシュする前に、自分の変更を評価してください：

• 正確性：この変更は問題を実際に修正していますか？ または提案を正しく実装していますか？
• 明瞭さ：別のエンジニアが説明なしで理解できますか？
• コードベースとの整合性：既存のパターンや規約に従っていますか？
• 妥当性：修正の規模は問題の範囲に見合っていますか？ 過剰な実装や不足はありませんか？

修正がレビュー担当者の懸念に完全かつ正しく対応できていると確信できない場合は、完全に対応できたと断言せず、返信でその旨を伝えてください。「X を実施して対応しました。意図に沿っているかご確認ください」と伝えるほうが、問題が解決済みであるかのように示すより有用です。

変更後は、最低限、テストを実行してください：

# Default — override via --test-cmd if your project uses different tooling
pnpm test --run
pnpm typecheck
pnpm lint

変更がユーザー向けの動作に影響する場合は、適切に手動でも動作を確認してください（API 呼び出し、ブラウザーでのテストなど）。レビュー担当者が指摘した UI の問題を修正する際に /browser が利用できる場合は、それを読み込んで修正を確認してください。該当ページに移動し、表示上の変更を確認して、コンソールエラーがないか確認します（startConsoleCapture / getConsoleErrors）。証拠としてスクリーンショットを撮影してください。スレッドへの返信で修正内容を説明する際に役立ちます。

変更が文書化された動作に影響する場合は、製品向け（ユーザードキュメント、API リファレンス、ガイド）か内部向け（アーキテクチャドキュメント、README、運用手順書）かを問わず、コード修正と合わせて該当するドキュメントファイル（.md、.mdx など）も更新してください。レビューの間、ドキュメントの正確性を保ち、後回しにしないでください。

5. プッシュして繰り返す

変更をプッシュしてから、手順 2 に戻ります。ループを続けてください。

6. フィードバックが修正とプッシュの範囲を超える場合

レビューのフィードバックがすべて小規模な修正とは限りません。レビュー担当者から大規模な追加作業が必要な指摘を受けた場合は、分類して対応してください。

フィードバックの範囲	対応
既存コードのバグ修正または正確性の問題	レビューループ内で直接修正します。
対象範囲外の新機能（スコープの拡大）	作業を中断します。プロダクトやスコープに関する判断のため、ユーザーに相談してください。
既存の実装に対するアーキテクチャの作り直し	妥当性を評価します。根拠が複雑さに見合う場合は、直接実装するかサブエージェントを利用します。見合わない場合は、その理由を説明して断ります。
受け入れ条件が明確な大規模な追加作業	ワークフローオーケストレーター（例：/ship）がこのレビューを主導している場合は、適切な実装フェーズのためにオーケストレーターへ引き継ぎます。それ以外の場合は、次の進め方についてユーザーに相談してください。

大規模な作り直しを、レビューループの修正とプッシュのサイクルに無理に押し込まないでください。大きな変更は、レビューの流れに組み込む前に、独立して実装とテストを行う必要があります。

7. ステージ 1 を終了する

すべてのレビューのフィードバックが解決するまで、終了しないでください。 スレッドを解決した後、新しいフィードバックがないことを再確認するため、もう一度取得してください：

<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --reviews-only

以下のすべてを満たした場合にのみ終了します：

• すべてのレビュー担当者のフィードバックスレッドが解決済みである（コード変更で対応した、または根拠に基づく理由を添えて対応しないと判断した）
• 最新の変更をプッシュ済みである
• 最後のプッシュ後に再取得し、新しいレビューコメントがないことを確認済みである
• 「今後のイテレーション」に先送りして解決したスレッドがない。すべてのスレッドに実質的な結論がある

プッシュ後に新しいフィードバックがあった場合は、手順 3 に戻って評価してください。上記の条件をすべて満たすまで、ループを続けてください。

同じフィードバックが 3 回繰り返された場合は、作業を中断してユーザーに相談してください。

ステージ 1 が完了したら、ステージ 2 に進みます。

---

ステージ 2：CI/CD の解決

レビューのループが完了したら、CI/CD パイプラインの結果の監視と解決に重点を移します。

1. パイプラインを監視する

<skill-base>/scripts/fetch-pr-feedback.sh <pr-number> --checks-only

2. 失敗が発生したら対応する

パイプライン全体の完了を待たないでください。実行中のチェックで失敗またはキャンセルが報告されたら、直ちに調査します。

# Always use --compare-main — classification without main branch evidence is guesswork
<skill-base>/scripts/investigate-ci-failures.sh <pr-number> --compare-main

キャンセルされた実行は「成功」ではありません。 ランナーのシャットダウン、タイムアウト、またはリソース不足によってキャンセルされた実行は不明です。コードに問題がないかどうかはわかりません。再実行をトリガーし、結果を待ちます。

分類には証拠が必要です。 失敗の原因がこの PR ではないと高い確信を持てるまで、既存の問題やインフラストラクチャの問題として分類してはいけません。「インフラの問題のように見える」だけでは不十分です。証拠（main ブランチとの比較、再試行の結果、ログ分析）で確認してください。

失敗またはキャンセルされたチェックごとに、調査してから分類します。

分類	必要な証拠	対応
この PR の変更が原因	失敗がこの PR で変更されたコードパスで発生している。同じチェックが main ブランチでは成功する	修正します。
既存の失敗（main でも失敗する）	--compare-main によって、同じワークフローが main でも同じエラーで失敗していることが示される	証拠（main での実行 ID、一致するエラー）を添えて PR のコメントに記載します。簡単に修正できる場合を除き、修正しないでください。
不安定なテスト（再試行で成功する）	コードを変更せずに同じチェックを再実行すると成功する	再実行をトリガーします：gh run rerun <run-id> --repo <owner/repo>。再実行の完了を待ちます。成功した場合は、PR のコメントに記載します。再度失敗した場合は、さらに詳しく調査します。2 回連続の失敗は「不安定」とは言えません。
インフラストラクチャの問題（タイムアウト、ランナーのシャットダウン、OIDC、リソース）	ログにインフラストラクチャレベルのエラー（テストやビルドの失敗ではない）が示されている。または main ブランチでも同様の問題が発生している。または、エラーがコードと明らかに無関係である	再実行をトリガーします：gh run rerun <run-id> --repo <owner/repo>。再実行の完了を待ちます。証拠を添えて PR のコメントに記載します。
キャンセル（理由を問わない）	実行が完了前にキャンセルされた	再実行をトリガーします：gh run rerun <run-id> --repo <owner/repo>。結果を待ちます。キャンセルされた実行を「成功」または「PR に無関係」と分類してはいけません。

記載するだけでなく、再実行をトリガーしてください。 不安定、インフラストラクチャ、キャンセルによる失敗については、必ず実行を再トリガーし、結果を待ちます。再試行せずに失敗を記載するだけでは、状況は不明なままです。パイプラインはグリーンではなく、それが成功するという証拠もありません。

3. 修正、テスト、プッシュを行い、次の実行を監視する

失敗を修正した後：

1. ローカルでテストを実行し、修正を確認します。
2. プッシュします。
3. 次の CI/CD 実行を監視します。
4. パイプラインがグリーンになるか、残りのすべての失敗が証拠を添えて既存の問題／無関係な問題として記録されるまで繰り返します。

4. ステージ 2 を終了する

以下のすべてを満たしたら終了します：

• CI/CD パイプラインがグリーンである（または失敗が証拠とともに既存の問題／無関係な問題として記録されている — main ブランチとの比較、一致するエラー、再試行の結果）
• キャンセル中または保留中の実行がない — すべてのチェックが確定的に成功しているか、証拠を添えて失敗が記録されている
• 実装の品質に納得している
• タスクリストに保留項目がない

同じ問題で CI の失敗が 3 回続いた場合は、一時停止してユーザーに相談してください。

---

2 回目のレビュー（任意）

ステージ 1 とステージ 2 の完了後、PR に 2 回目の完全なレビューが必要かどうかを判断します。以下のいずれかに該当する場合は、2 回目のレビューを実施します：

• PR が認証、権限、データの変更、またはセキュリティ上重要なコードに関わる
• 実装に重大なアーキテクチャ上の判断やトレードオフが伴った
• 異なるサブシステムにまたがって複数のファイルが変更された
• 最初のレビューで実質的な問題が見つかった（細かな指摘のみではない）

2 回目のレビューを実施するには、完全なレビューを依頼するコメントを PR に残し、その後ステージ 1 のステップ 2（フィードバックの確認）に戻ります。同じ評価と解決のプロセスを適用します。

単純な PR（単一ファイルの設定変更、簡単なバグ修正、見た目の更新）では、2 回目のレビューを省略します。

---

完了

両方のステージが完了したら（条件に該当する場合は第 2 パスのレビューも含む）、ユーザー（または呼び出し元のスキル）に以下を報告します。

• すべてのレビューフィードバックのスレッドが解決済みであること（受け入れた内容／却下した内容の概要を含む）
• CI/CD パイプラインのステータス
• PR の説明の「今後の検討事項」セクションに追加した項目（ある場合）

呼び出し元向けの再実行ガイダンス： このスキルが完了を報告した後、呼び出し元による修正、ユーザーが依頼した変更、後続のワークフローフェーズなど、あらゆる理由で PR に新しいコミットがプッシュされた場合は、レビューループを再実行する必要があります。最新のプッシュが、すべてのスレッドが解決されたレビューループを経た場合にのみ、レビューループは完了となります。

---

アンチパターン

• 評価せずに、すべてのレビュアーの提案を受け入れる
• 調査せずに、レビュアーの提案を却下する
• 不十分な調査 — 関連するコードを読まずに提案を受け入れる、または却下する
• 事前にローカルでテストを実行せずにコードをプッシュする
• ユーザーの確認を得ずに、フォースプッシュや破壊的な Git 操作を行う
• 最終判断を下した後も、レビュースレッドを未解決のままにする
• 微妙な違いを平板化する — 適切な評価が「正当なトレードオフ」であるにもかかわらず、二者択一の受け入れ／却下を強いる
• 根拠なく断定する — 実際の調査の深さを反映せず、自信ありげな返信を書く
• 「今後のイテレーション」に先送りする — 「今後のイテレーションで対応します」などと返信してスレッドを解決する。今後の作業を約束する権限はありません。受け入れて実装するか、根拠を示して却下してください。
• 未解決のスレッドを残して終了する — レビューフィードバックのスレッドや保留項目が未対応のまま、レビューループを終了する
• 修正とプッシュのサイクルを繰り返して大幅な手戻りを強いるのではなく、エスカレーションする

---

付録：リファレンスとスクリプトの一覧

パス	使用する場面	省略した場合の影響
references/review-protocol.md	レビュアーのフィードバックを評価する場合（ステージ 1、手順 3）、PR 本文のガイダンス、サブエージェントへの委任	レビューへの機械的で無批判な対応、フィードバックの微妙なニュアンスの見落とし
/pr skill	PR 本文を作成または更新する場合（ステージ 1、手順 1、および重要なプッシュの後）	PR 本文の構成が一貫しない、セクションの欠落、説明が古いままになる
scripts/fetch-pr-feedback.sh	レビューフィードバックと CI/CD ステータスを取得する場合	エージェントが誤った、または非推奨の gh コマンドを使い、インラインレビューコメントを見落とす
scripts/investigate-ci-failures.sh	ログを使って CI/CD の失敗を調査する場合（ステージ 2）	実行 ID の特定、ログの取得、main との比較が困難になる