agent-context-dotnet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-context-dotnet — Bootstrap .NET Repository Context

agent-context-dotnet — 快速搭建.NET仓库上下文

You are generating a context pack: a small, cross-linked set of Markdown docs that makes an unfamiliar .NET repository legible to an AI coding agent. It has two halves, produced in one run:

the base pack —
```
AGENTS.md
```
,
```
CLAUDE.md
```
, and
```
docs/
```
(business, architecture, data model, infrastructure, ADRs);
the .NET deep-dive —
```
docs/dotnet.md
```
: the solution/project graph, target frameworks, package management, EF Core data access, the DI composition root, configuration & secrets, analyzer posture, the UI/API surface, packaging, and CI.

You MUST NOT write application code, install packages, or run destructive commands. Your only outputs are Markdown files at the repo root and under

docs/

你将生成一个上下文包：一组小型、相互关联的Markdown文档，让AI编码Agent能够读懂陌生的.NET仓库。一次运行会生成两部分内容：

基础包——
```
AGENTS.md
```
、
```
CLAUDE.md
```
和
```
docs/
```
目录（业务文档、架构文档、数据模型、基础设施文档、ADRs）；
.NET深度解析——
```
docs/dotnet.md
```
：包含解决方案/项目图谱、目标框架、包管理、EF Core数据访问、DI组合根、配置与密钥、分析器配置、UI/API接口、打包和CI内容。

你绝对不能编写应用代码、安装包或执行破坏性命令。唯一的输出是仓库根目录和

docs/

下的Markdown文件。

Philosophy (hold these in mind throughout)

核心原则（全程遵循）

AGENTS.md is a table of contents, not an encyclopedia. Keep it under ~80 lines.
The repository is the system of record. Anything not in the repo is invisible to the agent.
Context is a scarce resource. Every line in every doc must earn its place. A deleted section beats a section full of TODOs.
Progressive disclosure. AGENTS.md points to specialized docs; each specialized doc delegates further.
TODOs over fabrication. Never invent a framework version, NuGet version, or schema detail.
No application code. This skill documents; it does not build.

AGENTS.md是目录，不是百科全书。控制在约80行以内。
仓库是唯一可信来源。不在仓库中的内容对Agent不可见。
上下文是稀缺资源。每篇文档的每一行都必须有存在的价值。删除一个章节比留下满是TODO的章节更好。
渐进式披露。AGENTS.md指向专业文档；每个专业文档进一步关联更细分的内容。
优先留TODO而非编造内容。绝不凭空捏造框架版本、NuGet版本或 schema 细节。
不编写应用代码。此工具仅负责文档生成，不负责构建项目。

Input: language

输入：语言

$ARGUMENTS

is either

en

es

, or empty.

If
```
$ARGUMENTS == "es"
```
→ output docs in Spanish. Load templates from
```
templates/es/
```
.
If
```
$ARGUMENTS == "en"
```
or empty → output docs in English (default). Load templates from
```
templates/en/
```
.

The skill's own instructions (this file) stay in English regardless.

$ARGUMENTS

的值为

en

、

es

或为空。

若
```
$ARGUMENTS == "es"
```
→ 生成西班牙语文档，从
```
templates/es/
```
加载模板。
若
```
$ARGUMENTS == "en"
```
或为空 → 默认生成英语文档，从
```
templates/en/
```
加载模板。

本工具自身的说明文档（即本文）始终保持英语不变。

Phase 1 — Discover (silent)

第一阶段——发现（静默执行）

Do this without talking to the user. Use Glob, Grep, and Read.

此阶段无需与用户交互，使用Glob、Grep和Read命令完成。

1a. Confirm this is a .NET repo

1a. 确认这是.NET仓库

Look for

*.csproj

*.sln

*.slnx

*.fsproj

*.vbproj

global.json

, or

Directory.Build.props

Before concluding "not .NET", also check for file-based apps (.NET 10+): standalone

.cs

files carrying

#:package

#:sdk

#:project

#:property

directives, or a

#!/usr/bin/env dotnet

shebang. These have no project file and a

*.csproj

glob will miss them.

