/review Skill (PR Comprehensive Review)

Purpose

Next.js 16 + Supabase + Stripe + Playwright コードベースのPRを包括レビューし、 マージ可否を判定する。

Invocation

/review [owner/repo] [pr-number] [--focus <aspect>] /review --local [--focus <aspect>]

引数

引数 必須 説明

owner/repo

Yes* GitHubリポジトリ（例: my-org/ppt-trans ）

pr-number

Yes* PRの番号

--local

No ローカルの差分をレビュー（PR作成前のセルフレビュー用）

--focus

No 実行するレビュー観点を限定（デフォルト: all ）

*--local 指定時は owner/repo と pr-number は不要

--focus オプション

値 実行されるエージェント ユースケース

all

全5エージェント 通常のPRレビュー（デフォルト）

security

security-code-reviewer 認証/認可/Stripe変更時

perf

performance-reviewer N+1/キャッシュ/PPTX処理変更時

qa

test-coverage-reviewer テストファイル変更時

docs

documentation-accuracy-reviewer env/README/CLAUDE.md変更時

types

code-quality-reviewer 型定義/API変更時

--local オプション（ローカルレビュー）

/review --local [--focus <aspect>]

PR作成前にローカルの差分をレビュー:

• ベースブランチを自動検出（下記優先順）

• PRコメント投稿なし（ターミナル出力のみ）

• 全観点レビュー or --focus で限定

ベースブランチ自動検出（優先順）:

• git symbolic-ref refs/remotes/origin/HEAD → default branch

• main が存在すれば main

• master が存在すれば master

• develop が存在すれば develop

• git merge-base HEAD <candidate> で有効なもの

例

全観点レビュー（デフォルト）

/review my-org/ppt-trans 123

セキュリティのみ

/review my-org/ppt-trans 123 --focus security

パフォーマンスのみ

/review my-org/ppt-trans 123 --focus perf

ローカル差分の全観点レビュー

/review --local

ローカル差分のセキュリティレビューのみ

/review --local --focus security

Output Contract（必須出力）

• Summary（2-4行）

• Checklist Coverage（MUST - 必ず出力）:

Checklist Coverage (must-check v1.0)

• Blockers（各: why + where + fix + Evidence）

• Suggestions（confidence>=75 には Evidence必須）

• Nice-to-have

• Merge decision:

• ✅ Merge

• ⚠️ Merge with follow-ups（follow-up一覧）

• ❌ Needs changes（blockers一覧）

Evidence ルール（MUST）

confidence >= 75 の指摘には必ず Evidence を付与:

• ファイルパス + 行番号

• 加えて grep/diff の断片、または該当コード引用

例:

• [confidence=85] RLS policy が無い (supabase/migrations/xxx.sql:15) Evidence: grep -n "CREATE POLICY" supabase/migrations/xxx.sql → 結果なし

Guardrails

• 秘密情報（env値、keys、tokens）をログ/コメントに出さない

• Blockersは「実際にバグ/脆弱性/データ損失/課金エラー/flaky CI」を引き起こすものに限定

• 大規模リファクタはfollow-up issueとして提案

Workflow

Phase 0: 事前情報収集

プロジェクトルール読み込み

• CLAUDE.md を Read

• 抽出項目:

• スタック（Next.js 16, React 19, Supabase, Stripe, Playwright）

• コーディング規約（any禁止、Server Actions優先、Schema-First）

• セキュリティ方針（RLS、Rate Limiting、CSRF）

• テスト方針（UNIFIED_TEST_CONFIG、MVP範囲）

レビューチェックリスト読み込み

• .claude/review-checklists/README.md を Read

• .claude/review-checklists/must-check.md を Read

• バージョン（例: v1.0 ）を記録

PR情報取得

--local オプション時（堅牢なBASE検出）:

0) 事前 fetch（失敗しても続行）

git fetch origin --prune --tags >/dev/null 2>&1 || true

ベースブランチ自動検出（ループ式で安全に）

BASE=""

1) origin/HEAD から default branch を取得

if git symbolic-ref -q refs/remotes/origin/HEAD >/dev/null 2>&1; then BASE="$(git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||')" fi

2) fallback candidates（main → master → develop）

if [ -z "$BASE" ]; then for b in main master develop; do if git show-ref -q "refs/remotes/origin/$b"; then BASE="$b" break fi done fi

3) last resort

[ -z "$BASE" ] && BASE="main"

echo "Base branch: $BASE"

4) 対象ファイル列を先に確定（レビュー負荷軽減）

CHANGED_FILES=$(git diff --name-only "origin/$BASE...HEAD") echo "Changed files:" echo "$CHANGED_FILES"

