well-architected-framework-assessment

用途

本技能用于对 Snowflake 客户账户执行 Well-Architected Framework（WAF）评估，依据 WAF 最佳实践对账户进行结构化检查。适用于客户需要结构化评估、项目启动（engagement kickoff）、健康检查或架构评审等场景。

覆盖五大支柱：安全与治理（Security & Governance）、运营卓越（Operational Excellence）、成本优化（Cost Optimization）、性能（Performance）、可靠性（Reliability）。
采用三级量表：On Track / Needs Improvement / Needs Attention。
结合自动化 SQL 检查与人工问答：自动化检查通过子代理（subagent）并发执行 SQL，人工检查通过 ask_user_question 收集用户输入。
自动检测账户版本（Edition），如 BUSINESS_CRITICAL → Business Critical、ENTERPRISE → Enterprise、STANDARD → Standard、VPS → VPS；若检测失败则询问用户。
输出指标卡、Top Needs Improvement 表格、按支柱的详细表格与柱状图。
可导出 HTML 报告（Step 5），与内联结果共用同一份规范 JSON，保证分数一致。

Step 1：确认活动连接

运行查询确认连接并捕获头部元数据：

SELECT
  CURRENT_ACCOUNT()          AS account_name,
  CURRENT_ORGANIZATION_NAME() AS org_name;

若出现权限错误，建议切换到 ACCOUNTADMIN：USE ROLE ACCOUNTADMIN;。若查询本身失败（连接错误、超时），请用户先确认 Snowflake 连接处于活动状态。

随后尝试自动检测账户版本：

SELECT PARSE_JSON(SYSTEM$BOOTSTRAP_DATA_REQUEST('ACCOUNT')):accountInfo:serviceLevelName::STRING AS service_level;

若成功，将返回值映射为版本并作为 EDITION，跳过版本询问；若失败，则回退到询问用户版本。

然后通过 ask_user_question 选择支柱（若版本自动检测失败，还需询问版本）。CUSTOMER_NAME 始终直接使用组织名称，不询问用户确认或提供友好名称。ACCOUNT_NAME 来自 CURRENT_ACCOUNT()。

Step 2：加载参考文件、派发子代理并收集人工输入

2a：并行读取子代理提示模板与所选支柱的 YAML 文件。
2b：先以 run_in_background: true 派发所有支柱子代理，再在子代理后台运行时通过 ask_user_question 收集人工问题。子代理仅处理 type: automated 的检查，跳过 type: manual 的检查。人工问题采用静默收集，不向用户输出任何关于人工检查的文本，直接调用 ask_user_question。问题标题格式为 <Pillar Name>: <Control or Check Name>，选项必须来自 YAML 的 question_options 字段，不得省略或杜撰选项，且不加字母或数字前缀。评分时将用户所选选项文本与控制的 thresholds 字段匹配；“I don't know” 始终映射为 needs_attention。
2c：输出人工结果列表与子代理结果 JSON。若子代理失败，记录该支柱为错误并继续；部分失败时展示成功结果并说明错误支柱，失败支柱最多重试一次（每支柱最多 2 次尝试）。

Step 3：合并并在 CoCo 中内联呈现结果

3a：合并结果。仅人工控制直接使用主代理评分；仅自动化控制使用子代理的控制级评分；混合控制结合人工与自动化检查结果，按控制 thresholds 整体重新评分。
3b：构建规范 JSON 对象（单一事实来源），所有分数均从该结构计数得出，避免内联与 HTML 输出分数不一致。
3c：整体分数指标卡。评分基于控制而非单个检查，整体分数 = 在轨控制数 / 总控制数。按顺序调用 visualize_data metric_card：Card 1 仅输出整体分数；Card 2 输出安全与治理、运营卓越、可靠性；Card 3 输出成本优化、性能。若评估支柱少于 5 个，按相同顺序分配，单卡不超过 3 个支柱。
3d：Top Needs Improvement Items 表格，收集所有 NEEDS_ATTENTION 与 NEEDS_IMPROVEMENT 控制，按严重程度排序，取前 6 项，使用控制名称而非 ID。
3e：按支柱的详细表格，包含标题、领域在轨率柱状图与控制摘要表。

颜色系统仅使用 🟢 On Track、🟡 Needs Improvement、🟠 Needs Attention，不使用红色或红色编码指示器。
禁止使用 “critical”、“high-risk”、“danger”、“failure”、“violation”、“urgent” 等词，改用 “needs attention”、“opportunity for improvement”、“below best practice”、“recommended action”。
必须在整体指标卡之后逐字输出免责声明（斜体）：This report is intended to help you evaluate your account against a set of recommended well-architected framework best practices; it is not a comprehensive audit. Results may vary based on the model chosen by the user.