agent-context-dotnet

agent-context-dotnet — .NET リポジトリのコンテキストを構築する

コンテキストパックを生成します。これは、見慣れない .NET リポジトリを AI コーディングエージェントが理解しやすくする、相互にリンクされた小規模な Markdown ドキュメント群です。1 回の実行で、次の 2 つの部分を生成します。

• ベースパック — AGENTS.md、CLAUDE.md、および docs/（ビジネス、アーキテクチャ、データモデル、インフラストラクチャ、ADR）。
• .NET 詳細ガイド — docs/dotnet.md：ソリューションとプロジェクトのグラフ、ターゲットフレームワーク、パッケージ管理、EF Core によるデータアクセス、DI のコンポジションルート、構成とシークレット、アナライザーの方針、UI/API サーフェス、パッケージング、CI。

アプリケーションコードを書いたり、パッケージをインストールしたり、破壊的なコマンドを実行したりしてはいけません。出力として作成するのは、リポジトリのルートと docs/ 以下の Markdown ファイルのみです。

基本方針（常に念頭に置いてください）

• AGENTS.md は目次であり、百科事典ではありません。 約 80 行以内に収めてください。
• リポジトリが信頼できる唯一の情報源です。 リポジトリ内にない情報は、エージェントからは見えません。
• コンテキストは貴重なリソースです。 すべてのドキュメントのすべての行に、記載する価値がなければなりません。TODO だらけのセクションより、削除したセクションのほうが適切です。
• 段階的な情報開示。 AGENTS.md から専門ドキュメントへ案内し、各専門ドキュメントからさらに詳細な情報へ案内します。
• 推測せず、TODO を記載してください。 フレームワークのバージョン、NuGet のバージョン、スキーマの詳細を決して作り上げないでください。
• アプリケーションコードは書きません。 このスキルの役割はドキュメント作成であり、ビルドではありません。

入力：言語

$ARGUMENTS は en、es、または空です。

• $ARGUMENTS == "es" の場合 → ドキュメントをスペイン語で出力します。templates/es/ からテンプレートを読み込みます。
• $ARGUMENTS == "en" または空の場合 → ドキュメントを英語で出力します（デフォルト）。templates/en/ からテンプレートを読み込みます。

このスキル自体の指示（このファイル）は、英語のままにしてください。

---

フェーズ 1 — 調査（ユーザーには伝えずに実施）

ユーザーに話しかけずに行います。Glob、Grep、Read を使用してください。

1a. .NET リポジトリであることを確認する

*.csproj、*.sln、*.slnx、*.fsproj、*.vbproj、global.json、または Directory.Build.props を探してください。

「.NET ではない」と結論づける前に、ファイルベースアプリ（.NET 10 以降）も確認してください。#:package / #:sdk / #:project / #:property ディレクティブを含む単独の .cs ファイル、または #!/usr/bin/env dotnet のシバンが対象です。これらにはプロジェクトファイルがなく、*.csproj の glob では見つかりません。

何も該当しない場合は、処理を中止し、このスキルが適用されるのは .NET リポジトリのみであることをユーザーに伝えてください。ファイルは作成しないでください。

1b. 既存のコンテキストを検出 → 拡張モード

次のいずれかが存在する場合は、拡張モードに切り替えてください。

• リポジトリのルートにある AGENTS.md、CLAUDE.md
• .md ファイルを含む docs/ ディレクトリ
• ARCHITECTURE.md、ARCHITECTURE.rst
• ADR/、adrs/、decisions/、doc/adr/

拡張モードでは、既存の内容を読み、フェーズ 2 でユーザーに報告してから、不足しているドキュメントのみを作成してください。既存のファイルを上書きしてはいけません。

docs/ ツリーがこのスキルの作成物とは限りません。 多くのリポジトリには、独自のドキュメント（docs/architecture/、設計メモ、データベースダンプなど）が含まれており、このスキルで作成されたものではない場合があります。これらを編集してはいけません。ただし、既存の情報を無視したり重複させたりするのではなく、docs/dotnet.md の「関連ドキュメント」と AGENTS.md からリンクし、生成するコンテキストが既存のドキュメントを参照するようにしてください。

