☁️ 技術調査 - multi-cloud-lifecycle-skills

概要

クラウドインフラの設計には「特定ベンダーに依存しない設計にしたい」と「各ベンダーが推奨するベストプラクティスに従いたい」という矛盾する 2 つの要求があります。multi-cloud-lifecycle-skills は、この矛盾を 4 層の設計パイプラインで解決する Claude Code スキル群です。

AWS / Azure / GCP を対象に、ベンダー中立の正規モデル（Canonical Model）からベンダー別マッピング、IaC スケルトンまでを AI エージェントとの対話で一貫して生成します。クラウドアーキテクト、プラットフォームエンジニア、インフラ設計者を主な対象としています。

特徴

• 4層設計パイプライン: Vendor Sources → Canonical Model → Vendor Mapping → Implementation Artifacts の 4 層でベンダー中立性とベストプラクティス準拠を両立
• fidelity 評価によるギャップの可視化: Vendor Mapping 層で exact / partial / workaround / gap の fidelity スコアを付与し、ベンダー間の適合度を定量化
• 3スキル階層による段階的設計: mcl-foundation-design → mcl-shared-platform-design → mcl-product-design の順に設計を進め、上位スキルの出力が下位スキルの入力
• YAML 正本ポリシー: 全 artifact の正本を YAML に統一。Markdown は常に派生生成物
• 対話型ヒアリングで自動生成: スキルが選択肢付きのヒアリングを実施し、回答に基づいて canonical model、vendor mapping、IaC スケルトン、アーキテクチャドキュメントを一括生成
• mcl-common によるテンプレート共有: 3スキル共通のメタスキルとして、YAML テンプレート、スキーマ、正規化ルール、マッピングルールを一元管理
• ベンダーソースの自動収集: AWS / Azure / GCP の公式ガイダンスページを自動収集して Markdown として保存。既存ソースがある場合はそれを優先
• Claude Code プラグインとして配置: .claude/skills/ 配下にシンボリックリンクを設置。install.sh でグローバルまたはプロジェクト固有に導入可能
• 3クラウド全対応・サブセット指定可能: AWS / Azure / GCP の 3 クラウドを標準サポートし、呼び出し時に対象クラウドをサブセット指定可能

構造

4層設計パイプラインの全体像

競合時は上位層を優先します（source > canonical > mapping > implementation）。クラウドを追加・変更する場合は Vendor Mapping と Implementation Artifacts のみを差し替えます。

スキル階層と Canonical Model のスコープ

システムコンテキスト図

コンテナ図

コンポーネント図

データ

概念モデル

情報モデル

構築方法

前提条件

• Claude Code（claude.ai/code）
• pandoc（ベンダーソースの HTML → Markdown 変換に使用）

# macOS
brew install pandoc

リポジトリ取得

git clone https://github.com/suwa-sh/multi-cloud-lifecycle-skills.git
cd multi-cloud-lifecycle-skills

グローバルインストール

全プロジェクトで利用する場合は以下を実行します。

./install.sh
# ~/.claude/skills/ にシンボリックリンクを作成

プロジェクト固有インストール

特定プロジェクトのみで利用する場合は以下を実行します。

./install.sh /path/to/your-project
# <project>/.claude/skills/ にシンボリックリンクを作成

install.sh の動作

• .claude/skills/ 配下の各 mcl-* ディレクトリをシンボリックリンクで配置
• 既に同じリンクが存在する場合はスキップ
• リンク先が変わっている場合は再リンク
• 通常ファイル・ディレクトリが既存の場合は警告してスキップ

利用方法

基本的な流れ

Claude Code で対話的に設計を依頼します。スキルは自動的にトリガーされます。上位スキルの出力が下位スキルの入力となるため、Foundation → Shared Platform → Product の順に実行します。

# 1. Foundation（最初に実行）
「AWS と Azure を対象に、3つのBUで foundation 設計をしてください」

# 2. Shared Platform（foundation の後に実行）
「EKS/AKS ベースの共有プラットフォームを設計してください」

# 3. Product（foundation + shared platform の後に実行）
「EC サイトのバックエンド API を設計してください」

対象クラウドの指定

呼び出し時に対象クラウドをサブセット指定できます。

「AWS のみで foundation 設計をしてください」
「Azure と GCP で共有プラットフォームを設計してください」

ヒアリングフロー

入力 YAML が未準備の場合、スキルが選択肢付きのヒアリングを行います。

• ヒアリング 1: 対象クラウド、BU 数、環境構成
• ヒアリング 2: セキュリティ・コンプライアンス要件、ログ保持期間
• ヒアリング 3: 予算責任境界、共有コスト按分ルール

選択肢はテーブル形式（番号付き・推奨マーク付き）で提示されます。一度に最大 3 項目です。

スキルのワークフロー

全スキルは以下の順で処理を進めます。

