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

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

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

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 到构建验证

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

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

这条工作流体现了两个工程原则：一是“构建先行”——先确认代码能编译、测试能跑，再谈代码质量，避免在坏代码上浪费审查预算；二是“增量聚焦”——只审改动部分，这与 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）——要求构造器注入；
@Singletonvs@ApplicationScoped（QUARKUS）：@Singletonbean 不走代理——优先使用@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 相关能力是三层联动的：

Steering 层（.kiro/steering/java-patterns.md）：以fileMatch: "*.java"自动加载，在编写代码时注入 record/不可变性、构造器注入、Optional 使用、安全与测试规范；
Agent 层（.kiro/agents/java-reviewer.md）：在代码变更时执行审查，按三级优先级输出 Approve/Warning/Block；
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 时值得借鉴的细节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考