If nothing matches, stop and tell the user this skill only applies to .NET repositories. Write no files.

查找

*.csproj

、

*.sln

、

*.slnx

、

*.fsproj

、

*.vbproj

、

global.json

或

Directory.Build.props

文件。

在判定“非.NET仓库”前，还需检查基于文件的应用（.NET 10+）：带有

#:package

#:sdk

#:project

#:property

指令的独立

.cs

文件，或带有

#!/usr/bin/env dotnet

shebang的文件。这类应用没有项目文件，用

*.csproj

全局搜索会遗漏。

如果完全没有匹配项，停止操作并告知用户此工具仅适用于.NET仓库，不生成任何文件。

1b. Detect prior context → augment mode

1b. 检测已有上下文 → 切换至增量模式

If ANY of these exist, switch to augment mode:

```
AGENTS.md
```
,
```
CLAUDE.md
```
at repo root
```
docs/
```
directory with
```
.md
```
files
```
ARCHITECTURE.md
```
,
```
ARCHITECTURE.rst
```
```
ADR/
```
,
```
adrs/
```
,
```
decisions/
```
,
```
doc/adr/
```

In augment mode: read what exists, report it to the user in Phase 2, and only create missing docs. Never overwrite.

A
docs/
tree is not necessarily yours. Many repos ship their own documentation (

docs/architecture/

, design notes, database dumps) that this skill did not create. Those are not yours to edit — but DO cross-link them from

docs/dotnet.md

("Related docs") and from AGENTS.md, so the generated context points at what already exists instead of ignoring or duplicating it.

When pre-existing docs are in one language, prefer matching it in Phase 2's language question.

若存在以下任意一项，切换至增量模式：

仓库根目录下的
```
AGENTS.md
```
、
```
CLAUDE.md
```
包含
```
.md
```
文件的
```
docs/
```
目录
```
ARCHITECTURE.md
```
、
```
ARCHITECTURE.rst
```
```
ADR/
```
、
```
adrs/
```
、
```
decisions/
```
、
```
doc/adr/
```
目录

增量模式下：读取已有文档，在第二阶段告知用户，仅生成缺失的文档，绝不覆盖已有内容。

docs/
目录下的内容不一定是本工具生成的。许多仓库自带自己的文档（如

docs/architecture/

、设计说明、数据库转储文件），这些内容不可编辑——但需在

docs/dotnet.md

的“相关文档”部分和AGENTS.md中添加交叉链接，让生成的上下文指向已有内容，而非忽略或重复。

当已有文档为某种语言时，第二阶段询问语言时优先匹配该语言。

1c. Deep .NET discovery

1c. .NET深度发现

Run the full checklist in

references/dotnet-inspection.md

. It covers the solution/project graph, target frameworks, package management (including central package management), Aspire orchestration, data access, DI, configuration & secrets, build/run/test including the test-platform split, quality gates, the UI/API surface, deployment & packaging, cross-cutting concerns, the C# language posture, and hotspots.

The checklist is conditional: inspect only what the repo actually signals, and carry that conditionality into the doc — delete

docs/dotnet.md

sections that don't apply.

Read real files. Where a fact isn't readable, you'll leave a TODO — do not guess.

执行

references/dotnet-inspection.md

中的完整检查清单，涵盖解决方案/项目图谱、目标框架、包管理（包括中央包管理）、Aspire编排、数据访问、DI、配置与密钥、构建/运行/测试（包括测试平台拆分）、质量门禁、UI/API接口、部署与打包、横切关注点、C#语言规范和热点模块。

检查清单是条件式的：仅检查仓库实际存在的内容，并将这种条件性带入文档——删除

docs/dotnet.md

中不适用的章节。

读取真实文件。若无法获取某一事实，留TODO标记——绝不猜测。

1d. Adjacent signals

1d. 关联信号检测

A .NET repo is rarely only .NET. Glob for these, since they feed

architecture.md

and

infrastructure.md

