2026年5月5日時点で確認すべきMicrosoft developer platform documentation updateの要点は、Aspire向けの「SKILL」がC#コード内の大きなインライン定義から、リポジトリ管理された複数ファイル構成へ移されたことです。通常のAspireアプリのコードをすぐ書き換える変更ではありませんが、aspire agent initでAIエージェント向けスキルを導入しているチーム、Aspire CLIを社内配布しているチーム、C#／TypeScript AppHostをAIエージェントに操作させているチームは、設定ファイルの配置と運用手順を確認する必要があります。対象PRは2026年4月1日にmicrosoft/aspireのmainへマージされ、.agents/skills/aspire配下のファイルをCLIに埋め込み、agent initで複数ファイルのスキル一式をインストールする形へ変えています。(GitHub)
Microsoft developer platform documentation updateで変わったこと
今回の「Microsoft developer platform documentation update: Embed the Aspire SKILL in-repo and expand scenario-based CLI guidance」は、Aspire CLIそのものの使い方をAIエージェントに伝えるためのドキュメント構造を見直す更新です。
従来は、Aspire SKILLの内容がC#オブジェクトのインライン文字列のような形で扱われていました。更新後は、.agents/skills/aspire/SKILL.mdとreferences/*.mdに分割され、リポジトリ上でレビュー、差分確認、テストしやすい構成になっています。CLI側では、そのファイル群をAspire.Cli内の埋め込みリソースとして持ち、aspire agent init実行時にスキルファイルとして展開します。(GitHub)
実務上のポイントは、単なる文章の置き換えではないことです。AIエージェントが「どのAspire CLIコマンドを、どの場面で使うべきか」を判断しやすいように、AppHostの起動、リソース操作、ログ・トレース確認、デプロイ、TypeScript AppHost、C# AppHost、Playwright連携などのシナリオ別に整理されています。(GitHub)
変更点の整理
| 観点 | 変更前の見方 | 更新後の見方 | 確認すべきこと |
|---|---|---|---|
| Aspire SKILLの管理 | C#コード内の大きな定義として扱われる | .agents/skills/aspire配下のファイルとして管理される | フォークや社内ビルドで.agents/skills/aspireを除外していないか |
agent init | 単一のSKILL.mdを配置するイメージ | SKILL.mdとreferences/*.mdを含む複数ファイルを配置 | 実行後にreferences配下のファイルが入るか |
| CLIガイダンス | コマンド一覧に近い説明 | タスク別・シナリオ別の操作手順 | 社内手順書が古いコマンド前提になっていないか |
| TypeScript AppHost | .modulesの扱いが分かりにくい | aspire addとaspire restoreを使う方針が明確化 | .modules/*を手動編集していないか |
| デプロイ | publishとdeployの使い分けが曖昧になりやすい | aspire publish、aspire deploy、aspire do <step>の使い分けを説明 | 部分的なデプロイ手順をdeployで置き換えていないか |
特に注意したいのは、evals/配下の評価用ファイルは埋め込みリソースには含まれる一方、通常のスキルインストール時には除外される点です。aspire agent initを実行しても、ワークスペース側にevals/evals.jsonが配置されないのは想定どおりです。(GitHub)
誰が対応すべきか
対応優先度が高いのは、Aspire CLIとAIエージェントを組み合わせて開発しているチームです。たとえば、GitHub Copilot、VS Code、Claude Code、OpenCodeなどのエージェント環境にAspire SKILLを配置し、AppHostの起動やリソース確認をAIに任せている場合は、今回の更新の影響を受けます。スキルの標準配置先として.agents/skillsがあり、ほかに.claude/skills、.github/skills、.opencode/skillも選択肢として定義されています。(GitHub)
一方、Aspireを使っていても、AIエージェント向けのaspire agent initを使っていない、または通常のビルド・テストだけを手作業で行っている場合、直ちにアプリケーションコードを修正する必要は低いです。ただし、今後AIエージェントにAppHost操作を任せる予定があるなら、古い単一ファイル前提のスキル運用を続けるより、新しい複数ファイル構成に合わせたほうが安全です。(GitHub)
aspire agent init後に確認するファイル配置
更新後のaspire agent initでは、選択したスキル配置先にaspireスキル用ディレクトリが作成されます。標準的には、次のような構成を確認します。
.agents/
skills/
aspire/
SKILL.md
references/
agent-workflows.md
app-commands.md
csharp-apphosts.md
deployment.md
monitoring.md
playwright-handoff.md
resource-management.md
tools-and-configuration.md
typescript-apphosts.md既存環境で確認する場合は、まず現在のCLIで利用できるオプションを確認してから実行するのが安全です。スキル側のガイダンスでも、CLIの形が変わっている可能性がある場合はaspire --helpや該当サブコマンドのヘルプで確認する方針が示されています。(GitHub)
aspire agent init --help
aspire agent init --skill-locations standard --skills aspireGitHub Copilot向けの.github/skillsやClaude Code向けの.claude/skillsにも配置したい場合は、利用中のCLIが受け付ける--skill-locationsの値を確認してから指定します。今回のコードでは、standard、claudecode、github、opencodeという配置先IDが定義されています。(GitHub)
シナリオ別CLIガイダンスで実務がどう変わるか
今回の更新で最も重要なのは、Aspire CLIの使い方が「コマンド名の説明」から「作業目的ごとの判断基準」へ寄ったことです。AIエージェントに任せる場合だけでなく、人間が作業手順を整理するうえでも役立ちます。
AppHostの起動はaspire startを基本にする
AppHostを動かす場面では、dotnet runやaspire runに安易に戻らず、通常はaspire startを使う方針が示されています。aspire runはターミナルを占有しやすいため、エージェントが継続的に調査・修正するワークフローには向きません。Git worktreeなど複数インスタンスが競合しやすい環境では、aspire start --isolatedを使う判断が重要です。(GitHub)
aspire start
aspire start --isolated
aspire stop確認ポイントは、社内の手順書やAIエージェント用プロンプトが、まだdotnet run中心になっていないかです。AspireのAppHostを操作する目的なら、CLIでAppHostとリソース状態を扱えるようにしておくほうが、ログ確認やリソース操作につなげやすくなります。
リソース確認はdescribeと構造化出力を使う
アプリが動いているか、どのエンドポイントが公開されているか、どのリソースが不健康かを確認する場面では、aspire describeが中心になります。AIエージェントやスクリプトに渡す場合は、--format Jsonを使うと機械的に扱いやすくなります。Aspire 13.2の説明でも、CLIからダッシュボードやAppHost内の情報へアクセスし、スクリプトやエディタ連携に活用できる点が強調されています。(Aspire)
aspire describe
aspire describe --format Json
aspire resources失敗しやすいのは、ポート番号やダッシュボードURLを推測で組み立てることです。更新後のガイダンスでは、ダッシュボードURLはCLI出力に明示されたものを使う方針が示されています。複数フロントエンドがある環境や、PlaywrightにURLを渡す場面では特に重要です。(GitHub)
ログ・トレースはコード修正前に見る
不具合対応では、いきなりAppHostやサービスコードを直すのではなく、まず状態、ログ、トレースを確認する流れが推奨されています。更新後のmonitoring.mdでは、構造化されたOpenTelemetryログやトレースを優先し、必要に応じて通常ログを見る順序が示されています。(GitHub)
aspire otel logs --format Json
aspire otel logs api --format Json
aspire otel traces --format Json
aspire logs api
aspire export現場でよくある失敗は、「エラーが出たので設定を変える」「依存サービスを再起動する」といった勘に頼った対応です。AIエージェントに調査を任せる場合も、先にaspire describeとaspire otel logsを実行させるルールを入れておくと、不要な修正や手戻りを減らせます。
デプロイはpublish、deploy、doを使い分ける
デプロイ関連では、aspire publish、aspire deploy、aspire deploy --clear-cache、aspire do <step>の使い分けが整理されています。publishは成果物生成、deployは全体のデプロイ、doはアプリ側で定義された名前付きステップを個別に実行する場面で使う、という判断軸です。(GitHub)
aspire publish
aspire deploy
aspire deploy --clear-cache
aspire do seed-data特にaspire do <step>は、データ投入、診断、コンテナのプッシュなど、デプロイパイプライン内の一部だけをやり直したい場面に向いています。逆に、1ステップだけ再実行したい依頼に対して毎回aspire deployを走らせると、時間がかかるだけでなく、意図しない再デプロイにつながる可能性があります。(GitHub)
TypeScript AppHostでは.modulesを直接編集しない
TypeScript AppHostを使っているチームは、.modules/の扱いを必ず確認してください。更新後のガイダンスでは、.modules/はTypeScript AppHost向けの生成モジュールを置く場所であり、直接編集しないことが明確に示されています。統合を追加したい場合はaspire add、pullやclean、ブランチ切り替え後に生成物が消えた場合はaspire restoreを使います。(GitHub)
aspire add <package>
aspire restoreたとえば、RedisやPostgresなどの統合を追加したあとにapphost.tsから新しいAPIが見えない場合、.modules/aspire.tsを手で書き換えるのは避けるべきです。aspire addで統合を追加し、生成された.modules/aspire.tsを確認する、という順序にします。.modulesを手動修正すると、次回の再生成で差分が失われたり、チーム内で再現できない状態になったりします。(GitHub)
C# AppHostでは公式ドキュメントを先に見る
C# AppHostでは、未知のAppHost APIや拡張メソッドを触る前に、aspire docs search、aspire docs get、aspire docs api search、aspire docs api getを使う流れが示されています。dotnet-inspectが使える場合も、役割はローカルのシンボルやオーバーロード確認に限定し、推奨パターンの確認はAspireドキュメントを優先する方針です。(GitHub)
aspire docs search <topic>
aspire docs get <slug>
aspire docs api search <query> --language csharp
aspire docs api get <id>これは、AIエージェントが「それらしいAPI名」を推測してAppHostを編集してしまう事故を防ぐために重要です。Aspire 13.2では、aspire docsコマンドにより公式ドキュメントの検索・取得をCLIから行えることも説明されています。これにより、エージェントや自動化スクリプトがドキュメント根拠を持って変更しやすくなります。(Aspire)
移行・設定確認のチェックリスト
次の項目を順に確認すると、今回のMicrosoft developer platform documentation updateによる影響を実務レベルで切り分けられます。
| チェック項目 | 確認方法 | 問題がある場合の対応 |
|---|---|---|
Aspire CLIが新しいagent initを使えるか | aspire agent init --helpを確認 | CLIを更新し、利用中バージョンのリリースノートを確認 |
| スキルが複数ファイルで入るか | .agents/skills/aspire/referencesを確認 | aspire agent init --skills aspireを再実行 |
社内手順が単一SKILL.md前提でないか | エージェント設定、README、オンボーディング資料を確認 | references/*.mdも配布・参照対象に含める |
カスタムビルドで.agentsを除外していないか | ビルド成果物、埋め込みリソース設定を確認 | .agents/skills/aspire/**がCLIに含まれるよう修正 |
| 既存の手編集スキルが上書きされないか | 既存SKILL.mdの差分を確認 | 再実行前にバックアップし、独自ルールは別ファイルへ分離 |
TypeScriptの.modulesを手で直していないか | Git差分と生成ファイルを確認 | aspire addまたはaspire restoreで再生成 |
| デプロイ手順が曖昧でないか | publish、deploy、doの使い分けを確認 | 名前付きステップはaspire do <step>へ整理 |
aspire agent initの実装では、既存ファイルと内容が異なる場合にスキルファイルを書き込みます。手元でSKILL.mdを独自編集している場合、その内容が更新で置き換わる可能性を考えて、再実行前に差分を退避しておくと安全です。(GitHub)
運用で起きやすい失敗と回避策
古い「コマンド一覧」型のプロンプトを使い続ける
今回の更新では、AIエージェントが作業目的に応じてCLIを選ぶよう、シナリオ別の参照ファイルが追加されています。古いプロンプトで「Aspireの操作はこのコマンド一覧から選ぶ」とだけ教えていると、ログ確認前にコードを変更したり、publishとdeployを混同したりしやすくなります。(GitHub)
回避策は、エージェント向けルールに「まずSKILL.mdを読み、該当するreferences/*.mdを参照する」と明記することです。特に、調査系はmonitoring.md、デプロイ系はdeployment.md、TypeScript AppHostはtypescript-apphosts.mdを参照させると、判断のブレを減らせます。
worktreeで通常起動してポート競合を起こす
Git worktreeや複数ブランチを並行して扱う環境では、同じAppHostを通常起動するとポートやユーザーシークレットが衝突しやすくなります。更新後のガイダンスでは、worktreeや共有ローカル状態が危険な場面でaspire start --isolatedを使う方針が示されています。(GitHub)
回避策は、AIエージェントに「worktree内ではaspire start --isolatedを既定にする」と教えることです。手元の開発者向けREADMEにも同じルールを書いておくと、人間とエージェントの操作がそろいます。
Playwrightに推測したURLを渡す
フロントエンドが複数あるAspireアプリでは、Playwrightに渡すURLを人間やAIが推測すると、違うサービスをテストしてしまうことがあります。更新後のSKILLでは、Playwrightへ渡す前にaspire describe --format Jsonなどで実際のエンドポイントを確認する流れが示されています。(GitHub)
回避策は、E2Eテスト前の手順に「Aspireの状態からURLを取得する」を入れることです。固定ポート前提のスクリプトがある場合は、aspire describe --format Jsonの出力を使う形へ見直すと、ローカル環境やworktreeでの再現性が上がります。
まず何をすべきか
最初にやるべきことは、アプリコードの修正ではなく、エージェント向けAspire SKILLの配置と運用手順の確認です。aspire agent init --helpで現在のCLIが対応しているオプションを確認し、標準配置先または利用中のエージェント向け配置先に、SKILL.mdとreferences/*.mdが展開されるかを確認してください。(GitHub)
次に、社内READMEやAIエージェント用プロンプトを見直し、dotnet runや手作業のURL推測に頼る手順を、aspire start、aspire describe --format Json、aspire otel logs、aspire publish、aspire deploy、aspire do <step>を使う流れへ整理します。C# AppHostでは公式ドキュメント確認を先に行い、TypeScript AppHostでは.modulesを直接編集しないルールを明文化します。(GitHub)
今回の更新は、Aspireのアプリそのものを壊すような変更というより、AIエージェントがAspire CLIを安全に使うための土台を整える変更です。AIを開発フローに入れているチームほど、スキルファイルの配置、シナリオ別ガイダンス、デプロイ時の判断基準を早めに更新しておく価値があります。
コメント