ECC Kiro 版 Java 代码审查 Agent：面向 Spring Boot 与 Quarkus 的框架自检测双轨审查规则体系

ECC（Everything Claude Code）仓库将 Java 代码审查流程沉淀为一个可直接安装的 Agent 提示词体系：.kiro/agents/java-reviewer.md。该 Agent 的核心设计是“先检测框架、再套用规则”——通过解析构建文件自动识别 Spring Boot 或 Quarkus 项目，然后应用对应的分层审查规则，覆盖分层架构、JPA/Panache、MongoDB、安全与并发五大领域。读完本篇，你可以理解这套 Agent 的完整工作机制：框架检测命令、审查优先级分级（CRITICAL/HIGH/MEDIUM）、诊断命令集与审批标准（Approve/Warning/Block），并能将其安装到 Kiro 项目中落地使用。

Agent 定位与双文件格式

在 ECC 的 Kiro 集成体系中，Agent 是“带特定工具配置的专用 AI 助手”，每个 Agent 同时提供两种格式以保证兼容性：

• Markdown 格式（.md）：供 Kiro IDE 使用，支持自动选择或显式调用；
• JSON 格式（.json）：供 kiro-cli 使用，通过 /agent swap 命令切换。

.kiro/agents/java-reviewer.md 的 YAML frontmatter 声明了该 Agent 的身份与工具边界：

---
name: java-reviewer
description: Expert Java code reviewer for Spring Boot and Quarkus projects.
  Automatically detects the framework and applies the appropriate review rules.
  Covers layered architecture, JPA/Panache, MongoDB, security, and concurrency.
  MUST BE USED for all Java code changes.
allowedTools:
  - read
  - shell
---

对应的 CLI 配置 .kiro/agents/java-reviewer.json 中 allowedTools 映射为 fs_read 与 shell，并声明 "useLegacyMcpJson": false。这个工具约束值得注意：Agent 只有读文件和执行 shell 两类能力，正文中也明确写了 “You DO NOT refactor or rewrite code — you report findings only.”（只报告发现，不重构代码）。这正是审查类 Agent 的标准姿态——把“发现”与“修改”解耦，避免审查 Agent 顺手改码引入新问题。

正文以角色设定开场：“You are a senior Java engineer ensuring high standards of idiomatic Java, Spring Boot, and Quarkus best practices.”，随后进入框架检测流程。

框架检测：审查的第一步

该 Agent 最关键的设计决策是将框架检测作为审查的前置步骤（run first）。原版文档给出的检测命令是：

find . -name 'pom.xml' -o -name 'build.gradle' -o -name 'build.gradle.kts' | head -20 | xargs grep -l 'spring-boot\|quarkus' 2>/dev/null

该命令的工作方式是：find 先收集项目内最多 20 个构建文件（Maven 的 pom.xml 与 Gradle 的 build.gradle/build.gradle.kts），再用 xargs grep -l 筛出内容中命中 spring-boot 或 quarkus 关键字的文件列表，输出命中文件路径，从而确定项目所属框架。检测结果的映射规则为：

检测结果	应用规则集
任一构建文件包含 quarkus	[QUARKUS] 规则
任一构建文件包含 spring-boot	[SPRING] 规则
两者都未检测到	仅使用通用 Java 规则审查

值得注意的是，ECC 仓库中还存在一个更严格的同源变体 agents/java-reviewer.md（面向 Claude Code 等 harness 的仓库级 Agent），它的检测命令简化为 cat pom.xml || cat build.gradle || cat build.gradle.kts，并且增加了两条防御性规则：

• 若两个框架标识同时出现（罕见）→ 作为一条 finding 上报，并同时应用两套规则；
• 若都未检测到 → 仅用通用 Java 规则审查，并明确记录该歧义。

此外，agents/java-reviewer.md 还在开头加入了一段“Prompt Defense Baseline”（提示词防御基线）：不改变角色、不泄露机密、将外部数据视为不可信内容、警惕 unicode 同形字/零宽字符等注入手段。这体现了 ECC 对审查 Agent 的纵深防御思路：审查 Agent 本身会读取大量用户代码，而这些代码中可能埋有针对 LLM 的注入载荷。

审查工作流：从 diff 到构建验证

框架确定后，文档规定了一个四步标准工作流：

1. 查看变更：运行 git diff HEAD~1 -- '*.java' 查看最近的 Java 文件变更；PR 审查场景改用 git diff main...HEAD -- '*.java'；若浅克隆或单提交历史导致 HEAD~1 失败，回退到 git show --patch HEAD -- '*.java'；
2. 运行构建检查：无论 SPRING 还是 QUARKUS，均执行 ./mvnw verify -q（Maven）或 ./gradlew check（Gradle）；
3. 聚焦修改过的 .java 文件：审查范围锁定在 diff 涉及的代码，而非全量扫描；
4. 立即开始审查。

