sfra-review

name	sfra-review
description	SFRA (Storefront Reference Architecture) code review skill using Swarm pattern. Analyzes controllers, models, ISML, services, jobs for best practices, security, and performance. Triggers on "SFRA review", "SFCC code review", "cartridge review"
version	1.1.0
triggers	["SFRA review","SFCC code review","cartridge review","SFRA レビュー","コードレビュー"]

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 を算出

検出項目:

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

出力形式:

# 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 判定結果

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 呼び出し例

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 呼び出し例

全 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
│   │   ├── model.md
│   │   ├── isml.md
│   │   ├── client.md
│   │   ├── service.md
│   │   ├── cartridge.md
│   │   └── jobs.md
│   ├── 03_explorer_unified.md     # Phase 2: 統合分析
│   ├── 04_reviewer/               # Phase 3: Reviewer 生出力
│   │   ├── performance.md
│   │   ├── security.md
│   │   ├── bestpractice.md
│   │   └── antipattern.md
│   └── 05_review_unified.md       # Phase 3: 統合レビュー
└── sfra-review.md                 # 最終レポート