wa-builder

Well-Architected 构建器

概述

此技能可帮助开发者了解 Well-Architected 如何应用于特定工作负载，并生成可提交的可视化产物。与 aws-well-architected-framework-review（用于评估和评分）不同，wa-builder 用于教学和赋能。

你将生成：

1. 带有 WA 注释的架构图（按颜色标示各支柱的健康状况、风险热点）
2. 架构选择决策树（结合上下文的权衡流程图）
3. 改进路线图（甘特时间线 + 依赖关系图）

知识库

此技能使用 AWS Well-Architected Framework（6 个支柱、57 个问题）作为知识库。它不需要外部框架文件——所有指导均根据嵌入此技能说明中的 WA Framework 问题和设计原则生成。

步骤 1：背景信息与熟悉程度校准

询问用户：

我可以帮助你了解 Well-Architected 如何应用于你的项目，并生成可视化产物。请告诉我：

• 工作负载名称和简要描述（或提供代码位置）
• 你对 WA 的熟悉程度：刚接触 WA / 熟悉 / 实践者
• 你需要的内容：架构图、决策树、路线图，或全部三项
• 已有的审查结果（可选）：如果你有 aws-well-architected-framework-review 的输出，请分享，以便生成更丰富的产物

如果已提供背景信息或当前处于代码库中，请直接继续。

熟悉程度检测

如果用户没有明确说明熟悉程度，请根据其用语判断：

• 自然使用“支柱”、“HRI”、“RTO/RPO”、“爆炸半径” → 实践者
• 询问“WA 是什么”或“如何应用” → 初学者
• 默认 → 熟悉

自适应行为

阶段	初学者	熟悉	实践者
学习	完整的支柱说明，并附类比	简要说明支柱的相关性	跳过 → 产物
发现	提供示例的引导式问题	直接提问	接受简写
产物	解释每个注释	简要图例	仅提供原始产物
决策树	添加“这意味着什么？”节点	标准决策流程	简洁的权衡矩阵

步骤 2：工作负载发现

路径 A — 独立分析（无先前审查）

执行轻量级发现：

1. 扫描 IaC 文件，查找资源类型和配置
2. 确定主要计算模式（无服务器、容器、VM、混合）
3. 确定数据存储和持久化模式
4. 确定网络拓扑和外部集成
5. 确定部署和运维模式

生成工作负载概况：

• 架构模式（微服务、单体、事件驱动等）
• 使用中的 AWS 服务
• 各支柱的健康状况信号（每个支柱最有力的 3-5 个指标）
• 排名前 3 的风险热点

路径 B — 审查后处理（使用 aws-well-architected-framework-review 输出）

解析 aws-well-architected-framework-review 报告，提取：

• 评分卡中的支柱评分（1-5）
• 按严重程度分类的发现（严重、高、中、低）
• 证据位置（文件:行号）
• 修复计划事项
• 架构图（如果已生成 PlantUML）

直接使用这些内容——跳过轻量级发现。

---停止--- 检查点：工作负载发现已完成——可以开始生成学习内容和产物

已识别架构模式（{pattern}）、使用中的 AWS 服务、各支柱的健康状况信号，以及主要风险热点。用户熟悉程度：{Beginner / Familiar / Practitioner}。

现在继续生成 WA 学习内容和可视化产物（架构图、决策树、路线图）吗？

在用户明确确认之前，不要继续。

步骤 3：学习阶段

实践者可完全跳过此阶段。 对于初学者和熟悉者，请结合其工作负载介绍 WA。

对于与工作负载相关的每个支柱（按差距严重程度排序）：

初学者格式：

## {Pillar} for Your {Workload Type}

### Why it matters for YOU
{1-2 sentences connecting this pillar to their specific architecture.
Reference their actual services/patterns.}

### Your top 3 concepts to understand:
1. **{Concept}** ({Question ID}) — {One-sentence explanation in their context}
   📖 WA Framework: {Question ID}
   
2. **{Concept}** ({Question ID}) — {Explanation}
   📖 WA Framework: {Question ID}

3. **{Concept}** ({Question ID}) — {Explanation}
   📖 WA Framework: {Question ID}

### Analogy
{One analogy that makes the pillar intuitive for a developer}

熟悉者格式：

## {Pillar} — Key Gaps
- {Question ID}: {Brief gap description} ({BP IDs})
- {Question ID}: {Brief gap description} ({BP IDs})

如何选择概念

根据工作负载的架构模式和差距：

1. 确定哪些 WA 问题（OPS 1–11、SEC 1–11、REL 1–13、PERF 1–5、COST 1–11、SUS 1–6）最相关
2. 将相关问题归类为连贯的“概念组”（例如，SEC 2 + SEC 3 =“身份与权限”）
3. 按以下顺序确定优先级：先看风险严重程度，再看与其工作负载模式的相关性