既存のドキュメントが 1 つの言語で書かれている場合は、フェーズ 2 の言語に関する質問でも、その言語に合わせることを優先してください。

1c. .NET の詳細調査

references/dotnet-inspection.md のチェックリストをすべて実施してください。ソリューションとプロジェクトのグラフ、ターゲットフレームワーク、パッケージ管理（中央パッケージ管理を含む）、Aspire によるオーケストレーション、データアクセス、DI、構成とシークレット、ビルド・実行・テスト（テストプラットフォームの違いを含む）、品質ゲート、UI/API サーフェス、デプロイとパッケージング、横断的関心事、C# 言語の方針、ホットスポットを確認します。

このチェックリストは条件付きです。リポジトリで実際に確認できるものだけを調査し、その条件性をドキュメントにも反映してください。該当しない docs/dotnet.md のセクションは削除してください。

実際のファイルを読んでください。確認できない事実は TODO として残し、推測してはいけません。

1d. 隣接するシグナル

.NET リポジトリが .NET だけで構成されていることはほとんどありません。これらを Glob で検索してください。architecture.md と infrastructure.md の作成に役立ちます。

シグナル	推測できること
Dockerfile、docker-compose*.yml、compose.yaml	コンテナ化（ただしチェックリストを参照してください。SDK は Dockerfile なしでイメージをビルドできます）
Chart.yaml、values.yaml、k8s/、kustomization.yaml	Kubernetes ／ Helm
*.tf、terraform.tfvars、*.bicep、cdk.json、serverless.yml、template.yaml	Infrastructure as Code
azure-pipelines*.yml、.github/workflows/、Jenkinsfile、.gitlab-ci.yml	CI/CD
*.wsdl、*.xsd、*.proto、openapi.yaml、swagger.json	API 契約のスタイル（SOAP、gRPC、REST）
package.json、pnpm-workspace.yaml、angular.json、vite.config.*	.NET バックエンドと並行する JS/TS フロントエンド
sonar-project.properties、.editorconfig	品質ゲート（詳細はチェックリストを参照）

1e. README を読む

README.md がある場合は読み、プロジェクトの概要を一文でまとめる際の参考にしてください。大きな まとまりをそのままコピーしてはいけません。目的だけを抽出してください。

1f. 明らかなドメインの手がかりを調べる

エンティティ／モデル／DbContext クラスを Grep で検索します。主要なドメイン名詞（例：Order、 Invoice、Patient、Course）を記録してください。これらは Phase 2 の質問の手がかりとしてのみ使い、 確認できないドメインをでっち上げてはいけません。

---

Phase 2 — 質問

ここでは10問前後が標準ですが、リポジトリに重要な情報の不足が実際にある場合は、さらに質問しても問題ありません。 面倒にならないのは、スキップルールが絶対だからです。 Phase 1 ですでに読み取った内容を質問してはいけません。 十分に文書化されたリポジトリなら質問が3つで済む場合もありますし、ドキュメントがほとんどない古いソリューションなら12問になる場合もあります。どちらも適切です。

AskUserQuestion は1回あたり質問を4つ、各質問の選択肢を4つまでに制限しているため、構造化された質問は2回に分けて送る必要があります。 自由記述の回答にはまったく適していないため、通常のチャットで質問してください。

2a. バッチ A — 範囲と曖昧さの解消（AskUserQuestion を1回）

