Imported from Zongsoft/guidelines (
AGENTS.md). Install upstream withnpx skills add Zongsoft/guidelines. Copyright stays with the author.
Zongsoft .NET/C# AI 开发协作规范
本文件面向执行编码、重构、审查和文档维护任务的 AI 助手。编码风格、类型设计和公共契约以 Zongsoft .NET/C# 开发规范 为准，本文件只补充执行流程与操作边界，不复制技术规范。
在本规范仓库中工作时遵循本文件；其他 Zongsoft 项目引用本文件时，同时遵循目标项目及目录内的 AGENTS.md、SKILL.md。本文件不替代目标项目的专用技能和领域说明。
1. 指令与依据
- 开始 .NET/C# 编码、重构或审查前，必须完整阅读 开发规范，并将其作为实现和审查依据；自动检测的级别、例外和修复边界同时核对 规则列表。
- 当前任务的明确要求优先；目标项目的就近文档补充具体约束。遇到实质冲突时说明冲突和处理依据，不默默忽略，也不自行扩大任务范围。
- 未规定的细节遵循同项目、同职责代码和
.editorconfig；语言正确性、业务语义、兼容性和资源安全优先于形式一致。 - 历史代码、第三方代码和生成代码中的个别写法不自动构成规范。不得仅凭类型名、旧文档或通用 .NET 经验编造 API。
- 文档与实现不符时，在任务范围内同步；不适合本次修正的差异必须在结果中指出。尚未核实的推断不得写成框架已提供的保证。
2. 编码前定位
- 检查工作区差异，识别用户已有修改。
- 阅读仓库和目标目录的
AGENTS.md、SKILL.md、相关README*.md。 - 阅读
.editorconfig、.gitattributes、解决方案、目标.csproj、共享构建和包配置；存在global.json时核对 SDK 限制。 - 搜索同职责接口、基类、实现、调用方和测试，至少阅读一条真实调用链，确认实际可用的构造函数、重载和扩展点。
- 确定行为归属层、复用点、兼容边界、资源所有权和最小验证范围，再开始修改。
3. 修改边界
- 只修改任务所需代码及关联文档，保留用户原有修改；不得重置、覆盖或清理无关差异。
- 不为统一风格批量重排导入、重命名、改变换行符、转换构造函数或改写无关实现。
- 不为使用新语法自行升级 SDK、目标框架、包版本或启用预览功能；不借局部任务启用全仓可空迁移。
- 优先复用已有类型和扩展点；不为假想需求增加公共接口、配置开关或继承层次，也不为测试扩大生产 API。
- 修改公共契约前，搜索直接实现、派生类、调用方、反射使用及关联产物；破坏性变更仅在任务明确要求的范围内处理，并说明迁移影响。
- 新增或修改服务、配置及插件入口时，检查
.plugin、.option、.mapping、.deploy、打包项、资源及双语 README 的同步需要。 - 保持已有文件的编码、BOM 和换行符；新建文本文件使用 UTF-8、无 BOM、CRLF，代码和 XML 使用 Tab 缩进。
.cmd必须使用 CRLF，.sh等平台脚本遵循.gitattributes使用 LF。 - 保留版权和许可头，不虚构作者、贡献者或版权年份，不复制错误的库名。
- 不提交或输出真实密钥、令牌、私钥、完整连接字符串及敏感业务负载。
- 未经任务明确要求，不执行发布、推包、部署、升级、安装、容器启停或接触真实外部服务的脚本。
4. Zongsoft 框架专项核对
本节只在目标任务使用相应框架能力时适用。具体行为必须以目标分支的实现和就近技能为准，不能将此处记录作为永久不变的 API 保证。
服务与插件
- 从公共消费契约追踪具体提供者、注册路径、插件清单、配置及首次调用；接口声明本身不证明已注册。
- 核对
ServiceAttribute的继承特性、Members静态成员注册和IServiceRegistration自定义注册路径。普通特性注册通常为单例，不要推断为 transient；实际生命周期以注册代码为准。 - 分别核对
Resolve、Find、Locate的匹配与回退语义，不能机械替换；区分服务别名、模块名、具名实例和连接名称。 Locate<T>("name@provider")的后缀选择具名实例提供者；插件表达式{service:...@module}的后缀选择模块容器。不得混写两套语法。- 模块服务容器不等于 HTTP 请求作用域。检查共享实例身份、线程安全和释放所有者，普通消费者不得释放共享服务。
- 应用自己的
Module.Current由应用定义，不得假设 Core 存在通用的同名 API。 - XML 和配置按 XSD 与加载器行为共同核对；节点名称、大小写、顺序、依赖和局部格式不得无关重排。
- 编译通过、插件发现、配置绑定和首次实际调用是不同验证阶段；不能只验证插件列表就宣称服务可用。
构建与依赖
- 每次读取实际配置，不把目标版本写死。2026-09-14 核对时，框架根配置为
net8.0、net9.0、net10.0及LangVersion=latest，项目可以覆盖。 - 核对 Debug／Release 引用来源。框架部分项目 Debug 使用 Core 输出的
HintPath，Release 使用 NuGet；下游编译成功不证明已使用本次修改的 Core。 - 包版本遵循集中管理，保留有依据的
VersionOverride；不为一次编译失败随意添加直接包、升级依赖或扩大警告抑制。 - 框架
Zongsoft.Diagnostics/proto为 Git 子模块，不写入无关上游变更或生成物。
5. 验证与交付
-
规范检查采用 代码规范检查 中的接入方式和命令；默认只检查，自动修正限定本次修改文件。检查通过不代表覆盖了 规则列表 中注明需人工审查的要求。
-
代码改动先构建受影响的具体
.csproj或.slnx，公共契约变化再验证直接下游；涉及多目标兼容性时分别验证项目实际支持的各目标框架。 -
行为修复使用能覆盖原始失败的聚焦回归验证；新增行为覆盖关键成功、失败和边界情形。按项目测试约定选择必要范围，不默认运行全仓构建或外部集成测试。
-
纯文档及低风险格式修改不增加无关单元测试；检查
git diff --check、链接、编码、CRLF 和内容差异。新建未跟踪文件也需检查行尾空白与格式。 -
新增或变更声称可编译的示例时，进行相应编译核对；示例依赖上下文时必须明确标注。
-
集成测试先确认环境、端口、开关和依赖服务；条件不满足时说明未验证范围，不以临时代码绕过校验或访问生产服务。
-
性能结论以聚焦测量为依据；未测量时说明推断，不夸大优化收益。
-
交付时说明改动、实际验证结果和未验证部分。未运行、未完成或失败的检查不得写成通过。
6. 完成前自检
- 已阅读开发规范、目标项目约束和真实调用链，所用 API 均已核实。
- 行为位于正确层次，复用已有能力，未增加无关抽象或配置开关。
- 命名、
this.、Tab、CRLF、分段和局部布局符合开发规范。 - 参数、空值、默认值、异常、取消、并发和资源所有权清楚。
- 公共兼容性、共享状态、重入和生命周期影响已检查。
- 插件、配置、映射、部署、资源与文档已按实际变更同步。
- 已完成适当构建、聚焦验证和差异检查，并说明验证限制。
- 保留用户原有修改，没有未授权的外部副作用。
7. 本规范仓库的维护约定
-
Zongsoft.CodeAnalysis不维护向后兼容，不添加旧版 API 回退、兼容开关或旧编译器支持层；使用支持 Roslyn 5.9 的 VS2026／.NET 10 SDK。此约定不改变消费项目的目标框架。 -
分析器文档仅描述当前规则与用法，不记录变更历史或实施过程。测试按规则和职责组织，不按审查问题编号或业务项目名称建立测试文件；交付前清理临时脚本、日志和中间产物。
-
开发规范 面向开发者，保存代码风格、技术规则、设计原则与示例；本文件面向 AI，保存阅读流程、检索要求、修改边界和交付检查。
-
开发规范维护编码与设计要求；规则列表 集中维护诊断编号、级别、检测例外与修复示例。README 维护接入和操作步骤，AI 文件通过链接引用；新增诊断同步中英文规则列表及固定锚点，避免多处复制检测细节。
-
项目专用技能留在目标项目的
SKILL.md中；仅在有独立工作流需要时新增技能，不为重复本文件而创建一份空泛技能。 -
人工阅读文档使用适量章节图标和重点提示，保持导航与正文简洁；图标不替代规范措辞，不进入代码示例或标识符。
-
修改文档入口或文件名时，同步相互链接及中英文 README。
