@gong-ym/ai-spec-auto 0.2.14 → 0.2.15

package/.agents/rules/profiles/springboot/04-/345/210/206/345/261/202/350/247/204/350/214/203.md

@@ -1,33 +1,33 @@
----
-alwaysApply: false
-description: Spring Boot 项目的分层规范，包括 Controller / Service / Repository 职责边界、禁止跨层直接调用的约束。当新增或修改业务代码时读取此规则。
----
-
-# 分层规范（Spring Boot）
-
-## 分层职责
-
-| 层次 | 职责 | 禁止事项 |
-|------|------|----------|
-| Controller | 接收 HTTP 请求、参数校验、调用 Service、返回响应 | 禁止包含业务逻辑、禁止直接调用 Repository |
-| Service | 业务逻辑编排、事务管理、跨模块调用 | 禁止直接处理 HTTP 请求 / 响应对象 |
-| Repository | 数据访问、SQL / ORM 操作 | 禁止包含业务逻辑 |
-| Domain / Entity | 领域模型定义 | 禁止依赖 Service 或 Repository |
-| DTO | 数据传输对象，用于跨层传递 | 禁止包含业务逻辑 |
-
-## 调用规则（NON-NEGOTIABLE）
-
-- Controller 只调用 Service，不直接调用 Repository
-- Service 调用 Repository 或其它 Service（同层可调用）
-- Repository 只负责数据操作，不引用 Service
-
-## 事务管理
-
-- 事务注解 `@Transactional` 加在 Service 层
-- 只读操作使用 `@Transactional(readOnly = true)` 提升性能
-- 跨 Service 的复杂事务需明确传播行为（`REQUIRED` / `REQUIRES_NEW`）
-
-## 接口与实现分离
-
-- Service 层优先定义接口（`XxxService`），由 `XxxServiceImpl` 实现
-- 单实现场景下可酌情省略接口，但需团队统一约定
+---
+alwaysApply: false
+description: Spring Boot 项目的分层规范，包括 Controller / Service / Repository 职责边界、禁止跨层直接调用的约束。当新增或修改业务代码时读取此规则。
+---
+
+# 分层规范（Spring Boot）
+
+## 分层职责
+
+| 层次 | 职责 | 禁止事项 |
+|------|------|----------|
+| Controller | 接收 HTTP 请求、参数校验、调用 Service、返回响应 | 禁止包含业务逻辑、禁止直接调用 Repository |
+| Service | 业务逻辑编排、事务管理、跨模块调用 | 禁止直接处理 HTTP 请求 / 响应对象 |
+| Repository | 数据访问、SQL / ORM 操作 | 禁止包含业务逻辑 |
+| Domain / Entity | 领域模型定义 | 禁止依赖 Service 或 Repository |
+| DTO | 数据传输对象，用于跨层传递 | 禁止包含业务逻辑 |
+
+## 调用规则（NON-NEGOTIABLE）
+
+- Controller 只调用 Service，不直接调用 Repository
+- Service 调用 Repository 或其它 Service（同层可调用）
+- Repository 只负责数据操作，不引用 Service
+
+## 事务管理
+
+- 事务注解 `@Transactional` 加在 Service 层
+- 只读操作使用 `@Transactional(readOnly = true)` 提升性能
+- 跨 Service 的复杂事务需明确传播行为（`REQUIRED` / `REQUIRES_NEW`）
+
+## 接口与实现分离
+
+- Service 层优先定义接口（`XxxService`），由 `XxxServiceImpl` 实现
+- 单实现场景下可酌情省略接口，但需团队统一约定

package/.agents/rules/profiles/springboot/05-/346/216/245/345/217/243/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md

