platform-architecture-analyze

架构分析（Well-Architected 评审）

依据 Salesforce Well-Architected 框架为 Salesforce DX 项目评分，并生成诚实且有证据支撑的报告：一份按支柱评分的表格，展示代码和元数据中可观察到的内容；另附一份人工检查清单，涵盖本地仓库无法揭示的治理和流程问题。

此技能是一个编排器。它不会重新实现静态分析，而是调用插件已有的分析技能，并将其输出映射到 Well-Architected 支柱。它是只读的：仅进行评分并提出建议；绝不会编辑、部署或删除任何内容。

它还支持 architecture-review Agent，该 Agent 会作为专用的只读评审器，运行完全相同的工作流。需要端到端评审时，请调用该 Agent；如果想在当前会话中直接运行工作流，请直接使用此技能。

能力解析

1. 技能编排的评审（此技能）——通过委派给现有技能/MCP 工具来执行可观察性检查，为每个子支柱评分，并生成手动检查清单。
2. 直接使用 CLI / grep——仅用于评分标准中列出的轻量级结构信号（共享关键字、旧版技术文件类型、部署策略）。可独立使用，但会跳过此技能提供的支柱评分和治理检查清单。
3. API——不适用。

评分标准（请先阅读）

评分前，请阅读以下三个参考文件——它们是权威依据：

• references/well-architected-rubric.md — 完整的“支柱 → 子支柱 → 标准”树，每项标准均标记为 [observable] 或 [manual]。
• references/observable-checks.md — 每项 [observable] 标准对应的检测方式（技能 / MCP 工具 / grep 模式）以及所标记的反模式。
• references/manual-review-checklist.md — 可直接复制粘贴的治理检查清单，包含 [manual] 标准。

工作流

步骤 1 — 确定项目范围

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

确定以下内容：

• 包目录（来自 packageDirectories[].path）——源代码所在位置。
• 清单——统计 Apex 类、触发器、LWC bundle、Aura、Flow、对象的数量：

  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/）、Lint（.eslintrc*、.prettierrc*），以及使用的是 package.xml 还是 source/package 策略？
• Org 连接——sf org display --json 是否成功 → 若成功，则会执行依赖 Org 的检查（OWD、权限集）；否则将它们标记为手动检查。

在报告标题中记录范围说明。

步骤 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 解析 + 选择性、编译级诊断 → 当 lsp_health 为 green 时使用 platform-lsp-integrate（apex_diagnostics、lwc_diagnostics、check_soql_selectivity）→ Reliable / Automated。
• OWD / 共享模型 / 权限集 → 仅在已连接 Org 时使用 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 步 — 报告

按以下格式生成一份报告。先列出支柱结论，再列出可观察问题（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），为所有三个支柱评分，输出完整的人工检查清单并生成报告。这是默认的完整评审。

示例 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	在报告中注明；改用基于 grep 的 Apex 结构检查，并将仅限 PMD 的标准标记为“不可观察”。
sf org display 失败	未连接任何组织	将 OWD / 权限集 / 组织元数据标准标记为人工检查；仅评估基于文件的标准。
LSP 工具返回 lsp_disabled / no_apex_workspace	LSP 已关闭或没有工作区	跳过基于 LSP 的检查；改用 dx-code-analyzer-run + grep。注明此处的检查缺口。
没有 sfdx-project.json	不是 SFDX 项目	停止——此技能用于评审 SFDX 项目。告知开发者。
代码库过大，扫描缓慢	全项目 PMD + 图构建	将 dx-code-analyzer-run 的范围限定为软件包目录；注明跨文件（sfge）发现结果可能不完整。

规则

• 评分前阅读三个 references/*.md 文件——评分标准是唯一依据。
• 将可观察项的检测委托给现有技能/MCP 工具；仅对评分标准指定的轻量级结构信号使用 grep。
• 每项可观察发现都必须附带 file:line（或工具结果）证据。没有证据 → 放入人工检查清单，而非评分表。
• 绝不要根据推断为 [manual] 治理标准评分——将其列出，供人工评审。
• 只读：建议修复方法并注明应用修复的技能（Apex 编写 / 触发器重构使用 platform-apex-generate）；绝不编辑、部署或删除。
• 优先列出 Trusted/Secure 发现；不要把安全问题埋在风格问题之下。
• 简要说明没有发现问题的子支柱（“可观察检查中未发现问题”），不要省略。