5) 領域判定（docs/ だけなら security/perf を N/A に寄せる等）

if echo "$CHANGED_FILES" | grep -qv '^docs/'; then

コード変更あり → 全観点レビュー

git diff "origin/$BASE...HEAD" else

docs/ のみ → documentation 観点のみ

echo "Docs-only change detected, focusing on documentation review" fi

通常（owner/repo PR#）時:

gh pr view <PR_NUMBER> --repo <REPO> --json title,body,author,labels,files,additions,deletions,url gh pr diff <PR_NUMBER> --repo <REPO>

• PR要約作成

• 変更目的（1-2行）

• 影響範囲（UI/API/DB/Billing/Auth/PPTX/E2E）

• リスクフラグ（スキーマ変更、認証変更、課金変更、ファイル処理）

Phase 1: エージェント並列実行

--focus オプションに応じてエージェントを選択:

--focus 実行エージェント

all （デフォルト） 全5エージェント並列

security

security-code-reviewer のみ

perf

performance-reviewer のみ

qa

test-coverage-reviewer のみ

docs

documentation-accuracy-reviewer のみ

types

code-quality-reviewer のみ

全エージェント一覧:

エージェント subagent_type 責務

code-quality-reviewer code-quality-reviewer コード品質・設計・型安全

performance-reviewer performance-reviewer パフォーマンス・N+1・キャッシュ

security-code-reviewer security-code-reviewer RLS・Webhook・IDOR・XSS

test-coverage-reviewer test-coverage-reviewer Playwright決定論・モック・カバレッジ

documentation-accuracy-reviewer documentation-accuracy-reviewer env・手順・文言の整合性

実装時の注意:

• --focus all または未指定の場合、全5エージェントを 並列で Task実行

• --focus <aspect> 指定時、該当エージェントのみ実行

各エージェントへのプロンプト共通部分:

コンテキスト

• スタック: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
• プロジェクトルール: [CLAUDE.md要約]
• PR要約: [Phase 0の要約]
• 変更ファイル: [ファイル一覧]

重点チェック（ppt-trans固有）

• Next.js 16: params: Promise<T> の正しい実装
• Server Actions vs API Routes の使い分け
• Schema-First開発（openapi.yaml先行）
• Supabase RLS、snake_case型、型再生成
• E2E: UNIFIED_TEST_CONFIG参照、ハードコード禁止

Phase 2: 自動チェック（推奨）

実行可能なら以下を実行し、結果をレビュー本文に記載:

npm run type-check # 型チェック npm run lint # リント npm run test # 影響範囲のテスト

結果形式:

• ✅成功

• ❌失敗（エラー内容）

• ⏭️未実行（理由）

Phase 2.5: セキュリティゲート自動検出（3本）

PR差分に含まれるファイルに対して以下を自動実行する。grepベースで検出可能なもののみ。

Gate 1: performSecurityChecks() 呼び出し漏れ

PR差分のAPI Routeファイルで performSecurityChecks を呼んでいないものを検出

allowlist: webhook(自前署名検証), health, test endpoints

for f in $(git diff --name-only "origin/$BASE...HEAD" | grep 'src/app/api/./route.ts'); do if ! grep -q "performSecurityChecks" "$f"; then basename_dir=$(dirname "$f" | sed 's|src/app/api/||') # allowlist check case "$basename_dir" in stripe/webhook|health|test/) continue ;; *) echo "MISSING performSecurityChecks: $f" ;; esac fi done

出力: 漏れがあれば Blocker として報告（confidence=90）

Gate 2: 新テーブル RLS policy 存在確認

PR差分のマイグレーションで CREATE TABLE があるのに CREATE POLICY がないものを検出

for f in $(git diff --name-only "origin/$BASE...HEAD" | grep 'supabase/migrations/.*.sql'); do tables=$(grep -oP 'CREATE TABLE (?:IF NOT EXISTS )?(?:public.)?\K\w+' "$f" 2>/dev/null) for t in $tables; do if ! grep -q "CREATE POLICY.ON.$t" "$f"; then echo "MISSING RLS: table=$t in $f" fi done done

出力: 漏れがあれば Blocker として報告（confidence=95）

Gate 3: SecurityMonitor.logEvent() 未導入検出

PR差分でセキュリティ関連コードパス(reject/error/401/403)があるのにlogEventがないファイルを検出

for f in $(git diff --name-only "origin/$BASE...HEAD" | grep -E '.(ts|tsx)$'); do

セキュリティ判定コード(403/401返却, reject, unauthorized)を含むか

