architecture-well-architected-commerce

VTEX における Well-Architected Commerce

このスキルを使用する場合

VTEX のコマース機能を横断するタスクや、意思決定を伴うタスクでこのスキルを使用してください。単一の製品スキルで作業内容がすでに十分に定義されている場合は使用しないでください。

• ソリューションアーキテクチャ（ストアフロントのモデル＋統合＋運用）を定義またはレビューする場合。
• VTEX のネイティブ機能とカスタムサービス（IO アプリ、外部 BFF、ミドルウェア）のどちらを選ぶか決める場合。
• アーキテクチャまたは準備状況のレビュー（セキュリティベースライン、スケーラビリティの方針、可観測性、デリバリープロセス）を実施する場合。
• FastStore、Headless、VTEX IO、Marketplace、Payments、またはその他の VTEX モジュールにまたがる作業の範囲を定める場合。

タスクがすでに特定の範囲に限定されている場合（例：「PPP の返金を実装する」→決済トラック、「Feed v3 と Hook のどちらを選ぶか」→マーケットプレイストラック）は、このスキルを製品スキルの代わりに使用しないでください。

3 つの柱（フレームワーク）

これらの柱は、あらゆるアーキテクチャ上の選択に適用する Well-Architected Commerce の視点です。以下の概要は社内フレームワークの説明に沿っています。目標、基本価値、重点的に取り組むべき重要領域の全容については、Well-Architected Commerce MCP（およびプログラムの正式なフレームワーク文書）を参照してください。

技術基盤

目標： 信頼を得られる、安全で信頼性が高く、コンプライアンスに準拠した基盤を構築します。

基本価値： 信頼性（一貫したパフォーマンス）、信頼（透明性と説明責任を備えたプロセス）、誠実性（データ、コード、リソースの倫理的な取り扱い）。

重要領域（例）： 高度なセキュリティ（データ保護、トランザクションセキュリティ、脅威への認識）、信頼性の高いインフラストラクチャ（可用性、スケーラビリティ、復旧）、コンプライアンス（規制、監査証跡、モニタリング）。継続的な学習により、ガイダンスをテクノロジーと VTEX の方針に合わせて最新の状態に保ちます。

Future-proof や Operational Excellence に取り組む場合も、この柱の要件を緩和することはありません。

将来への備え

目標： ビジネスやプラットフォームの進化に合わせて、適応性と保守性を維持できるソリューションを構築します。

基本価値： イノベーション（最新の VTEX および業界のベストプラクティス）、シンプルさ（包括的な価値。カスタム領域を必要最小限に抑え、ソリューション全体の一貫性を保つこと）、効率性（労力とプラットフォームの活用を最適化すること）。

重要領域（例）： スケーラブルなソリューション、ビジネスや市場への適応性、モジュール型／コンポーザブルな設計、迅速なデプロイ（アジャイルなデリバリー、CI/CD）、システム統合（VTEX を中心とした API ファーストの接続）。

オペレーショナルエクセレンス

目標： データに基づいた意思決定と、説明責任を伴う実行によってプログラムを運営します。

基本価値： 正確性、誠実性、説明責任、データに基づく意思決定（および規律としてのオペレーショナルエクセレンス）。

重要領域（例）： プロセスの最適化（効率性、リーン、オートメーション）、データに基づく戦略（分析、予測的なインサイト、モニタリング）、パフォーマンスの向上（VTEX のインサイト、継続的なモニタリング、俊敏性）、顧客体験（パーソナライゼーション、フィードバック、オムニチャネル）。

製品トラックへの振り分け

プラットフォーム固有の方法は、このメタスキルではなく製品スキルに記載します。柱との整合性を確認した後、次を使用してください。

トピック	トラックスキル
VTEX IO のサービスパス、エッジ／CDN の動作、Cache-Control とデータスコープの違い	vtex-io-service-paths-and-cdn
VTEX IO のアプリケーションパフォーマンス（キャッシュレイヤー、AppSettings、並列フェッチ、テナントスコープのインメモリーキー）	vtex-io-application-performance
Master Data のストレージ適合性（MD が適切な保存先かを検討すること）、購入パス、BFF、信頼できる唯一の情報源	vtex-io-masterdata
Marketplace のフルフィルメント、シミュレーション、統合フロー	marketplace-fulfillment（および関連するマーケットプレイススキル）

VTEX 全体に適用されるルール（引き続きアーキテクチャレベル）：

