geekfujiwara/codeappsdevelopmentstandard/standard

Power Platform 包括開発標準スキル

全スキル共通の開発基盤。このスキルが扱うのは 認証 / .env / ソリューション運用 の 3 テーマのみ。 個別コンポーネントの設計・構築ルールは各専門スキルが持つ（→ スキルカタログ README）。

クイックスタートは認証後の一度の確認から開発デプロイ・検証まで継続する

リポジトリ URL と「クイックスタート」を依頼されたら quickstart.md を優先する。 .github/agents / .github/skills / .gitignore を安全に配置しただけでは停止せず、 利用可能な環境情報取得 → 共通認証・.env・認証キャッシュの再利用検証まで実行する。 認証準備後は AskUserQuestion で要望確認し、必ず回答待ちで一旦停止する。 資料があれば対象資料からの継続・対象変更・準備までを選べる形にし、 資料なしならフォルダー名から具体的なアプリ案を複数提示して選んでもらう。 回答前に資料変換・仕様作成・設計提案へ進まず、継続回答後は Step 0〜3 の契約に従い、 ルートの業務資料を spec/input/ へ整理 → spec-builder → architecture・既存テンプレート提案 → 認証キャッシュで既存環境・必要時の Azure を調査 → フル構成の開発デプロイ・実動作検証まで進む。 以降は自分で分かることを調べ、既知事項や通常の実装判断で AskUserQuestion を繰り返さない。 要望確認の選択肢には、資料・テンプレートに基づく開発デプロイ・テストまでの範囲を明記する。 白紙の業務ヒアリングではなく、事実・仮説を分けた業務改善と AI 活用の推奨を先に示す。 業務フローと構成の Mermaid 図をチャットと Markdown の両方へ出す。図は質問ポップアップ内に入れない。 例外的に本人の判断が不可欠な事項だけ質問し、承認済みの開発範囲では提案の都度停止しない。 各専門スキルのプレデプロイ・品質テスト・デプロイ後の検証を行い、実際の構成・各 URL・文書を報告する。 必須構成が全て検証済みの場合だけ「全て完了」とし、未検証・承認待ちは明示する。 環境スキャンは接続先等のメタデータ取得であり、DLP / ACP・Code Apps 許可の事前診断とは分ける。 共通認証・承認・既存ファイル保護は省略せず、サインインや回答待ちの後は同じタスクを再開する。

サブリファレンス（必要に応じて参照）

共有ユーティリティ（複数スキルから参照される横断リファレンス）

以下は単一の専門スキルに属さず複数スキルから参照されるため、共通基盤である standard/references に置いている。各スキルの SKILL.md からリンク済み。

大前提: 一つのソリューション内に開発

初回に本人が承認したアカウント・Edgeプロファイル・必要時の追加認証許可を Git除外済み .env の PP_AUTH_* 設定へ記録する。 トークンはOS暗号化キャッシュ、AuthenticationRecordはホームで管理し、.env に保存しない。 auth_helper.get_token() は保存済み許可がある場合に限り、追加認証要求からブラウザー認証へ戻る。 SDK credentialの自動対話は無効のままなので、SDK操作前に共通get_tokenで必要scopeを準備する。 Code Appsのnpm CLIは別キャッシュとして 認証運用 で準備する。 認証許可は業務書き込みやデプロイの許可を兼ねず、CIでは対話を禁止する。

Dataverse テーブル・Code Apps・Power Automate フロー・Copilot Studio エージェントは すべて同一のソリューション内 に含める。 .env の SOLUTION_NAME と PUBLISHER_PREFIX を全フェーズで統一して使用する。

既定の開発契約（全スキル共通）

