はじめかた（初期セットアップ）

前提条件

ツール	必須 / オプション	用途
GitHub アカウント	必須	リポジトリ操作・Copilot 利用
GitHub Copilot ライセンス	必須	Copilot cloud agent 利用
Git	必須	リポジトリのクローン
Web ブラウザ	必須	GitHub.com の操作（Web UI 方式）
Python 3.11+	hve アプリケーション版のみ	hve アプリケーション版ワークフロー実行
GitHub Copilot CLI（外部 `copilot` コマンド）	オプション	SDK 同梱ではなく外部 CLI を明示利用する場合
Node.js（npm/npx）	オプション	MCP Server（filesystem 等）/ Work IQ / npm 方式の外部 Copilot CLI 使用時
Microsoft Work IQ（`@microsoft/workiq`）	オプション	hve アプリケーション版で M365 補助情報を参照する場合（詳細）

Issue Template から実行する場合は、フォーム内の 「使用するモデル」 で Auto（既定: GitHub が最適モデルを動的選択。0.9x 計上）または任意モデルを選択できます。公式: https://docs.github.com/en/copilot/concepts/auto-model-selection

Work IQ のセットアップ手順は hve-app-guide.md — Work IQ MCP 連携を参照してください。

Step.1. リポジトリの作成

GitHub リポジトリを作成します。GitHub Copilot cloud agent が作業をするためのリポジトリです。

Step.1.1. テンプレートリポジトリを使う（推奨）

本リポジトリ（dahatake/RoyalytyService2ndGen）はテンプレートリポジトリです。GitHub の「Use this template」ボタンから自分のリポジトリを作成できます。

dahatake/RoyalytyService2ndGen を開く
右上の 「Use this template」 ボタンをクリック
「Create a new repository」 を選択
リポジトリ名・可視性を設定して作成

注意: このリポジトリは HypervelocityEngineering-Japanese テンプレートから作成されたインスタンスです。テンプレートから直接作成する場合は dahatake/HypervelocityEngineering-Japanese も参照してください。

Step.1.2. Git Clone で取得する場合

git clone https://github.com/dahatake/RoyalytyService2ndGen.git

Step.2. ファイルのコピー

「Use this template」を使った場合は、このステップは不要です。

Git Clone でファイルを取得した場合は、ダウンロードしたファイルをあなたのプロジェクトのリポジトリに全てコピーします。

フォルダー構造は以下のようになります:

your-project/
├── .github/
│   ├── agents/
│   │   ├── Arch-Microservice-DomainAnalytics.agent.md
│   │   ├── Arch-Microservice-ServiceIdentify.agent.md
│   │   └── ... (その他の Custom Agent ファイル)
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/
│   ├── scripts/
│   └── copilot-instructions.md
├── README.md
├── users-guide/
└── ... (その他のプロジェクトファイル)

Custom Agent ファイルの編集（オプション）

各 Custom Agent ファイルは、プロジェクトの要件に応じてカスタマイズできます。

## ユースケースID
- UC-xxx  ← あなたのユースケース ID に変更

## ユースケース
  - docs/usecase/{ユースケースID}/usecase-description.md  ← パスを変更

編集する際の注意点:

ファイル先頭の YAML フロントマター（--- で囲まれた部分）の name と description は Custom Agent の識別に使用されます
tools: ["*"] は全てのツールへのアクセスを許可する設定です

詳細: Copilot ベストプラクティス

Step.3. MCP Server 設定

GitHub リポジトリに GitHub Copilot cloud agent が MCP Server を利用できるように設定します。

GitHub リポジトリの Settings → Copilot → Cloud agent → MCP Servers で以下の設定を追加してください。

設定文字列

{
  "mcpServers": {
    "Azure": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@azure/mcp@latest",
        "server",
        "start"
      ],
      "tools": ["*"]
    },
    "MicrosoftDocs": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp",
      "tools": ["*"]
    }
  }
}

参考リンク

Azure MCP Server 設定: Microsoft Learn
Microsoft Learn Docs MCP Server: Qiita 解説記事

hve アプリケーション版の MCP Server 設定については hve アプリケーションユーザーガイド付録A を参照してください。

Step.3.1. GitHub Copilot Skills 設定（推奨）

Azure 関連の作業を効率化するため、Azure Skills のインストールを推奨します。

Azure Skills: https://github.com/microsoft/azure-skills
Skills CLI: https://github.com/microsoft/skills

初回インストール