1. 出力言語 — $ARGUMENTS が空の場合のみ。選択肢：English (default)、Spanish。
2. 任意のドキュメント — 「target-user.md や design.md も生成しますか？」multiSelect: true。 選択肢：target-user.md、design.md。
3. 追加モードの確認 — Phase 1b で既存のドキュメントが見つかった場合のみ：「既存のドキュメントが検出されました： [list]。不足分のみ生成しますか？」選択肢：Yes (augment only)、Overwrite matching docs、 Cancel。
4. Phase 1 で解消できなかった曖昧さ — 調査で判断できなかった事項を1つだけ質問します。通常は DB プロバイダー （DbContext とパッケージ一覧の内容が食い違う場合）か、主なターゲットフレームワーク（プロジェクトごとに異なる場合）です。一般的な候補ではなく、実際に確認した有力候補を提示してください。

2b. バッチ B — リポジトリ外にある情報（2回目の AskUserQuestion）

5. 本番環境のデプロイ先 — ソースから読み取れることはほとんどなく、infrastructure.md の作成に必要です。選択肢：Azure App Service、Azure Container Apps / AKS、IIS on VM / on-prem、Other。
6. 本番環境のシークレットの保存先 — 選択肢：Azure Key Vault、Environment variables、 User-secrets only (dev)、Other。
7. 認証／ID モデル — パッケージから判断できない場合のみ。選択肢： Entra ID (Microsoft.Identity.Web)、ASP.NET Core Identity、IdentityServer / Duende、 Other。
8. 本番環境への反映方法 — マージ後、デプロイ先に反映されるまでの流れ：CI deploys on merge to main、Tag / release triggers deploy、Manual release、Other。infrastructure.md の作成に役立ちます。 パイプラインファイルでビルド手順は確認できても、デプロイ先への反映手順がわからないことがよくあります。

2c. 自由記述の回答 — 通常のチャットで質問する

9. ビジネスコンテキスト — 「1～2文で、この製品は何をするもので、誰が料金を支払いますか？」
10. 自明ではないルール — 「AI コーディングエージェントが把握しておく必要がある、不変条件や注意点を最大3つ挙げてください。ただし、リンターやテストでは強制できないものに限ります。例：「Core から Infrastructure を参照してはならない」、「テナントのクエリフィルターを決して迂回しない」、「常に CancellationToken を引き回す」、「API の起動前にマイグレーションを実行する」、「レガシーの Billing プロジェクトに手を加えない」。思い当たるものがなければ、「skip」と回答してください。」

2d. 条件付きの追加質問 — リポジトリに情報の不足がある場合のみ質問する

11. テストに関する期待事項 — Phase 1 でテストカバレッジが薄い、または不足していると判明した場合のみ：「このリポジトリで変更を完了とみなす基準は何ですか？単体テストのみ、統合テスト必須、またはエンドツーエンドテストですか？」
12. オーナーシップ／エスカレーション — CODEOWNERS がなく、明確なメンテナーもいない場合のみ：「このリポジトリの変更をレビューするのは誰ですか？」

インタビューが完了するまで、Phase 3 に進まないでください。

---

Phase 3 — ドラフトの作成

生成する各ドキュメントについて、templates/<lang>/<doc>.md.template のテンプレートを読み込み、プレースホルダーを置き換えて、対象のパスに書き込みます。プレースホルダーは {{UPPER_SNAKE}} 形式です。各テンプレートの先頭に、そのテンプレート固有のプレースホルダーが記載されています。

対象のパス：

• AGENTS.md（リポジトリのルート）— Phase 4 を参照
• CLAUDE.md（リポジトリのルート）— Phase 4 を参照
• docs/business.md
• docs/architecture.md
• docs/data-model.md
• docs/infrastructure.md
• docs/dotnet.md
• docs/adrs/README.md + docs/adrs/adr-template.md + docs/adrs/adr-0001-<slug>.md（シード ADR 1～3件）
• docs/target-user.md（オプトインした場合のみ）
• docs/design.md（オプトインした場合のみ）

テンプレートへの記入ルール：