1. VTEX IO よりもネイティブ機能と OOTB を優先 — VTEX のネイティブ機能と設定を、VTEX IO 拡張より優先してください。適切なネイティブの方法がない場合に限り IO を使用し、それでも IO を選ぶ場合は、ネイティブでは不適切な理由を記録してください。

2. シンプルさとコモディティ機能 — コモディティ機能にはプラットフォームネイティブの動作を優先してください。カスタム開発は、プロセスや責任範囲の問題を置き換えるためではなく、差別化要因や真の不足部分に限定してください。

3. 統合の規律 — ホップ数を減らし、責任範囲を明確にし、API 中心の設計を優先してください（Future-proof system integration を参照）。詳細なパターンは IO、ヘッドレス、マーケットプレイスの各スキルに記載されています。

判断ルール

1. 主要な判断はすべて、1 つ以上の柱に分類してください（**三つの柱（フレームワーク）**を参照）。どの柱にも当てはまらない選択肢については、それが本当に必要かどうかを検討してください。
2. プラットフォームを拡張する場合（VTEX IO、Master Data、統合）、製品トラックへの振り分けの表を使用してください。キャッシュ、パス、MD の使用方法、マーケットプレイスのフローは該当するスキルに従って実装し、その選択が将来への対応力と運用の卓越性をどのように支えるかを記録し、技術基盤を損なわないようにしてください。
3. カスタムコードが引き続き必要な場合は、統合ホップ数の削減を優先してください。ホップが増えるたびに、障害の発生要因と運用負荷が増えます。サービスやバックエンドの追加が妥当なのは、障害ドメインの分離やチーム境界の明確化につながる場合であり、デフォルトではありません。
4. アーキテクチャ上の選択が明確になったら、実行を製品トラックスキルに割り当ててください（製品トラックへの振り分けと関連スキルを参照）。このスキルは方針を定め、製品スキルは VTEX 固有の要件を徹底します。
5. 運用の規律には、定義可能なメトリクスと責任者（誰が運用し、インシデントをどのように検知し、変更をどのようにリリースするか）が必要です。文書化されていない「ベストエフォート」の運用は、設計が簡素であっても運用の卓越性に反します。

厳守事項

制約：速度を優先してテクニカルファンデーションを省略しない

セキュリティ、認証情報の取り扱い、PCI スコープ、プライベート API へのアクセスは、必ず VTEX および業界の基準に従う必要があります。シークレットを漏えいさせたり、PCI スコープを拡大したり、信頼できないクライアントからプライベート API を呼び出したりするアーキテクチャ上の近道は、決して開発速度とのトレードオフとして許容できません。

重要な理由 — データ侵害、不正行為、アカウントの乗っ取りは顧客の信頼を損ない、プログラム全体のコンプライアンス態勢を無効にする可能性があります。

検出方法 — 設計上、VTEX_APP_KEY／VTEX_APP_TOKEN、カード情報そのもの、または購入者のセッショントークンをブラウザーコード、公開リポジトリ、ログに配置する場合は、停止して、プロダクトスキルを活用した設計（ヘッドレス BFF、決済 Secure Proxy など）に見直します。

適切な対応 — データと API を分類し、シークレットとプライベート API の呼び出しはサーバー側に保持します。選択した統合方式に応じた PCI および認証ガイドを参照します。

Architecture decision log:
- Private VTEX APIs → server-side only (BFF or IO service).
- Card data → Payment Provider Protocol / Secure Proxy patterns only.

不適切な対応 — 「速度を優先して、SPA から Checkout OMS を呼び出します」や「開発の利便性のため、アプリトークンを NEXT_PUBLIC に保存します」。

制約：将来への備えとは、複雑さの最大化ではなく、根拠のある複雑さを選ぶこと

新しいサービス、キュー、データストアを追加する場合は、それぞれに明示された担当者、障害モード、そして柱（分離、スケーリング、規制上の境界など）に結び付いた理由が必要です。サービスを無制限に増やすことは、シンプルさというコアバリューに反します。

重要な理由 — ドキュメント化されていない分散システムは運用、デバッグ、アップグレードが不可能になり、コストとインシデントの対応時間が増加します。

検出方法 — 柱との対応付けなしに「柔軟性のため」という理由で新たなボックスを図に追加している場合は、異議を唱えます。明確なモジュールを持つ 1 つの VTEX IO アプリに 2 つのサービスを統合できる場合は、統合するか、導入を見送ります。

