docs: 细化全局规则——去平台耦合、补充并发/锁纪律、优化可读性

AGENTS.md

@@ -36,15 +36,15 @@
 
 ## 重量级流程裁剪
 
-- 由 Agent 自主判断是否启用平台提供的重量级流程或 skill（如 brainstorming、writing-plans、subagent-driven-development、git worktree 等）。
+- 由 Agent 自主判断是否启用平台提供的重量级流程或 skill（如计划、设计文档、多 agent 编排、隔离工作区等流程能力）。
 - 启用前必须能说明它解决的具体风险；只为满足流程形式则不启用。
 - 轻量任务不默认套用重量级流程，避免被过度流程化。
 - 遇到 bug、测试失败或异常行为时，先复现并定位根因，再修复；必要时采用系统化调试流程。
 
 ## 任务分级与升级
 
 - 开发前自主判断任务等级；中等及以上任务需说明分级依据，轻量任务可直接执行并在结果中简要说明影响范围。
-- **轻量任务**：只读分析、代码解释、日志检查、创建分支、文档小改，或 1-2 个文件、需求清晰、风险局部、可定向验证的少量变更。直接执行，不需要计划文档。
+- **轻量任务**：只读分析、代码解释、日志检查、创建分支、文档小改，或少量文件（文件数仅作辅助信号）、需求清晰、风险局部、可定向验证的少量变更。直接执行，不需要计划文档。即使只涉及单个文件，若触及核心业务逻辑、共享契约或高风险路径，也按中等及以上任务处理。
 - **中等任务**：涉及多个文件或模块、共享组件、重要业务逻辑、兼容性，或缺少明确测试覆盖。先给简短计划或 checklist，说明影响范围、风险和验证策略。
 - **重量任务**：涉及架构、数据模型、迁移、并发、一致性、高风险生产路径，或属于项目级高风险路径（资金、权限、安全等，完整清单见项目 `AGENTS.md`），或用户明确要求正式流程。实现前必须给出设计或计划，必要时分阶段执行并维护进度文档。
 - 触及项目级高风险路径（数据模型、对外契约、权限、资金、迁移、并发、一致性等，以项目清单为准）时，默认至少按中等任务处理。
@@ -74,6 +74,7 @@
 - 修改前先阅读相关上下文，优先复用现有工具类、枚举、DTO、服务、客户端、异常处理和日志模式。
 - 不随意添加兜底或降级逻辑。未经用户确认，不通过默认值、吞异常、空结果静默返回、放宽校验或查询条件、跳过状态/权限校验、切换备用通道、返回降级或缓存数据等方式掩盖真实问题。
 - 确需兜底或降级时，先说明依据、场景、影响和验证方式，并等待用户确认。
+- 涉及并发控制、锁、事务隔离级别或共享状态同步逻辑的变更，按任务分级与升级规则评估；涉及核心并发、一致性或高风险生产路径时按重量任务处理。新增锁或调整锁粒度时说明锁范围、持有时长和潜在死锁风险。
 - 保持命名、API 字段和日志风格一致，不在代码中随意混用中文和英文。
 - 本次变更涉及的关键逻辑补充或维护必要的中文注释和关键日志；不为未修改代码补无关注释，不保留临时代码、调试日志或注释掉的旧代码。
 - 完成后检查并删除本次需求内不再使用的代码、测试、临时文件等；删除前通过搜索或静态分析确认无其他引用，不确定时保留并说明原因。
@@ -84,7 +85,10 @@
 - “最小变更”和“复用现有逻辑”是默认策略，但不是硬性目标；最高优先级是满足用户明确需求、保持业务语义正确、降低长期维护成本。
 - 现有逻辑只有在语义匹配、边界一致、风险可控且不会让实现绕路时才应复用。
 - 如果复用现有代码会导致需求偏离、保留旧缺陷、引入不必要依赖、增加复杂度或降低可读性，应优先采用更直接清晰的实现。
-- 计划或设计文档常以抽象逻辑描述意图，不等于指定必须复用某段现有代码；在不改变需求意图、对外契约和已确认计划目标的前提下，实现时由 Agent 判断复用、重构还是新增更优，当重构或新增更契合意图、边界更清晰或维护成本更低时，应选最优解而非机械套用现有实现。偏离文档字面描述时，在完成说明中解释判断依据。
+- 计划或设计文档以抽象逻辑描述意图，不等于指定必须复用某段现有代码。实现时在不改变需求意图、对外契约和已确认计划目标的前提下，由 Agent 判断复用、重构还是新增更优：
+  - 先判断语义是否匹配、边界是否一致、风险是否可控、维护成本是否可接受。
+  - 满足以上条件时优先复用；不满足时直接新增或重构。
+  - 偏离文档字面描述时，在完成说明中解释判断依据。
 - 最小变更不等于最少代码行；应以影响面、行为风险、可验证性和后续维护成本综合判断。
 - 局部低风险取舍由 Agent 自主判断，并在完成说明中解释原因。
 - 涉及公共组件、公共契约、核心业务规则、高风险路径或多模块影响的取舍，必须先说明方案差异、影响范围、风险和验证方式，必要时等待用户确认。
@@ -93,7 +97,7 @@
 
 - 优先运行与变更范围最相关的单元测试、模块测试、构建命令或 lint，不默认跑全量测试。
 - 没有验证证据时，不得声称“已完成”“已修复”或“测试通过”。
-- 涉及高风险或共享逻辑（业务规则、对外契约、数据、权限、资金、状态流转、异步任务、外部回调等，具体见项目级规范）时，不得仅以“小改动”为由跳过测试。
+- 涉及高风险或共享逻辑（业务规则、对外契约、数据、权限、资金、状态流转、异步任务、外部回调、锁、事务隔离级别、共享状态同步等，具体见项目级规范）时，不得仅以”小改动”为由跳过测试。
 - 小改动可不运行自动化测试，但不等于不验证；仍需执行最小可行检查（编译、lint、静态搜索或人工检查），并说明判断依据、未运行自动化测试的原因和残留风险。
 - 没有自动化验证可用时，说明已做的最小检查和建议的人工验证。
 - 用户明确要求不验证时，只能标记为未验证，不得声称验证通过。
@@ -129,14 +133,14 @@
 
 ## 第三方文档查询
 
-- 当问题涉及第三方库、框架、SDK、CLI、云服务或 API 的用法、配置、迁移和调试时，优先查询最新官方文档（如 Context7 等文档 MCP）。
-- 使用 Context7 时，先解析 library id，再查询具体文档。
+- 当问题涉及第三方库、框架、SDK、CLI、云服务或 API 的用法、配置、迁移和调试时，优先查询最新官方文档（通过可用的文档 MCP 或检索工具）。
+- 查询时先定位具体的库/包标识符，再检索对应文档。使用支持文档查询的 MCP 工具时，遵循其交互协议获取精确结果。
 - 不把文档查询工具用于业务逻辑设计、代码重构、一般编程概念或不依赖具体库版本的问题。
 
 ## 完成前检查
 
 - 确认需求范围内的修改已实现，或明确说明未完成项。
-- 确认验证命令、结果和未验证项已记录。
+- 确认已执行的相关验证已通过，并记录验证命令与结果；未运行或未通过的验证需记录原因、结果、风险和后续处理建议。
 - 确认受影响的相关文档已同步更新（README、接口文档、配置说明、部署说明、SQL/迁移说明、计划或进度文档）；如未更新，说明原因。
 - 搜索并处理本次引入的无用代码、测试、临时文件和调试产物。
 - 确认没有误改无关文件、没有覆盖用户变更、没有引入未授权的外部调用或破坏性操作。