• 短い文を使ってください。明確さを優先し、文法は犠牲にしてかまいません。
• セクションの情報がない場合は、`` マーカーを残してください。内容をでっち上げてはいけません。セクション全体が該当しない場合（UI、Aspire、MAUI がないなど）は、TODO で埋めずに削除してください。
• 拡張モードでは、ユーザーのコンテンツを決して上書きしないでください。 `` の箇所を埋めるか、明確なラベルを付けたサブセクションを追加し、それ以外はそのままにします。リポジトリにすでに含まれているドキュメントは読み取り専用です。代わりに相互リンクを追加してください。

各ドキュメントに含めるべき .NET の調査結果：

• docs/dotnet.md — Phase 1c の主要な成果物です。プロジェクト一覧と参照グラフには、実際のプロジェクト名を記載してください。他のドキュメントの内容を繰り返さず、相互リンクを追加してください。
• docs/architecture.md — 技術スタックの概要にフレームワークと EF Core を明記してください（例：「ASP.NET Core 10 + SQL Server + EF Core 10」）。また、プロジェクトグラフとレイヤー構成について docs/dotnet.md を参照する一文を加えてください。
• docs/data-model.md — マイグレーションツールは EF Core です。DbContext の場所、プロバイダー、マイグレーションのワークフロー（dotnet ef、起動時の Migrate()、または CI での適用）を記録してください。
• docs/infrastructure.md — CI システムとそのパイプラインファイル、構成とシークレットのレイヤー構成、デプロイ／パッケージングの形式を記載してください（Dockerfile または SDK によるコンテナー発行、使用されている場合は AOT／トリミング／単一ファイル発行）。

ADR のシード — 明確に行われた決定を1～3件提案してください。各 ADR に Status、Context（検討した代替案を含む）、Decision、Consequences（容易になること／難しくなること）を含めます。適切な候補：

• adr-0001-target-framework.md — ソリューションで標準とするターゲットフレームワーク。
• データアクセス — 永続化方式としての EF Core（およびプロバイダー）。
• Dockerfile、IaC、または SDK のコンテナープロパティが検出された場合は、デプロイ先。

ADR の根拠を決して捏造しないでください。

フェーズ 4 — 接続（AGENTS.md + CLAUDE.md）

AGENTS.md は厳密に目次として生成します。

• 冒頭： 最大 2 行（プロジェクト名 + 目的を 1 行で説明）。
• 「Where to find things」： すべてのドキュメントを箇条書きにし、それぞれ 1 行で説明します。 docs/dotnet.md（「.NET の詳細なコンテキスト：プロジェクトグラフ、TFM、EF Core、DI」）と、フェーズ 1b で見つかった既存のリポジトリドキュメントも含めます。
• 「Commands」： 開発者が実際に実行する 3〜6 個のコマンドを記載します。慣例ではなく、実際のリポジトリから選びます。
  • Aspire がある場合、エントリポイントは aspire run / dotnet run --project *.AppHost です。各サービスを個別に実行するのではありません。これを誤ると、エージェントを誤った経路に進ませてしまいます。
  • リポジトリで実際に必要なテストコマンド（チェックリストのテストプラットフォームの違いを参照）と、dotnet ef の呼び出し方法（グローバルツールか dotnet tool run か）を記載します。
• 「Non-obvious rules」： フェーズ 2 でユーザーが回答した内容を、それぞれ簡潔な理由とともに箇条書きにします。エージェントが確実に間違える、調査で判明した機械的なルールも追加します。
  • パッケージ管理の一元化：Directory.Packages.props でバージョンを管理している場合、.csproj 内の <PackageReference> に Version を含めてはなりません。
  • AOT / トリミングに関する制約（制限のないリフレクションや、リフレクションベースのシリアル化を使用しない）。
  • 存在する場合は、プロジェクトのレイヤリングに関するルール。
• 「Testing」 と 「Code style」： フェーズ 1 で検出したフレームワークとアナライザーを明記し、それぞれ 1 段落で記述します。
• 「Security」： シークレットをコミットしないこと、.env / user-secrets を VCS に含めないこと、PII をログに記録しないこと。

約 80 行の上限を守ります。超える場合は、詳細を docs/dotnet.md に移します。

