Skills
skills/yusuketsunoda/ppt-trans/review

review

SKILL.md

/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 で限定

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

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

例

# 全観点レビュー（デフォルト）
/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 - 必ず出力）: 
    ### 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 の断片、または該当コード引用

例:

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

# 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>
  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-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の処理:

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

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

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

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

  1. Phase 0 を最初に実行: CLAUDE.md読み込み → チェックリスト読み込み → PR情報取得
  2. --focus に応じてエージェント選択: all なら全5エージェント並列、限定なら該当のみ
  3. Agent Prompt Templates を参照: references/agent-prompts.md からプロンプトを取得
  4. Phase 2.5 Security Gates を実行: PR差分に含まれるファイルに対して3本のgrepチェック
  5. review-aggregator で統合: confidence フィルタリング → 重複排除 → Merge Decision
  6. 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 をスキップしない（プロジェクトルールの理解が品質に直結）

注意事項

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

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

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

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

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

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

  4. gh CLI前提

    • ghがインストール・認証されている必要あり
Weekly Installs
30
Repository
yusuketsunoda/ppt-trans
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
opencode30
codex30
gemini-cli30
continue29
cursor29
antigravity29