1. 入力収集（input YAML またはヒアリング）
2. ベンダーソース取得（fetch-vendor-sources.sh）
3. Canonical Model 生成
4. Vendor Mapping 生成（fidelity 評価付き）
5. 競合解決（decision record 作成）
6. Implementation Spec 生成
7. IaC スケルトン生成
8. Conformance Report 生成
9. ターゲットアーキテクチャ Markdown 生成
10. Context YAML 生成（下位スキルへの入力）

ベンダーソースの活用

ソースが未準備でもスキルは動作します。設計実行時にソースが見つからない場合、公式ガイダンスページから最新コンテンツを自動収集して Markdown として保存します。

出力ディレクトリ構造

AWS + Azure で 3 レイヤーをすべて実行した場合、利用プロジェクトに以下の構成が生成されます。

your-project/
├── specs/{layer}/output/         # YAML artifacts（canonical, mapping, impl, context）
├── docs/cloud-context/
│   ├── sources/                  # ベンダーソース（自動収集 or 手動配置）
│   ├── decisions/{layer}/        # 設計判断記録
│   ├── conformance/{layer}/      # 適合性検証レポート
│   └── generated-md/{layer}/     # Mermaid 図付きアーキテクチャ Markdown
└── infra/{layer}/{vendor}/       # IaC スケルトン（Terraform HCL 等）

運用

ベンダーソースの取得・更新

fetch-vendor-sources.sh でベンダー公式ドキュメントを HTML → Markdown に変換して保存します。保存先は利用プロジェクトの docs/cloud-context/sources/{aws,azure,gcp}/ です。

# 全ベンダー・全レイヤーを取得
./scripts/fetch-vendor-sources.sh /path/to/your-project

# AWS の foundation レイヤーのみ取得
./scripts/fetch-vendor-sources.sh /path/to/your-project --vendor aws --layer foundation

# 既存ファイルも強制再取得
./scripts/fetch-vendor-sources.sh /path/to/your-project --force

ベンダーソースの鮮度管理

各ソースファイルのメタデータヘッダに fetched_at（ISO 8601）が記録されます。fetched_at が 90 日以上前のファイルはリフレッシュを推奨します。

# ソースファイルのメタデータヘッダ例
source_url: "https://docs.aws.amazon.com/organizations/latest/userguide/orgs_best-practices.html"
fetched_at: "2026-01-01T00:00:00Z"
vendor: "aws"
layer: "foundation"

sources.tsv による収集対象管理

sources.tsv に vendor / layer / name / url の 4 列 TSV で収集対象を定義します。AWS 13 件・Azure 12 件・GCP 12 件、合計 37 件の公式ドキュメントが登録済みです。

vendor	layer	name	url
aws	foundation	aws-organizations-best-practices	https://docs.aws.amazon.com/...
azure	foundation	azure-landing-zone	https://learn.microsoft.com/...
gcp	foundation	gcp-landing-zones	https://cloud.google.com/...

artifact のライフサイクル管理

• YAML が全 artifact の正本。Markdown は常に YAML からの派生生成物
• status フィールドで進捗を管理（draft → review → approved → superseded）
• ベンダーソース更新後に再生成した場合、差分が意図した変化かを L3 テストで検証

テスト戦略

最低完了条件は Tier A（スキーマ検証 + 適合性チェック + 決定性チェック）と Tier B（IaC 静的検証）です。

evals.json の構造

id・prompt・expected_output・files・assertions で構成されます。

{
  "skill_name": "mcl-foundation-design",
  "evals": [
    {
      "id": 1,
      "prompt": "...",
      "expected_output": "...",
      "assertions": [
        {"id": "canonical-model-exists", "type": "file_exists"},
        {"id": "soc2-addressed", "type": "content_check"}
      ]
    }
  ]
}

各スキルの評価シナリオ

ベストプラクティス

4 層モデルの優先順位遵守

• 設計判断に迷った場合は source > canonical > mapping > implementation の優先順位に従う
• 上位層（ベンダーソース・canonical model）の変更は全ベンダーの下位 artifact に影響
• クラウドの追加・変更時は Vendor Mapping と Implementation Artifacts のみを差し替え

正規化プロセスの遵守

ベンダー固有のガイダンスを canonical model に変換する際は、以下の 5 ステップに従います。

1. ベンダーソースから capability または関心事を特定
2. ベンダー固有の用語を抽象化
3. 測定可能な属性を持つ capability 要件として表現
4. 安定した canonical 識別子を付与（scope.capability_name 形式の snake_case）
5. 追跡可能性のためソース参照を記録

ベンダー固有: "AWS Organizations with SCPs"
Canonical: organization_boundary.policy_enforcement

命名規約:

• 全識別子は lowercase snake_case
• スコープ接頭辞を付与: foundation. / shared_platform. / product.
• ベンダー製品名ではなく capability 名を使用

YAML 正本ポリシーの徹底

全 YAML artifact は common-metadata.yaml スキーマの必須フィールドを含む必要があります。

