From 44c7475284b523d308d638bae6e75d6dd7e9d21f Mon Sep 17 00:00:00 2001 From: itstarts Date: Sun, 5 Jul 2026 18:41:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BB=86=E5=8C=96=E5=85=A8=E5=B1=80?= =?UTF-8?q?=E8=A7=84=E5=88=99=E2=80=94=E2=80=94=E5=8E=BB=E5=B9=B3=E5=8F=B0?= =?UTF-8?q?=E8=80=A6=E5=90=88=E3=80=81=E8=A1=A5=E5=85=85=E5=B9=B6=E5=8F=91?= =?UTF-8?q?/=E9=94=81=E7=BA=AA=E5=BE=8B=E3=80=81=E4=BC=98=E5=8C=96?= =?UTF-8?q?=E5=8F=AF=E8=AF=BB=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - skill 名称泛化为类别描述，去除产品名绑定 - Context7 等特定工具名改为泛化表述 - 最小变更复用取舍长句拆分为 decision checklist - 轻量任务文件数降为辅助信号，单文件核心逻辑同样升级 - 完成前检查显式化验证通过确认 - 新增并发/锁/事务/共享状态同步的变更纪律 - 测试高风险列表补充锁/事务/共享状态 --- AGENTS.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5fecafd..89a7a4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,7 @@ ## 重量级流程裁剪 -- 由 Agent 自主判断是否启用平台提供的重量级流程或 skill（如 brainstorming、writing-plans、subagent-driven-development、git worktree 等）。 +- 由 Agent 自主判断是否启用平台提供的重量级流程或 skill（如计划、设计文档、多 agent 编排、隔离工作区等流程能力）。 - 启用前必须能说明它解决的具体风险；只为满足流程形式则不启用。 - 轻量任务不默认套用重量级流程，避免被过度流程化。 - 遇到 bug、测试失败或异常行为时，先复现并定位根因，再修复；必要时采用系统化调试流程。 @@ -44,7 +44,7 @@ ## 任务分级与升级 - 开发前自主判断任务等级；中等及以上任务需说明分级依据，轻量任务可直接执行并在结果中简要说明影响范围。 -- **轻量任务**：只读分析、代码解释、日志检查、创建分支、文档小改，或 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/迁移说明、计划或进度文档）；如未更新，说明原因。 - 搜索并处理本次引入的无用代码、测试、临时文件和调试产物。 - 确认没有误改无关文件、没有覆盖用户变更、没有引入未授权的外部调用或破坏性操作。