这条工作流体现了两个工程原则：一是“构建先行”——先确认代码能编译、测试能跑，再谈代码质量，避免在坏代码上浪费审查预算；二是“增量聚焦”——只审改动部分，这与 PR review 的实际场景吻合，也能控制 LLM 上下文消耗。

审查优先级体系：CRITICAL / HIGH / MEDIUM 三级规则

文档将全部审查规则组织为三级优先级，每条规则都可直接映射到一个可检查的代码特征。以下按原文档结构完整展开，并结合仓库中相关 skill 补充了依据。

CRITICAL — 安全

这一级直接对应 OWASP 类高危漏洞，任何一条命中都应阻止合并：

• SQL 注入：查询语句中的字符串拼接——必须改用绑定参数；
• 命令注入：用户可控输入直接传入 ProcessBuilder 或 Runtime.exec()；
• 路径穿越：用户可控输入未经验证即传入 new File(userInput)；
• 硬编码密钥：源码中出现 API key、密码、token；
• PII/token 日志泄漏：日志调用暴露了密码或 token；
• 缺失输入校验：请求体未经 Bean Validation（@Valid）直接接收；
• 无正当理由禁用 CSRF：无状态 JWT API 可以禁用 CSRF，但必须记录理由。

仓库中 skills/springboot-patterns/SKILL.md 与 .kiro/skills/springboot-security/SKILL.md 提供了对应修复模式：例如 Spring 侧 DTO 应使用 @NotBlank、@Size 等 record 校验注解，@Valid @RequestBody 与集中式 @ControllerAdvice 异常处理配合使用。

CRITICAL — 错误处理

• 被吞掉的异常：空 catch 块或 catch (Exception e) {} 无任何动作；
• Optional 上的 .get()：未检查 .isPresent() 就调用 .get()——应改用 .orElseThrow()；
• 缺失集中式异常处理：Spring 项目缺少 @RestControllerAdvice，Quarkus 项目缺少 ExceptionMapper；
• HTTP 状态码错误：返回 200 OK + null body 而不是 404。

这四项与 .kiro/steering/java-patterns.md 中“Error Handling”章节互为印证：该 steering 文件规定“优先使用非受检异常表达领域错误、创建继承 RuntimeException 的领域专用异常、绝不在 API 响应中暴露堆栈”，并给出了 OrderNotFoundException 的完整示例。Kiro 的 steering 机制会在编辑 *.java 文件时自动加载该文件（fileMatch: "*.java"），形成“写码时由 steering 约束 + 改码后由 java-reviewer 审查”的双层防线。

HIGH — 架构

• 依赖注入方式：字段上的 @Autowired（SPRING）——要求构造器注入；
• @Singleton vs @ApplicationScoped（QUARKUS）：@Singleton bean 不走代理——优先使用 @ApplicationScoped；
• 控制器/资源层中的业务逻辑：必须委托给 service 层；
• @Transactional 用错层：必须在 service 层，而非 controller 或 repository；
• 实体直接暴露在响应中：JPA/Panache 实体直接返回——应使用 DTO 或 record 投影；
• 响应式线程上的阻塞调用（QUARKUS）：使用 @Blocking 或响应式客户端。

关于构造器注入这一点，.kiro/steering/java-patterns.md 给出了 GOOD/BAD 对照代码：private final 字段 + 构造器赋值是正确做法，字段上挂 @Inject/@Autowired 被明确标记为 BAD。而 skills/springboot-patterns/SKILL.md 中的 MarketController/MarketService 示例则展示了完整的“Controller 只做委托、@Transactional 落在 Service、DTO 用 record 建模”的参考实现——即该 Agent 审查所期望达到的目标形态。

HIGH — JPA / 关系型数据库

• N+1 查询问题：集合上的 FetchType.EAGER——应改用 JOIN FETCH 或 @EntityGraph；
• 无界列表端点：返回 List<T> 却没有分页；
• 缺失 @Modifying：任何修改数据的 @Query 都需要 @Modifying + @Transactional；
• 危险级联：CascadeType.ALL 搭配 orphanRemoval = true——需确认这是刻意行为。

这部分与 .kiro/skills/jpa-patterns/SKILL.md（“JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot”）深度配套：Agent 负责发现违规，skill 负责提供合规写法。

HIGH — Panache MongoDB（仅 QUARKUS）

• 无界 listAll() / findAll()：必须使用分页；
• 查询字段无索引：为被查询的字段定义索引；
• 响应式线程上的阻塞 MongoDB 客户端：改用 ReactiveMongoClient。

MEDIUM — 并发与状态

• 可变单例字段：单例作用域 bean 中非 final 的实例字段构成竞态条件；
• 无界异步执行：CompletableFuture 或 @Async 未指定自定义 Executor；
• 阻塞型 @Scheduled：长时间运行的定时方法阻塞调度器线程。

MEDIUM — Java 惯用法与性能