Signal	Infer
`Dockerfile` , `docker-compose*.yml` , `compose.yaml`	Containerization (but see the checklist — the SDK can build images with no 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 contract style (SOAP, gRPC, REST)
`package.json` , `pnpm-workspace.yaml` , `angular.json` , `vite.config.*`	JS/TS frontend alongside the .NET backend
`sonar-project.properties` , `.editorconfig`	Quality gates (details in the checklist)

.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. Read the README

1e. 读取README

Read

README.md

if present. Use it to seed the one-line project summary. Do NOT copy large chunks — just extract the purpose.

若存在

README.md

则读取，提取项目的一行简介作为种子内容。不要大段复制——仅提取核心用途。

1f. Scan for obvious domain cues

1f. 扫描明显的领域线索

Grep the entity / model /

DbContext

classes. Note dominant domain nouns (e.g.

Order

Invoice

Patient

Course

). Use them only as prompts for your Phase 2 interview — don't hallucinate a domain you can't verify.

全局搜索实体/模型/

DbContext

类，记录主要领域名词（如

Order

、

Invoice

、

Patient

、

Course

）。仅将这些名词作为第二阶段访谈的提示——绝不编造无法验证的领域信息。

Phase 2 — Interview

第二阶段——访谈

Around ten questions is the norm here, and asking more is fine when the repo genuinely left a load-bearing gap. What keeps that from being tedious is the skip rule, which is absolute: never ask what Phase 1 already read. On a well-documented repo you may end up asking three questions; on a bare legacy solution, twelve. Both are correct.

AskUserQuestion

caps at 4 questions per call and 4 options per question, so the structured set needs two batched calls. Long-form answers don't fit it at all — ask those in plain chat.

通常约10个问题，若仓库存在大量关键信息缺失，可适当增加问题。避免繁琐的关键是跳过规则：绝不询问第一阶段已获取的信息。对于文档完善的仓库，可能只需问3个问题；对于基础薄弱的遗留解决方案，可能需要问12个问题，两种情况都是合理的。

AskUserQuestion

每次调用最多4个问题，每个问题最多4个选项，因此结构化问题需要分两次批量调用。长文本回答不适合此方式——直接用普通聊天询问。

2a. Batch A — scope and disambiguation (one

AskUserQuestion

)

2a. 批量A——范围与歧义消除（一次

AskUserQuestion

调用）

Output language — only if
```
$ARGUMENTS
```
was empty. Options:
```
English (default)
```
,
```
Spanish
```
.

Optional docs — "Generate also

target-user.md

and/or

design.md

multiSelect: true

. Options:

target-user.md

design.md

Augment-mode confirmation — only if Phase 1b found existing docs: "Existing docs detected: [list]. Only generate missing ones?" Options:
```
Yes (augment only)
```
,
```
Overwrite matching docs
```
,
```
Cancel
```
.
Phase-1 ambiguity — the one thing discovery could not settle. Usually the DB provider (when the
```
DbContext
```
and the package list disagree) or the primary target framework (when projects differ). Offer the top candidates you actually read, not generic ones.

输出语言——仅当
```
$ARGUMENTS
```
为空时询问。选项：
```
English (default)
```
、
```
Spanish
```
。
可选文档——“是否同时生成
```
target-user.md
```
和/或
```
design.md
```
？”
```
multiSelect: true
```
。选项：
```
target-user.md
```
、
```
design.md
```
。
增量模式确认——仅当第一阶段1b检测到已有文档时询问：“检测到已有文档：[列表]。仅生成缺失的文档？”选项：
```
Yes (augment only)
```
、
```
Overwrite matching docs
```
、
```
Cancel
```
。
第一阶段歧义点——发现阶段无法确定的一个问题，通常是数据库提供程序（当
```
DbContext
```
和包列表不一致时）或主要目标框架（当项目间存在差异时）。提供实际读取到的候选选项，而非通用选项。

2b. Batch B — facts that live outside the repo (second

AskUserQuestion

)

2b. 批量B——仓库外的事实信息（第二次

AskUserQuestion

调用）

Production deployment target — rarely readable from source, and
```
infrastructure.md
```
needs it. Options:
```
Azure App Service
```
,
```
Azure Container Apps / AKS
```
,
```
IIS on VM / on-prem
```
,
```
Other
```
.

Production secrets source — Options:

Azure Key Vault

Environment variables

User-secrets only (dev)

Other

Auth / identity model — only if ambiguous from the packages. Options:

Entra ID (Microsoft.Identity.Web)

ASP.NET Core Identity

IdentityServer / Duende

Other

Path to production — how a merge reaches the deployment target:
```
CI deploys on merge to main
```
,
```
Tag / release triggers deploy
```
,
```
Manual release
```
,
```
Other
```
. Feeds
```
infrastructure.md
```
; the pipeline file often shows the build but not the promotion path.

生产部署目标——很少能从源码中读取到，但
```
infrastructure.md
```
需要此信息。选项：
```
Azure App Service
```
、
```
Azure Container Apps / AKS
```
、
```
IIS on VM / on-prem
```
、
```
Other
```
。

生产密钥来源——选项：

Azure Key Vault

、

Environment variables

、

User-secrets only (dev)

、

Other

。

认证/身份模型——仅当从包信息中无法明确时询问。选项：
```
Entra ID (Microsoft.Identity.Web)
```
、
```
ASP.NET Core Identity
```
、
```
IdentityServer / Duende
```
、
```
Other
```
。
上线流程——代码合并后如何部署到目标环境：
```
CI deploys on merge to main
```
、
```
Tag / release triggers deploy
```
、
```
Manual release
```
、
```
Other
```
。此信息用于
```
infrastructure.md
```
；流水线文件通常仅显示构建步骤，不包含发布流程。

2c. Free-text answers — ask in plain chat

2c. 自由文本回答——用普通聊天询问

Business context — "In one or two sentences: what does this product do, and who pays for it?"
Non-obvious rules — "List up to 3 invariants or gotchas an AI coding agent must know that are NOT enforceable by linters or tests. Examples: '
Core
must not reference
Infrastructure
', 'never bypass the tenant query filter', 'always thread
CancellationToken
', 'run migrations before starting the API', 'do not touch the legacy
Billing
project'. If none come to mind, reply 'skip'."

业务上下文——“用1-2句话描述：这个产品的功能是什么，付费用户是谁？”
非显性规则——“列出最多3条AI编码Agent必须知晓的、无法通过代码分析器或测试强制执行的不变规则或陷阱。示例：'
Core
模块不得引用
Infrastructure
模块'、'绝不绕过租户查询过滤器'、'始终传递
CancellationToken
'、'启动API前先执行迁移'、'不要修改遗留的
Billing
项目'。若没有相关规则，回复'skip'。”

2d. Conditional extras — ask only when the repo left the gap

2d. 条件性附加问题——仅当仓库存在信息缺口时询问

Test expectations — only if Phase 1 found thin or missing test coverage: "What counts as done for a change here — unit tests only, integration tests required, or end-to-end?"
Ownership / escalation — only if there is no
```
CODEOWNERS
```
and no obvious maintainer: "Who reviews changes to this repo?"

Do not proceed to Phase 3 until the interview is complete.

测试要求——仅当第一阶段发现测试覆盖率不足或缺失时询问：“此处的变更完成标准是什么——仅单元测试、需要集成测试，还是端到端测试？”
所有权/升级路径——仅当没有
```
CODEOWNERS
```
文件且无明显维护者时询问：“谁负责审核此仓库的变更？”

完成访谈后再进入第三阶段。

Phase 3 — Draft

第三阶段——起草

For each doc to generate, read the template at

templates/<lang>/<doc>.md.template

, substitute the placeholders, and write to the target path. Placeholders use

{{UPPER_SNAKE}}

syntax; each template declares its own at the top.

Target paths:

```
AGENTS.md
```
(repo root) — see Phase 4
```
CLAUDE.md
```
(repo root) — see 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 seed ADRs)