if grep -qE '(status.*40[13]|"unauthorized"|"forbidden"|rejectWith|createErrorResponse.*40)' "$f"; then if ! grep -q "logEvent|SecurityMonitor" "$f"; then echo "MISSING SecurityMonitor: $f" fi fi done

出力: 漏れがあれば Suggestion として報告（confidence=75）

Phase 3: フィードバック統合（review-aggregator使用）

review-aggregator エージェント（.claude/agents/review-aggregator.md ）を呼び出し、 各reviewerの出力を統合する。

aggregatorの処理:

• パース: 各reviewer出力から [confidence=XX] タグを抽出

• フィルタリング:

• Blockers: 全て残す（confidence<60 は「⚠️ 要確認」ラベル）

• Important: confidence>=70 のみ（<70 は「要確認」に降格）

• Suggestions: confidence>=80 のみ（<80 は省略）

• 重複排除: 同一 file:line の指摘をマージ、最高confidence採用

• Merge Decision判定:

• Blockers 0件 → ✅ Merge

• Blockers 全て「要確認」かつ<=2件 → ⚠️ Merge with follow-ups

• Blockers に confidence>=60 が1件以上 → ❌ Needs changes

入力フォーマット: 各reviewerは統一フォーマットで出力（.claude/docs/reviewer-output-format.md 参照）

Phase 4: PR投稿

Top-level comment（必須）:

gh pr comment <PR_NUMBER> --repo <REPO> --body "$(cat <<'EOF'

Code Review Summary

Summary

[2-4行の要約]

Checklist Coverage (must-check v1.0)

🔴 Blockers

• [なければ「なし」]

🟡 Suggestions

• [confidence>=75 には Evidence 必須]

🟢 Nice-to-have

• [箇条書き]

Automated Checks

• Type check: [✅/❌/⏭️]
• Lint: [✅/❌/⏭️]
• Tests: [✅/❌/⏭️]

Merge Decision

[✅/⚠️/❌ + 理由]

🤖 Reviewed by Claude Code (5-domain parallel review) EOF )"

Inline comment（選択的）:

• 特定ファイル・行に明確にアンカーできる場合のみ

• スパム回避のため最小限に

機械処理可能な出力（末尾YAMLブロック）

レビュー結果の末尾に以下のYAMLブロックを必ず追加（1個だけのYAMLフェンス、ネスト禁止）:

review_meta: checklist_version: "v1.0" domains_ran: ["code-quality","security","performance","test-coverage","documentation"] blockers_count: 0 important_count: 2 suggestions_count: 5 confidence_max: 85 merge_decision: "merge" # merge | merge_with_followups | needs_changes

フッター:

🤖 Reviewed by Claude Code (ppt-trans 5-domain review)

--local オプション時:

• PRコメント投稿なし（ターミナル出力のみ）

• review_output.md ファイルへの保存も可能（GitHub Actions用）

Agent Prompt Templates

各エージェントのプロンプトテンプレートは references/agent-prompts.md を参照。

AI Assistant Instructions

このスキルが有効化された時:

• Phase 0 を最初に実行: CLAUDE.md読み込み → チェックリスト読み込み → PR情報取得

• --focus に応じてエージェント選択: all なら全5エージェント並列、限定なら該当のみ

• Agent Prompt Templates を参照: references/agent-prompts.md からプロンプトを取得

• Phase 2.5 Security Gates を実行: PR差分に含まれるファイルに対して3本のgrepチェック

• review-aggregator で統合: confidence フィルタリング → 重複排除 → Merge Decision

• Output Contract に厳密に従う: Summary, Checklist, Blockers, Suggestions, Nice-to-have, Merge Decision

Always:

• Blockers には Evidence（file:line + コード引用）を必ず付与する

• confidence>=75 の Suggestions にも Evidence 必須

• review_meta YAMLブロックを末尾に必ず追加する

• --local 時はPRコメント投稿せずターミナル出力のみ

Never:

• 秘密情報（env値、keys、tokens）をログ/コメントに出さない

• Blockers を「念のため」で追加しない（実際のバグ/脆弱性/データ損失に限定）

• Phase 0 をスキップしない（プロジェクトルールの理解が品質に直結）

注意事項

Phase 2の自動チェック結果をレビュー本文に記載

• 成功/失敗/未実行を明示

Merge with follow-upsのfollow-upはIssue化前提の粒度

• 例: "RLSテスト追加", "429復帰のE2E安定化"

Inlineコメントは差分にアンカーできる時だけ

• スパム回避、top-levelコメントに集約

gh CLI前提

• gh がインストール・認証されている必要あり