update: 增加工具类或通用辅助方法前的能力复用检索规则

.claude/agents/backend-common-infrastructure.md

@@ -11,6 +11,7 @@ description: 公共基础模块专家。用于修改 ruoyi-common 下的 mybatis
 2. 优先保持公开方法签名、泛型、返回值、异常语义兼容。
 3. 新增能力要贴合已有命名和链式调用风格，不自造平行体系。
 4. 只补注释时不改实现、不重排 import、不运行无关格式化。
+5. 新增工具类或通用辅助方法前，先读取 `.claude/agents/backend-engineering.md` 的“已有能力复用”规则，按能力类别检索、确认模块依赖可用性并核对业务语义；满足需求时直接复用，不添加无业务语义的包装。
 
 ## common-mybatis
 
@@ -38,5 +39,5 @@ description: 公共基础模块专家。用于修改 ruoyi-common 下的 mybatis
 
 - 是否破坏已有调用点。
 - 是否遗漏 `instance()` / `clear()` / 批量翻译 / 缓存失效等公共模块关键路径。
-- 是否新增了与现有工具重复的临时类或临时方法。
+- 是否已检索同模块、`ruoyi-common` 和已有依赖，避免重复能力；确需新增时，是否在交付说明中简述现有能力为何不适用（无需为此额外添加代码注释，既有 JavaDoc 规则仍适用）。
 - JavaDoc 是否简洁说明公共 API 的参数、返回值和兼容语义。

.claude/agents/backend-crud.md

@@ -11,6 +11,7 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
 2. 再参考当前模块内最近似的标准管理模块。
 3. 分层保持稳定：
    `domain`、`domain.bo`、`domain.vo`、`mapper`、`service`、`service.impl`、`controller`
+4. 新增工具类或通用辅助方法前，先读取 `.claude/agents/backend-engineering.md` 的“已有能力复用”规则，按能力类别检索、确认模块依赖可用性并核对业务语义；满足需求时直接复用，不添加无业务语义的包装。
 
 ## 结构约定
 
@@ -57,6 +58,7 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
 
 ## 自检
 
+- 新增工具类或通用辅助方法是否已完成同类能力检索与语义核对；确需新增时，在交付说明中简述现有能力为何不适用，无需为此额外添加代码注释，既有 JavaDoc 规则仍适用
 - CRUD 链路是否完整
 - BO / VO / Entity 是否职责分离
 - 导出、分页、删除前校验是否齐全

.claude/agents/backend-engineering.md

@@ -14,19 +14,32 @@ description: 后端工程总入口。用于在当前 RuoYi-Vue-Plus 项目中识
 5. 如果只要求补充或修正 JavaDoc 注释，优先使用 `backend-javadoc.md` 的规则。
 6. 如果同时要求同步前端接口或前端页面骨架，先确认目标前端是 Vue 还是 React，保持后端路由与 generator 风格稳定，便于前端 agent 对接。
 
-文档读取顺序：
+文档读取规则：
 
-- 后端 Java、Mapper、Service、Controller、BO、VO、Entity、权限、查询、公共模块或 JavaDoc 任务，先读 `.codex/skills/ruoyi-plus-ai-coding/references/backend.md`。
-- 同步前端 Vue、React、TypeScript、api、types 或页面骨架时，再读 `.codex/skills/ruoyi-plus-ai-coding/references/frontend.md`。
-- 任务边界不清晰或需要标准场景示例时，再读 `.codex/skills/ruoyi-plus-ai-coding/references/examples.md`。
-- 只读取当前任务相关的 reference，不一次性展开全部文档。
-- reference 用来约束实现方式和检查范围；如果 reference、generator 模板和真实代码冲突，优先相信当前模块真实代码和实际调用点。
+- 按任务类型读取上面对应的 `.claude/agents` 文档，只读取当前任务相关内容。
+- 同步前端时，直接阅读目标 Vue 或 React 工程的现有 API、types、页面及对应 generator 模板，确认路由、返回结构和日期范围参数。
+- 需要场景示例时，优先阅读当前模块最近似实现及实际调用点。
+- 本套规则独立维护，不依赖 `.codex` 下的技能或 reference；规则、generator 模板和真实代码冲突时，优先相信当前模块真实代码和实际调用点。
 
 通用要求：
 
 - 先读同模块最近似实现，再动代码。
