geekfujiwara/codeappsdevelopmentstandard/architecture

Power Platform 共通アーキテクチャデザインスキル

ユーザー要件から Power Platform のどのコンポーネントを使うか を判断し、全体アーキテクチャを設計する。 各コンポーネントの得意領域・制約・統合パターンを把握し、迷わず最適な構成を選定するためのスキル。

このスキルの位置づけ: Phase 1（設計）の最初に実行する。個別コンポーネントのスキルに入る前に、まず要件を深掘りして全体像を確定させる。

SharePoint URL だけでは直接接続の指示と解釈しない。 Code Apps の業務データは、直接接続・継続利用が 明示された場合を除き Dataverse に移行する。URL は仕様・移行元の参照情報として扱う。 dataverse でスキーマを構築し、data-migration で承認付き移行・照合を行う。 ナレッジとしての文書参照と Code Apps の業務データ保存先は区別する。

0. 要件ヒアリング（Phase 1 の最初に必ず実行）

クイックスタート時は提案先行モードを優先する

standard/references/quickstart.md Step 1 から来た場合は、認証準備後の要望確認で得た回答・環境情報・資料・ spec-builder の結果を引き継ぎ、以下の通常ヒアリング表を一から質問しない。 要望確認の回答前なら、この提案工程へ進まず AskUserQuestion の回答を待つ。 資料がなければワークスペース名から提示済みのアプリ案のうち、選ばれた案を具体化し、方向性を聞き直さない。 業界知識とベストプラクティスを使って、事実・仮説・推奨を分けた To-Be 業務、AI 改善、 Code Apps + Dataverse を既定とする構成、段階的な実装計画まで具体化する。 未確認の固有規程・人数・価格・契約は創作せず、仮説または要確認とする。 白紙の要件ヒアリングや既存システムの単純なリフト&シフトで終わらせない。

業務フロー図とアーキテクチャ図を Mermaid コードブロックでチャットと Markdown の両方へ出力する。 業務フローは spec/output/docs/business-requirements.md、構成・AI 改善・実装計画は spec/output/docs/design-requirements.md に既存内容を保護して統合する。 図は質問ポップアップ内に入れない。推奨案・代替案・判断材料はチャットに示す。 既存リポジトリの templates/ / samples/・マニフェスト・前提条件を調べ、適合するテンプレートの パス・選定理由・不足機能を示す。既知事項や通常の実装判断で AskUserQuestion を繰り返さない。 要望確認の回答・資料・テンプレート・読み取り API で分かることは自分で調べ、 承認済みの開発範囲では構成案ごとの再承認を求めず、環境調査・フル構成デプロイ・実動作検証へ進む。 認証や環境選択の回答後に利用者へ工程を投げ返さず、構成・各 URL・検証結果と文書更新まで同じタスクで進める。 設計・実装・デプロイ・移行・追加費用の承認範囲は区別する。

通常モードのヒアリング

IT に詳しくないエンドユーザーに向き合うプロの IT コンサルタントとして振る舞う。 専門用語を使わず、業務課題・現状・理想の姿を引き出すことを最優先にする。

AskUserQuestion で深掘りする項目

既知の情報は再質問せず、必要な不足事項だけを 1 問ずつ確認する。

全体像が掴みにくいときは、Excel・業務フロー図・画面イメージ・帳票の共有を依頼する（/spec-builder でドキュメントから要件整理も可）。要件が明確になったら、以下の判断フローチャートでコンポーネントを選定し設計提案へ進む。

実装前提ゲート（コンポーネント選定後に 1 回だけ）

構成案が固まったら、実装開始前に standard の共通事前確認契約を 確認する。クイックスタートでは Step 0 の要望確認の承認範囲を引き継ぎ、調査で埋められる値は 自律的に解決する。一律の AskUserQuestion を追加せず、本人の決定が不可欠な不足事項だけ確認する。 特に次を構成図と見積もりに含める。

既知の事項は再質問しない。Code Apps は共通契約の開発優先方針に従い、 環境設定・DLP・管理者権限の未調査を理由に実装を止めず、必要な実装先・承認範囲だけを確認して進む。 それ以外の製品固有の公開・プレビュー承認は各専門スキルに従う。 AI チームメイトでは Agent 365 と Frontier、Cowork では Microsoft Copilot ライセンスと Frontier、 Power Pages では認証方式と table permission をそれぞれ別条件として扱う。

1. コンポーネント早見表

Code Apps と Copilot Managed Runtime の選定:

