aibot88 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 構成と規模を把握
手順:
- プロジェクトルートで cartridge 構成を検出
cartridgeディレクトリ配下の構造を分析- 対象ファイル数と 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 情報
手順:
- Task ツールで
sfra-indexerエージェントを起動（model: sonnet） - Controllers/Routes のマッピング
- Models/Decorators の一覧化
- ISML テンプレートの依存関係
- Services/Hooks の定義収集
- 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 情報
手順:
- 並列実行: 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) ──┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- 各エージェントは担当範囲のみを分析し、ハンドオフ封筒形式で出力
- 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 の統合分析結果
手順:
- 並列実行: 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) ──┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- 各 Reviewer は P0/P1/P2 の重大度付きで指摘事項を出力
- 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 の統合レビュー結果
手順:
- Task ツールで
sfra-reporterエージェントを起動（model: sonnet） - テンプレートに基づいてレポート生成
- Executive Summary 作成
- カテゴリ別 Findings 整理
- 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 # 最終レポート