```
docs/target-user.md
```
(only if opted in)
```
docs/design.md
```
(only if opted in)

Rules for filling templates:

Short sentences. Sacrifice grammar for clarity.
If you don't have info for a section, leave a
```

```
marker — don't hallucinate. If a whole section doesn't apply (no UI, no Aspire, no MAUI), delete it rather than filling it with TODOs.
In augment mode, never clobber user content. Fill
```

```
slots or append a clearly marked subsection; leave everything else alone. Docs the repo already shipped are read-only — cross-link them instead.

What each doc must carry from the .NET discovery:

docs/dotnet.md
— the primary output of Phase 1c. Keep the project table and the reference graph concrete (real project names). Cross-link, don't restate, the other docs.
docs/architecture.md
— name the framework + EF Core explicitly in the stack summary (e.g. "ASP.NET Core 10 + SQL Server + EF Core 10"), and add a one-line pointer to
```
docs/dotnet.md
```
for the project graph and layering.
docs/data-model.md
— migration tool is EF Core; record the
```
DbContext
```
location, the provider, and the migrations workflow (
```
dotnet ef
```
vs
```
Migrate()
```
on startup vs applied in CI).
docs/infrastructure.md
— the CI system and its pipeline file, the configuration & secrets layering, and the deployment/packaging shape (Dockerfile or SDK container publishing, AOT / trimming / single-file if in play).

