From f9f608ad64f77265be8bd62a5b81ef97d7b1e0aa Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Thu, 9 Apr 2026 19:23:17 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=B7=BB=E5=8A=A0AI=E4=BB=A3?=
 =?UTF-8?q?=E7=90=86=E7=BC=96=E7=A0=81=E8=A1=8C=E4=B8=BA=E8=A7=84=E8=8C=83?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 定义了环境能力清单和工具选择规则
- 规定了XML文档注释、内联注释和架构级注释要求
- 明确了代码风格包括命名约定、格式化和C#惯例
- 设立了测试覆盖范围、组织结构和验证命令标准
- 制定了安全规则防止输入验证和敏感数据泄露
- 规范了代码文档、任务跟踪和仓库文档更新流程
- 建立了审查标准确保代码质量和完整性
---
 AGENTS.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 4e39ad22..311042dd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,10 @@ All AI agents and contributors must follow these rules when writing, reviewing,
 - Use `@.ai/environment/tools.raw.yaml` only when you need the full collected facts behind the AI-facing hints.
 - Prefer the project-relevant tools listed there instead of assuming every installed system tool is fair game.
 - If the real environment differs from the inventory, use the project-relevant installed tool and report the mismatch.
+- When working in WSL against this repository's Windows-backed worktree, prefer Windows Git from WSL (for example
+  `git.exe`) instead of the Linux `git` binary.
+- If a Git command in WSL fails with a worktree-style “not a git repository” path translation error, rerun it with the
+  Windows Git executable and treat that as the repository-default Git path for the rest of the task.
 
 ## Commenting Rules (MUST)
 
@@ -114,6 +118,15 @@ All generated or modified code MUST include clear and meaningful comments where
 ### Analyzer and Validation Expectations
 
 - The repository uses `Meziantou.Analyzer`; treat analyzer feedback as part of the coding standard.
+- Treat SonarQube maintainability rules as part of the coding standard as well, especially cognitive complexity and
+  oversized parameter list findings.
+- When a method approaches analyzer complexity limits, prefer extracting named helper methods by semantic phase
+  (parsing, normalization, validation, diagnostics) instead of silencing the warning or doing cosmetic reshuffles.
+- When a constructor or method exceeds parameter count limits, choose the refactor that matches the shape of the API:
+  use domain-specific value objects or parameter objects for naturally grouped data, and prefer named factory methods
+  when the call site is really selecting between different creation modes.
+- Do not add suppressions for complexity or parameter-count findings unless the constraint is externally imposed and the
+  reason is documented in code comments.
 - Naming must remain compatible with `scripts/validate-csharp-naming.sh`.
 
 ## Testing Requirements