/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 オプション（ローカルレビュー）

bash

/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>
```
で有効なもの

例

bash

# 全観点レビュー（デフォルト）
/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 - 必ず出力）:

markdown

### Checklist Coverage (must-check v1.0)
| Domain | Status |
|--------|--------|
| Supabase | ✅ OK / ⚠️ 要確認 / ❌ NG / N/A |
| Pipeline | ✅ / ⚠️ / ❌ / N/A |
| Env/Secrets | ✅ / ⚠️ / ❌ / N/A |
| Tests | ✅ / ⚠️ / ❌ / N/A |
| Stripe | ✅ / ⚠️ / ❌ / N/A |

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 の断片、または該当コード引用

例:

markdown

- [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検出）:

bash

# 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#）時:

bash

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: 自動チェック（推奨）

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

bash

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

結果形式:

✅成功
❌失敗（エラー内容）
⏭️未実行（理由）

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

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

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

bash

# 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 存在確認

bash

# 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() 未導入検出

bash

# 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（必須）:

bash

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

### Summary
[2-4行の要約]

### Checklist Coverage (must-check v1.0)
| Domain | Status |
|--------|--------|
| Supabase | ✅ / ⚠️ / ❌ / N/A |
| Pipeline | ✅ / ⚠️ / ❌ / N/A |
| Env/Secrets | ✅ / ⚠️ / ❌ / N/A |
| Tests | ✅ / ⚠️ / ❌ / N/A |
| Stripe | ✅ / ⚠️ / ❌ / N/A |

### 🔴 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フェンス、ネスト禁止）:

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

code-quality-reviewer prompt

このPRのコード品質をレビューしてください。

Context:
- Stack: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
- Rules: [CLAUDE.md summary]
- PR Map: [short PR map]
- Files: [changed file list]

ppt-trans固有のチェック:
- Next.js 16: params: Promise<T> → await params
- Server Actions優先（API RoutesはWebhook/SSE/バイナリのみ）
- Schema-First開発（openapi.yaml → generate:types → 実装）
- any禁止、!禁止、@/*エイリアス必須

Output format:
Summary / Blockers / Suggestions / Nice-to-have

performance-reviewer prompt

このPRのパフォーマンスリスクをレビューしてください。

Context:
- Stack: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
- Rules: [CLAUDE.md summary]
- PR Map: [short PR map]
- Files: [changed file list]

ppt-trans固有のチェック:
- N+1クエリ、不要なSELECT
- PPTX処理の同期ブロック、プレビューキャッシュ
- Python subprocess呼び出しの効率

Output format:
Summary / Hotspots / Recommendations

security-code-reviewer prompt

このPRのセキュリティ問題をレビューしてください。

Context:
- Stack: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
- Rules: [CLAUDE.md summary]
- PR Map: [short PR map]
- Files: [changed file list]

ppt-trans固有のチェック:
- Supabase RLS有効確認、Service Role Key漏えい
- Stripe Webhook署名検証、冪等性（stripe_events）
- Rate Limiting: 認証10/15min、翻訳50/hour、アップロード20/hour

Output format:
Summary / Blockers / Findings / Follow-ups

test-coverage-reviewer prompt

このPRのテスト（unit/E2E）をレビューしてください。

Context:
- Stack: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
- Rules: [CLAUDE.md summary]
- PR Map: [short PR map]
- Files: [changed file list]

ppt-trans固有のチェック:
- UNIFIED_TEST_CONFIG参照必須（ハードコード禁止）
- 認証状態パス: .auth/user.json
- /api/auth/loginは存在しない（ナビゲーション待機を使用）

Output format:
Summary / Flaky risks / Missing scenarios / Improvements

documentation-accuracy-reviewer prompt

このPRのドキュメント整合性をレビューしてください。

Context:
- Stack: Next.js 16 + React 19 + TypeScript + Supabase + Stripe + Playwright
- Rules: [CLAUDE.md summary]
- PR Map: [short PR map]
- Files: [changed file list]

ppt-trans固有のチェック:
- .env.example / READMEのenv一覧が最新か
- Schema-First: openapi.yaml更新、generate:types実行
- CLAUDE.md / .claude/rules/ との整合

Output format:
Summary / Docs to update / Inconsistencies / Proposed edits

注意事項

Phase 2の自動チェック結果をレビュー本文に記載
- 成功/失敗/未実行を明示
Merge with follow-upsのfollow-upはIssue化前提の粒度
- 例: "RLSテスト追加", "429復帰のE2E安定化"
Inlineコメントは差分にアンカーできる時だけ
- スパム回避、top-levelコメントに集約
gh CLI前提
- ```
gh
```
  がインストール・認証されている必要あり

review

NPX Install

Tags

SKILL.md Content

/review Skill (PR Comprehensive Review)

Purpose

Invocation

引数

--focus オプション

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

例

Output Contract（必須出力）

Evidence ルール（MUST）

Guardrails

Workflow

Phase 0: 事前情報収集

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

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

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

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

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

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

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

Phase 4: PR投稿

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

Agent Prompt Templates

code-quality-reviewer prompt

performance-reviewer prompt

security-code-reviewer prompt

test-coverage-reviewer prompt

documentation-accuracy-reviewer prompt

注意事項