platform-architecture-analyze

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyzing Architecture (Well-Architected Review)

架构分析（Well-Architected审查）

Grade a Salesforce DX project against the Salesforce Well-Architected framework and produce an honest, evidence-backed report: a pillar-scored table for what's observable in code and metadata, plus a human checklist for the governance/process concerns a local repo can't reveal.

This skill is an orchestrator. It does not re-implement static analysis — it drives the analysis skills the plugin already ships and maps their output onto the Well-Architected pillars. It is read-only: it grades and recommends; it never edits, deploys, or deletes.

It also backs the

architecture-review

agent, which runs this exact workflow as a dedicated read-only reviewer. Invoke the agent for an end-to-end review; use this skill directly when you want the workflow inline in the current session.

依据Salesforce Well-Architected框架对Salesforce DX项目进行评分，并生成一份真实、有证据支撑的报告：包含代码和元数据中可观测项的支柱评分表，以及本地仓库无法揭示的治理/流程相关人工检查清单。

此功能是一个协调器。它不会重新实现静态分析——而是驱动插件已内置的分析能力，并将其输出映射到Well-Architected框架的各个支柱。它具备只读属性：仅进行评分和建议；绝不编辑、部署或删除任何内容。

它还为

architecture-review

Agent提供支持，该Agent会以专用只读审查者的身份运行此精确工作流。若需要端到端审查，可调用该Agent；若希望在当前会话中直接执行工作流，则可直接使用此功能。

Capability resolution

能力适配方案

Skill-orchestrated review (this skill) — runs the observable checks by delegating to existing skills/MCP tools, scores each sub-pillar, and emits the manual checklist.
Direct CLI / grep — used only for the lightweight structural signals the rubric names (sharing keywords, legacy-tech file types, deploy strategy). Fine standalone, but skips the pillar scoring and the governance checklist this skill provides.
API — not applicable.

功能协调式审查（本功能）——通过调用现有功能/MCP工具执行可观测检查，为每个子支柱评分，并生成人工检查清单。
直接CLI / grep命令——仅用于评分标准中提及的轻量级结构信号（共享关键字、遗留技术文件类型、部署策略）。单独使用时效果尚可，但缺少本功能提供的支柱评分和治理检查清单。
API——不适用。

The rubric (read these first)

评分标准（请先阅读）

Before scoring, read the three reference files — they are the source of truth:

```
references/well-architected-rubric.md
```
— the full pillar → sub-pillar → criteria tree, each criterion tagged
```
[observable]
```
or
```
[manual]
```
.
```
references/observable-checks.md
```
— each
```
[observable]
```
criterion mapped to its detection (skill / MCP tool / grep pattern) and the anti-pattern it flags.
```
references/manual-review-checklist.md
```
— the
```
[manual]
```
criteria as a copy-pasteable governance checklist.

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

```
references/well-architected-rubric.md
```
— 完整的支柱→子支柱→标准体系，每个标准标记为
```
[observable]
```
（可观测）或
```
[manual]
```
（人工）。
```
references/observable-checks.md
```
— 每个
```
[observable]
```
标准对应其检测方式（功能/MCP工具/grep模式）以及它标记的反模式。
```
references/manual-review-checklist.md
```
— 以可复制粘贴的治理检查清单形式呈现
```
[manual]
```
标准。

Workflow

工作流程

Step 1 — Scope the project

步骤1 — 确定项目范围

bash

undefined

bash

undefined

Package directories + API version

包目录 + API版本

cat sfdx-project.json


Establish:
- **Package dirs** (from `packageDirectories[].path`) — where the source lives.
- **Inventory** — count Apex classes, triggers, LWC bundles, Aura, Flows, objects:
  ```bash
  find <pkgdir> -name '*.cls' | wc -l
  find <pkgdir> -name '*.trigger' | wc -l
  find <pkgdir> -name '*.js-meta.xml' | wc -l   # LWC bundles

Tooling signals — does the repo have tests (
```
*Test.cls
```
,
```
__tests__/
```
), CI (
```
.github/workflows/
```
), linting (
```
.eslintrc*
```
,
```
.prettierrc*
```
), a
```
package.xml
```
vs source/package strategy?
Org connection —
```
sf org display --json
```
succeeds → org-dependent checks (OWD, permission sets) are in play; otherwise mark them manual.

Record the scope line for the report header.

cat sfdx-project.json


确认以下信息：
- **包目录**（来自`packageDirectories[].path`）——源代码所在位置。
- **资源清单**——统计Apex类、触发器、LWC包、Aura、Flow、对象的数量：
  ```bash
  find <pkgdir> -name '*.cls' | wc -l
  find <pkgdir> -name '*.trigger' | wc -l
  find <pkgdir> -name '*.js-meta.xml' | wc -l   # LWC包

工具信号——仓库是否包含测试文件（
```
*Test.cls
```
、
```
__tests__/
```
）、CI配置（
```
.github/workflows/
```
）、代码检查（
```
.eslintrc*
```
、
```
.prettierrc*
```
），以及采用
```
package.xml
```
还是源码/包策略？
组织连接——
```
sf org display --json
```
执行成功 → 可进行依赖于组织的检查（OWD、权限集）；否则将这些检查标记为人工项。