@@ -1,51 +1,51 @@
----
-alwaysApply: false
-description: Spring Boot 项目的接口与契约规范，包括 RESTful 接口设计、统一响应体、版本控制与参数校验约定。当新增或修改 HTTP 接口时读取此规则。
----
-
-# 接口与契约规范（Spring Boot）
-
-## RESTful 设计原则
-
-| 操作 | HTTP 方法 | URI 示例 |
-|------|-----------|----------|
-| 查询列表 | GET | `/api/v1/orders` |
-| 查询详情 | GET | `/api/v1/orders/{id}` |
-| 创建 | POST | `/api/v1/orders` |
-| 更新（全量） | PUT | `/api/v1/orders/{id}` |
-| 更新（部分） | PATCH | `/api/v1/orders/{id}` |
-| 删除 | DELETE | `/api/v1/orders/{id}` |
-
-## 统一响应体（NON-NEGOTIABLE）
-
-所有接口必须返回统一的响应结构：
-
-```java
-public class Result<T> {
-    private int code;       // 状态码，成功为 0 或 200
-    private String message; // 描述信息
-    private T data;         // 业务数据
-}
-```
-
-- 不允许直接返回裸数据，必须包装成统一响应体
-- 异常响应同样遵循此格式
-
-## API 版本控制
-
-- URI 路径版本：`/api/v1/`、`/api/v2/`
-- 新版本接口不应破坏已有版本的兼容性
-
-## 参数校验
-
-- 使用 JSR-303/380（`@Valid`、`@Validated`）进行请求参数校验
-- Controller 层统一触发校验，不在 Service 层重复校验入参格式
-- 自定义校验注解放在 `common` 模块的 `validation` 包
-
-## DTO 命名约定
-
-| 场景 | 命名 | 示例 |
-|------|------|------|
-| 请求参数 | `XxxRequest` / `XxxReqDTO` | `CreateOrderRequest` |
-| 响应数据 | `XxxResponse` / `XxxRespDTO` | `OrderDetailResponse` |
-| 查询条件 | `XxxQuery` | `OrderListQuery` |
+---
+alwaysApply: false
+description: Spring Boot 项目的接口与契约规范，包括 RESTful 接口设计、统一响应体、版本控制与参数校验约定。当新增或修改 HTTP 接口时读取此规则。
+---
+
+# 接口与契约规范（Spring Boot）
+
+## RESTful 设计原则
+
+| 操作 | HTTP 方法 | URI 示例 |
+|------|-----------|----------|
+| 查询列表 | GET | `/api/v1/orders` |
+| 查询详情 | GET | `/api/v1/orders/{id}` |
+| 创建 | POST | `/api/v1/orders` |
+| 更新（全量） | PUT | `/api/v1/orders/{id}` |
+| 更新（部分） | PATCH | `/api/v1/orders/{id}` |
+| 删除 | DELETE | `/api/v1/orders/{id}` |
+
+## 统一响应体（NON-NEGOTIABLE）
+
+所有接口必须返回统一的响应结构：
+
+```java
+public class Result<T> {
+    private int code;       // 状态码，成功为 0 或 200
+    private String message; // 描述信息
+    private T data;         // 业务数据
+}
+```
+
+- 不允许直接返回裸数据，必须包装成统一响应体
+- 异常响应同样遵循此格式
+
+## API 版本控制
+
+- URI 路径版本：`/api/v1/`、`/api/v2/`
+- 新版本接口不应破坏已有版本的兼容性
+
+## 参数校验
+
+- 使用 JSR-303/380（`@Valid`、`@Validated`）进行请求参数校验
+- Controller 层统一触发校验，不在 Service 层重复校验入参格式
+- 自定义校验注解放在 `common` 模块的 `validation` 包
+
+## DTO 命名约定
+
+| 场景 | 命名 | 示例 |
+|------|------|------|
+| 请求参数 | `XxxRequest` / `XxxReqDTO` | `CreateOrderRequest` |
+| 响应数据 | `XxxResponse` / `XxxRespDTO` | `OrderDetailResponse` |
+| 查询条件 | `XxxQuery` | `OrderListQuery` |

package/.agents/rules/profiles/springboot/06-/346/225/260/346/215/256/350/256/277/351/227/256/350/247/204/350/214/203.md