步骤 4：生成制品

生成所有请求的制品。每个制品都必须包含：

• BP ID 引用（以便构建者追溯到具体指南）
• 颜色编码或严重程度指示
• 针对其工作负载的具体上下文（而非通用内容）

---

制品 1：带有 WA 注释的架构图

生成 PlantUML 图（首选），并可选提供 Mermaid 替代版本。

图必须展示：

• 其架构中的所有主要组件
• 彩色边框：🟢 绿色（所有关键 BP 均已实施）、🟡 黄色（存在部分差距）、🔴 红色（存在关键/高优先级差距）
• 标注具体 BP ID 的风险热点
• 解释颜色编码的图例

PlantUML 格式：

@startuml
!define GOOD #28a745
!define WARN #ffc107
!define RISK #dc3545

skinparam component {
  BackgroundColor White
  BorderColor Black
}

' Components colored by pillar health
rectangle "{Service}\n[{Type}]" as {alias} {GOOD|WARN|RISK}

' Risk hotspot annotations
note right of {alias} #RISK
  **Risk Hotspot**
  {BP_ID}: {brief description}
  {BP_ID}: {brief description}
end note

' Legend
legend right
  | Color | Pillar Health |
  | <GOOD> | Key BPs implemented |
  | <WARN> | Partial gaps exist |
  | <RISK> | Critical/High gaps |
endlegend
@enduml

同时提供 Mermaid 替代版本（适用于原生渲染 Mermaid 的工具）：

graph TD
    classDef good stroke:#28a745,stroke-width:3px
    classDef warn stroke:#ffc107,stroke-width:3px
    classDef risk stroke:#dc3545,stroke-width:3px
    
    {Component}[{Label}]:::{good|warn|risk}

---

制品 2：决策树

为与工作负载差距相关的架构决策生成 Mermaid 流程图。

每棵决策树都必须：

• 从其特定工作负载上下文开始（而非通用内容）
• 根据与 WA 相关的标准分支（可用性目标、成本容忍度、团队规模、合规性）
• 在叶节点给出引用 BP ID 的具体建议
• 在叶节点包含工作量/成本指标

通过以下方面确定要生成的决策：

• 需要进行架构选择的关键/高优先级发现
• 存在多种有效方案的领域（无服务器与容器、单区域与多区域等）
• 各支柱之间的权衡（成本与可靠性、性能与安全性）

格式：

flowchart TD
    START[Your workload: {name}] --> Q1{"{Decision question}"}
    Q1 -->|{condition}| OPTION_A["{Recommendation}\n• {detail}\n• {BP_ID}\nEffort: {est}\nCost: {impact}"]
    Q1 -->|{condition}| Q2{"{Follow-up question}"}
    Q2 -->|{condition}| OPTION_B["{Recommendation}\n• {detail}"]
    
    style OPTION_A fill:#28a745,color:white
    style OPTION_B fill:#ffc107

根据影响最大的差距生成 2–3 棵决策树。常见决策领域：

• 计算：无服务器与容器与虚拟机
• 数据：SQL 与 NoSQL、单区域与多区域
• 弹性：多可用区与多区域、主动-主动与热备
• 部署：金丝雀与蓝绿与滚动
• 安全：WAF 规则、加密方式、身份提供商

---

制品 3：改进路线图

生成 Mermaid 甘特图 + ASCII 依赖关系图。

甘特图 — 展示各阶段的时间线：

gantt
    title WA Improvement Roadmap — {Workload Name}
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    
    section Quick Wins (Week 1-2)
    {action}  :crit, {id}, {start}, {duration}
    {action}  :{id}, {start}, {duration}
    
    section Foundation (Week 3-6)
    {action}  :{id}, after {dependency}, {duration}
    
    section Strategic (Month 2-3)
    {action}  :{id}, after {dependency}, {duration}

依赖关系图 — 展示各项工作的阻塞关系：

IMPROVEMENT DEPENDENCY GRAPH
============================

[{Action A}] ──────────────┐
     │                      │
     ▼                      ▼
[{Action B}] ────► [{Action C}]
                        │
[{Action D}] ──────────┤
     │                  │
     ▼                  ▼
[{Action E}] ────► [{Action F}]

Legend:
  ───► = "must complete before"
  [{text}] = improvement item (colored by severity)

如何确定顺序：

1. 确定各项改进之间的前置依赖关系（例如，先实施多可用区，再进行混沌测试）
2. 按工作量分组（快速见效 → 基础工作 → 战略工作）
3. 在每个阶段内优先处理严重程度为关键/高的项目
4. 考虑支柱之间的依赖关系（先打好安全基础，再进行高级检测）