対話モード（スキルを選択してインストール）:

npx -y skills add microsoft/skills

全スキルを一括インストール（非対話モード）:

npx skills add microsoft/skills --skill '*' --agent copilot --yes --copy

インストール後、.github/skills/ 配下に SKILL.md ファイルが配置され、GitHub Copilot cloud agent が Azure 関連タスクで自動的に Skills を活用します（.github/copilot-instructions.md §1「ワークフロー概要」および §2「Skills ルーティングテーブル」参照）。

自動同期（推奨）

このリポジトリには Azure Skills の定期同期ワークフロー（.github/workflows/sync-azure-skills.yml）が設定されています。

スケジュール: 毎週月曜 9:00 UTC に自動実行
動作: microsoft/skills の最新版と差分を検出し、変更がある場合は PR を自動作成
カスタムスキル保護: large-output-chunking, repo-onboarding-fast, task-dag-planning, work-artifacts-layout は同期対象外

手動で即座に同期する場合は、GitHub Actions タブから Sync Azure Skills ワークフローを手動実行してください。

Step.4. 認証設定（COPILOT_PAT）

PAT（Personal Access Token）をリポジトリのシークレットに設定します。Copilot が Issue に自動アサインされるために必要です。

1. Personal Access Token（PAT）を作成

GitHub.com → プロフィールアイコン → Settings → Developer settings
Personal access tokens → Fine-grained tokens → Generate new token
基本情報を入力:
- Token name: 任意（例: copilot-pat）
- Expiration: 90日以内を推奨
Repository access: 対象リポジトリを選択
Permissions（Repository permissions）:
- Issues: Read and write
- Metadata: Read-only（自動付与）
Generate token をクリックし、表示されたトークン文字列を必ずこの時点でコピー

⚠️ トークンはこの画面を離れると二度と表示されません。

2. リポジトリのシークレットに登録

リポジトリの Settings → Secrets and variables → Actions
New repository secret をクリック
Name: COPILOT_PAT
Value: 作成した PAT を貼り付け

MCP と PAT の設定が完了すると、Repository には以下のように secret が設定されます。

3. Azure Static Web Apps デプロイ用 Secrets（SWA デプロイ時）

Note

このステップは Web App デプロイ を実行する場合の確認です。

SWA デプロイは OIDC 認証（azure/login@v2）+ shibayan/swa-deploy@v1 の app-name モードを使用するため、AZURE_STATIC_WEB_APPS_API_TOKEN や GITHUB_PAT の設定は不要です。

以下の 3 つの Secrets は Functions deploy でも使用するものと共通です。すでに設定済みであれば追加作業は不要です。

Secret 名	説明
`AZURE_CLIENT_ID`	OIDC サービスプリンシパルのクライアント ID
`AZURE_TENANT_ID`	Azure AD テナント ID
`AZURE_SUBSCRIPTION_ID`	Azure サブスクリプション ID

スクリプト実行（PAT 不要）

# GITHUB_PAT は不要。Azure リソース作成のみ実行する。
bash infra/azure/create-azure-webui-resources.sh

スクリプトが Azure Static Web Apps リソースを作成します。CI/CD ワークフローが OIDC 経由でデプロイトークンを自動取得します。

ワークフロー権限設定

Important

Step.5（ラベル設定）より前に、この権限設定を完了してください。 setup-labels.yml ワークフローはラベル作成 API を呼び出すため、Read and write permissions でないとラベル作成が 403 エラーで失敗します。

リポジトリの Settings → Actions → General → Workflow permissions を Read and write permissions に設定してください。

Step.5. ラベル設定

ワークフローのトリガーに使用するラベルを GitHub リポジトリに作成します。

Warning

このステップは、他のワークフローを使い始める前に必ず完了してください。

ラベルが未設定の状態では、すべての Issue テンプレート経由のワークフロー起動が動作しません。これは setup-labels だけでなく、auto-app-selection・auto-app-detail-design・knowledge-management など全ワークフロートリガー系ラベルに影響します。

GitHub の Issue Template の labels: フィールドは、リポジトリに既に存在するラベルのみを Issue に自動付与します。ラベルが存在しない場合は Issue 作成時にラベルの付与がサイレントにスキップされ、ラベル付与を前提とした対象ジョブや処理は実行されません（ジョブがスキップされます）。

初回セットアップの全体フロー

