platform-architecture-analyze

アーキテクチャの分析（Well-Architected レビュー）

Salesforce DX プロジェクトを Salesforce Well-Architected フレームワークに照らして評価し、率直で根拠に基づくレポートを作成します。レポートには、コードとメタデータから確認できる内容を柱ごとに採点した表と、ローカルリポジトリからは把握できないガバナンスやプロセス上の懸念事項に関する人手によるチェックリストが含まれます。

このスキルはオーケストレーターです。静的解析を再実装するのではなく、プラグインに含まれる分析スキルを実行し、その出力を Well-Architected の柱に対応付けます。読み取り専用で、評価と推奨のみを行い、編集、デプロイ、削除は行いません。

また、専用の読み取り専用レビュー担当として、このワークフローをそのまま実行する architecture-review エージェントを支えます。エンドツーエンドのレビューにはエージェントを呼び出し、現在のセッション内でワークフローを実行する場合は、このスキルを直接使用してください。

機能の選択

1. スキルによるレビューのオーケストレーション（このスキル）— 既存のスキルや MCP ツールに委譲して確認可能な項目を調べ、各サブピラーを採点し、手動チェックリストを出力します。
2. 直接的な CLI／grep — ルーブリックで指定された軽量な構造シグナル（共有キーワード、レガシー技術のファイル形式、デプロイ戦略）の確認にのみ使用します。単独での使用も可能ですが、このスキルが提供する柱ごとの採点やガバナンスチェックリストは省略されます。
3. API — 該当しません。

ルーブリック（最初にこちらを読んでください）

採点する前に、次の3つの参照ファイルを読んでください。これらが情報源となります。

• references/well-architected-rubric.md — 柱 → サブピラー → 基準の全体ツリー。各基準には [observable] または [manual] のタグが付いています。
• references/observable-checks.md — 各 [observable] 基準に対応する検出方法（スキル／MCP ツール／grep パターン）と、検出対象のアンチパターン。
• references/manual-review-checklist.md — コピーして使用できるガバナンスチェックリストとしてまとめた [manual] 基準。

ワークフロー

Step 1 — プロジェクトの範囲を把握する

# Package directories + API version
cat sfdx-project.json

次の項目を確認します。

• パッケージディレクトリ（packageDirectories[].path から取得）— ソースの保存場所。
• インベントリ — Apex クラス、トリガー、LWC バンドル、Aura、フロー、オブジェクトの数：

  find <pkgdir> -name '*.cls' | wc -l
  find <pkgdir> -name '*.trigger' | wc -l
  find <pkgdir> -name '*.js-meta.xml' | wc -l   # LWC bundles
  

• ツール関連のシグナル — リポジトリにテスト（*Test.cls、__tests__/）、CI（.github/workflows/）、リンティング（.eslintrc*、.prettierrc*）、package.xml を使った戦略と source/package 戦略のどちらがあるか。
• 組織への接続 — sf org display --json が成功する場合、組織に依存する確認項目（OWD、権限セット）が対象になります。そうでない場合は手動確認として記録します。

レポートのヘッダーに記載する範囲の説明を記録します。

Step 2 — 確認可能な項目を調べる（委譲する。再スキャンしない）

references/observable-checks.md に沿って確認を進めます。主な分析は次の項目に委譲します。

• Apex のセキュリティとパフォーマンス → dx-code-analyzer-run。sf code-analyzer を実行し、検出結果を重大度別に分類します。ルールをルーブリックに対応付けます。
  • ApexSOQLInjection、ApexCRUDViolation、ApexInsecureEndpoint、ApexBadCrypto → Secure
  • ApexSharingViolations → Secure（共有）／Composable（分離）
  • OperationWithLimitsInLoop、OperationWithHighCostInLoop → Reliable／Automated
  • AvoidDebugStatements → Automated
• インライン SOQL の解析と選択性、コンパイルレベルの診断 → platform-lsp-integrate（apex_diagnostics、lwc_diagnostics、check_soql_selectivity）。lsp_health が green の場合、Reliable／Automatedに対応付けます。
• OWD／共有モデル／権限セット → platform-metadata-retrieve と sf org による調査。組織に接続されている場合にのみ実施し、Secureに対応付けます。

軽量な構造シグナルは、次のように直接 grep します（パターンは references/observable-checks.md を参照）。

# Secure — classes missing a sharing keyword
grep -rLE 'with(out)? sharing|inherited sharing' --include='*.cls' <pkgdir>

# Intentional — legacy tech still present
find <pkgdir> -name '*.workflow-meta.xml' -o -name '*.flowDefinition-meta.xml'
grep -rl '@future' --include='*.cls' <pkgdir>

# Composable — deploy strategy
ls manifest/package.xml 2>/dev/null            # package.xml-driven (anti-pattern past PoC)
grep -l '"path"' sfdx-project.json             # source/package strategy

# Composable — runtime config in custom settings vs CMT
find <pkgdir> -path '*objects*' -name '*.object-meta.xml' | xargs grep -l 'CustomSetting' 2>/dev/null

すべての検出結果について、file:line 形式の根拠を収集します。根拠のない確認結果は合格でも不合格でもなく、「確認不能」として手動チェックリストに回します。

ステップ 3 — 観測可能な各サブピラーを採点する

references/observable-checks.md のしきい値を使用して、サブピラーごとに ✅ / ⚠️ / ❌ を割り当てます。