比較リファレンスを参照する。

現時点では Code Apps は GA、Copilot Managed Runtime は Public Preview である。

@microsoft/power-apps から @microsoft/managed-apps への package 置換を移行手段として扱わない。

Managed Runtime を採用した場合の実装は `managed-runtime` スキル で行う。

2. 判断フローチャート

2.1 メイン判断: 「何を実現したいか？」

ユーザー要件
    │
    ├─ 対話型の体験が必要？ ──→ YES ──→ 対話の性質は？（下の 2.1.1 で分岐）
    │                          NO
    │                          ↓
    ├─ イベント/条件に基づく自動処理？ ──→ YES ──→ 【Power Automate】（§4 へ）
    │                                     NO
    │                                     ↓
    ├─ データの閲覧・編集 UI が必要？ ──→ YES ──→ 【Code Apps / Power Pages or Azure / Model-Driven Apps】（§5 へ、Canvas Apps は常に対象外）
    │                                    NO
    │                                    ↓
    ├─ Power Automate フロー内にイベント駆動（非チャット UI）で AI 処理を組み込みたい？
    │     （例: 通知・リマインドの文面生成、条件判定への AI 組み込み） ──→ YES ──→ 【AI Builder】（§6 へ）
    │                                   NO
    │                                   ↓
    └─ データモデル/ストレージが必要？ ──→ YES ──→ 【Dataverse のみ】

社内汎用業務は原則 Copilot Studio v2 スキル + Dataverse MCP（+ Code Apps）で実現する。AI Builder は「通知・リマインド等で

Power Automate フロー内に AI 処理を組み込みたい」イベント駆動・非チャット UI のケースに限定して採用する（§6 参照）。

2.1.1 「対話型が必要」の分岐: まず Copilot Studio v2 スキル + Dataverse MCP を検討する（★重要）

対話型の体験が必要 = 即 Copilot Studio（v1）ではない。 利用者が 自分から AI に話しかけて Dataverse へ登録・照会し、Code Apps で結果を見るような 「チャットで話しかけて実行する」業務は、Copilot Studio v2 スキル + Dataverse MCP を第一候補にする。 環境制約が少なく作りやすいため、Cowork プラグインより先に検討する。

対話型の体験が必要
    │
    ├─ ① ユーザーが能動的に AI へ話しかけて解決する
    │     （Dataverse への登録/照会 + Code Apps で閲覧。Teams / Copilot Studio 上で完結）
    │        ──→ ★【Copilot Studio v2 スキル + Dataverse MCP】を第一候補（→ copilot-studio-v2 スキル）
    │                 M365 Copilot 上での利用が必須要件の場合かつ会社環境で Cowork の利用が許可されている場合のみ Cowork プラグインを追加検討
    │
    ├─ ② 自律的に起動して動く必要がある
    │     （メール受信・Teams 返信・スケジュール等のイベントで自動実行、無人で判断・応答）
    │        ├─ トリガーが Dataverse のレコード作成/更新 ──→ ★【Copilot Studio v2 ワークフロー（Agentflow: Dataverse トリガー + エージェント ノード）】（設計リファレンス パターン F）
    │        └─ トリガーがメール/Teams/スケジュール等の外部イベント ──→ 【Copilot Studio（Workflow / トリガー）+ Power Automate】（§3・§4 へ）
    │
      ├─ ③ Code Apps に AI 対話を組み込む
      │        ├─ Copilot Studio の標準チャット UI をそのまま表示
      │        │    ──→ ★【Copilot Studio v2 Web app iframe】を第一候補
      │        ├─ 業務 UI と要求・結果を統合（非同期でよい）
      │        │    ──→ ★【Code Apps + Dataverse 要求/結果 + Workflow Agent ノード + v2】
      │        │          （設計リファレンス パターン F2）
      │        └─ 親アプリからのメッセージ注入・応答イベント取得・ストリーミングが必須
      │             ──→ 【Copilot Studio v1 の直接 SDK 連携】（§3 へ）
      │
      ├─ ④ 一般 Web サイトに表示する
      │        ├─ 標準チャット UI の iframe ──→ 【Copilot Studio v2 Web app】
      │        └─ WebChat SDK で UI・メッセージを制御 ──→ 【Copilot Studio v1】（§3 へ）
    │
      └─ ⑤ カスタムエンジンエージェントとして Teams / M365 Copilot に公開する
          （独自モデル・独自ツール・コードファーストのバージョン管理が要る
           ★または、エージェント自身がメールアドレス・予定表・権限を持つ「人」として働く）
             ──→ 【Agent 365 / AI チームメイト】（§7 へ）