@@ -1,34 +1,34 @@
----
-alwaysApply: false
-description: Spring Boot 项目的数据访问规范，包括 ORM 框架选型约定、Repository 命名、SQL 管理与事务边界。当编写数据访问层代码时读取此规则。
----
-
-# 数据访问规范（Spring Boot）
-
-## ORM 框架约定
-
-- 项目统一使用团队约定的 ORM 框架（MyBatis / JPA / Spring Data），禁止混用
-- MyBatis 项目：SQL 写在 XML 中（`src/main/resources/mapper/`），禁止直接在注解里写复杂 SQL
-- JPA 项目：简单查询使用 Repository 方法命名，复杂查询使用 `@Query` 或 Specification
-
-## Repository 命名
-
-- 接口命名：`XxxMapper`（MyBatis）或 `XxxRepository`（JPA）
-- 每个实体对应一个 Mapper / Repository，禁止跨实体混合操作
-
-## 分页查询
-
-- 统一使用框架提供的分页机制（MyBatis-Plus `Page`、Spring Data `Pageable`）
-- 禁止手写 `LIMIT offset, size` 做内存分页
-
-## SQL 安全
-
-- 禁止字符串拼接构造 SQL（防 SQL 注入）
-- 动态 SQL 使用框架提供的条件拼接（`<if>`、`Criteria`）
-- 批量操作使用框架批量接口，禁止循环单条操作
-
-## 实体设计
-
-- 主键统一通过框架生成策略管理（雪花 ID、自增、UUID 按项目选一）
-- 审计字段（创建时间、更新时间、创建人、更新人）统一由基类或 `@EntityListeners` 自动填充
-- 逻辑删除字段统一命名（如 `is_deleted`），不做物理删除
+---
+alwaysApply: false
+description: Spring Boot 项目的数据访问规范，包括 ORM 框架选型约定、Repository 命名、SQL 管理与事务边界。当编写数据访问层代码时读取此规则。
+---
+
+# 数据访问规范（Spring Boot）
+
+## ORM 框架约定
+
+- 项目统一使用团队约定的 ORM 框架（MyBatis / JPA / Spring Data），禁止混用
+- MyBatis 项目：SQL 写在 XML 中（`src/main/resources/mapper/`），禁止直接在注解里写复杂 SQL
+- JPA 项目：简单查询使用 Repository 方法命名，复杂查询使用 `@Query` 或 Specification
+
+## Repository 命名
+
+- 接口命名：`XxxMapper`（MyBatis）或 `XxxRepository`（JPA）
+- 每个实体对应一个 Mapper / Repository，禁止跨实体混合操作
+
+## 分页查询
+
+- 统一使用框架提供的分页机制（MyBatis-Plus `Page`、Spring Data `Pageable`）
+- 禁止手写 `LIMIT offset, size` 做内存分页
+
+## SQL 安全
+
+- 禁止字符串拼接构造 SQL（防 SQL 注入）
+- 动态 SQL 使用框架提供的条件拼接（`<if>`、`Criteria`）
+- 批量操作使用框架批量接口，禁止循环单条操作
+
+## 实体设计
+
+- 主键统一通过框架生成策略管理（雪花 ID、自增、UUID 按项目选一）
+- 审计字段（创建时间、更新时间、创建人、更新人）统一由基类或 `@EntityListeners` 自动填充
+- 逻辑删除字段统一命名（如 `is_deleted`），不做物理删除

package/.agents/rules/profiles/springboot/07-/351/205/215/347/275/256/344/270/216/350/277/220/350/241/214/346/227/266/350/247/204/350/214/203.md