• ✅ そのサブピラーの観測可能なチェックでアンチパターンが見つからなかった。
• ⚠️ 低/中程度の指摘がある、または一部の基準しか観測できない。
• ❌ 重大/高リスクの指摘がある（例: SOQL インジェクション、FLS バイパス、大規模なループ内 SOQL）。

次に、サブピラーの判定をピラーの判定に集約します（最悪のものを採用し、注記を添える）。

ステップ 4 — 手動チェックリストを出力する

references/manual-review-checklist.md から [manual] 基準を未チェック項目としてレポートにコピーし、ピラーごとにグループ化します。セクションには明確にラベルを付けます: 「自動採点なし — チームで評価してください。」 これらを推測しないでください。目的は、開発者に構造化されたガバナンスチェックリストを渡すことであり、スコアを偽装することではありません。

ステップ 5 — レポート

以下の形式で 1 つのレポートを作成します。まずピラーの判定を記載し、次に観測可能な指摘（Trusted/Secure を先頭に — セキュリティをスタイルの下に埋もれさせないこと）、次に手動チェックリスト、最後に各修正を適用するスキル名を明記した推奨される次のステップを記載します。

Well-Architected Review — <project name>
Scope: <pkg dirs>, <N classes / M triggers / K LWC>, tests: <y/n>, CI: <y/n>, org: <connected alias / none>

PILLAR VERDICTS
  🛡️ Trusted     <✅|⚠️|❌>  (Secure …, Compliant …, Reliable …)
  ⚡ Easy         <✅|⚠️|❌>  (Intentional …, Automated …, Engaging …)
  🔁 Adaptable    <✅|⚠️|❌>  (Resilient …, Composable …)

OBSERVABLE FINDINGS  (graded from code + metadata)
  Sub-pillar | Verdict | Finding | Evidence (file:line / tool)

MANUAL REVIEW  (not auto-graded — assess with your team)
  [ ] <item>  …

RECOMMENDED NEXT STEPS
  - <highest-signal fix> → via `<skill>`

例

例 1 — 「このプロジェクトは適切に設計されていますか？」

プロジェクトをスコープし、すべての観測可能なチェックを実行し（Apex 分析は dx-code-analyzer-run に委任）、3 つのピラーすべてを採点し、完全な手動チェックリストを出力してレポートします。これがデフォルトの完全レビューです。

例 2 — 「プロジェクトのセキュリティとガバナ制限のリスクをレビューして」

Secure と Reliable/Automated のサブピラーに絞ります: dx-code-analyzer-run をセキュリティ + パフォーマンスのセレクター付きで実行し、選択性については platform-lsp-integrate の check_soql_selectivity を使用し、共有キーワードの欠落を grep で検索します。それらのサブピラーを採点し、Secure/Compliant の手動項目（セキュリティマトリクス、暗号化戦略）は引き続き出力します。依頼がない限り Adaptable の詳細調査は省略します。

例 3 — 「リリース用にパッケージ化する前に Well-Architected チェックを実行して」

完全レビューで、Composable（パッケージ化可能性 — CMT 対カスタム設定、疎結合、LATEST エイリアシング、package.xml 駆動のデプロイがないこと）と Resilient（ソーストラッキング、CI、失敗したデプロイがないこと）を重視します。レポートの先頭にパッケージ化可能性の準備状況の判定を記載します。

失敗モード

症状	原因	復旧
dx-code-analyzer-run がアナライザーがインストールされていないと報告する	Code Analyzer v5 が存在しない	レポートに記載し、Apex の grep ベースの構造チェックにフォールバックし、PMD のみの基準を「観測不可」とマークします。
sf org display が失敗する	org が接続されていない	OWD / 権限セット / org メタデータの基準を手動とマークし、ファイルベースの基準のみを採点します。
LSP ツールが lsp_disabled / no_apex_workspace を返す	LSP がオフ、またはワークスペースがない	LSP に基づくチェックをスキップし、dx-code-analyzer-run + grep に依存します。ギャップを記載します。
sfdx-project.json がない	SFDX プロジェクトではない	停止します — このスキルは SFDX プロジェクトをレビューします。開発者に伝えます。
リポジトリが巨大で、スキャンが遅い	プロジェクト全体の PMD + グラフ構築	dx-code-analyzer-run をパッケージディレクトリにスコープし、クロスファイル（sfge）の指摘が部分的になる可能性があることを記載します。

ルール

• 採点の前に 3 つの references/*.md ファイルを読んでください — ルーブリックが信頼できる情報源です。
• 観測可能な検出は既存のスキル/MCP ツールに委任し、ルーブリックが挙げる軽量な構造的シグナルのみを grep します。
• すべての観測可能な指摘には file:line（またはツール結果）のエビデンスを添えます。エビデンスがない場合は手動チェックリストに入れ、採点表には入れません。
• [manual] のガバナンス基準を推測で採点しないでください — 人によるレビュー用に列挙します。
• 読み取り専用: 修正を推奨し、それを適用するスキル名を明記します（Apex の作成 / トリガーのリファクタリングには platform-apex-generate）。編集、デプロイ、削除は決して行いません。
• Trusted/Secure の指摘を先頭に記載し、セキュリティをスタイルの些細な指摘の下に埋もれさせないでください。
• 指摘がゼロのサブピラーも省略せず簡潔に記載します（「観測可能なチェックでは問題は見つかりませんでした」）。