+- 新增工具类或通用辅助方法前，必须执行下方“已有能力复用”流程。
 - 发生冲突时优先相信当前模块真实代码，其次是公共基础设施，再其次才是 generator 模板。
 - 默认直接产出可落地代码，而不是只给抽象建议。
 - 不要把 `BaseMapperPlus`、`PageQuery`、`PageResult`、`R`、`MapstructUtils`、`StringUtils`、`StreamUtils` 等项目工具替换成临时自造方案。
 - import、注解顺序、文件结构以附近代码为准，不做无关重排。
 - 修改公开 API 前先查调用点；公共模块优先保持方法签名、泛型、返回值和异常语义兼容。
+
+## 已有能力复用
+
+1. 按能力类别检索同模块、`ruoyi-common` 和已有依赖，例如类型转换、字符串处理、集合处理、日期计算，不只搜索拟新增的方法名。
+2. 优先阅读实际调用示例，再核对候选实现或依赖 API；结合目标模块的 `pom.xml`、传递依赖及版本确认可用性，不能仅凭其他模块有调用或根 POM 管理了版本就认定可用。
+3. 核对空值、非法输入、默认值、异常和数值精度（含溢出、截断），依赖行为以当前版本的实现或测试为准。满足业务语义时直接复用，不添加无业务语义的包装；不满足时保留必要的业务差异，不能为了复用改变业务行为。
+
+例如容错 ID 转换可先查已有调用中的 Hutool `Convert.toLong`，确认所用重载的失败返回值和默认值符合需求；必须抛错的严格解析不能改成返回 `null` 或默认值，还要核对小数、越界等输入的处理。这里只示范核对方式，不维护全量工具 API 清单。
+
+交付自检：
+
+- 新增工具类或通用辅助方法是否已检索并核对同类能力，避免重复实现。
+- 确需新增时，在交付说明中简述现有能力为何不适用，无需为此额外添加代码注释；既有 JavaDoc 规则仍适用。

.claude/agents/backend-module-enhancement.md

@@ -12,6 +12,7 @@ description: 复杂后端模块增强专家。用于修改当前项目中已经
 3. 保留已有的数据权限、事务、缓存、导入导出、唯一性校验、删除前校验。
 4. 不能为了“简洁”把复杂模块退化成模板式单表 CRUD。
 5. 修改 workflow 模块时检查同包是否需要 `@ConditionalOnEnable`。
+6. 新增工具类或通用辅助方法前，先读取 `.claude/agents/backend-engineering.md` 的“已有能力复用”规则，按能力类别检索、确认模块依赖可用性并核对业务语义；满足需求时直接复用，不添加无业务语义的包装。
 
 ## 常见任务
 
@@ -33,6 +34,7 @@ description: 复杂后端模块增强专家。用于修改当前项目中已经
 
 ## 自检
 
+- 新增工具类或通用辅助方法是否已完成同类能力检索与语义核对；确需新增时，在交付说明中简述现有能力为何不适用，无需为此额外添加代码注释，既有 JavaDoc 规则仍适用
 - 是否破坏了原模块的权限边界
 - 是否误删了旧逻辑中的事务或校验
 - 是否错误简化了复杂关系维护

.claude/agents/backend-query-permission.md

@@ -12,6 +12,7 @@ description: 后端查询、联表与数据权限专家。用于当前项目中
 3. 复杂联表优先参考 MPJ 风格，不轻易改回手写零散 SQL。
 4. 如果 `BaseMapperPlus + wrapper` 足够，不要额外补 XML。
 5. wrapper 查询条件优先使用项目已有工具和命名，不自造查询 DSL。
+6. 新增工具类或通用辅助方法前，先读取 `.claude/agents/backend-engineering.md` 的“已有能力复用”规则，按能力类别检索、确认模块依赖可用性并核对业务语义；满足需求时直接复用，不添加无业务语义的包装。
 
 ## 重点关注
 
@@ -38,6 +39,7 @@ description: 后端查询、联表与数据权限专家。用于当前项目中
 
 ## 输出要求
 
+- 自检新增工具类或通用辅助方法是否已完成同类能力检索与语义核对；确需新增时，在交付说明中简述现有能力为何不适用，无需为此额外添加代码注释，既有 JavaDoc 规则仍适用
 - 明确说明查询是单表、联表还是带权限控制
 - 保持与当前模块 mapper 风格一致
 - 不要让查询参数风格和前端现有调用脱节

.codex/skills/ruoyi-plus-ai-coding/SKILL.md

@@ -31,7 +31,7 @@ description: 在仓库内按代码生成器模板、项目 reference 文档和
 ## 执行流程
 
 1. 先判断任务类型，并按“文档读取规则”读取当前任务需要的 reference。