CLAUDE.md は 1 行とし、@AGENTS.md を記載して、委譲する旨のコメントを添えます。

---

フェーズ 5 — 記述内容の検証（Claimify に着想）

生成されたドキュメントには、事実と異なる内容が含まれることがあります。完了する前に、記述した根拠となる重要な事実の主張を洗い出し、不確かなものをユーザーに確認します。この手順は Microsoft Research のClaimifyを参考にしています。原子的で、自己完結しており、検証可能な主張を抽出し、推測せずに曖昧さを明示します。references/claim-validation.md の全手順に従ってください。要点は次のとおりです。

1. 選択。 作成したドキュメントから、検証可能で根拠となる重要な主張を選びます。対象フレームワーク、永続化プロバイダーとマイグレーションのワークフロー、デプロイ先、CI システム、主要なエンティティ、コマンド、パッケージのバージョン、DI のライフタイム、ユーザーが示した重要なルールが含まれます。TODO、定型文、意見は除外します。
2. 原子化 + 出典のタグ付け。 それぞれを自己完結した 1 つの記述とし、出典（file:line または inferred）と確信度を付けます。確信度は high（ファイルから読み取った）、medium（弱い根拠が 1 つ）、low（推測 / 未検証）とします。
3. 曖昧さの明示。 複数の妥当な解釈がある主張や、明確な出典がない主張（例：2 つのプロジェクトで対象フレームワークの指定が異なる場合）には、曖昧さを明示します。確信度が low の主張を黙って残してはなりません。
4. ユーザーによる確認。 簡潔な一覧を提示し、medium / low の主張と曖昧な主張について、確認または修正を依頼します（優先度の高い二択の確認には AskUserQuestion を使用し、それ以外は通常のチャットで確認します）。具体的な出典のある確信度 high の主張も提示しますが、確認を必須とはしません。
5. 反映。 修正内容をドキュメントに反映します。確認されていない確信度 low の主張は、断定せず `` に置き換えます。
6. 保存。 監査証跡として、一覧を docs/claims-ledger.md に保存します（形式はリファレンスを参照）。

フェーズ 6 — 検証

1. 作成または追記したファイルのツリーを出力します。
2. AGENTS.md と docs/dotnet.md 内のすべてのリンクが、実在するファイルを参照していることを確認します （Read を使用）。
3. ユーザーに次の点を伝えます。
   • コミット：git add AGENTS.md CLAUDE.md docs/ && git commit -m "docs: bootstrap .NET context pack for AI coding agents"
   • `` マーカーを埋め、ADR を確認し、docs/claims-ledger.md に未検証の項目が残っていないか目を通してください。
   • 品質ゲートがない場合は、.editorconfig とアナライザー （StyleCop.Analyzers、Microsoft.CodeAnalysis.NetAnalyzers）、および アーキテクチャのレイヤリングを強制するアーキテクチャリンティングツール （NsDepCop / ArchUnitNET）の導入を検討してください。
   • 後日 /arkandia:agent-context-dotnet を再実行してください。既存の内容を上書きせず、追記します。

---

参考資料

• references/dotnet-inspection.md — .NET の完全な調査チェックリスト（フェーズ 1c）。
• references/claim-validation.md — Claimify に着想を得たクレーム検証手順（フェーズ 5）。
• templates/en/ と templates/es/ — ドキュメントのひな形。

ルール

• アプリケーションコードを書かないでください。
• ユーザーが明示的に許可していない限り、既存のドキュメントを上書きしないでください。TODO を埋めるか、明確に区別できるセクションを追記して内容を充実させてください。
• 読んでいないフレームワークやパッケージのバージョン、プロバイダー、エンドポイント名、スキーマを捏造しないでください。
• 人の入力が必要な箇所には `` マーカーを残し、該当しないセクションは水増しせず削除してください。
• 各ドキュメントの焦点を絞ってください。それぞれの役割は 1 つにし、AGENTS.md から委任してください。