新規リポジトリ作成
  → Step.4. COPILOT_PAT 設定
  → ワークフロー権限設定（Read and write permissions）
  → Step.5. Actions タブから Setup Labels を手動実行  ← ★ ここが最重要
  → ラベル作成完了
  → 以降は Issue テンプレートからワークフローを起動可能

推奨方法: Setup Labels ワークフローを実行する

Note

リポジトリ作成後に 1度だけ 実行する想定です。ラベル定義（.github/labels.json）が更新された場合は再実行できます（冪等設計のため、複数回実行しても安全です）。

初回実行（Actions タブから手動実行）

なぜ手動実行が必要か（鶏と卵問題）

setup-labels ワークフロー自体は Issue の opened でも起動しますが、実際のラベル作成ジョブは setup-labels ラベルの有無を if: 条件で判定しています。新規リポジトリの初回は setup-labels ラベル自体がまだ存在しないため、Issue テンプレートから起動しても処理がスキップされます。このため、初回は Issue テンプレートからではなく、Actions タブから直接手動実行する必要があります。

Important

手動実行の前提条件: ワークフロー権限が「Read and write permissions」 になっていることを確認してください（上記「ワークフロー権限設定」セクション参照）。権限が「Read-only」のままでは、ラベル作成 API が 403 エラーで失敗します。

setup-labels ラベルがまだリポジトリに存在しない場合は、以下の手順で手動実行してください:

GitHub リポジトリの Actions タブを開く
左サイドバーから Setup Labels ワークフローを選択
Run workflow ボタンをクリック
Run workflow で実行する

実行後の確認手順

Actions タブでワークフローの実行結果が ✅ 成功（緑チェック）になっていることを確認する
Settings → Labels を開き、auto-app-selection・auto-app-detail-design・setup-labels などのラベルが作成されていることを目視確認する
（オプション）Issues タブ → New issue → Setup Labels: ラベル初期セットアップ テンプレートを選択し、Issue を作成したときに setup-labels ラベルが自動付与されることを確認する（2回目以降の動作確認）

2回目以降（Issue テンプレートから実行）

setup-labels ラベルが作成済みの場合は、Issue テンプレートから実行できます:

GitHub リポジトリの Issues タブを開く
New issue をクリック
Setup Labels: ラベル初期セットアップ テンプレートを選択
確認チェックボックスにチェックを入れて Issue を作成する

トラブルシューティング

Issue テンプレートから Issue を作成したが、ワークフローが起動しない

原因: ラベルがリポジトリに存在しないため、Issue 作成時にラベルが付与されませんでした。

対処法: Actions タブから Setup Labels ワークフローを手動実行してください（上記「初回実行」手順参照）。

Setup Labels ワークフローが失敗する（ラベル作成 API が 403 を返す）

原因: ワークフロー権限が「Read-only」になっています。

対処法: Settings → Actions → General → Workflow permissions を 「Read and write permissions」 に変更してから、再度 Actions タブから Setup Labels ワークフローを手動実行してください。

管理対象ラベル

Setup Labels ワークフローが作成・更新するラベル一覧です:

ワークフロートリガー系（13 個）

ラベル名	色	用途
`auto-app-selection`	`#0E8A16`	AAS ワークフロートリガー
`auto-app-detail-design`	`#0E8A16`	AAD ワークフロートリガー
`auto-app-detail-design-web`	`#1D76DB`	AAD-WEB ワークフロートリガー
`auto-ai-agent-design`	`#7B68EE`	AAG ワークフロートリガー
`auto-app-dev-microservice`	`#1D76DB`	ASDW ワークフロートリガー
`auto-app-dev-microservice-web`	`#0E8A16`	ASDW-WEB ワークフロートリガー
`auto-ai-agent-dev`	`#6A5ACD`	AAGD ワークフロートリガー
`auto-batch-design`	`#0E8A16`	ABD ワークフロートリガー
`auto-batch-dev`	`#0E8A16`	ABDV ワークフロートリガー
`auto-app-documentation`	`#0E8A16`	ADOC ワークフロートリガー
`knowledge-management`	`#0E8A16`	AKM ワークフロートリガー
`self-improve`	`#0E8A16`	自己改善ループトリガー
`original-docs-review`	`#0E8A16`	AQOD ワークフロートリガー

PR 制御系（6 個）

