sfra-review

# SFRA Best Practices Review スキル SFCC/SFRA コードベースのベストプラクティスレビューを実行する。**Swarm パターン**（並列エージェント実行）で網羅的な分析を行い、P0/P1/P2 の重大度付きレビューレポートを生成。 ## 概要 | 項目 | 内容 | |------|------| | **対象** | SFRA Storefront + Jobs（app_storefront_base + overlay cartridges） | | **除外** | Headless/SCAPI/PWA Kit の実装レビュー（別スキルで対応）。SCAPI 移行**準備度**チェックは含む | | **出力形式** | Markdown レビューレポート（P0/P1/P2 重大度付き） | | **中間成果物** | `docs/review/.work/` に保存 | | **最終成果物** | `docs/review/sfra-review.md` | ## アーキテクチャ ``` ┌─────────────────────────────────────────────────────────────────┐ │ Orchestrator (SKILL.md) │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Phase 0: Scope Detection │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ - Cartridge 構成検出（app_storefront_base, plugin_, int_） ││ │ │ - Sites/Locales 検出 ││ │ │ - 対象ファイル数/LOC 算出 ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ │ │ Phase 1: Indexer (sequential) │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ Controllers/Routes マップ、ISML 一覧、Services 定義、 ││ │ │ Hooks/Jobs 一覧、Model 一覧を "地図" として生成 ││ │ └─────────────────────────────────────────────────────────────┘│ │ │ │ │ Phase 2: Explorer Swarm (並列 - 7 agents) │ │ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ │ │controller│ model │ isml │ client │ service │cartridge│ jobs │ │ │ (sonnet) │ (opus) │(sonnet) │(sonnet) │ (opus) │(sonnet) │(sonnet) │ │ └────┬─────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┘ │ └──────────┴─────────┼─────────┴─────────┴─────────┴─────────┘│ │ ▼ │ │ Aggregator (opus) │ │ Two-step Reduce │ │ │ │ │ Phase 3: Reviewer Swarm (並列 - 4 agents) │ │ ┌─────────┬─────────┬─────────┬─────────┐ │ │ │perform. │security │ best- │ anti- │ │ │ │ (haiku) │ (opus) │practice │ pattern │ │ │ │ │ │ (haiku) │ (haiku) │ │ │ └────┬────┴────┬────┴────┬────┴────┬────┘ │ │ └─────────┴─────────┼─────────┘ │ │ ▼ │ │ Aggregator (opus) │ │ 統合レビュー + Gate 判定 │ │ │ │ │ Phase 4: Reporter (sonnet) │ │ ▼ │ │ sfra-review.md │ └─────────────────────────────────────────────────────────────────┘ ``` ## ワークフロー ### Phase 0: スコープ検出 **目的**: レビュー対象の Cartridge 構成と規模を把握 **手順**: 1. プロジェクトルートで cartridge 構成を検出 2. `cartridge` ディレクトリ配下の構造を分析 3. 対象ファイル数と LOC を算出 **検出項目**: ```yaml scope: cartridges: - name: "app_storefront_base" type: "base" path: "cartridges/app_storefront_base" - name: "app_custom_mystore" type: "overlay" path: "cartridges/app_custom_mystore" - name: "int_payment" type: "integration" path: "cartridges/int_payment" stats: total_files: 450 total_loc: 25000 controllers: 35 models: 28 templates: 120 jobs: 8 ``` **出力**: `docs/review/.work/00_scope.json` **Done 条件**: cartridge 構成が検出され、stats が算出されている --- ### Phase 1: Indexer（コードベース地図作成） **目的**: レビュー対象のコードベース全体像を "地図" として可視化 **入力**: Phase 0 の scope 情報 **手順**: 1. Task ツールで `sfra-indexer` エージェントを起動（model: sonnet） 2. Controllers/Routes のマッピング 3. Models/Decorators の一覧化 4. ISML テンプレートの依存関係 5. Services/Hooks の定義収集 6. Jobs の一覧化 **出力**: `docs/review/.work/01_index.md` **出力形式**: ```markdown # SFRA Codebase Index ## Controllers (35 files) | Controller | Routes | Middleware | Cartridge | |------------|--------|------------|-----------| | Account.js | Login, Register, ... | auth, csrf | app_custom | ## Models (28 files) | Model | Decorators | Used By | |-------|------------|---------| | ProductModel.js | base, full | PDP, PLP | ## ISML Templates (120 files) | Template | Includes | Remote Includes | |----------|----------|-----------------| | pdpMain.isml | productCard, reviews | recommendations | ## Services (12 definitions) | Service ID | Type | Timeout | Retry | |------------|------|---------|-------| | payment.authorize | HTTP | 30s | 3 | ## Jobs (8 definitions) | Job ID | Steps | Schedule | |--------|-------|----------| | ProductSync | 3 | Daily 2AM | ``` **Done 条件**: 全カテゴリの index が生成されている --- ### Phase 2: Explorer Swarm（コード分析） **目的**: 各レイヤーを専門エージェントが並列で分析 **入力**: Phase 1 の index 情報 **手順**: 1. **並列実行**: 7 つの Explorer エージェントを Task ツールで同時起動 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 並列実行（単一メッセージで複数 Task tool 呼び出し） │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Task(sfra-explorer-controller, model: sonnet) ──┐ │ │ Task(sfra-explorer-model, model: opus) ──┼─→ 並列 │ │ Task(sfra-explorer-isml, model: sonnet) ──┤ │ │ Task(sfra-explorer-client, model: sonnet) ──┤ │ │ Task(sfra-explorer-service, model: opus) ──┤ │ │ Task(sfra-explorer-cartridge, model: sonnet) ──┤ │ │ Task(sfra-explorer-jobs, model: sonnet) ──┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` 2. 各エージェントは担当範囲のみを分析し、ハンドオフ封筒形式で出力 3. **Aggregator 呼び出し**: Two-step Reduce で統合 - Step 1: JSON 正規化（各エージェントの findings をマージ） - Step 2: Adjudication Pass（矛盾解消、重複排除） **Explorer エージェント一覧**: | Agent | Model | 担当範囲 | |-------|-------|----------| | explorer-controller | sonnet | Controllers, Routes, Middleware | | explorer-model | opus | Models, Decorators, Transactions | | explorer-isml | sonnet | Templates, Resource Bundles | | explorer-client | sonnet | Client-side JS, CSS | | explorer-service | opus | Services, External Integrations | | explorer-cartridge | sonnet | Architecture, Layering | | explorer-jobs | sonnet | Jobs, Batch Processing | **出力**: - `docs/review/.work/02_explorer/*.md`（各エージェントの生出力） - `docs/review/.work/03_explorer_unified.md`（統合済み分析） **Done 条件**: - 7 エージェントすべてが status: ok で完了 - explorer_unified.md が生成されている --- ### Phase 3: Reviewer Swarm（品質レビュー） **目的**: Cross-cutting concerns を専門エージェントが並列でレビュー **入力**: Phase 2 の統合分析結果 **手順**: 1. **並列実行**: 4 つの Reviewer エージェントを Task ツールで同時起動 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 並列実行（単一メッセージで複数 Task tool 呼び出し） │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Task(sfra-reviewer-performance, model: haiku) ──┐ │ │ Task(sfra-reviewer-security, model: opus) ──┼─→ 並列 │ │ Task(sfra-reviewer-bestpractice, model: haiku) ──┤ │ │ Task(sfra-reviewer-antipattern, model: haiku) ──┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` 2. 各 Reviewer は P0/P1/P2 の重大度付きで指摘事項を出力 3. **Aggregator 呼び出し**: 指摘の統合と Gate 判定 **Reviewer エージェント一覧**: | Agent | Model | 担当範囲 | |-------|-------|----------| | reviewer-performance | haiku | Caching, require scope, API calls | | reviewer-security | opus | XSS, CSRF, Input validation, PII | | reviewer-bestpractice | haiku | SFRA guidelines, patterns | | reviewer-antipattern | haiku | Known anti-patterns detection | **出力**: - `docs/review/.work/04_reviewer/*.md`（各エージェントの生出力） - `docs/review/.work/05_review_unified.md`（統合済みレビュー） **Done 条件**: - 4 エージェントすべてが status: ok で完了 - Gate 判定が実行されている --- ### Phase 4: Reporter（レポート生成） **目的**: 最終レビューレポートを生成 **入力**: Phase 3 の統合レビュー結果 **手順**: 1. Task ツールで `sfra-reporter` エージェントを起動（model: sonnet） 2. テンプレートに基づいてレポート生成 3. Executive Summary 作成 4. カテゴリ別 Findings 整理 5. Recommendations 作成 **出力**: `docs/review/sfra-review.md` **Done 条件**: レポートが生成され、P0/P1/P2 のサマリーが含まれている --- ## Gate 判定ロジック ### P0 (Blocker) - 1 つで FAIL | Category | Trigger | |----------|---------| | Security | XSS 脆弱性、PII ログ出力、CSRF 未対策 | | Transaction | Transaction 境界外の書き込み | | Architecture | app_storefront_base 直接編集 | | Performance | グローバル require が 10 箇所以上 | ### P1 (Major) - 2 つ以上で FAIL | Category | Trigger | |----------|---------| | Controller | server.append() での ViewData 変更 | | ISML | isscript 内 business logic 5 箇所以上 | | Service | タイムアウト/リトライ未設定 | | Cartridge | Naming collision 検出 | | Jobs | 冪等性未保証、Transaction 境界違反 | ### P2 (Minor) - 要対応リスト | Category | Trigger | |----------|---------| | Performance | キャッシュ未活用 | | Code Quality | Magic numbers | | Best Practice | 軽微なガイドライン違反 | ### Gate 判定結果 ```yaml gate_decision: p0_count: 0 p1_count: 3 p2_count: 12 result: "PASS" # P0=0 かつ P1<2 なら PASS overall_status: "REVIEW_NEEDED" # P1>0 または P2>5 なら要レビュー ``` --- ## エージェント呼び出しパターン ### Phase 2 Explorer Swarm 呼び出し例 ```markdown 7 つの Explorer エージェントを並列で起動する。 単一のメッセージ内で複数の Task tool を呼び出す。 Task( description: "Analyze SFRA controllers", prompt: "Index ファイル (.work/01_index.md) を読み、 Controllers/Routes/Middleware を分析して ベストプラクティス違反を検出せよ。 出力: .work/02_explorer/controller.md", subagent_type: "sfra-explorer-controller", model: "sonnet" ) Task( description: "Analyze SFRA models", prompt: "Index ファイル (.work/01_index.md) を読み、 Models/Decorators/Transactions を分析して ベストプラクティス違反を検出せよ。 出力: .work/02_explorer/model.md", subagent_type: "sfra-explorer-model", model: "opus" ) // ... 残り 5 エージェント同様 ``` ### Aggregator 呼び出し例 ```markdown 全 Explorer の出力が揃ったら Aggregator を呼び出す。 Task( description: "Aggregate explorer findings", prompt: ".work/02_explorer/ 配下の全ファイルを読み、 Two-step Reduce で統合せよ。 Step 1: findings のマージ Step 2: 矛盾解消・重複排除 出力: .work/03_explorer_unified.md", subagent_type: "sfra-aggregator", model: "opus" ) ``` --- ## ツール使用ルール ### 各 Phase で使用可能なツール | Phase | 許可ツール | 備考 | |-------|-----------|------| | Phase 0 | Glob, Bash (read-only) | ファイル検出のみ | | Phase 1 | Read, Glob, Grep | Index 作成 | | Phase 2 | Read, Glob, Grep | 分析のみ | | Phase 3 | Read | レビューのみ | | Phase 4 | Read, Write | レポート生成 | ### 書き込み制限 - **書き込み可能**: `docs/review/` および `docs/review/.work/` のみ - **読み取り専用**: その他すべてのディレクトリ --- ## Orchestrate コマンド 自動実行モードでは、以下のフローで全 Phase を順次実行する: ### 自動実行フロー ``` /sfra-review → Phase 0 → Phase 1 → Phase 2 (7 agents) → Aggregator → Phase 3 (4 agents) → Aggregator + Gate → Phase 4 → Report ``` ### Done 判定 各 Phase の完了条件をチェックし、次の Phase に自動遷移: | Phase | Done 条件 | |-------|----------| | 0 | `00_scope.json` が生成済み | | 1 | `01_index.md` が生成済み | | 2 | 7 Explorer が status: ok、`03_explorer_unified.md` 生成済み | | 3 | 4 Reviewer が status: ok、Gate 判定完了 | | 4 | `sfra-review.md` が生成済み | ### エラーリカバリー - Explorer 一部失敗: 成功分のみで Aggregator 実行（警告付き） - Reviewer 失敗: Phase 3 からリトライ - Aggregator 失敗: 対応する Phase からリトライ --- ## エラーハンドリング | 状況 | 対応 | |------|------| | Cartridge 未検出 | status: blocked、ユーザーにパス確認を求める | | Explorer 一部失敗 | 警告を出力し、成功したものだけで続行 | | 全 Explorer 失敗 | status: blocked、原因を報告 | | Aggregator 失敗 | Phase 2 からリトライ | | Reporter 失敗 | Phase 4 からリトライ | --- ## 出力ディレクトリ構造 ``` docs/review/ ├── .work/ # 中間成果物（.gitignore 推奨） │ ├── 00_scope.json # Phase 0: スコープ │ ├── 01_index.md # Phase 1: Index │ ├── 02_explorer/ # Phase 2: Explorer 生出力 │ │ ├── controller.md