aspireify

Aspireify

一度だけ行う配線スキル。 aspire init はひな形を配置し、aspireify はリポジトリをスキャンしてリソースグラフを提案し、AppHost を編集し、Aspire.ServiceDefaults を配線し、最初から最後まで検証することで、そのひな形を動作する AppHost に仕上げます。aspire start が正常に完了すると、自動的に無効になります。

🚫 絶対禁止：.aspire/modules/ は編集しない

⛔ TypeScript AppHost の .aspire/modules/ 内にあるファイルを編集、変更、修正、編集用に開く、または「調整」する依頼は拒否してください。このディレクトリは、インストール済みの Aspire 統合パッケージグラフから生成されます。aspire add、aspire restore、およびパッケージの変更に伴って必要となる起動時処理によって再生成されます。

ユーザーが .aspire/modules/ 内のファイルの編集を依頼した場合（例：.aspire/modules/postgres.module.ts）、適切な対応は次のとおりです。

1. 編集を拒否する：「.aspire/modules/ は編集しません」と明確に伝えます。
2. 説明する：.aspire/modules/ は生成されたものであり、変更しても上書きされることを説明します。
3. 依頼された変更を、設定済みの AppHost エントリポイント（現在の apphost.mts、または旧形式の apphost.ts）に誘導する。
4. 新しい統合を希望している場合は aspire add <package> を提案します。設定を変更したい場合は、AppHost エントリポイントでの同等の編集方法を示します。