ADR seeds — propose 1–3 decisions that were clearly made, each with Status, Context (with alternatives considered), Decision, and Consequences (easier / harder). Good candidates:

```
adr-0001-target-framework.md
```
— the target framework the solution standardizes on.
Data access — EF Core (and the provider) as the persistence approach.
Deployment target, if a Dockerfile, IaC, or SDK container properties were detected.

Never fabricate the rationale for an ADR.

对于每个要生成的文档，读取

templates/<lang>/<doc>.md.template

模板，替换占位符，然后写入目标路径。占位符使用

{{UPPER_SNAKE}}

语法；每个模板顶部会声明所需的占位符。

目标路径：

```
AGENTS.md
```
（仓库根目录）——见第四阶段
```
CLAUDE.md
```
（仓库根目录）——见第四阶段
```
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
——第一阶段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
```
vs 启动时执行
```
Migrate()
```
vs CI中执行）。
docs/infrastructure.md
——CI系统及其流水线文件、配置与密钥分层、部署/打包形式（Dockerfile 或 SDK容器发布，若启用AOT/裁剪/单文件则需注明）。

初始ADR——提出1-3个已明确做出的决策，每个决策包含状态、背景（含备选方案）、决策内容和影响（利弊）。合适的候选主题：

```
adr-0001-target-framework.md
```
——解决方案统一使用的目标框架。
数据访问——采用EF Core（及其提供程序）作为持久化方案。
部署目标——若检测到Dockerfile、IaC或SDK容器属性。

绝不编造ADR的理由。

Phase 4 — Wire (AGENTS.md + CLAUDE.md)

第四阶段——关联（AGENTS.md + CLAUDE.md）

Generate

AGENTS.md

strictly as a table of contents:

Opening: 2 lines max (project name + one-line purpose).
"Where to find things": a bulleted list of every doc with a one-line description, including
```
docs/dotnet.md
```
("deep .NET context: project graph, TFMs, EF Core, DI") and any pre-existing repo docs found in Phase 1b.
"Commands": the 3–6 commands a developer actually runs. Take them from the real repo, not from habit:
- When Aspire is present the entry point is
```
aspire run
```
  /
```
dotnet run --project *.AppHost
```
  , not each service individually. Getting this wrong sends an agent down the wrong path.
- Note the test command the repo's runner actually needs (see the test-platform split in the checklist), and
```
dotnet ef
```
  invocation style (global tool vs
```
dotnet tool run
```
  ).
"Non-obvious rules": the user's Phase 2 answers, each as a bullet with a short rationale. Add the mechanical rules discovery turned up, which agents reliably get wrong:
- central package management — when
```
Directory.Packages.props
```
  manages versions, a
```
<PackageReference>
```
  in a
```
.csproj
```
  must not carry
  Version
  ;
- any AOT / trimming constraint (no unbounded reflection, no reflection-based serialization);
- the project-layering rule, if one exists.
"Testing" and "Code style": one paragraph each, naming the frameworks and analyzers detected in Phase 1.
"Security": no secrets committed,
```
.env
```
/ user-secrets not in VCS, don't log PII.

Enforce the ~80-line ceiling. If you exceed it, move detail into