適切な対応 — 次のように記録します。「サービス X はパートナーの Webhook 変換を担当する。テクニカルファンデーション：監査ログ。将来への備え：交換可能なアダプター。運用：オンコール担当 Z。」

Before adding a service:
1. Which pillar(s) require it?
2. What fails if it is absent?
3. Can native/OOTB, existing BFF, or a minimal IO surface cover it?

不適切な対応 — 運用モデルがない、またはプロダクトスキルに記載された VTEX 統合の制約に従わず、デフォルトで「マイクロサービスアーキテクチャ」を採用すること。

制約：VTEX IO 拡張は、ネイティブ／標準搭載の選択肢を使い切った後に行う

すでにネイティブまたは標準搭載で存在する機能（あるいは設定や標準的な統合で実現できる機能）を実装するためにVTEX IOを選択し、例外とする根拠を文書化しない場合、長期的なコスト、アップグレードのリスク、運用上の負債が生じます。

重要な理由 — 重複した実装はプラットフォームの進化から取り残され、アップグレード時に破損し、差別化に充てるべきエンジニアリングリソースを消費します。

検出方法 — ネイティブ／標準搭載の代替手段を検討した一覧を示す前に、「X 用の IO アプリを構築します」と提案している場合は要確認です。Help Center または Developers ガイドに標準的な方法が記載されているにもかかわらず、「なぜネイティブ機能を使わないのか」が文書化されていない場合も要確認です。

適切な対応 — 意思決定ログに次のように記録します。ネイティブ／標準搭載の選択肢を評価 → [具体的な不足点] のため不採用 → IO の適用範囲はその不足点のみに限定。

Native/OOTB check before IO:
1. What does VTEX ship for this (admin, module, API, partner app)?
2. If still building IO: what exactly cannot be done natively?

不適切な対応 — ネイティブ機能では要件を満たせないという根拠なしに、「常に IO でカスタマイズします」や「ネイティブ機能を学ぶより IO のほうが簡単です」とすること。

制約：Master Data は汎用データストアでも、チェックアウトのクリティカルなデータストアでもありません

Master Data の ストレージモデル、制限、整合性 を理解せずに使用したり、すべてのカスタムデータのデフォルトの保存先として使用したり、購入のクリティカルパスで使用したりすると、規模の拡大に伴い、レイテンシー、信頼性、サポートに関する問題が発生するリスクがあります。

重要な理由 — MD は、ドキュメント化されたエンティティのパターンに最適化されており、チェックアウトの途中で任意の OLTP を処理する用途には向いていません。誤用すると、収益と安定性に影響します。

検出方法 — 同期的な注文フローで、カートを変更するたびに MD を呼び出している。「すべてのカスタムフィールドを MD に入れる」としながら、スキーマを適切に管理していない。カタログ、プロフィール、OMS ネイティブの選択肢を評価する前に MD を選択している。

適切な対応 — vtex-io-masterdata に従います（ストレージの適合性、カタログを優先、BFF）。正当なユースケースに限定してエンティティを設計します。購入時の必須ではない MD アクセスは、クリティカルパスから外すか、非同期パターンを使用します。

Before MD for new data:
1. Can Catalog, Checkout, Profile, or another native store hold this?
2. Is access in the hot path of purchase? If yes, redesign or justify.

誤った対応 — ピーク時の負荷で厳格なパフォーマンスの証明がないまま、「あらゆる用途に MD を使う」、または MD とのラウンドトリップが完了するまでチェックアウトをブロックする。

推奨パターン

1. セッション内で 3 つの柱（フレームワーク）についてチームの認識を合わせます。フレームワークの説明を詳しく確認する場合や、最新の説明が必要な場合は、Well-Architected Commerce MCP を使用します。
2. IO、MD、マーケットプレイスに関する懸念事項を、製品トラックへの振り分けの表に従って振り分けます。まずネイティブ/OOTB を検討し、その後、根拠を文書化したうえで、対象を限定して IO または MD を使用します。
3. 差別化要因と運用上の課題を分けます。カスタム開発ごとに、戦略的な差別化要因かプロセス／運用上の改善かを明記します。後者の場合は、コードよりもプロセスやネイティブツールを優先します。
4. 簡潔な意思決定ログを作成します。対処した柱、ネイティブと IO と MD の選択、「ネイティブを選ばなかった理由」（該当する場合）、未解決のリスクを記録します。
5. 実装ストリーム（ストアフロント、決済、IO、マーケットプレイス）ごとに、関連する製品トラックのガイダンスを添付します。
6. 本番稼働前にオペレーショナルエクセレンスを見直します。プラットフォームで汎用品を提供し、チームはサポートと差別化要因に注力するとともに、指標、リリースプロセス、インシデント対応も確認します。