-2. 确认目标模块，优先复用同模块中最近似功能的写法。
+2. 确认目标模块，优先复用同模块中最近似功能的写法；新增工具类或通用辅助方法前，执行“已有能力检索”。
 3. 新增标准 CRUD 代码前，先读取 `ruoyi-modules/ruoyi-gen/src/main/resources/fm/` 下的 FreeMarker 模板。
 4. 命名和分层保持与仓库一致：
    `domain` entity、`domain.bo`、`domain.vo`、`mapper`、`service`、`service.impl`、`controller`。
@@ -40,6 +40,12 @@ description: 在仓库内按代码生成器模板、项目 reference 文档和
 7. 修改 `ruoyi-common` 公共模块前，先阅读同包接口、实现类和调用点，优先保持已有 API 语义与兼容性。
 8. 只补注释或文档时，不运行无关格式化，不重排 import，不改代码逻辑。
 
+### 已有能力检索
+
+1. 按能力类别搜索同模块、`ruoyi-common` 和已有依赖，例如类型转换、字符串处理、集合处理、日期计算；不要只搜拟新增的方法名。
+2. 优先阅读实际调用示例，再核对候选实现或依赖 API；结合目标模块的 `pom.xml`、传递依赖及版本确认可用性，不能仅凭仓库其他模块有调用或根 POM 管理了版本就认定可用。
+3. 按适用 reference 核对业务语义；满足需求时直接复用，不添加无业务语义的包装。不满足时保留必要的业务差异，再决定是否新增。
+
 ## 文档读取规则
 
 使用本 skill 时，先按任务类型读取适用 reference，不一次性展开所有文档：
@@ -148,9 +154,11 @@ Vue 3、React、TypeScript API 文件、生成式列表页、表单状态、字
 - 查询、分页、删除校验、写入校验逻辑闭环完整。
 - 权限、日志、防重、事务、数据权限尽量贴近同模块现有实现。
 - 如果同步改前端，前端 API 路径和后端接口保持一致。
+- 确需新增工具类或通用辅助方法时，在交付说明中简述检索过的现有能力为何不适用，无需为此额外添加代码注释；既有 JavaDoc 规则仍适用。
 
 ## 快速检查清单
 
+- 新增工具类或通用辅助方法是否已完成同类能力检索与语义核对，避免重复实现或无业务语义的包装。
 - 包路径和 `@RequestMapping` 与模块保持一致。
 - 权限标识遵循 `${module}:${business}:${action}`。
 - Mapper 继承 `BaseMapperPlus<Entity, Vo>`。

.codex/skills/ruoyi-plus-ai-coding/references/backend.md

@@ -166,6 +166,8 @@
 
 - 分页统一使用 `PageQuery` 和 `PageResult`，不要无故引入新的分页 DTO。
 - 优先使用项目工具类：`MapstructUtils`、`StringUtils`、`StreamUtils`、`ValidatorUtils`、`SpringUtils`、`RedisUtils`。
+- 复用前核对空值、非法输入、默认值、异常和数值精度（含溢出、截断）的行为，不能为了复用改变业务语义；依赖行为以当前版本的实现或测试为准。
+- 例如容错 ID 转换可先查已有调用中的 Hutool `Convert.toLong`，核对所用重载的失败返回值与默认值是否符合需求；必须抛错的严格解析不能改成返回 `null` 或默认值，也要核对小数、越界等输入的处理。此处只示范核对方式，不维护全量工具 API 清单。
 - 数组转列表按附近代码习惯使用 `List.of(ids)` 或 `Arrays.asList(ids)`。
 - 日期范围查询通常从 `bo.getParams()` 中读取 `beginTime`、`endTime` 或 `beginFieldName`、`endFieldName`。
 - 构建查询优先识别 `QueryBuilder.lambda(...)`、`QueryBuilder.lambdaJoin(...)`、`BaseMapperPlus#lambda()` 三类入口，不要退回临时手写 SQL 或自造 wrapper。

AGENTS.md

@@ -0,0 +1,6 @@
+# 项目指令
+
+## 已有能力复用
+
+- 新增工具类或通用辅助方法前，必须检索同模块、`ruoyi-common` 和已有依赖中的同类能力；满足业务语义且当前模块可用时直接复用，不添加无业务语义的包装。
+- 检索流程、后端语义核对与交付自检见 `.codex/skills/ruoyi-plus-ai-coding/SKILL.md` 及其适用 reference。