docs/dotnet.md

CLAUDE.md

is one line:

@AGENTS.md

, with a comment explaining that it delegates.

严格将

AGENTS.md

生成为目录：

开头：最多2行（项目名称+一行简介）。
“内容位置”：每个文档的项目符号列表，附带一行描述，包括
```
docs/dotnet.md
```
（“.NET深度上下文：项目图谱、TFMs、EF Core、DI”）和第一阶段1b发现的所有仓库已有文档。
“常用命令”：开发者实际使用的3-6个命令。从真实仓库中获取，而非凭习惯：
- 若存在Aspire，入口命令为
```
aspire run
```
  /
```
dotnet run --project *.AppHost
```
  ，而非单独启动每个服务。此处错误会引导Agent走弯路。
- 注明仓库运行器实际需要的测试命令（见检查清单中的测试平台拆分），以及
```
dotnet ef
```
  的调用方式（全局工具 vs
```
dotnet tool run
```
  ）。
“非显性规则”：用户在第二阶段的回答，每条作为项目符号并附带简短理由。添加发现阶段找到的、Agent容易出错的机械规则：
- 中央包管理——当
```
Directory.Packages.props
```
  管理版本时，
```
.csproj
```
  中的
```
<PackageReference>
```
  不得包含
  Version
  属性；
- 任何AOT/裁剪约束（无无界反射、无基于反射的序列化）；
- 项目分层规则（若存在）。
“测试”和“代码风格”：各一段，列出第一阶段检测到的框架和分析器。
“安全”：不提交密钥，
```
.env
```
/用户密钥不在版本控制系统中，不记录PII。

严格控制在约80行以内。若超出，将细节移至

docs/dotnet.md

。

CLAUDE.md

仅一行：

@AGENTS.md

，附带注释说明其指向AGENTS.md。

Phase 5 — Validate claims (Claimify-inspired)

第五阶段——验证声明（借鉴Claimify）

Generated docs hallucinate. Before finishing, surface the load-bearing factual claims you wrote and confirm the uncertain ones with the user. This step is adapted from Microsoft Research's Claimify — extract atomic, self-contained, verifiable claims, and flag ambiguity instead of guessing. Follow

references/claim-validation.md

in full. In short:

Select the verifiable, load-bearing claims from the docs you just wrote: target frameworks, the persistence provider and migration workflow, the deployment target, the CI system, key entities, the commands, package versions, DI lifetimes, and the user's non-obvious rules. Skip TODOs, boilerplate, and opinions.
Atomize + tag provenance. One self-contained statement each, with a source ref (
```
file:line
```
or
```
inferred
```
) and a confidence:
```
high
```
(read from a file),
```
medium
```
(one weak signal),
```
low
```
(guessed / unverified).
Flag ambiguity. Mark any claim with more than one plausible reading or no clear source (e.g. two projects pinning different target frameworks). Never silently keep a low-confidence claim.
Verify with the user. Present a compact ledger; confirm or correct the
```
medium
```
/
```
low
```
/ ambiguous claims (use
```
AskUserQuestion
```
for the top binary confirmations, plain chat for the rest).
```
high
```
-confidence claims with a concrete source are shown but not blocking.
Apply. Write corrections into the docs. Downgrade any unconfirmed
```
low
```
-confidence claim to
```

```
rather than asserting it.
Persist the ledger to
```
docs/claims-ledger.md
```
(format in the reference) as an audit trail.

生成的文档可能存在编造内容。完成前，提炼你所写的关键事实声明，并与用户确认不确定的内容。此步骤改编自微软研究院的Claimify——提取原子化、独立、可验证的声明，标记歧义而非猜测。完整遵循

references/claim-validation.md

中的步骤，简要说明：