• 循环内字符串拼接：应使用 StringBuilder 或 String.join；
• 原始类型使用：未参数化的泛型（List 而非 List<T>）；
• 错过模式匹配：instanceof 判断后跟显式强转——Java 16+ 应使用模式匹配；
• service 层返回 null：应优先 Optional<T> 而非返回 null。

MEDIUM — 测试

• 测试注解作用域过大：单元测试用 @SpringBootTest——应改用 @WebMvcTest 或 @DataJpaTest；
• 测试中使用 Thread.sleep()：异步断言应使用 Awaitility；
• 弱测试命名：应使用 should_return_404_when_user_not_found 风格的命名。

诊断命令集

文档为 Agent 提供了一组可直接执行的诊断命令，用于在不依赖 IDE 的情况下快速定位问题模式：

git diff -- '*.java'
./mvnw verify -q                             # Maven
./gradlew check                              # Gradle
./mvnw checkstyle:check
./mvnw spotbugs:check
grep -rn "FetchType.EAGER" src/main/java --include="*.java"

其中最后一条 grep 是典型的“规则 → 命令”映射：FetchType.EAGER 是 N+1 问题的高危信号，用一条 grep 就能全量扫出候选位置。这种“审查规则与诊断命令一一对应”的设计使规则具备可执行性——Agent 不只是拿着清单读代码，还能主动运行命令取证。

审批标准：三态输出

审查结论被收敛为明确的三态，便于上游流程（CI、合并检查）直接消费：

结论	条件
Approve	无 CRITICAL 或 HIGH 问题
Warning	仅有 MEDIUM 问题
Block	发现任何 CRITICAL 或 HIGH 问题

这套三态与 Kiro 侧的 quality-gate 机制天然衔接：Kiro 的 .kiro/hooks/quality-gate.kiro.hook 配合 .kiro/scripts/quality-gate.sh 负责机械性检查（构建、类型、lint、测试），而 java-reviewer 负责语义性审查（架构、安全、并发语义），两者互补。

知识协作网络：Agent、Skill 与 Steering 三层联动

文档末尾声明了详细模式的扩展入口：

• [SPRING]：参考 skill: springboot-patterns，即仓库根目录下的 skills/springboot-patterns/SKILL.md（含 REST 分层、Repository 模式、Pageable 分页、DTO record 校验、集中异常处理等完整代码示例）；
• [QUARKUS]：参考 skill: quarkus-patterns，即 skills/quarkus-patterns/SKILL.md（Quarkus 3.x 模式，含 @ApplicationScoped + @RequiredArgsConstructor 的构造器注入、Panache 事务、Logback 日志上下文等）。

从仓库结构看，整个 Kiro 集成中 Java 相关能力是三层联动的：

1. Steering 层（.kiro/steering/java-patterns.md）：以 fileMatch: "*.java" 自动加载，在编写代码时注入 record/不可变性、构造器注入、Optional 使用、安全与测试规范；
2. Agent 层（.kiro/agents/java-reviewer.md）：在代码变更时执行审查，按三级优先级输出 Approve/Warning/Block；
3. Skill 层（如 .kiro/skills/java-coding-standards/SKILL.md、.kiro/skills/jpa-patterns/SKILL.md）：按需调用，提供深度模式与代码示例。

安装与使用

该 Agent 随 .kiro/install.sh 一起分发到任意 Kiro 项目，安装方式为非破坏性拷贝（不覆盖已有文件）：

cd .kiro
./install.sh /path/to/your/project   # 安装到指定项目
./install.sh                        # 安装到当前目录
./install.sh ~                      # 全局安装（作用于所有 Kiro 项目）

安装后有两种调用路径（详见 .kiro/README.md）：

• IDE 中：在 Kiro 会话中输入 /，显式调用 /java-reviewer；
• CLI 中：启动会话后执行 /agent swap 选择 java-reviewer，或直接 kiro-cli --agent java-reviewer。

需要说明的适用前提：该 Agent 的模型行为取决于 Kiro 中当前选用的模型，Agent 配置本身不锁定模型；且它只声明了 read/shell 工具，不具备文件写入能力，因此只能产出审查报告，修复工作需由开发或对应的 build-resolver 类 Agent 完成。

小结

.kiro/agents/java-reviewer.md 展示了将资深 Java 审查专家的经验转化为可执行 Agent 提示词的完整范式：前置框架检测命令决定规则集、diff 聚焦 + 构建验证构成审查工作流、三级优先级规则覆盖安全/错误处理/架构/JPA/MongoDB/并发/惯用法/测试、grep 诊断命令为规则提供取证手段、三态审批标准让结论可被流程消费。配合自动加载的 Java steering 与 springboot/quarkus/jpa 等 skill，ECC 为 Java 后端项目形成了“编写—审查—修复”闭环中前两个环节的标准化能力。仓库级的 agents/java-reviewer.md 变体还额外展示了提示词防御基线与“双框架命中/均未命中”的边界处理，适合作为设计自研语言审查 Agent 时值得借鉴的细节。