使い分けの原則:

- ユーザーがチャットで話しかけて実行するケース（能動的・有人）は Copilot Studio v2 スキル + Dataverse MCPで実装する。

環境制約が少なく作りやすいため、第一候補とする。

Dataverse + Code Apps で組んだ業務データへのアクセスは、原則 Copilot Studio v2 スキル経由の自然言語操作を提案する。

M365 Copilot との統合が必須要件の場合のみ Cowork プラグインを追加検討（Global Admin 等の権限が別途必要。会社環境で Cowork の利用が許可されている場合のみ推奨）。

- Copilot Studio でエージェントを作るのは次の 4 つのケース:

1. チャットで話しかけて実行するケース（v2 スキル + Dataverse MCP）— 第一候補（①）

2. 自律的なケース — イベント/トリガーで無人起動し、自分で判断・応答・データ更新する（②）

3. Code Apps に組み込むケース — 標準 UI は v2 iframe、業務 UI 統合は v2 ワーカー方式、直接 SDK 制御が必須なら v1（③）

4. 一般 Web サイトへ表示するケース — 標準 UI の v2 iframe、または UI を制御する v1 WebChat SDK（④）

- v2 ワーカー方式（③）は、Code Apps がユーザー所有の要求行を Dataverse に作成し、Workflow の Agent ノードが

既存の発行済み v2 を呼び、完全応答を結果行へ保存して Code Apps が読む。v2 のフラット Python スキルを再利用できるため、

JSON・文書・設計候補などの構造化生成では標準の第一候補とする。これは ExecuteCopilotAsyncV2 や WebChat による

直接埋め込みではない。重複 Claim、要求者認可、相関 ID、タイムアウト後の同一 receipt 照合、AI 結果の独立検証を必須とする

（設計リファレンス パターン F2）。

- 自律的なケース（②）で、すでに Copilot Studio v2 スキルを採用している場合は、Power Automate + v1 トリガーではなく Copilot Studio v2 ワークフロー（Agentflow: Dataverse トリガー + エージェント ノード）を標準の第一候補とする。既存の発行済み v2 スキルをエージェント ノードから呼び出せるため、Power Automate も v1 も追加せずに同一アーキテクチャで完結できる（設計リファレンス パターン F）。

- 構築手順は `copilot-studio-v2` スキル（①）、Cowork の UI 併設方針は §5 を参照。

- 参照したいデータが Dataverse に無い場合（既存の基幹 DB・ファイルサーバー・業務 API）は、

上記のどの分岐であっても 自前 MCP Server（Azure Functions） を併せて検討する（→ §6.5）。

同じ MCP Server を Copilot Studio v2 にも Cowork にも登録できるため、公開先は後から増やせる。

2.2 複合パターン（最も多い）

多くの要件は 複数コンポーネントの組み合わせになる（CRUD+通知、対話+データ操作、対話+外部連携、対話+定期実行/イベント駆動、AI 分析+対話、外部ポータル+データ操作、フルスタック）。各パターンの構成・典型ユースケースの一覧表は 設計リファレンス を参照。

3. Copilot Studio を使う判断ポイント

★ まず §2.1.1 を確認する。「ユーザーがチャットで話しかけて Dataverse に登録/照会する」有人の対話は

Copilot Studio v2 スキル + Dataverse MCP を第一候補とする。Code Apps への標準チャット表示は v2 Web app iframe、

業務 UI と要求・結果を統合する場合は Dataverse 要求/結果 + Workflow Agent ノードによる v2 ワーカー方式を標準提案する。

v1 は親アプリからのプログラム的な会話制御、WebChat SDK、または既存 v1 資産の継続利用が必要な場合に採用する。

使う: 自律起動（イベント/トリガー）での無人実行・アプリ埋め込み/Web 公開・複数ツールの自律オーケストレーション・ナレッジ検索・要約/分析/レポート生成。 使わない（→ 代替）: ユーザーが能動的にチャットで登録/照会するだけ → Copilot Studio v2 スキル + Dataverse MCP（Cowork は M365 Copilot 必須時かつ会社環境で利用が許可されている場合のみ）／確定手順の 100% 実行・大量一括処理・LLM 不要の条件分岐 → Power Automate／UI 入力編集 → Code Apps／承認ワークフロー → Power Automate。