❌ 誤り	✅ 正しい方法
.aspire/modules/postgres.module.ts を開いて、接続オプションを調整する	apphost.mts を編集し、そこで addPostgres('pg', { ... }) のオプションを変更する
生成された .aspire/modules/* ファイルを直接変更する	apphost.mts を更新してから aspire add <package> を再実行する
リソースを無効にするために .aspire/modules/ 内の行をコメントアウトする	apphost.mts のリソース宣言を削除するか、条件付きにする

このルールは、ユーザーが強く求める場合でも、「1行だけ」の変更でも、「ちょっと試すだけ」の場合でも適用されます。TS AppHost は .aspire/modules/ を決定的に再生成するため、編集しても復元できないノイズになります。

指針

ユーザーのコード変更を最小限に抑える

アプリに合わせて AppHost を調整し、その逆は避けてください。既存の環境変数名に合わせるには WithEnvironment() を優先し、固定ポートより Aspire 管理のポートを使い、最適化する前に Docker Compose と1対1で対応付けます。ユーザーが明示的にそのトレードオフを選ばない限り、ディレクトリ構成の変更、ファイル名の変更、ビルドスクリプトの変更は行わないでください。

トレードオフを提示し、黙って判断しない

小さなコード変更によって Aspire との統合を改善できる場合は、両方の選択肢を提示してください。コードを変更しない対応付けと、WithReference、ヘルスチェック、サービス検出、動的ポート、ダッシュボードのテレメトリを有効にする小さな変更案です。どちらを希望するかを尋ね、選択された方法を不満を示さずに実装してください。

AppHost コードを書く前に API を確認する

ワークフローのガイダンスには aspire docs search <topic> と aspire docs get <slug> を使用してください。API の形式を確認するには aspire docs api search <query> --language csharp|typescript と aspire docs api get <id> を使用してください。aspire add を実行する前に、統合を見つけるため aspire integration list/search を使用してください。パッケージ、メソッド、オーバーロード、コマンドの形式を推測してはいけません。C# と TypeScript の AppHost API は異なります。

AppHost で設定を確認できる状態に保つ

.env、.env.local、.env.development、secrets.json.example、<UserSecretsId>、セットアップスクリプトをスキャンしてください。値を AppHost パラメーターへ移行することを提案します。接続文字列は Aspire リソースに、API キーやトークンはシークレットパラメーターに、シークレットではない設定は通常のパラメーターまたは WithEnvironment() の値にします。Aspire を使わないワークフローが依存している可能性があるため、ユーザーの明示的な承認なしに .env ファイルを削除したり、既存の UserSecretsId エントリを削除したりしてはいけません。

ローカル開発を優先

このスキルは、本番環境へのデプロイではなく、ローカル開発を最適化します。データベースやキャッシュには、コンテナーのライフタイムとデータボリュームを永続化して使用し、デフォルトで HTTPS エンドポイントを使い、ハードコードした URL ではなくエンドポイントの参照を渡してください。また、外部 SaaS の URL や API キーはパラメーターとしてモデル化し、ダッシュボードで確認できるようにしてください。

Redis の TLS に関する例外

Aspire は、コンテナーリソース用の TLS 証明書を自動的にプロビジョニングできます。Redis のヘルスチェックで SSL/TLS ハンドシェイクエラーが発生した場合は、AddContainer() にフォールバックしないでください。接続するアプリがプレーンな Redis を想定している場合は、Redis リソースで WithoutHttpsCertificate() を使用してください。

プロジェクトローカルのオーバーライド

.agents/skills/aspireify/SKILL.md（aspire init または aspire agent init --skills aspireify によってインストール）が存在する場合は、プロジェクトローカルのコピーがあることをユーザーに警告し、そちらを優先してください。プラグインのバージョンはフォールバックです。

⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it.

前提条件

要件	インストール
.NET 10.0 SDK（C# AppHost）	https://dotnet.microsoft.com/download
Node.js ^20.19.0、^22.13.0、または >=24（TS AppHost）	https://nodejs.org
Aspire CLI	npm install -g @microsoft/aspire-cli、インストールスクリプト、または dotnet tool install -g Aspire.Cli
スケルトンがすでに配置済み	aspire init により aspire.config.json と AppHost のスタブが生成されていること

検出 — 有効化するタイミング

次のシグナルが1つ以上存在し、かつ AppHost が未配線（スタブ以外にリソースが宣言されていない）の場合に有効化します。

シグナル	検出方法	確度
スケルトンが配置された直後	このセッションで aspire init が実行された	✅ 確定
空の AppHost スタブ	apphost.cs / Program.cs / 現在の apphost.mts（または旧式の apphost.ts）に Build().Run() しか含まれていない	✅ 確定
リソースのない aspire.config.json	設定ファイルがあり、AppHost に AddProject/addProject がない	高
ユーザーがリソースグラフの「配線」や「スキャフォールディング」を依頼	動詞で判定：wire、scaffold、integrate、hook up、Postgres/Redis などの追加	高
ユーザーが「aspire init の次に何をすればよいか」と質問	直接的な引き継ぎリクエスト	✅ 確定
サービスがある既存リポジトリに新しい AppHost がある	リポジトリに .csproj/package.json のプロジェクトがあるが、AppHost がどれも参照していない	高

AppHost にすでにリソースが配線されていて、ユーザーがアプリの起動／停止を希望する場合は aspire-orchestration を使用します。ユーザーがデプロイを希望する場合は aspire-deployment を使用します。

言語サポート

AppHost のスタイル	検出方法	編集対象
C# SDK スタイル	<Sdk Name="Aspire.AppHost.Sdk" /> を含む .csproj	Program.cs（トップレベルステートメント）
ファイルベースの C#	#:sdk Aspire.AppHost.Sdk と #:package ディレクティブを含む apphost.cs	apphost.cs 自体
TypeScript	生成された .aspire/modules/ を含む、現在の apphost.mts または旧式の apphost.ts	設定された AppHost のエントリーポイントのみ — .aspire/modules/ は編集しないでください

references/csharp-authoring.md と references/typescript-authoring.md を参照してください。

aspire-orchestration は、旧式の apphost.ts からの CLI 主導の移行を担当します。パッケージと移行アーティファクトの更新後も、AppHost のソース配線または作成が必要な場合に限り、aspireify に戻ってください。

TypeScript AppHost パッケージマネージャー

依存関係やツールチェーンの問題は、このスキルの対象です。コマンドを推奨する前に、AppHost ディレクトリと、その直上にある対象の親ディレクトリを確認してください。各ディレクトリでは、次の順序で最初に見つかったマーカーが優先されます。

1. package.json の packageManager（npm、pnpm、yarn、bun。バージョン指定は任意）
2. bun.lock
3. bun.lockb
4. pnpm-lock.yaml
5. yarn.lock
6. .yarnrc.yml
7. package-lock.json

AppHost 内のマーカーは、親ディレクトリのすべてのマーカーより優先されます。どちらのディレクトリにも認識可能なマーカーがない場合、Aspire は npm をデフォルトで使用します。選択されたパッケージマネージャーとマーカーを報告してください。

選択したパッケージマネージャーは、依存関係の修復またはツールチェーンの診断にのみ使用してください。依存関係の解決コマンドは npm install、bun install、yarn install です。生成された brownfield の pnpm AppHost では pnpm install --ignore-workspace を使用し、それ以外の pnpm による依存関係のインストールでは pnpm install を使用してください。Yarn Classic（yarn@1... または v1 のロックファイル）はサポートされていません。処理を中止し、Yarn 4+ にアップグレードするか、npm、pnpm、Bun へ明示的に移行するようユーザーに依頼してください。

検出結果に影響を与えたり、パッケージマネージャーを切り替えたりするためだけに、packageManager を変更したり、ロックファイルを作成、置換、再生成したりしないでください。ユーザーが明示的にアップグレードまたは移行を選択するまでは、既存のファイルを保持してください。AppHost は、生のパッケージマネージャーランチャーではなく、aspire start --non-interactive で起動してください。コマンドの全一覧と依存関係の解決に関する詳細は、references/typescript-authoring.md を参照してください。

ワークフローのフェーズ

1. SCAN     → discover projects, services, dependencies, integration candidates
2. PROPOSE  → resource graph + integration list, confirm with user
3. EDIT     → wire AppHost, add ServiceDefaults + OTel + health checks
4. VALIDATE → aspire start --non-interactive → aspire wait <each resource>
5. DEACTIVATE → confirm clean start, hand off to aspire-orchestration

詳細な upstream と同等のワークフローについては、編集前に次のリファレンスを読み込んでください。

• apphost-wiring.md — AppHost の配線に関するワークフロー全体、API の参照、エンドポイント／パラメーターのパターン、検証、ソリューションの更新、クリーンアップ。
• docker-compose.md — docker-compose の移行、プロファイル、イメージのマッピング、ポート、ボリューム、depends_on。
• full-solution-apphosts.md — 大規模ソリューションのトリアージ、混在する SDK の境界、ソリューションへの登録、ServiceDefaults の配置、レガシーホストの移行。
• javascript-apps.md — JavaScript リソースの選択、ワークスペース／モノレポのパッケージマネージャーの取り扱い、ポート、スクリプト、TS AppHost のパッケージ設定。
• opentelemetry.md — 非 .NET サービス向けの、Node.js、Python、Go への任意の OpenTelemetry 配線。

1. スキャン

リポジトリを調べ、次の情報を一覧にします。

対象	方法
.NET プロジェクト	find . -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*'
Node サービス	find . -name 'package.json' -not -path '*/node_modules/*'
Python サービス	find . -name 'pyproject.toml' -o -name 'requirements.txt'
compose 内のコンテナー依存関係	docker-compose.yml、compose.yaml（Postgres？Redis？Rabbit？）
接続文字列	appsettings*.json、.env*、config/* を対象に Postgres、Redis、Mongo、RabbitMQ、Cosmos、ServiceBus を grep
統合パッケージ	プロジェクトごとに dotnet list package を実行。package.json の dependencies
既存のエンドポイント	launchSettings.json、next.config.js、vite.config.ts にハードコードされたポート

ヒューリスティクスの全容は references/scan-and-propose.md を参照してください。

2. 提案

編集前にリソースグラフを提示します。次のような確認事項を尋ねてください。

• 「docker-compose.yml に Postgres があります。AddPostgres('db') としてモデル化しますか、それとも Azure Database for PostgreSQL を使用しますか？」
• 「React アプリで http://localhost:5000 がハードコードされています。Aspire のサービス検出（endpoint.url）に置き換えますか？」
• 「API に /admin エンドポイントがあります。利用側に公開されないよう、WithReference() の対象から除外しますか？」

3. 編集

提案したグラフを適用します。AppHost の言語に適した記述スタイルを使用してください。

4. 検証

aspire start --non-interactive --format Json
aspire wait <resource>          # repeat for each declared resource
aspire describe --format Json   # sanity check graph

検証フロー全体と復旧方法は references/validation.md を参照してください。

5. 自動無効化

aspire start が正常に完了したら、次のように通知します。

✅ AppHost wired and validated. Handing off to aspire-orchestration for
   day-to-day start/stop/wait. Aspireify is done.

統合検出カタログ

検出されたサービスを Aspire の統合にマッピングします。カタログの全容については、 references/scan-and-propose.md を参照してください。

検出対象	C#	TS
compose 内の Postgres／Npgsql パッケージ	AddPostgres("pg").AddDatabase("db")	addPostgres('pg').addDatabase('db')
compose 内の Redis／StackExchange.Redis	AddRedis("cache")	addRedis('cache')
RabbitMQ	AddRabbitMQ("mq")（pub-sub トレースに対応した v7 クライアント）	addRabbitMQ('mq')
MongoDB	AddMongoDB("mongo")	addMongoDB('mongo')
Cosmos DB	AddAzureCosmosDB("cosmos")	addAzureCosmosDB('cosmos')
Azure Service Bus	AddAzureServiceBus("sb")	addAzureServiceBus('sb')
Azure Cache for Redis（Entra）	AddAzureRedis("cache")（GA になりました）	addAzureRedis('cache')
Next.js フロントエンド	AddNextJsApp("web", "./web")	addNextJsApp('web', '../web')
Vite SPA	AddViteApp("web", "./web")	addViteApp('web', '../web')
プレーンな Node アプリ	AddNodeApp("api", "server.js")	addNodeApp('api', 'server.js')

現在のオーサリングルール

ルール	理由
TS では統一された withEnvironment(name, value) を使用してください。非推奨の種類別ヘルパー（withEnvironmentEndpoint、withEnvironmentParameter など）は使用しないでください	単一の API ですべての値の種類を扱えます。種類別ヘルパーは非推奨です
JS フロントエンドでは、独自に Dockerfile を作成するのではなく、AddNextJsApp／AddViteApp を使用してください	ライフサイクルと PublishAs* の統合が標準で提供されます
JS の発行には PublishAsStaticWebsite／PublishAsNodeServer／PublishAsPackageScript を使用してください	独自に作成した Dockerfile を置き換えます。SPA → Static、SSR Node → NodeServer、package-script SSR → PackageScript となります
フロントエンドのリソースに WithBrowserLogs() を追加し、ブラウザーコンソールとスクリーンショットをダッシュボードで確認できるようにしてください	Aspire.Hosting.Browsers により、ブラウザーのテレメトリがダッシュボードに表示されます
複数の環境がある場合は、すべてのリソースを WithComputeEnvironment(env) でコンピューティング環境にバインドしてください	複数環境へのデプロイには明示的なバインドが必要です
TS AppHost の .aspire/modules/ は絶対に編集しないでください	生成ファイルのため、編集内容は上書きされます。設定済みの apphost.mts（または旧形式の apphost.ts）のみを編集してください
エンドポイントの更新には WithEndpoint("name", e => ...) を使用してください	エンドポイントのコールバックは、重複時に例外をスローするのではなく、既存のエンドポイントを更新します
管理者用エンドポイントには ExcludeReferenceEndpoint = true を設定してください	WithReference() 経由で利用側に管理者用 URL が渡るのを防ぎます
不慣れな API を調べるには、aspire docs api search <query> --language csharp|typescript を使用してください	オーバーロードやビルダーチェーンを推測しないでください
コンテキストの .Services／await ctx.services().getInteractionService() を使用してください	.ServiceProvider は廃止予定であり、ctx.services() 単独ではサービスアクセサーが返されます
外部接続文字列には AddConnectionString を使用してください	PublishAsConnectionString は廃止予定です
プロンプトを表示する前に IInteractionService.IsAvailable を確認してください	CLI から呼び出されたコマンドは非対話型の場合があります。ダッシュボードと CLI の入力にはコマンド引数を優先してください
WithTerminal() は実験的な機能として扱ってください	ASPIRETERMINAL001 を抑制してください。削除済みの TerminalOptions.Shell や TypeScript のディメンションオプションは生成しないでください
すべての Aspire SDK パッケージと Aspire.Hosting.* パッケージを同じリリース系列に揃えてください	リリース系列が混在すると、起動に失敗する場合があります
GitHub Models の統合は Azure AI Foundry に移行してください	Aspire.Hosting.GitHub.Models は非推奨であり、統合検出の対象にも含まれていません
Redis 8 のモジュールには WithModule(RedisModules.*) を使用してください	生のモジュールパスよりも、型付きの JSON、Search、Bloom Filter、TimeSeries 定数を優先してください
ホスト型の実行可能ファイル／コンテナーエージェントには、Foundry の AsHostedAgent(...) を使用してください	現在の Azure AI Foundry の方法は、非推奨の GitHub Models に代わるものです

C# と TS のクイックリファレンス

概念	C#	TypeScript
ビルダー	var builder = DistributedApplication.CreateBuilder(args);	const builder = await createBuilder();
プロジェクトの追加	builder.AddProject<Projects.Api>("api")（SDK）または AddProject("api", "../Api/Api.csproj")	await builder.addProject('api', '../Api/Api.csproj')
環境変数の設定（値の型は問いません）	.WithEnvironment("KEY", value)	.withEnvironment('KEY', value) ← 統一 API
依存関係を待機	.WaitFor(db)	.waitFor(db)
接続の受け渡し	.WithReference(db)	.withReference(db)
外部 HTTP	.WithExternalHttpEndpoints()	.withExternalHttpEndpoints()
エンドポイント式	api.GetEndpoint("http")	api.getEndpoint('http').url / .host / .port
ビルドと実行	builder.Build().Run();	await builder.build().run();

ServiceDefaults の接続

各プロジェクトで builder.AddServiceDefaults(); を呼び出し、OpenTelemetry、 ヘルスチェック、サービスディスカバリーを有効にしてください。Aspire.ServiceDefaults プロジェクトへの 参照を追加してください（モノレポ以外では NuGet を使用）。詳細は references/service-defaults.md を参照してください。

エンドポイントと参照の規約

// Public-facing API. Mark "admin" endpoint as not-for-consumers.
var api = builder.AddProject<Projects.Api>("api")
    .WithExternalHttpEndpoints()
    .WithEndpoint("admin", e => e.ExcludeReferenceEndpoint = true);

// Frontend wires the API via service discovery.
builder.AddNextJsApp("web", "./web")
    .WithReference(api)        // injects services__api__http and __https
    .WaitFor(api)
    .WithBrowserLogs();        // browser console + screenshots

検証と復旧

症状	対処
aspire start がビルドエラーで失敗する	コードを修正し、aspire start を再実行します
編集中にファイルロックエラーが発生する	aspire-orchestration に引き継ぐ → aspire stop → 再試行します
aspire describe にリソースが表示されない	aspire describe --include-hidden を再実行します。aspire ps は AppHost レベルです
TS AppHost の変更が反映されない	.aspire/modules/ ではなく、設定されている apphost.mts（または旧形式の apphost.ts）を編集したことを確認します
aspire start の JSON 出力に別の内容が混在する	解析前に JSON 以外の行を取り除きます（#15843）

全体のフローについては、references/validation.md を参照してください。

引き継ぎルール

シナリオ	引き継ぎ先
AppHost のひな形がまだ作成されていない	→ aspire-init スキル
日常的な起動／停止／待機／再起動	→ aspire-orchestration スキル
発行、デプロイ、破棄、パイプラインの手順	→ aspire-deployment スキル
ログ、トレース、メトリクス、ダッシュボード、ブラウザーログの確認	→ aspire-monitoring スキル
デプロイ済み（Azure／AKS）アプリの診断	→ azure-diagnostics スキル（azure-skills）

主なルール

• 既存のファイルを上書きしないでください — 必ず追記またはマージしてください。
• サービスコードを変更する前に確認してください。特に、OpenTelemetry と ServiceDefaults の挿入には注意してください。
• 既存のプロジェクト構成を尊重してください — リポジトリを再編成しないでください。
• 行き詰まった場合は、aspire doctor を使用して環境の問題を診断してください。
• WithEnvironment／withEnvironment に URL をハードコードしないでください — 文字列リテラルではなく、api.GetEndpoint("http") や api.getEndpoint('http') などのエンドポイント参照を渡してください。
• WithUrlForEndpoint／withUrlForEndpoint を使用して dev.localhost URL を設定しないでください — この API はダッシュボードの表示ラベル専用です。dev.localhost は AppHost の起動／プロファイル設定に指定してください。

参考資料

• apphost-wiring.md — AppHost の詳細な配線ワークフローと API の検索パターン
• docker-compose.md — Docker Compose の移行パターン
• full-solution-apphosts.md — 大規模なソリューション／ソリューション全体の AppHost に関するガイダンス
• javascript-apps.md — JavaScript／TypeScript アプリとワークスペースの扱い
• opentelemetry.md — .NET 以外の OpenTelemetry のセットアップ
• scan-and-propose.md — リポジトリのスキャンに関するヒューリスティックと統合カタログ
• csharp-authoring.md — C# AppHost のパターン
• typescript-authoring.md — TS AppHost のパターンと同等の API
• service-defaults.md — OTel、ヘルスチェック、サービス検出の配線
• validation.md — エンドツーエンドの検証と復旧
• aspire-13-5-breaking-changes.md — 13.5 で導入された破壊的変更と、影響を受けるリリース向けの修正