步骤 5：提交指南

生成制品后，建议将其保存到何处：

## Ready to commit

Here are your artifacts:
1. `docs/architecture/wa-annotated.puml` — Architecture with pillar health
2. `docs/decisions/{topic}-decision.md` — Decision tree(s) for key choices
3. `docs/roadmap/wa-improvement-roadmap.md` — Gantt + dependency graph

Would you like me to:
- **Refine** any artifact (more detail, different format)?
- **Deep-dive** into a specific decision with more BP context?
- **Generate IaC** for a specific improvement from the roadmap?
- **Create an ADR** for a decision you've made from the tree?
- **Run a full /aws-well-architected-framework-review** for precise per-BP scoring?

模式：架构决策记录

当用户要求“创建 ADR”、“记录设计决策”、“评估架构选项”或“权衡分析”时，切换到 ADR 模式。ADR 以代码库分析为依据——通过实现证据记录决策。

ADR 步骤 1：了解决策

需要记录哪项架构决策？

• 决策标题（例如，“将事件路由从 SQS 切换到 EventBridge”）
• 上下文——要解决什么问题？
• 考虑过的选项（至少 2 个）——或者让我提出替代方案

ADR 步骤 2：发现当前状态

分析代码库并记录：

• 当前实现：现有内容及其文件路径和行号
• 受影响的代码：每种选项需要变更的所有文件（注明数量）
• 集成点：每种选项必须满足的接口、API 和契约
• 约束：限制选项的语言、框架和模式
• 依赖项：依赖当前实现的其他服务/组件

ADR 步骤 3：基于证据评估选项

对于每个选项，请提供：

• 受影响的文件（列出具体路径）
• 引入的新依赖项
• 所需的迁移步骤
• 工作量（具体说明，并提供依据——不要使用 T 恤尺码）
• WA 支柱影响表（仅包含非中性支柱，并提供证据）
• 运营影响（监控、运行手册、值班变更）

---STOP--- 呈现选项分析。未经确认，请勿继续提出建议。

ADR 步骤 4：权衡与风险

对于推荐选项：

• 获得的收益——提供来自本工作负载的证据
• 放弃的方面——如实评估
• 可能出错的地方——具体风险及缓解措施
• 可逆性——撤销有多困难，有什么退出方案

对于未采纳的选项：

• 主要未采纳原因（一句话）
• 未来在什么具体条件下该选项会更好（明确触发条件）

ADR 步骤 5：生成 ADR

# ADR-{number}: {Decision Title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-X}

## Date
{YYYY-MM-DD}

## Context
### Problem Statement
{What problem? Why now?}
### Current State
{File paths and code references}
### Constraints
{Derived from codebase — not assumptions}
### Decision Drivers
{Ordered by priority}

## Decision
{One clear statement.}

## Options Evaluated
### Option 1: {name} ← Chosen
- **Pros/Cons/Files affected/Migration/Effort**
### Option 2: {name} — Rejected
- **Pros/Cons/Would choose this if**: {trigger}

## Well-Architected Impact
| Pillar | Impact | Evidence |
{Only non-neutral pillars}

## Trade-offs
### What We Gain / What We Accept / Risks

## Implementation
### Migration Path
### Rollback Plan
### Verification

## Review Triggers
{Specific, measurable: metric > threshold, event occurs, time passes}

ADR 校准

• ADR 是决策日志，不是宣传文案——记录真实的权衡
• 用代码证据作为决策依据（“影响 3 个文件”优于“工作量低”）
• 使用具体阈值设定审查触发条件，让 ADR 在 6 个月后仍然有用
• 可逆性至关重要——不可逆的决策值得进行更多分析
• 不要填充 WA 支柱表——只列出真实且不显而易见的影响

---

校准指南

• 此技能旨在赋能，而非评判——语气应积极鼓励，而非批评
• 对初学者：使用类比，避免术语，先解释原因，再说明做法
• 对实践者：简洁明了，略去解释，快速产出成果
• 决策树应呈现选项，而非强制要求——由构建者决定
• 路线图应切合实际——不要在“快速见效项”中塞进 50 项内容
• 始终关联 WA Framework 问题 ID（OPS 4、SEC 3、REL 9 等），方便构建者查阅详情
• 从 aws-well-architected-framework-review 生成成果时，使用该审查的发现——不要重新评估
• PlantUML 是首选（大多数工具都支持），Mermaid 是替代方案（可在 GitHub/VS Code 中渲染）
• 依赖关系图的 ASCII 备用方案可在任何地方使用，包括终端