@@ -1,38 +1,38 @@
----
-alwaysApply: false
-description: Spring Boot 项目的配置与运行时规范，包括配置文件分层、环境隔离、敏感配置管理与 Bean 生命周期约定。当新增或修改配置时读取此规则。
----
-
-# 配置与运行时规范（Spring Boot）
-
-## 配置文件分层
-
-```text
-src/main/resources/
-├── application.yml          # 公共配置（不含敏感信息）
-├── application-dev.yml      # 开发环境
-├── application-test.yml     # 测试环境
-├── application-prod.yml     # 生产环境
-└── bootstrap.yml            # 配置中心加载（如使用）
-```
-
-- 通过 `spring.profiles.active` 激活环境配置
-- 公共配置放 `application.yml`，环境差异放对应的 profile 文件
-
-## 敏感配置管理（NON-NEGOTIABLE）
-
-- 数据库密码、中间件密码、第三方 API 密钥禁止写入 Git
-- 生产敏感配置通过配置中心（Nacos / Apollo）或环境变量注入
-- 本地开发可使用 `.env` 文件（已加入 `.gitignore`）存储敏感值
-
-## 配置类约定
-
-- 自定义配置使用 `@ConfigurationProperties` 而非多处 `@Value`
-- 配置类放在 `config/` 包，命名为 `XxxProperties` 或 `XxxConfig`
-- 配置校验：在 `@ConfigurationProperties` 类上使用 `@Validated` 及 JSR-303 注解
-
-## Bean 生命周期
-
-- 使用构造函数注入（而非字段注入），便于测试与不变性保证
-- 避免循环依赖；若存在，优先通过重构消除，而非使用 `@Lazy`
-- `ApplicationRunner` / `CommandLineRunner` 仅用于应用启动后的一次性初始化
+---
+alwaysApply: false
+description: Spring Boot 项目的配置与运行时规范，包括配置文件分层、环境隔离、敏感配置管理与 Bean 生命周期约定。当新增或修改配置时读取此规则。
+---
+
+# 配置与运行时规范（Spring Boot）
+
+## 配置文件分层
+
+```text
+src/main/resources/
+├── application.yml          # 公共配置（不含敏感信息）
+├── application-dev.yml      # 开发环境
+├── application-test.yml     # 测试环境
+├── application-prod.yml     # 生产环境
+└── bootstrap.yml            # 配置中心加载（如使用）
+```
+
+- 通过 `spring.profiles.active` 激活环境配置
+- 公共配置放 `application.yml`，环境差异放对应的 profile 文件
+
+## 敏感配置管理（NON-NEGOTIABLE）
+
+- 数据库密码、中间件密码、第三方 API 密钥禁止写入 Git
+- 生产敏感配置通过配置中心（Nacos / Apollo）或环境变量注入
+- 本地开发可使用 `.env` 文件（已加入 `.gitignore`）存储敏感值
+
+## 配置类约定
+
+- 自定义配置使用 `@ConfigurationProperties` 而非多处 `@Value`
+- 配置类放在 `config/` 包，命名为 `XxxProperties` 或 `XxxConfig`
+- 配置校验：在 `@ConfigurationProperties` 类上使用 `@Validated` 及 JSR-303 注解
+
+## Bean 生命周期
+
+- 使用构造函数注入（而非字段注入），便于测试与不变性保证
+- 避免循环依赖；若存在，优先通过重构消除，而非使用 `@Lazy`
+- `ApplicationRunner` / `CommandLineRunner` 仅用于应用启动后的一次性初始化

package/.agents/rules/profiles/springboot/09-/345/274/202/345/270/270/344/270/216/346/227/245/345/277/227/350/247/204/350/214/203.md