• SharePoint URL だけでは直接接続の指示と解釈しない。 Code Apps の業務データは Dataverse に移行して利用する。URL は既存仕様・移行元の参照情報であり、shared_sharepointonline を自動追加しない。SharePoint の継続利用・直接接続が明示された場合だけ例外とする。
• 移行は dataverse でスキーマを構築し、data-migration で取得済み CSV / JSON のマッピング・承認・投入・照合を行う。URL の受領だけをデータ読み取り・書き込み・削除・同期への承認としない。移行元の変更や削除は行わない。
• 環境チェックを明示的に依頼されない限り、すぐに開発を開始する。 DLP / ACP、Code Apps 許可、マネージド環境、MCP、管理者ロールの網羅確認を先行させず、管理 API が読めないことを開発停止理由にしない。
• 既知の対象環境・ソリューション・認証を再利用し、Code Apps は scaffold → init → ローカル predeploy / build → 対象環境への初回 push を優先する。初回 push はテーブル全件構築・データ移行・ローカライズの完了を待たない。未接続画面はその旨を表示し、データ接続後に改善デプロイする。
• 障害時だけ admin の権限確認付き復旧 へ進む。原因に関係する委任権限・対象範囲を確認し、実行可能な診断・承認済み最小修復・限定リトライを行う。権限なし・不明なら無駄な管理操作をせず管理者へ依頼する。
• これは事前の網羅的な環境診断を省く契約であり、既知の組織ポリシー、デプロイ先の確認、設計・移行・公開・設定変更の承認、ローカル品質チェックは省略しない。

共通の事前確認契約（会話の最初に 1 回だけ）

依頼文・既存 .env・認証プロファイルから分かる事項は再質問せず使う。 Code Apps では上の既定の開発契約を優先し、ローカル開発に不要な管理者確認やライセンス棚卸の回答を待たない。 実操作に必要な実装先や承認範囲が不明な場合だけ、AskUserQuestion で不足事項を 1 問ずつ確認する。 クイックスタートでは認証後の要望確認を必ず行い、回答後は既存設定・資料・テンプレート・API 調査で 分かる事項を自律的に解決する。以下の分類ごとの質問や承認を必須にせず、既存の承認範囲を超える判断だけを確認する。 以下は確認事項の分類であり、全項目の調査完了を一律の着手条件にしない。以降の Step で同じ内容を聞き直さない。

既知の値を再利用し、実操作に必要な不足事項だけ確認する。
1. 対象テナント、Power Platform 環境、Azure サブスクリプションなどの実装先
2. 開発、テスト、本番のどこまで実施するかと、デプロイまたは公開の承認範囲
3. 必要な製品ライセンス、容量、プレビュー参加条件が満たされているか
4. 作成・変更・公開・管理者同意・ロール割り当てを行う担当者と最小権限
5. 対象ソリューション、パブリッシャー、命名、利用者または公開対象
6. 認証方式、接続、シークレットストア、データ分類と外部共有の可否
7. 検証担当者、受け入れ条件、ロールバックまたはクリーンアップ方針

各専門スキルは、この7分類から不要な項目を省き、必要な固有質問を加えた 「事前確認（会話の最初に 1 回だけ）」を持つ。最低限、次を守る。

• 製品ライセンスとプレビュー制度を別項目として扱う。
• 「管理者権限が必要」とだけ書かず、工程ごとの最小ロールまたは必要な具体的権限を示す。
• 開発者が全ロールを持つと仮定せず、ライセンス、公開、管理者同意、Azure RBAC の担当者を分けて記録する。
• Global Administrator、Owner、System Administrator は、より狭いロールで完了できない工程に限定する。
• デプロイや公開の前に対象・承認範囲・ローカル品質を確認する。既知の必須条件が未充足ならその操作を停止するが、管理 API による環境診断は明示依頼時・障害時だけとする。
• 検証チェックリストに、実際の対象環境・公開範囲・承認を確認したことを含める。製品固有の公開・プレビュー承認は各スキルに従う。

共通基盤: .env と認証

すべてのデプロイスクリプトは以下の 共通パラメータ と 共通認証 を使用する。 各スキルから個別に認証を設定する必要はない。

.env 共通パラメータ

推奨: [インタラクティブセットアップ](references/interactive-setup.md) で pac CLI から対話的に .env を構成する（PAC 認証 → 環境選択 → パブリッシャー/ソリューション選択を AskUserQuestion で進行）。

PAC 認証プロファイルがない場合（PAC CLI 未インストール・auth create 不可）は、Power Apps ポータル > 設定（右上の⚙）> セッション詳細 から以下の値を取得して手動設定する（インタラクティブセットアップの Step 2 参照）。

# === 必須（全フェーズ共通）===
DATAVERSE_URL=https://{org}.crm7.dynamics.com/   # セッション詳細: Instance URL
TENANT_ID={your-tenant-id}                       # セッション詳細: Tenant ID
SOLUTION_NAME={YourSolutionName}
PUBLISHER_PREFIX={prefix}
 
