review

Original🇺🇸 English
Translated

Performs comprehensive PR code review from 5 perspectives (quality/performance/tests/docs/security) in parallel, providing Blockers/Suggestions/Nice-to-have and merge decision. Args: /review [owner/repo] [pr-number] [--focus all|security|perf|qa|docs|types] Activates when user mentions "review", "PR確認", "コードレビュー", "マージ判定".

1installs
Added on

NPX Install

npx skill4agent add yusuketsunoda/ppt-trans review

/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-reviewerN+1/キャッシュ/PPTX処理変更時
qa
test-coverage-reviewerテストファイル変更時
docs
documentation-accuracy-reviewerenv/README/CLAUDE.md変更時
types
code-quality-reviewer型定義/API変更時

--local オプション(ローカルレビュー)

bash
/review --local [--focus <aspect>]
PR作成前にローカルの差分をレビュー:
  • ベースブランチを自動検出(下記優先順)
  • PRコメント投稿なし(ターミナル出力のみ)
  • 全観点レビュー or
    --focus
    で限定
ベースブランチ自動検出(優先順):
  1. git symbolic-ref refs/remotes/origin/HEAD
    → default branch
  2. main
    が存在すれば
    main
  3. master
    が存在すれば
    master
  4. develop
    が存在すれば
    develop
  5. 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(必須出力)

  1. Summary(2-4行)
  2. 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 |
  3. Blockers(各: why + where + fix + Evidence
  4. Suggestions(confidence>=75 には Evidence必須
  5. Nice-to-have
  6. 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: 事前情報収集

  1. プロジェクトルール読み込み
    • CLAUDE.md
      を Read
    • 抽出項目:
      • スタック(Next.js 16, React 19, Supabase, Stripe, Playwright)
      • コーディング規約(any禁止、Server Actions優先、Schema-First)
      • セキュリティ方針(RLS、Rate Limiting、CSRF)
      • テスト方針(UNIFIED_TEST_CONFIG、MVP範囲)
  2. レビューチェックリスト読み込み
    • .claude/review-checklists/README.md
      を Read
    • .claude/review-checklists/must-check.md
      を Read
    • バージョン(例:
      v1.0
      )を記録
  3. 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>
  1. 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-reviewercode-quality-reviewerコード品質・設計・型安全
performance-reviewerperformance-reviewerパフォーマンス・N+1・キャッシュ
security-code-reviewersecurity-code-reviewerRLS・Webhook・IDOR・XSS
test-coverage-reviewertest-coverage-reviewerPlaywright決定論・モック・カバレッジ
documentation-accuracy-reviewerdocumentation-accuracy-reviewerenv・手順・文言の整合性
実装時の注意:
  • --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の処理:
  1. パース: 各reviewer出力から
    [confidence=XX]
    タグを抽出
  2. フィルタリング:
    • Blockers: 全て残す(confidence<60 は「⚠️ 要確認」ラベル)
    • Important: confidence>=70 のみ(<70 は「要確認」に降格)
    • Suggestions: confidence>=80 のみ(<80 は省略)
  3. 重複排除: 同一 file:line の指摘をマージ、最高confidence採用
  4. 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

注意事項

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