选择：从生成的文档中提取可验证的关键声明：目标框架、持久化提供程序和迁移流程、部署目标、CI系统、核心实体、命令、包版本、DI生命周期、用户提供的非显性规则。跳过TODO、模板内容和主观意见。
原子化+标记来源：每个声明为独立语句，附带来源引用（
```
file:line
```
或
```
inferred
```
）和置信度：
```
high
```
（从文件读取）、
```
medium
```
（弱信号）、
```
low
```
（猜测/未验证）。
标记歧义：标记任何存在多种合理解读或无明确来源的声明（例如两个项目使用不同的目标框架）。绝不保留低置信度的声明而不标记。
与用户验证：呈现简洁的声明清单；确认或修正
```
medium
```
/
```
low
```
/歧义声明（用
```
AskUserQuestion
```
确认主要的二元选项，其余用普通聊天）。具有具体来源的
```
high
```
置信度声明仅展示，不阻塞流程。
应用修正：将修正内容写入文档。将未确认的
```
low
```
置信度声明降级为
```

```
，而非断言。
保存清单：将声明清单保存至
```
docs/claims-ledger.md
```
（格式参考文档）作为审计跟踪。

Phase 6 — Verify

第六阶段——验证

Print a tree of files written (or augmented).
Check that every link in
```
AGENTS.md
```
and
```
docs/dotnet.md
```
resolves to a file that exists (use Read).
Remind the user:
- Commit:
```
git add AGENTS.md CLAUDE.md docs/ && git commit -m "docs: bootstrap .NET context pack for AI coding agents"
```
- Fill in the
```

```
  markers, review the ADRs, and skim
```
docs/claims-ledger.md
```
  for anything still unverified.
- If quality gates were absent, consider adopting
```
.editorconfig
```
  + analyzers (
```
StyleCop.Analyzers
```
  ,
```
Microsoft.CodeAnalysis.NetAnalyzers
```
  ) and an arch-linting tool (
```
NsDepCop
```
  /
```
ArchUnitNET
```
  ) to enforce the layering the docs describe.
- Re-run
```
/arkandia:agent-context-dotnet
```
  later; it will augment, not overwrite.

打印已生成（或增量更新）的文件树。
检查
```
AGENTS.md
```
和
```
docs/dotnet.md
```
中的每个链接是否指向存在的文件（使用Read命令）。
提醒用户：
- 提交：
```
git add AGENTS.md CLAUDE.md docs/ && git commit -m "docs: bootstrap .NET context pack for AI coding agents"
```
- 填充
```

```
  标记，审核ADRs，浏览
```
docs/claims-ledger.md
```
  查看未验证内容。
- 若缺失质量门禁，考虑采用
```
.editorconfig
```
  +分析器（
```
StyleCop.Analyzers
```
  、
```
Microsoft.CodeAnalysis.NetAnalyzers
```
  ）和架构检查工具（
```
NsDepCop
```
  /
```
ArchUnitNET
```
  ）来强制执行文档中描述的分层规则。
- 后续可重新运行
```
/arkandia:agent-context-dotnet
```
  ；工具会执行增量更新，而非覆盖。

Reference

参考文档

```
references/dotnet-inspection.md
```
— the full .NET discovery checklist (Phase 1c).
```
references/claim-validation.md
```
— the Claimify-inspired claim-validation procedure (Phase 5).
```
templates/en/
```
and
```
templates/es/
```
— the doc skeletons.

```
references/dotnet-inspection.md
```
——完整的.NET发现检查清单（第一阶段1c）。
```
references/claim-validation.md
```
——借鉴Claimify的声明验证流程（第五阶段）。
```
templates/en/
```
和
```
templates/es/
```
——文档模板。

Rules

规则

Do NOT write application code.
Do NOT overwrite existing docs without explicit user opt-in; enrich by filling TODOs or appending clearly marked sections.
Do NOT fabricate framework or package versions, providers, endpoint names, or schema you haven't read.
DO leave
```

```
markers where human input is needed, and delete sections that don't apply rather than padding them.
DO keep every doc focused: each has one job, delegated from AGENTS.md.

绝不编写应用代码。
未经用户明确许可，绝不覆盖已有文档；通过填充TODO或添加明确标记的章节来丰富内容。
绝不编造未读取到的框架或包版本、提供程序、端点名称或schema。
在需要人工输入的位置留
```

```
标记，删除不适用的章节而非填充内容。
保持每个文档聚焦：每个文档只有一个核心用途，由AGENTS.md关联。