ラベル名	色	用途
`auto-context-review`	`#1D76DB`	Copilot 敵対的レビュートリガー
`auto-qa`	`#BFD4F2`	Copilot 質問票作成トリガー
`create-subissues`	`#E4E669`	Sub Issue 自動作成トリガー
`split-mode`	`#D93F0B`	分割モード PR 識別
`plan-only`	`#D93F0B`	plan.md のみの PR 識別
`auto-approve-ready`	`#1D76DB`	PR 自動 Approve & Auto-merge トリガー

モデル選択系（8 個）

ラベル名	色	用途
`model/Auto`	`#6f42c1`	Copilot cloud agent モデル指定: Auto（GitHub が最適モデルを動的選択。0.9x 計上、1x 超モデルは対象外）
`model/claude-opus-4-7`	`#6f42c1`	Copilot cloud agent モデル指定: claude-opus-4-7（deprecated: `model/claude-opus-4.7` を推奨）
`model/claude-opus-4.7`	`#6f42c1`	Copilot cloud agent モデル指定: claude-opus-4.7
`model/claude-opus-4.6`	`#6f42c1`	Copilot cloud agent モデル指定: claude-opus-4.6
`model/claude-sonnet-4.6`	`#6f42c1`	Copilot cloud agent モデル指定: claude-sonnet-4.6
`model/gpt-5.4`	`#6f42c1`	Copilot cloud agent モデル指定: gpt-5.4
`model/gpt-5.3-codex`	`#6f42c1`	Copilot cloud agent モデル指定: gpt-5.3-codex
`model/gemini-2.5-pro`	`#6f42c1`	Copilot cloud agent モデル指定: gemini-2.5-pro

セットアップ系（1 個）

ラベル名	色	用途
`setup-labels`	`#C5DEF5`	Setup Labels ワークフロートリガー

Important

ステートラベル（aas:initialized, aas:ready, aas:running, aas:done, aas:blocked など）は、各オーケストレーターワークフローが自動作成します。手動作成は不要です。

auto-app-documentation / knowledge-management / auto-approve-ready は .github/labels.json の管理対象です。ラベル定義を更新した場合は Setup Labels ワークフローを再実行してください。

ラベルの詳細一覧は workflow-reference.md を参照してください。

ラベル設定後の画面例:

設定後は PR のコメントで以下のように指示を出すと、Copilot cloud agent が Sub Issue を作成します。

レガシー方式（過去互換）: 手動でラベルを作成する

Note

現在は Setup Labels ワークフローで自動管理されています。このセクションは過去バージョンとの互換運用や緊急時の手動作成が必要な場合のために残しています。

過去互換や緊急時に手動作成する場合は、以下を Settings → Labels から作成してください:

ラベル名	色	用途
`auto-app-documentation`	`#0E8A16`	ADOC ワークフロートリガー
`knowledge-management`	`#0E8A16`	AKM ワークフロートリガー
`auto-approve-ready`	`#1D76DB`	PR 自動 Approve & Auto-merge トリガー

GitHub リポジトリの Settings → Labels から上記を手動作成してください。
それ以外のラベルは Setup Labels ワークフロー（.github/labels.json）で管理されます。

Copilot 有効化

リポジトリで GitHub Copilot cloud agent が有効になっていることを確認してください。

Settings → Copilot → Cloud agent から有効化できます。

knowledge/ ディレクトリについて

knowledge/ フォルダーには業務要件ドキュメント（D01〜D21）が格納されます。これらは knowledge-management ワークフロー（km-guide.md 参照）によって生成されます。ただし、生成されるのは qa/ の質問データに QA マッピングが存在する D クラスのみです（マッピングがない D クラスのファイルは生成されません）。