# === オプション ===
PAC_AUTH_PROFILE={YourProfileName}         # PAC CLI 認証プロファイル名
ADMIN_EMAIL=admin@example.com              # Power Automate 通知先
BOT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # Copilot Studio Bot ID（URL でも可）

セッション詳細の Environment ID は pac auth create --environment {env-id} でも使用する。

共通認証: auth_helper.py

./auth_helper.py が全デプロイスクリプトの認証を一元管理する。 同一マシン・同一 OS ユーザー・同一 tenant/client ID のプロジェクト間でキャッシュを共有する 2 層構成。 通常は初回だけブラウザ認証し、以後はサイレント更新する。条件付きアクセスのサインイン頻度・ 失効・同意要求で再認証が必要になることはある。有効期間をクライアント側で延長しない。

層1: AuthenticationRecord (~/.power-platform-cli/auth_record_{TENANT_ID}.json)
  - アカウント情報（テナント・ユーザー ID）を保存
  - ホームディレクトリ配下の固定パスに永続化（プロジェクトフォルダに依存しない）
  - そのため、別プロジェクトを新規に開いても再度ブラウザ認証を求められない
 
層2: TokenCachePersistenceOptions (MSAL OS 資格情報ストア)
  - リフレッシュトークン・アクセストークンを永続化（同一マシンで共有）
  - 更新トークンが利用可能ならサイレントリフレッシュ（暗号化必須、平文保存へフォールバックしない）
 
初期セットアップ: get_token(allow_interactive=True) → キャッシュを優先 → 必要時だけブラウザで認証
2回目以降（別プロジェクトでも）: キャッシュから自動取得（認証プロンプトなし）
追加認証が必要な場合: AuthenticationRequiredError → キャッシュを保持し、保存済み継続許可または明示許可でブラウザ認証
テナント切替: テナント別の既存キャッシュを使い、他テナントのファイルは削除しない

PAC CLI プロファイルでトークンを取得できない場合は、ローカルブラウザでのインタラクティブ認証 （InteractiveBrowserCredential）を使用する。デバイスコード認証は行わず、初回の認証後はキャッシュから サイレントにトークンを取得する。 初期セットアップで tenant/client ID ごとに get_token(..., allow_interactive=True) を実行し、 AuthenticationRecord をホームディレクトリの JSON に保存する。トークン自体は JSON に含めず、 OS 資格情報ストアに保存する。以後のスキルは共通 auth_helper.py からキャッシュを再利用し、 個別の認証フローやプロジェクト内の認証 JSON を作らない。 get_credential() も同じ credential を SDK に渡す。get_token() はまずサイレント取得し、 追加認証要求だけ PP_AUTH_ALLOW_INTERACTIVE=true の保存済み継続許可で復旧する。 許可なし・CIではブラウザを開かない。SDK credential自体の自動対話は無効のままにする。 python .github/skills/standard/scripts/verify_auth_cache.py --env .env で、別作業ディレクトリの 新規プロセス 2 回からサイレント取得できることを検証する（トークン非表示）。 Power Apps npm CLI は別 client ID・専用キャッシュのため、直接共有とは区別する （キャッシュ境界）。 Foundry 上で動作するエージェント本体の Managed Identity など、実行環境固有の資格情報はこのローカル開発者認証の共有対象外とする。

認証の公開 API・パターンの詳細実装は 認証リファレンス を参照。

設計・要件ヒアリングは architecture スキルへ

要件ヒアリング → コンポーネント選定 → 全体アーキテクチャ設計は `architecture` スキル が担当する。 Phase 1（設計）の最初に必ず architecture を参照し、IT に詳しくないユーザーから業務課題を引き出して設計提案・承認を得てから、各専門スキルでの構築に進む。

→ 詳細: `architecture` スキル

関連スキルと推奨開発フロー

各スキルの説明・カテゴリ・推奨開発フローは スキルカタログ に一元化している（standard には重複記載しない）。

→ Power Platform Skills カタログ（README）

クイックリファレンス: standard が扱うテーマ

このスキルが扱うのは以下の 共通基盤テーマのみ。

個別の構築ルール・トラブルシューティング（Copilot Studio・Code Apps・Power Automate・Dataverse・Security Role・AI Builder・Model-Driven App 等）は 各専門スキルの SKILL.md / references に記載している。standard には重複して持たない。

どのスキルに何があるかは スキルカタログ README を参照。