用途
本技能面向使用 Spring Data JDBC 的项目，提供一组规则与指南，用于在项目中正确地新增、删除或修改 Spring Data JDBC 实体，并保证实体与聚合的建模方式符合该技术栈的约定。技能还会在用户要求审查项目中的 JDBC 模式、约定或代码质量时，将检测到的项目约定与最佳实践进行比对并输出改进建议。
检测守卫
在应用任何规则之前，需要先确认目标文件是否导入 org.springframework.data.relational.core.mapping 或 org.springframework.data.annotation。如果看到 jakarta.persistence.* 导入，应停止并切换到 spring-data-jpa 技能——两套技术栈不可互换，JPA 的模式（HibernateProxy、@ManyToOne、@OneToMany、@JoinColumn、FetchType）在此并不适用。
运行时兼容性
技能设计为可在多种智能体运行时（Claude Code、Codex、OpenCode）中工作。其中引用到两个特定运行时的原语，按“优先但可选”处理，并在缺失时优雅降级：AskUserQuestion（Claude Code 的结构化多选提示）与“Memory”（Claude Code 的持久化文件自动记忆）。当运行时不支持这些原语时，改为在对话中内联提出同样的问题，或改为扫描本次会话的早期轮次来复用已确定的约定；若会话是全新的，则从头执行检测步骤。不应因缺少上述原语而拒绝任务，并且应在任务开始时声明一次替换行为。
前置检查：Spring MCP
本技能属于 Spring Agent Toolkit，设计上与 Spring MCP 服务器（由 Amplicode IntelliJ 插件提供）配合使用。开始前应先检查工具列表中是否存在 Spring MCP 工具，它们由 amplicode MCP 服务器暴露，例如 get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories；若至少有一个可用，则 MCP 已连接，可继续执行。若均不可用，应停止并调用随 Spring Agent Toolkit 一起提供的 amplicode-install 技能；它负责安装 Amplicode 插件并引导用户完成欢迎屏按钮与 MCP 客户端重启。安装完成后 MCP 工具可用，再恢复本技能。如果 amplicode-install 未注册或用户拒绝安装（例如在不支持 MCP 的 CI 沙箱中运行），则继续使用文件读取备用方案，不阻塞任务。
MCP 可用性与降级方案
技能优先使用 Spring MCP 工具（get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories），因为它们可一次调用返回已解析的全项目答案。如果 Spring MCP 服务器不可达且用户选择不安装插件，则降级为直接读取文件与 grep，并且不应拒绝任务。项目以 Kotlin 为主（Kotlin 2.2.20 为主，部分模块使用 Java），因此每次备用 grep 都必须同时命中 *.kt 与 *.java；不要传 -t java，而应省略类型过滤或使用 -t kotlin -t java。枚举 JDBC 实体可改为 grep org.springframework.data.relational.core.mapping.Table 导入或解析到该处的 @Table 注解；枚举仓储可改为 grep 仓储声明关键字，并显式列出各个基础接口（ListCrudRepository、CrudRepository、ListPagingAndSortingRepository、PagingAndSortingRepository）。替代 get_jdbc_entity_details 的手工流程见 references/aggregate-rules-impl.md 中“Without get_jdbc_entity_details”小节，可通过读取源文件得到 idField.type、aggregateRootFqn、aggregates、referencedBy 等信息。进入降级模式时应在任务开始时说明一次及原因，不要静默切换。
处理 JDBC 实体
当任务涉及创建或修改 Spring Data JDBC 实体时：如果本次会话尚未检测实体约定，先检查记忆（或在无持久记忆的运行时中检查早期对话轮次）；若没有，则读取 references/entity-conventions.md 并按其所有子步骤检测项目约定。随后读取 references/entity-rules-impl.md，并在编写或修改实体时遵循其中的规则。如果实体之间或与既有实体之间存在任何关系（集合字段、引用字段、外键列，或用户请求中描述的关系），还需在决定任何链接形态之前读取 references/aggregate-rules-impl.md：实体规则覆盖字段语法，聚合规则决定哪些关系形态合法以及链接可持有的方向；跳过此步骤会导致生成非法形态（指向另一聚合成员的裸外键、指向非根实体的引用）。
工具与源码的使用策略：当准备编辑实体时，直接读取源文件。get_jdbc_entity_details 被文档标注为只读分析工具，并明确说明“如果之后计划修改实体类，应直接读取文件”。该 MCP 工具仅用于从单个文件看不到的跨聚合上下文：目标在其聚合中的角色（aggregateRootFqn）、指向此处的其他聚合（referencedBy）、以及需要通过 AggregateReference<Other, IdType> 关联的其他聚合的 id 类型。对于正在编辑的文件本身（id 类型、当前字段、当前 @MappedCollection / @Embedded 声明），一律读取文件。
审查 JDBC 模式
当用户要求审查项目中的 JDBC 模式、约定或代码质量时：先按 references/entity-conventions.md 的步骤 1.1–1.5 检测当前约定；再将检测到的约定与 references/entity-rules-impl.md 中定义的最佳实践比对。对每处偏差输出如下格式的建议：“### JDBC Review”，随后列出“[约定或模式名称]”，并给出 Current（项目当前做法）、Recommended（最佳实践做法）、Reason（为何重要）。如果没有发现偏差，则说明项目符合最佳实践。
处理 JDBC 仓储
当任务涉及新增或修改 Spring Data JDBC 仓储时：如果本次会话尚未检测仓储约定，先检查记忆或早期对话轮次；否则读取 references/repository-conventions.md 并遵循其子步骤。随后读取 references/repository-rules-impl.md 并遵循其中的规则。创建新仓储之前，应以 entityFqn = <目标> 调用 list_entity_repositories 确认该实体尚无仓储，并调用 get_jdbc_entity_details 检查目标——仓储只能为聚合根创建（aggregateRootFqn == null）。注意 list_entity_repositories 没有 JDBC 过滤器；若未传 entityFqn 调用，需要手动过滤结果。
处理聚合
当任务涉及聚合边界时（添加 AggregateReference 字段、将受拥有的 @MappedCollection 转换为跨聚合链接、拆分聚合、在实体之间创建任何关系包括一对多与多对多，或回答“谁引用了 X？”/“聚合 Y 里有什么？”）：必须首先读取 references/aggregate-rules-impl.md，并扫描其中适用于当前特定关系类型的规则；在确认适用哪条规则之前，不要继续修改实体。如果本次会话尚未检测聚合约定，先检查记忆或早期对话轮次；否则读取 references/aggregate-conventions.md 并遵循其子步骤。只有在读取这两份参考文件之后，才继续实体修改，并严格遵循其中的规则。MCP 工具 get_jdbc_entity_details 是聚合归属的事实来源，其响应包含 aggregateRootFqn（若该实体自身即为根则为 null）、aggregates（拥有的子实体，递归，仅对根填充）、referencedBy（通过 AggregateReference 链接到此处的其他聚合）。在做任何聚合边界决策之前应读取这些信息。
关键：一对多与多对多关系
不同聚合之间的任何一对多或多对多关系都需要一个链接实体，这一点没有商量余地。在实现此类关系之前：通过 get_jdbc_entity_details（或读取实体）确认双方均为聚合根，或检查其聚合归属；如果它们位于不同聚合，必须创建中间链接实体，不要使用直接指向另一个根的 @MappedCollection；读取 references/aggregate-rules-impl.md 中的具体规则——“Rule: One-to-many between two aggregates goes through a link entity”或“Rule: Many-to-many between two aggregates goes through a link entity”；并严格按文档化的链接实体模式实现：持有侧通过 @MappedCollection 拥有链接集合，每个链接实体携带指向目标根的 AggregateReference<Target, IdType>。
限制
资料未提供该技能支持的具体数据库平台、版本兼容范围、收费或价格信息，以及除上述规则之外的更多使用步骤；这些内容暂未提供。技能的参考文件（references/entity-conventions.md、references/entity-rules-impl.md、references/aggregate-rules-impl.md、references/aggregate-conventions.md、references/repository-conventions.md、references/repository-rules-impl.md）的具体内容未在资料中展开，暂未提供。