ドキュメント（生成されたもののみ存在）	内容
`knowledge/D01-事業意図-成功条件定義書.md`	経営課題・KPI・成功条件・ROI仮説
`knowledge/D02-スコープ-対象境界定義書.md`	スコープ・対象境界
`knowledge/D04-業務プロセス仕様書.md`	業務プロセス
`knowledge/D05-ユースケース-シナリオカタログ.md`	ユースケース・シナリオ
`knowledge/D06-業務ルール-判定表仕様書.md`	業務ルール・判定表
`knowledge/D07-用語集-ドメインモデル定義書.md`	用語・ドメインモデル
`knowledge/D08-データモデル-SoR-SoT-データ品質仕様書.md`	データモデル・SoR/SoT
`knowledge/D09-システムコンテキスト-責任境界-再利用方針書.md`	システムコンテキスト・責任境界
`knowledge/D10-API-Event-File-連携契約パック.md`	API/イベント/ファイル連携契約
`knowledge/D11-画面-UX-操作意味仕様書.md`	画面UX・操作仕様
`knowledge/D12-権限-認可-職務分掌設計書.md`	権限・認可・職務分掌
`knowledge/D13-セキュリティ-プライバシー-監査-法規マトリクス.md`	セキュリティ・プライバシー・監査
`knowledge/D14-国際化-地域差分仕様書.md`	国際化・地域差分
`knowledge/D15-非機能-運用-監視-DR-仕様書.md`	非機能・運用・監視・DR
`knowledge/D16-移行-導入-ロールアウト計画書.md`	移行・導入計画
`knowledge/D17-品質保証-UAT-受入パッケージ.md`	品質保証・UAT
`knowledge/D18-Prompt-ガバナンス-入力統制パック.md`	Promptガバナンス
`knowledge/D19-ソフトウェアアーキテクチャ-ADR-パック.md`	ソフトウェアアーキテクチャ・ADR
`knowledge/D20-セキュア設計-実装ガードレール.md`	セキュア設計・実装ガードレール
`knowledge/D21-CI-CD-ビルド-リリース-供給網管理仕様書.md`	CI/CD・ビルド・リリース

knowledge/ ファイルが存在すると、設計・開発の各 Custom Agent が業務要件・制約のコンテキストとして自動参照します。アプリケーション設計・開発ワークフローを開始する前に、knowledge-management ワークフローを実行しておくことを推奨します。

次のステップ

セットアップが完了したら、まず全体像を把握してから方式を選んでください。

全体像の把握: まず overview.md で全体像と 3 つの使い方を把握してください
Custom Agent エコシステム図: agent-ecosystem-overview.svg
方式1（個別 Issue + Custom Agent 手動実行）: web-ui-guide.md
方式2（ワークフローオーケストレーション Web）: web-ui-guide.md
方式3（ローカル: hve アプリケーション版）: hve-app-guide.md
フェーズ別ガイド: overview.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

はじめかた（初期セットアップ）

目次

前提条件

Step.1. リポジトリの作成

Step.1.1. テンプレートリポジトリを使う（推奨）

Step.1.2. Git Clone で取得する場合

Step.2. ファイルのコピー

Custom Agent ファイルの編集（オプション）

Step.3. MCP Server 設定

設定文字列

参考リンク

Step.3.1. GitHub Copilot Skills 設定（推奨）

初回インストール

自動同期（推奨）

Step.4. 認証設定（COPILOT_PAT）

1. Personal Access Token（PAT）を作成

2. リポジトリのシークレットに登録

3. Azure Static Web Apps デプロイ用 Secrets（SWA デプロイ時）

スクリプト実行（PAT 不要）

ワークフロー権限設定

Step.5. ラベル設定

初回セットアップの全体フロー

推奨方法: Setup Labels ワークフローを実行する

初回実行（Actions タブから手動実行）

なぜ手動実行が必要か（鶏と卵問題）

実行後の確認手順

2回目以降（Issue テンプレートから実行）

トラブルシューティング

管理対象ラベル

レガシー方式（過去互換）: 手動でラベルを作成する

Copilot 有効化

knowledge/ ディレクトリについて

次のステップ

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

はじめかた（初期セットアップ）

目次

前提条件

Step.1. リポジトリの作成

Step.1.1. テンプレートリポジトリを使う（推奨）

Step.1.2. Git Clone で取得する場合

Step.2. ファイルのコピー

Custom Agent ファイルの編集（オプション）

Step.3. MCP Server 設定

設定文字列

参考リンク

Step.3.1. GitHub Copilot Skills 設定（推奨）

初回インストール

自動同期（推奨）

Step.4. 認証設定（COPILOT_PAT）

1. Personal Access Token（PAT）を作成

2. リポジトリのシークレットに登録

3. Azure Static Web Apps デプロイ用 Secrets（SWA デプロイ時）

スクリプト実行（PAT 不要）

ワークフロー権限設定

Step.5. ラベル設定

初回セットアップの全体フロー

推奨方法: Setup Labels ワークフローを実行する

初回実行（Actions タブから手動実行）

なぜ手動実行が必要か（鶏と卵問題）

実行後の確認手順

2回目以降（Issue テンプレートから実行）

トラブルシューティング

管理対象ラベル

レガシー方式（過去互換）: 手動でラベルを作成する

Copilot 有効化

knowledge/ ディレクトリについて

次のステップ