よくある失敗パターン

• メタスキルの過剰使用 — 製品スキルですでに完全に仕様が定まっている問題（例：PPP の冪等性ルール）に、アーキテクチャの説明を費やす。
• 柱の形骸化 — 3 つの柱をスライドに掲げても、具体的な意思決定や責任の所在を変えない。
• IO をデフォルトにする偏り — ネイティブ/OOTB では要件を満たせないことを確認する前に VTEX IO に頼り、カスタマイズを最初の手段にする。
• MD を Postgres のように扱う — モデリングせずにあらゆるエンティティに Master Data を使用したり、チェックアウトを同期的な MD の読み書きに結び付けたりする。
• シンプルさの誤解 — 「シンプルなアーキテクチャ」を「何でもこなす大規模な IO アプリ 1 つ」と解釈し、「カスタム領域を最小限にし、ネイティブ機能を最大限に活用する」という意味を見落とす。
• プロセスより技術を優先 — 運用上のワークフローの破綻を、責任の所在、SLA、トレーニングを見直すのではなく、自動化やコーディングで補おうとする。
• 汎用品のカスタマイズ — VTEX が標準製品としてすでに提供している動作の独自実装を顧客の技術チームが保守し、本当の差別化要因に割く余力をなくす。
• 引き継ぎの不足 — アーキテクチャの文書に、開発者が従うべき製品スキルや VTEX の公式ガイドへの参照がない。

レビューチェックリスト

• Technical Foundation に関する懸念（認証、シークレット、PCI の対象範囲、プライベート API）が明示的に扱われていますか？
• VTEX IO の各拡張について、まず ネイティブ／OOTB が評価されましたか？ また、IO を選択した場合、**「なぜネイティブではないのか」**が文書化されていますか？
• Master Data を使用する場合、チームは MD のアーキテクチャ（「参考資料」を参照）を理解していますか？ また、強く正当化されない限り、MD は購入のクリティカルパスから外れていますか？
• 各カスタムコンポーネントは、差別化要因と運用／プロセス上のギャップのどちらかに分類されていますか？ また、新しいコードを追加する前にプロセスの改善が検討されていますか？
• 将来への備えはできていますか？ 新しいサービス、キュー、データストアごとに、オーナー、障害モード、柱に基づく理由が定められていますか？ 動機のない拡大はありませんか？
• 統合のホップ数は最小限ですか？ 追加のサービスは、障害の分離またはチームの境界によって正当化されていますか？
• オペレーショナルエクセレンスでは、プラットフォーム上のコモディティ機能、サポートと差別化要因への明確な注力に加え、メトリクス、監視、リリース／インシデントのオーナーシップが示されていますか？
• すべての実装ストリームがプロダクトトラックのスキルに対応付けられていますか？
• プラットフォーム固有の制約がある領域について、公式の VTEX ドキュメントへのリンクが設定されていますか？

関連スキル

• vtex-io-service-paths-and-cdn — service.json のパス、エッジ／CDN、セッションの動作。
• vtex-io-application-performance — LRU／VBase、AppSettings、並列フェッチ、共有ポッド上のテナントキー。
• vtex-io-app-contract — IO マニフェスト、ビルダー、ポリシー（ネイティブ／OOTB の方法が除外された後にのみ使用）。
• vtex-io-masterdata — Master Data v2 のストレージ適合性の精査、BFF、単一の信頼できる情報源。
• headless-bff-architecture — ヘッドレス向けの BFF と認証情報の境界。
• payment-pci-security — PCI と Secure Proxy の制約。
• faststore-storefront — GraphQL 拡張とデータレイヤー。
• marketplace-order-hook — マーケットプレイスの注文統合パターン。

参考資料

• ヘッドレスコマースの概要 — ストアフロントの統合モデルとプラットフォームの境界
• エンジニアリングのベストプラクティス — Technical Foundation に沿ったスケーラビリティと IO 開発のプラクティス
• Master Data v2 での JSON スキーマの使用 — MD を選択する前に確認する MD のストレージモデルとスキーマの動作
• レート制限エラーを回避するためのベストプラクティス — VTEX API との信頼性の高い統合
• VTEX における PCI DSS 準拠 — 決済セキュリティの基本要件
• アプリケーションキーを使用するためのベストプラクティス — API キーの適切な管理と信頼性