@@ -1,48 +1,48 @@
----
-alwaysApply: false
-description: Spring Boot 项目的异常与日志规范，包括全局异常处理、自定义异常体系、日志级别与结构化日志约定。当编写异常处理或日志相关代码时读取此规则。
----
-
-# 异常与日志规范（Spring Boot）
-
-## 异常体系
-
-- 定义统一的业务异常基类（如 `BusinessException`）
-- 不同业务模块可扩展自己的子类（如 `OrderNotFoundException`）
-- 禁止直接抛出 `RuntimeException` 或 `Exception`，必须使用有语义的异常类型
-
-## 全局异常处理（NON-NEGOTIABLE）
-
-- 使用 `@RestControllerAdvice` + `@ExceptionHandler` 统一捕获异常
-- 全局处理器返回统一响应体（参考接口契约规范）
-- 以下异常必须全局处理：
-  - `BusinessException` 及其子类
-  - `MethodArgumentNotValidException`（参数校验失败）
-  - `HttpMessageNotReadableException`（请求体解析失败）
-  - 兜底 `Exception`（避免泄露堆栈信息到响应中）
-
-## 日志规范
-
-- 使用 `SLF4J` + `Logback` 或 `Log4j2`，禁止直接使用 `System.out.println`
-- 通过 `@Slf4j`（Lombok）或手动 `LoggerFactory.getLogger` 获取 Logger
-- 生产环境禁止 DEBUG 日志；开发/测试环境可开启
-
-### 日志级别使用场景
-
-| 级别 | 适用场景 |
-|------|----------|
-| ERROR | 系统异常、不可预期错误、需立即处理的问题 |
-| WARN | 可恢复的业务异常、配置缺失但有兜底 |
-| INFO | 关键业务操作节点（订单创建、支付完成等） |
-| DEBUG | 开发调试信息，生产禁止输出 |
-
-### 结构化日志
-
-- 关键操作日志包含：操作类型、业务 ID、操作人、耗时
-- 推荐使用 MDC 注入 traceId / requestId，便于链路追踪
-
-## 禁止事项
-
-- 禁止在 catch 块中吞掉异常（即 catch 后不记录、不抛出）
-- 禁止将异常堆栈直接返回给客户端
-- 禁止在循环内大量打印日志（性能风险）
+---
+alwaysApply: false
+description: Spring Boot 项目的异常与日志规范，包括全局异常处理、自定义异常体系、日志级别与结构化日志约定。当编写异常处理或日志相关代码时读取此规则。
+---
+
+# 异常与日志规范（Spring Boot）
+
+## 异常体系
+
+- 定义统一的业务异常基类（如 `BusinessException`）
+- 不同业务模块可扩展自己的子类（如 `OrderNotFoundException`）
+- 禁止直接抛出 `RuntimeException` 或 `Exception`，必须使用有语义的异常类型
+
+## 全局异常处理（NON-NEGOTIABLE）
+
+- 使用 `@RestControllerAdvice` + `@ExceptionHandler` 统一捕获异常
+- 全局处理器返回统一响应体（参考接口契约规范）
+- 以下异常必须全局处理：
+  - `BusinessException` 及其子类
+  - `MethodArgumentNotValidException`（参数校验失败）
+  - `HttpMessageNotReadableException`（请求体解析失败）
+  - 兜底 `Exception`（避免泄露堆栈信息到响应中）
+
+## 日志规范
+
+- 使用 `SLF4J` + `Logback` 或 `Log4j2`，禁止直接使用 `System.out.println`
+- 通过 `@Slf4j`（Lombok）或手动 `LoggerFactory.getLogger` 获取 Logger
+- 生产环境禁止 DEBUG 日志；开发/测试环境可开启
+
+### 日志级别使用场景
+
+| 级别 | 适用场景 |
+|------|----------|
+| ERROR | 系统异常、不可预期错误、需立即处理的问题 |
+| WARN | 可恢复的业务异常、配置缺失但有兜底 |
+| INFO | 关键业务操作节点（订单创建、支付完成等） |
+| DEBUG | 开发调试信息，生产禁止输出 |
+
+### 结构化日志
+
+- 关键操作日志包含：操作类型、业务 ID、操作人、耗时
+- 推荐使用 MDC 注入 traceId / requestId，便于链路追踪
+
+## 禁止事项
+
+- 禁止在 catch 块中吞掉异常（即 catch 后不记录、不抛出）
+- 禁止将异常堆栈直接返回给客户端
+- 禁止在循环内大量打印日志（性能风险）

package/.agents/rules/profiles/springboot/11-/346/265/213/350/257/225/350/247/204/350/214/203.md