记录范围信息，用于报告标题。

Step 2 — Run the observable checks (delegate; don't re-scan)

步骤2 — 执行可观测检查（调用其他功能，不重复扫描）

Work through

references/observable-checks.md

. For the heavy lifting, delegate:

Apex security + performance →

dx-code-analyzer-run

. It runs

sf code-analyzer

and classifies findings by severity. Map its rules onto the rubric:

ApexSOQLInjection

ApexCRUDViolation

ApexInsecureEndpoint

ApexBadCrypto

→ Secure

```
ApexSharingViolations
```
→ Secure (sharing) / Composable (separation)

OperationWithLimitsInLoop

OperationWithHighCostInLoop

→ Reliable / Automated

```
AvoidDebugStatements
```
→ Automated

Inline SOQL parse + selectivity, compile-level diagnostics →
```
platform-lsp-integrate
```
(
```
apex_diagnostics
```
,
```
lwc_diagnostics
```
,
```
check_soql_selectivity
```
) when
```
lsp_health
```
is green → Reliable / Automated.
OWD / sharing model / permission sets →
```
platform-metadata-retrieve
```
+
```
sf org
```
inspection, only if an org is connected → Secure.

For the lightweight structural signals, grep directly (patterns in

references/observable-checks.md

), e.g.:

bash

undefined

按照

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
```
为绿色时，使用
```
platform-lsp-integrate
```
（
```
apex_diagnostics
```
、
```
lwc_diagnostics
```
、
```
check_soql_selectivity
```
）→ 可靠（Reliable）/ 自动化（Automated）。
OWD / 共享模型 / 权限集 → 仅当已连接组织时，使用
```
platform-metadata-retrieve
```
+
```
sf org
```
检查 → 可信（Secure）。

对于轻量级结构信号，直接使用grep命令（模式见

references/observable-checks.md

），例如：

bash

undefined

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

ls manifest/package.xml 2>/dev/null # 基于package.xml的策略（PoC之后属于反模式） grep -l '"path"' sfdx-project.json # 源码/包策略

Composable — runtime config in custom settings vs CMT

可组合 — 自定义设置与CMT中的运行时配置

find <pkgdir> -path 'objects' -name '*.object-meta.xml' | xargs grep -l 'CustomSetting' 2>/dev/null


Collect every finding with `file:line` evidence. A check with no evidence is **not** a pass and **not** a fail — it's "not observable" and moves to the manual checklist.

find <pkgdir> -path 'objects' -name '*.object-meta.xml' | xargs grep -l 'CustomSetting' 2>/dev/null


收集每个带有`file:line`证据的检查结果。无证据的检查项**既不通过也不失败**——标记为「不可观测」并移至人工检查清单。

Step 3 — Score each observable sub-pillar

步骤3 — 为每个可观测子支柱评分

Assign ✅ / ⚠️ / ❌ per sub-pillar using the thresholds in

references/observable-checks.md

✅ no anti-patterns found in the observable checks for that sub-pillar.
⚠️ low/moderate findings, or only some criteria observable.
❌ critical/high findings (e.g. SOQL injection, FLS bypass, SOQL-in-loop at scale).

Then roll the sub-pillar verdicts up to a pillar verdict (worst-of, with a note).

依据

references/observable-checks.md

中的阈值，为每个子支柱分配✅ / ⚠️ / ❌：

✅ 该子支柱的可观测检查中未发现反模式。
⚠️ 存在低/中度问题，或仅部分标准可观测。
❌ 存在严重/高危问题（如SOQL注入、FLS绕过、循环中的SOQL大规模使用）。

然后将子支柱的结论汇总为支柱结论（取最差结果，并附带说明）。

Step 4 — Emit the manual checklist

步骤4 — 生成人工检查清单

Copy the

[manual]

criteria from

references/manual-review-checklist.md

into the report as unchecked items, grouped by pillar. Label the section clearly: "not auto-graded — assess with your team." Do not guess at these; the point is to hand the developer a structured governance checklist, not to fake a score.

将

references/manual-review-checklist.md

中的

[manual]

标准复制到报告中，作为未勾选的项，按支柱分组。明确标记该部分：「未自动评分 — 请与团队一起评估。」 请勿猜测这些项的结果；此部分的目的是为开发者提供结构化的治理检查清单，而非伪造评分。

Step 5 — Report

步骤5 — 生成报告

Produce one report using the format below. Lead with pillar verdicts, then observable findings (Trusted/Secure first — never bury security under style), then the manual checklist, then recommended next steps that name the skill which would apply each fix.

text

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>`

使用以下格式生成一份报告。首先展示支柱结论，然后是可观测结果（优先展示可信/安全项——绝不要将安全问题隐藏在风格细节之下），接着是人工检查清单，最后是推荐的后续步骤，并指明可应用修复的功能名称。

text

Well-Architected审查 — <项目名称>
范围：<包目录>，<N个类 / M个触发器 / K个LWC>，测试：<是/否>，CI：<是/否>，组织：<已连接别名 / 无>

支柱结论
  🛡️ 可信     <✅|⚠️|❌> （安全…，合规…，可靠…）
  ⚡ 易用         <✅|⚠️|❌> （明确…，自动化…，有吸引力…）
  🔁 可适配    <✅|⚠️|❌> （弹性…，可组合…）

可观测结果 （基于代码 + 元数据评分）
  子支柱 | 结论 | 发现问题 | 证据（文件:行号 / 工具）

人工审查 （未自动评分 — 请与团队一起评估）
  [ ] <项>  …

推荐后续步骤
  - <最高优先级修复> → 通过`<功能>`实现

Examples

示例

Example 1 — "Is this project well-architected?"

示例1 — 「该项目架构是否合规？」

Scope the project, run all observable checks (delegating Apex analysis to

dx-code-analyzer-run

), score all three pillars, emit the full manual checklist, and report. This is the default full review.

确定项目范围，执行所有可观测检查（将Apex分析委托给

dx-code-analyzer-run

），为三个支柱评分，生成完整的人工检查清单并报告。这是默认的全面审查。

Example 2 — "Review my project's security and governor-limit risk"

示例2 — 「审查我项目的安全和Governor限制风险」

Narrow to the Secure and Reliable/Automated sub-pillars: run

dx-code-analyzer-run

with a security + performance selector, use

platform-lsp-integrate

check_soql_selectivity

for selectivity, grep for missing sharing keywords. Score those sub-pillars; still emit the Secure/Compliant manual items (security matrix, encryption strategy). Skip the Adaptable deep-dive unless asked.

缩小范围至安全和可靠/自动化子支柱：运行带有安全+性能选择器的

dx-code-analyzer-run

，使用

platform-lsp-integrate

的

check_soql_selectivity

检查选择性，使用grep查找缺失的共享关键字。为这些子支柱评分；仍需生成安全/合规的人工项（安全矩阵、加密策略）。除非特别要求，否则跳过可适配的深入分析。

Example 3 — "Run a Well-Architected check before we package this for release"

示例3 — 「在打包发布前执行Well-Architected检查」

Full review, weighting Composable (packageability — CMT vs custom settings, loose coupling,

LATEST

aliasing, no

package.xml

-driven deploys) and Resilient (source-tracked, CI, no failed deploys). Lead the report with the packageability readiness verdict.

全面审查，重点关注可组合（可打包性——CMT vs 自定义设置、松耦合、

LATEST

别名、无基于

package.xml

的部署）和弹性（源码跟踪、CI、无部署失败）。报告开头展示可打包性就绪结论。

Failure modes

故障模式

Symptom	Cause	Recovery
`dx-code-analyzer-run` reports the analyzer isn't installed	Code Analyzer v5 missing	Note it in the report; fall back to grep-based structural checks for Apex and mark PMD-only criteria "not observable".
`sf org display` fails	No org connected	Mark OWD / permission-set / org-metadata criteria as manual; grade only file-based criteria.
LSP tools return `lsp_disabled` / `no_apex_workspace`	LSP off or no workspace	Skip the LSP-grounded checks; rely on `dx-code-analyzer-run` + grep. Note the gap.
No `sfdx-project.json`	Not an SFDX project	Stop — this skill reviews SFDX projects. Tell the developer.
Huge repo, scan is slow	Project-wide PMD + graph build	Scope `dx-code-analyzer-run` to the package dir; note that cross-file (sfge) findings may be partial.

症状	原因	恢复方案
`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）结果可能不完整。

Rules

规则

Read the three
```
references/*.md
```
files before scoring — the rubric is the source of truth.
Delegate observable detection to existing skills/MCP tools; grep only for the lightweight structural signals the rubric names.
Every observable finding carries
```
file:line
```
(or tool-result) evidence. No evidence → manual checklist, not the scored table.
Never score a
```
[manual]
```
governance criterion from inference — list it for human review.
Read-only: recommend fixes and name the skill that applies them (
```
platform-apex-generate
```
for Apex authoring / trigger refactoring); never edit, deploy, or delete.
Lead with Trusted/Secure findings; don't bury security under style nits.
Surface zero-finding sub-pillars briefly ("no issues found in observable checks") rather than omitting them.

评分前请阅读三份
```
references/*.md
```
文件——评分标准是权威依据。
将可观测检测委托给现有功能/MCP工具；仅对评分标准中提及的轻量级结构信号使用grep。
每个可观测结果都需附带
```
file:line
```
（或工具结果）证据。无证据→移至人工检查清单，而非评分表。
绝不要通过推断为
```
[manual]
```
治理标准评分——将其列出供人工审查。
只读属性：推荐修复方案并指明可应用修复的功能（如使用
```
platform-apex-generate
```
进行Apex编写/触发器重构）；绝不编辑、部署或删除任何内容。
优先展示可信/安全结果；不要将安全问题隐藏在风格细节之下。
简要提及无问题的子支柱（「可观测检查中未发现问题」），而非省略。