schema_version: "1.0"
artifact_type: "canonical_model"
skill_type: "foundation"
artifact_id: "foundation-canonical-v1"
title: "基盤 canonical model"
status: "draft"
generated_at: "2026-03-28T00:00:00Z"
source_refs: []
decision_refs: []
inputs_ref: []

ベンダーマッピング対象一覧

Foundation レイヤー:

Shared Platform レイヤー:

Product レイヤー:

fidelity 評価の記録

vendor mapping で各 canonical 要件の充足度を 4 段階で評価・記録します。gap の場合は必ず deviation record を生成し、リスクを明示します。

競合解決の記録

クラウド間で競合が発生した場合は、5 種類に分類して decision record を生成します。デフォルトは最も制限的な解釈を採用します。

ヒアリング運用

• ユーザーへの確認は必ず番号付き選択肢テーブルで提示
• 一度に聞く項目は最大 3 つまでとし、段階的にヒアリング
• 再実行時は specs/{layer}/input/ に入力 YAML を配置することでヒアリングをスキップ可能

チーム運用

• スキルはグローバルインストール（~/.claude/skills/）とプロジェクト固有インストールを使い分け
• mcl-workspace/ は with_skill / without_skill 比較用ワークスペースで、.gitignore 対象
• 生成 artifact はプロジェクトリポジトリに commit（スキルリポジトリには保存しない）
• ベンダーソース（docs/cloud-context/sources/）はプライベートリポジトリで管理

トラブルシューティング

ベンダーソース取得失敗

• FAILED (download): sources.tsv の URL が変更されていないか確認
• FAILED (content too small: N bytes): JS リダイレクトが解決できていない可能性
• pandoc 未インストール: brew install pandoc で導入

# エラー例と対処
ERROR: pandoc が見つかりません
# → brew install pandoc

FAILED (download)
# → sources.tsv の該当 URL をブラウザで確認し、正しい URL に更新

FAILED (content too small: 500 bytes, min: 1000)
# → リダイレクト先の URL を直接 sources.tsv に記載

YAML スキーマ検証エラー

• artifact_id が ^[a-z][a-z0-9-]+$ 形式でない場合はエラー
• generated_at が ISO 8601 形式でない場合はエラー
• artifact_type が定義外の値の場合はエラー

# NG: スキーマ違反例
artifact_id: "Foundation_Canonical"   # 大文字・アンダースコアは不可
generated_at: "2026/03/28"            # スラッシュ区切りは不可

# OK: 修正例
artifact_id: "foundation-canonical-v1"
generated_at: "2026-03-28T00:00:00Z"

スキル間のコンテキスト連携エラー

mcl-shared-platform-design が foundation-context.yaml を参照できない場合は、mcl-foundation-design を先に実行してください。

# コンテキストファイルの確認
ls specs/foundation/output/foundation-context.yaml
ls specs/shared-platform/output/shared-platform-context.yaml

IaC スケルトンのプレースホルダー

# TODO: コメントが付いている箇所はプレースホルダーです。実際の値を設定してから apply します。

# TODO: 実際の AWS アカウント ID に置き換えること
account_id = "123456789012"

gap fidelity の対処

gap と評価された canonical 要件は、そのベンダーでは native に実現できません。deviation record を生成し、リスクと代替手段を明示します。

# deviation_record.yaml 例
deviation_type: "gap"
canonical_element: "foundation.policy_enforcement"
vendor: "azure"
risk_level: "medium"
mitigation: "Azure Policy と Defender for Cloud の組み合わせで代替"
approval: "pending"
expiry: "2026-12-31"

Web ソース取得失敗時のフォールバック

• Web 取得に失敗した場合は、モデルの既存知識で設計を継続
• エラーをユーザーに通知し、設計結果に「Web 取得失敗のため知識ベースを使用」と記載
• 設計完了後に手動でソースを配置し、再生成することを推奨

まとめ

multi-cloud-lifecycle-skills は、4層設計パイプライン（Vendor Sources → Canonical Model → Vendor Mapping → Implementation Artifacts）と3スキル階層（foundation → shared-platform → product）により、ベンダーロックインを回避しつつ各クラウドのベストプラクティスに準拠したマルチクラウド基盤設計を、Claude Code との対話で一貫して構築できるスキル群です。fidelity 評価・競合分類・deviation record による設計判断の追跡可能性が、マルチクラウド環境特有の複雑さを管理可能にしています。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• GitHub
  • suwa-sh/multi-cloud-lifecycle-skills
  • mcl-common SKILL.md
  • mcl-foundation-design SKILL.md
  • mcl-shared-platform-design SKILL.md
  • mcl-product-design SKILL.md
  • common-metadata.yaml
  • canonical-model.yaml テンプレート
  • vendor-mapping.yaml テンプレート
  • install.sh
  • canonicalization-rules.md
  • mapping-rules.md
  • conflict-classification.md
  • vendor-source-policy.md
  • implementation-pack-schema.md
  • fetch-vendor-sources.sh
  • sources.tsv
• 公式ドキュメント
  • Claude Code