@@ -1,43 +1,43 @@
----
-alwaysApply: false
-description: Spring Boot 项目的测试规范，包括测试框架（JUnit 5 + Mockito + Spring Boot Test）、测试分层策略、测试文件约定与质量门禁。当编写测试或评审测试代码时读取此规则。
----
-
-# 测试规范（Spring Boot）
-
-## 测试框架
-
-- 统一使用 **JUnit 5**（`@ExtendWith(SpringExtension.class)` 或 `@SpringBootTest`）
-- Mock 框架：**Mockito**（`@MockBean`、`@Mock`、`@InjectMocks`）
-- 断言库：**AssertJ**（推荐）或 JUnit 5 原生 `Assertions`
-
-## 测试分层策略
-
-| 层次 | 注解 | 范围 | 说明 |
-|------|------|------|------|
-| 单元测试 | 无 Spring 上下文 | Service / 工具类 | 使用 Mockito 模拟依赖，运行最快 |
-| 切片测试 | `@WebMvcTest`、`@DataJpaTest` | Controller / Repository | 只加载对应层的 Spring 上下文 |
-| 集成测试 | `@SpringBootTest` | 全链路 | 加载完整上下文，速度慢，按需使用 |
-
-## 测试文件约定
-
-| 项目 | 约定 |
-|------|------|
-| 文件位置 | `src/test/java/<same-package-as-source>/` |
-| 文件命名 | `XxxTest.java`（单元测试）、`XxxIT.java`（集成测试） |
-| 测试配置 | `src/test/resources/application-test.yml` |
-
-## 编写规范
-
-- 测试方法命名使用中文或英文描述，表达预期行为而非实现步骤
-- 遵循 **Arrange-Act-Assert** 模式
-- 每个测试方法只验证一个行为点
-- 测试应互相独立，不依赖执行顺序
-- 使用 `@TestPropertySource` 或测试配置文件覆盖生产配置
-
-## 质量门禁（NON-NEGOTIABLE）
-
-- 所有 Service 层核心业务逻辑必须有单元测试覆盖
-- `@SpringBootTest` 集成测试按需使用，不要求全覆盖
-- 测试必须能独立运行，不依赖外部真实服务（使用 Mock 或嵌入式数据库）
-- 新增工具类必须附带测试用例
+---
+alwaysApply: false
+description: Spring Boot 项目的测试规范，包括测试框架（JUnit 5 + Mockito + Spring Boot Test）、测试分层策略、测试文件约定与质量门禁。当编写测试或评审测试代码时读取此规则。
+---
+
+# 测试规范（Spring Boot）
+
+## 测试框架
+
+- 统一使用 **JUnit 5**（`@ExtendWith(SpringExtension.class)` 或 `@SpringBootTest`）
+- Mock 框架：**Mockito**（`@MockBean`、`@Mock`、`@InjectMocks`）
+- 断言库：**AssertJ**（推荐）或 JUnit 5 原生 `Assertions`
+
+## 测试分层策略
+
+| 层次 | 注解 | 范围 | 说明 |
+|------|------|------|------|
+| 单元测试 | 无 Spring 上下文 | Service / 工具类 | 使用 Mockito 模拟依赖，运行最快 |
+| 切片测试 | `@WebMvcTest`、`@DataJpaTest` | Controller / Repository | 只加载对应层的 Spring 上下文 |
+| 集成测试 | `@SpringBootTest` | 全链路 | 加载完整上下文，速度慢，按需使用 |
+
+## 测试文件约定
+
+| 项目 | 约定 |
+|------|------|
+| 文件位置 | `src/test/java/<same-package-as-source>/` |
+| 文件命名 | `XxxTest.java`（单元测试）、`XxxIT.java`（集成测试） |
+| 测试配置 | `src/test/resources/application-test.yml` |
+
+## 编写规范
+
+- 测试方法命名使用中文或英文描述，表达预期行为而非实现步骤
+- 遵循 **Arrange-Act-Assert** 模式
+- 每个测试方法只验证一个行为点
+- 测试应互相独立，不依赖执行顺序
+- 使用 `@TestPropertySource` 或测试配置文件覆盖生产配置
+
+## 质量门禁（NON-NEGOTIABLE）
+
+- 所有 Service 层核心业务逻辑必须有单元测试覆盖
+- `@SpringBootTest` 集成测试按需使用，不要求全覆盖
+- 测试必须能独立运行，不依赖外部真实服务（使用 Mock 或嵌入式数据库）
+- 新增工具类必须附带测试用例

package/.agents/rules/profiles/springboot/13-/344/273/243/347/240/201/346/240/274/345/274/217/345/214/226/344/270/216/346/243/200/346/237/245.md

