agent-context-dotnet

agent-context-dotnet — 引导 .NET 仓库上下文

你正在生成一个上下文包：一组小型、相互链接的 Markdown 文档，让 AI 编码 Agent 能够读懂陌生的 .NET 仓库。它分为两部分，在一次运行中生成：

• 基础包 — AGENTS.md、CLAUDE.md 和 docs/（业务、架构、数据模型、基础设施、ADR）；
• .NET 深入指南 — docs/dotnet.md：解决方案／项目关系图、目标框架、包管理、EF Core 数据访问、DI 组合根、配置与密钥、分析器配置、UI／API 表面、打包和 CI。

你绝不能编写应用程序代码、安装包或运行破坏性命令。你唯一的输出是仓库根目录和 docs/ 下的 Markdown 文件。

理念（请始终牢记）

• AGENTS.md 是目录，不是百科全书。 控制在约 80 行以内。
• 仓库是事实来源。 仓库之外的内容对 Agent 不可见。
• 上下文是稀缺资源。 每份文档中的每一行都必须物有所值。删掉一个章节，也好过留下满是 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 shebang 的文件。这类应用没有项目文件，使用 *.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 中建立指向它们的链接，让生成的上下文指向已有内容，而不是忽略或重复编写。

如果已有文档使用某种语言，在阶段 2 的语言问题中优先选择该语言。

1c. .NET 深入发现

执行 references/dotnet-inspection.md 中的完整检查清单。它涵盖解决方案／项目关系图、目标框架、包管理（包括集中式包管理）、Aspire 编排、数据访问、DI、配置与密钥、构建／运行／测试（包括测试平台的区分）、质量门禁、UI／API 表面、部署与打包、横切关注点、C# 语言配置以及热点。

此检查清单按条件执行：只检查仓库实际显示的内容，并在文档中保留这种条件性——删除不适用的 docs/dotnet.md 章节。

阅读真实文件。无法从文件中确认的事实应留下 TODO，不要猜测。

1d. 相邻信号

.NET 仓库很少只包含 .NET。请搜索以下内容，因为它们会为 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	基础设施即代码
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 类。记录主要的领域名词（例如 Order、 Invoice、Patient、Course）。仅将它们作为第二阶段访谈的参考 — 不要臆测无法验证的领域。

---

第二阶段 — 访谈

通常会问大约十个问题；如果仓库确实存在影响重大且尚未解决的信息缺口，多问也无妨。 让访谈不至于冗长的关键在于跳过规则，这条规则必须严格遵守： 第一阶段已经读取的信息，绝不要再问。 对文档完善的仓库，最后可能只需问三个问题；对缺少文档的旧版解决方案，可能要问十二个问题。两种情况都没问题。

AskUserQuestion 每次调用最多支持 4 个问题，每个问题最多 4 个选项，因此结构化问题需要分两批调用。它完全不适用于长篇回答 — 请在普通聊天中提问。

2a. 第一批 — 范围与消歧（调用一次 AskUserQuestion）

1. 输出语言 — 仅当 $ARGUMENTS 为空时询问。选项：English (default)、Spanish。
2. 可选文档 — “是否也生成 target-user.md 和/或 design.md？” multiSelect: true。 选项：target-user.md、design.md。
3. 增补模式确认 — 仅当第一阶段 1b 发现已有文档时询问：“检测到已有文档： [列表]。是否只生成缺失的文档？”选项：Yes (augment only)、Overwrite matching docs、 Cancel。
4. 第一阶段的歧义 — 发现过程中无法确定的一项信息。通常是数据库提供程序 （当 DbContext 与软件包列表不一致时）或主要目标框架（当各项目不同时）。 请提供你实际读到的主要候选项，而非泛泛的选项。

2b. 第二批 — 仓库之外的信息（第二次调用 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. 身份验证 / 身份模型 — 仅当无法从软件包中确定时询问。选项： 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. 业务背景 — “请用一两句话说明：这个产品是做什么的，谁会为它付费？”
10. 不明显的规则 — “最多列出 3 条 AI 编码 Agent 必须了解、但无法通过代码检查工具或测试强制执行的不变量或注意事项。例如：‘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（1–3 篇种子 ADR）
• 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-0001-target-framework.md — 解决方案统一采用的目标框架。
• 数据访问 — 以 EF Core（及其提供程序）作为持久化方案。
• 部署目标（如果检测到 Dockerfile、IaC 或 SDK 容器属性）。

绝不要捏造 ADR 的决策依据。

阶段 4 — 接入（AGENTS.md + CLAUDE.md）

严格将 AGENTS.md 生成为目录：

• **开头：**最多 2 行（项目名称 + 一句话用途）。
• **“内容索引”：**列出每份文档，并用一句话描述，包括 docs/dotnet.md（“.NET 深度上下文：项目图、TFM、EF Core、DI”）以及在阶段 1b 中发现的任何现有仓库文档。
• **“命令”：**开发者实际运行的 3–6 条命令。根据真实仓库确定，而不是凭习惯臆测：
  • 存在 Aspire 时，入口是 aspire run / dotnet run --project *.AppHost，而不是分别运行各个服务。弄错会让 Agent 走错方向。
  • 注明仓库的运行器实际需要的测试命令（参见清单中的测试平台划分），以及 dotnet ef 的调用方式（全局工具还是 dotnet tool run）。
• **“不明显的规则”：**将用户在阶段 2 的回答各列为一条项目符号，并附上简短理由。 补充发现过程中找到的机械规则，这些规则是 Agent 经常弄错的：
  • 集中式包管理 — 当 Directory.Packages.props 管理版本时，.csproj 中的 <PackageReference> 不得包含 Version；
  • 任何 AOT / 修剪限制（不得使用无界反射，不得使用基于反射的序列化）；
  • 项目分层规则（如有）。
• **“测试”和“代码风格”：**各写一段，注明阶段 1 中检测到的框架和分析器。
• **“安全”：**不得提交密钥；.env / user-secrets 不得纳入 VCS；不得记录 PII。

确保不超过约 80 行。若超出，请将详细内容移至 docs/dotnet.md。

CLAUDE.md 只写一行：@AGENTS.md，并附注释说明它会委托给该文件。

---

阶段 5 — 验证声明（受 Claimify 启发）

生成的文档可能包含幻觉。完成前，请列出你所写的关键事实声明，并向用户确认不确定的部分。此步骤改编自 Microsoft Research 的 Claimify ——提取原子化、自包含、可验证的声明，并在存在歧义时明确指出，而非猜测。完整遵循 references/claim-validation.md。简而言之：

1. **筛选。**从刚写好的文档中挑出可验证且关键的声明：目标框架、持久化提供程序和迁移工作流、部署目标、CI 系统、关键实体、命令、包版本、DI 生命周期，以及用户提出的不明显规则。跳过 TODO、样板内容和观点。
2. **原子化并标注来源。**每条声明都应是自包含的陈述，并注明来源引用（file:line 或 inferred）和置信度：high（从文件中读取）、medium（只有一个较弱的信号）、low（猜测 / 未验证）。
3. **标明歧义。**标记有多种合理解读或没有明确来源的声明（例如，两个项目固定了不同的目标框架）。绝不要悄悄保留低置信度声明。
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 或追加明确标记的章节来补充内容。
• 不要编造尚未查阅过的框架或包版本、提供程序、端点名称或架构。
• 如果需要人工输入，请保留 `` 标记；对于不适用的章节，应删除，而不是凑字数。
• 每份文档都应聚焦于单一职责，并由 AGENTS.md 分派。