wa-builder

Well-Architected Builder

概要

このスキルは、開発者が自身のワークロードにおける 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 初心者／知識あり／実践者
• 希望する成果物：アーキテクチャ図、決定木、ロードマップ、または 3 つすべて
• 既存のレビュー（任意）：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）
• 重大度別の検出事項（Critical、High、Medium、Low）
• 根拠の場所（ファイル名:行番号）
• 修正計画の項目
• アーキテクチャ図（PlantUML が生成されている場合）

これをそのまま使用し、簡易的な調査はスキップします。

---STOP--- チェックポイント：ワークロードの把握が完了しました。学習コンテンツと成果物を生成する準備ができています

アーキテクチャパターン（{pattern}）、使用中の AWS サービス（{services}）、柱ごとの健全性を示すシグナル、主なリスクのホットスポットを特定しました。ユーザーの習熟度：{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. リスクの深刻度を最優先し、次にワークロードパターンとの関連性を基準に優先順位を付けます

Step 4: 成果物の生成

要求された成果物をすべて生成します。各成果物には、必ず以下を含めてください。

• BP ID の参照（ビルダーが具体的なガイダンスをたどれるようにするため）
• 色分けまたは深刻度の指標
• 汎用的な内容ではなく、対象のワークロードに固有のコンテキスト

---

Artifact 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}

---

Artifact 2: 意思決定ツリー

ワークロードのギャップに関連するアーキテクチャ上の決定について、Mermaid のフローチャートを生成します。

各意思決定ツリーには、必ず以下を含めてください。

• 汎用的な内容ではなく、対象ワークロード固有のコンテキストから始める
• WA に関係する基準（可用性目標、コスト許容度、チーム規模、コンプライアンスなど）に基づく分岐
• BP ID を参照する具体的な推奨事項で終える
• 葉ノードに作業量／コストの指標を含める

生成する意思決定を、以下の観点から特定してください。

• アーキテクチャ上の選択が必要となる Critical／High の検出結果
• 有効なアプローチが複数ある領域（サーバーレスとコンテナ、シングルリージョンとマルチリージョンなど）
• 複数の柱の間のトレードオフ（コストと信頼性、パフォーマンスとセキュリティなど）

形式：

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 個生成します。一般的な決定領域は以下のとおりです。

• コンピューティング：サーバーレス、コンテナ、VM
• データ：SQL、NoSQL、シングルリージョン、マルチリージョン
• レジリエンス：マルチ AZ、マルチリージョン、アクティブ／アクティブ、ウォームスタンバイ
• デプロイ：カナリア、ブルー／グリーン、ローリング
• セキュリティ：WAF ルール、暗号化方式、ID プロバイダー

---

Artifact 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. 改善項目間の前提条件となる関係を特定します（例：カオステストの前にマルチ AZ を導入）
2. 作業量ごとに分類します（クイックウィン → 基盤 → 戦略的）
3. 各フェーズ内では、深刻度が Critical／High の項目を優先します
4. 柱の依存関係を考慮します（高度な検出より先にセキュリティの基盤を整備）

Step 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?

Mode: アーキテクチャ決定記録

ユーザーが「ADR を作成する」「設計上の決定を記録する」「アーキテクチャの選択肢を評価する」または「トレードオフを分析する」と依頼した場合は、ADR モードに切り替えます。ADR はコードベースの分析に基づき、実装の根拠とともに決定を記録します。

ADR Step 1: 決定内容の把握

どのようなアーキテクチャ上の決定を記録する必要がありますか？

• 決定のタイトル（例：「イベントルーティングを SQS から EventBridge に切り替える」）
• コンテキスト — どのような問題を解決しようとしていますか？
• 検討した選択肢（2 つ以上）— または代替案の提案を依頼してください

ADR Step 2: 現状の調査

コードベースを分析し、以下を記録します。

• 現在の実装：現時点で存在するものと、ファイルパスおよび行番号
• 影響を受けるコード：各選択肢によって変更されるすべてのファイル（数を明記）
• 統合ポイント：各選択肢が満たす必要のあるインターフェース、API、コントラクト
• 制約：選択肢を制限する言語、フレームワーク、パターン
• 依存関係：現在の実装に依存する他のサービス／コンポーネント

ADR ステップ 3：根拠に基づいて選択肢を評価する

各選択肢について、以下を提示してください。

• 影響を受けるファイル（具体的なパスを列挙）
• 新たに導入する依存関係
• 必要な移行手順
• 工数（具体的に、根拠を示すこと。T シャツサイズは不可）
• WA ピラーへの影響の表（中立ではないピラーのみ、根拠を添える）
• 運用への影響（モニタリング、ランブック、オンコールの変更）

---STOP--- 選択肢の分析を提示してください。確認を得るまで、推奨に進まないでください。

ADR ステップ 4：トレードオフとリスク

推奨する選択肢について、以下を記載してください。

• 得られるもの — 今回のワークロードから得られる根拠を示す
• 手放すもの — 正直に評価する
• 問題が起こる可能性 — 具体的なリスクと緩和策
• 可逆性 — 元に戻す難しさと、代替手段

却下する選択肢について、以下を記載してください。

• 主な却下理由（1 文）
• 将来、どのような条件になればより適切になるか（具体的なトリガー）

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 ファイルに影響する」）
• 具体的な閾値を定めた見直しトリガーがあると、6 か月後にも役立つ ADR になります
• 可逆性は重要です。不可逆な決定には、より詳細な分析が必要です
• WA ピラーの表を埋めるためだけに項目を増やさず、実際に存在する明白でない影響のみを記載してください

---

調整の指針

• このスキルの目的は判断ではなく実現支援です。批判的ではなく、前向きなトーンにしてください
• 初心者向けには、たとえを使い、専門用語を避け、何をするかの前に理由を説明してください
• 実務者向けには、簡潔にし、説明を省いて、成果物をすばやく作成してください
• 意思決定ツリーでは、選択肢を提示し、必須事項として指示しないでください。決定するのはビルダーです
• ロードマップは現実的なものにしてください。「クイックウィン」に 50 項目を詰め込まないでください
• ビルダーが詳細を参照できるよう、WA フレームワークの質問 ID（OPS 4、SEC 3、REL 9 など）に必ず結び付けてください
• aws-well-architected-framework-review から成果物を生成するときは、そのレビューの所見を使用し、再評価しないでください
• PlantUML を主要な選択肢としてください（ほとんどのツールが対応しています）。Mermaid は代替手段です（GitHub／VS Code でレンダリングされます）
• 依存関係グラフの ASCII による代替表現は、ターミナルを含め、どこでも使用できます