@@ -1,48 +1,48 @@
----
-alwaysApply: false
-description: Spring Boot 项目的代码格式化与静态检查规范，包括 Checkstyle、SpotBugs、Google Java Format 等工具链职责与配置约定。当配置或调整代码检查工具时读取此规则。
----
-
-# 代码格式化与检查（Spring Boot）
-
-## 工具链
-
-| 工具 | 职责 | 配置文件 |
-|------|------|----------|
-| **Google Java Format** / **Spotless** | Java 代码格式化（缩进、括号等） | `pom.xml` / `build.gradle` 中的插件配置 |
-| **Checkstyle** | 代码风格检查（命名、注释等） | `checkstyle.xml` |
-| **SpotBugs** | 静态分析（潜在 bug 检测） | `spotbugs-exclude.xml` |
-
-## 格式化规则
-
-- 统一使用项目约定的 Java 格式化风格（Google Style 或 Alibaba Java Style）
-- 缩进：4 个空格，禁止使用 Tab
-- 单行最大宽度：120 字符
-- 所有 `import` 按字母顺序排列，禁止 wildcard import（`import java.util.*`）
-
-## Checkstyle 核心规则
-
-- 类、方法、字段命名遵循 Java 命名约定
-- 公共类和公共方法必须有 Javadoc 注释
-- 禁止空 catch 块（必须有注释说明忽略原因）
-
-## Maven / Gradle 集成
-
-```xml
-<!-- Maven 示例：Spotless 格式化插件 -->
-<plugin>
-  <groupId>com.diffplug.spotless</groupId>
-  <artifactId>spotless-maven-plugin</artifactId>
-  <configuration>
-    <java>
-      <googleJavaFormat/>
-    </java>
-  </configuration>
-</plugin>
-```
-
-## 开发流程集成
-
-- 提交前通过 Maven/Gradle 的 `verify` 阶段执行 Checkstyle 和 SpotBugs
-- IDE 推荐安装 Checkstyle 插件，实时提示规范问题
-- CI 流水线必须包含 `checkstyle:check` 步骤，失败则阻断合并
+---
+alwaysApply: false
+description: Spring Boot 项目的代码格式化与静态检查规范，包括 Checkstyle、SpotBugs、Google Java Format 等工具链职责与配置约定。当配置或调整代码检查工具时读取此规则。
+---
+
+# 代码格式化与检查（Spring Boot）
+
+## 工具链
+
+| 工具 | 职责 | 配置文件 |
+|------|------|----------|
+| **Google Java Format** / **Spotless** | Java 代码格式化（缩进、括号等） | `pom.xml` / `build.gradle` 中的插件配置 |
+| **Checkstyle** | 代码风格检查（命名、注释等） | `checkstyle.xml` |
+| **SpotBugs** | 静态分析（潜在 bug 检测） | `spotbugs-exclude.xml` |
+
+## 格式化规则
+
+- 统一使用项目约定的 Java 格式化风格（Google Style 或 Alibaba Java Style）
+- 缩进：4 个空格，禁止使用 Tab
+- 单行最大宽度：120 字符
+- 所有 `import` 按字母顺序排列，禁止 wildcard import（`import java.util.*`）
+
+## Checkstyle 核心规则
+
+- 类、方法、字段命名遵循 Java 命名约定
+- 公共类和公共方法必须有 Javadoc 注释
+- 禁止空 catch 块（必须有注释说明忽略原因）
+
+## Maven / Gradle 集成
+
+```xml
+<!-- Maven 示例：Spotless 格式化插件 -->
+<plugin>
+  <groupId>com.diffplug.spotless</groupId>
+  <artifactId>spotless-maven-plugin</artifactId>
+  <configuration>
+    <java>
+      <googleJavaFormat/>
+    </java>
+  </configuration>
+</plugin>
+```
+
+## 开发流程集成
+
+- 提交前通过 Maven/Gradle 的 `verify` 阶段执行 Checkstyle 和 SpotBugs
+- IDE 推荐安装 Checkstyle 插件，实时提示规范问题
+- CI 流水线必须包含 `checkstyle:check` 步骤，失败则阻断合并