Harness Engineering 实战四：Java 项目的 Harness 层写在哪？附完整Demo
01
先看目录结构
一个标准的 Java AI Harness 工程，长这样：
harness-java-demo/ ├── AGENTS.md # 约束层：Java/Spring 专属红线 ├── .pre-commit-config.yaml # 校验层：提交前快速拦截 ├── config/ │ └── harness.yaml # 执行层：JVM 沙盒/内存/命令限制 ├── .github/ │ └── workflows/ │ └── ai-check.yml # 监控层：CI 强制跑测试与覆盖率 ├── scripts/ │ └── check_ai_code.sh # 轻量级 Java 正则校验脚本 ├── pom.xml # Maven 依赖与插件 ├── src/main/java/... # Spring Boot 3.x 业务代码 └── src/test/java/... # JUnit 5 测试用例别嫌多。 每一层，都在替你挡一个线上故障。
02
让我们来逐层拆解
层一：约束层（AGENTS.md）
放哪： 项目根目录。
作用： AI 启动时自动读取，定义 Java/Spring 专属红线。
# AGENTS.md ## Context 你正在开发 Spring Boot 3.2+ 用户注册服务。 ## Java/Spring Constraints (红线) 1. 包名规范：必须使用 jakarta.*，禁止 javax.*（Spring Boot 3 已全面迁移）。 2. 参数校验：Controller 入参必须加 @Valid，DTO 字段必须加 @NotBlank/@Email。 3. 事务管理：涉及写操作的方法必须显式声明 @Transactional(rollbackFor = Exception.class)。 4. 日志规范：禁止 System.out.println。必须使用 @Slf4j 或 LoggerFactory。 5. 密码安全：绝对禁止明文存储！必须使用 BCryptPasswordEncoder。层二：校验层（.pre-commit-config.yaml）
放哪： 项目根目录。
作用： git commit 时，快速拦截 AI 幻觉代码。
repos: - repo: local hooks: - id: java-harness-fast-check name: Java AI 代码快速校验 entry: bash scripts/check_ai_code.sh language: system types: [java]💡 为什么不用 Maven 跑 pre-commit？
mvn checkstyle:check 启动 JVM 太慢（通常 3-5 秒）。pre-commit 需要毫秒级响应。
解法： 用轻量 Shell 脚本做正则拦截，重型检查（Checkstyle/SpotBugs）交给 CI。
层三：执行层（config/harness.yaml）
放哪： config/ 目录。
作用： 限制 AI Agent 的 JVM 参数与危险命令。
agent: jvm: max_heap_size: "512m" blocked_packages: - java.lang.Runtime - java.lang.ProcessBuilder allowed_paths: - ./src - ./target - ./logs limits: max_tokens_per_request: 8192 timeout_seconds: 45 max_file_edits_per_session: 10层四：监控层（.github/workflows/ai-check.yml）
放哪： .github/workflows/。
作用： PR 合并前，CI 强制跑完整测试与覆盖率。不达标，不准合入。
name: Java AI Harness Check on: [pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up JDK 17 uses: actions/setup-java@v4 with: { java-version: '17', distribution: 'temurin' } - name: Cache Maven uses: actions/cache@v4 with: path: ~/.m2/repository key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }} - name: Build & Test run: mvn clean verify jacoco:report03
怎么跑起来？（3 步）
1.环境准备
确保已安装Java 17+、Maven 3.9+ 和 Git。
💡 IDE 提示：请在 IntelliJ IDEA/Eclipse 中安装 Lombok 插件/或者pom引入Lombok，否则 @Data 等注解会报错。
2.挂载 Hook（两种姿势任选）
- 姿势 A（推荐，毫秒级拦截）：
使用pre-commit 框架（Java 大厂项目标配，管理 Hooks 最方便）：
pip install pre-commit pre-commit install- 姿势 B（纯 Java 极简，免 Python）：
不想装Python？直接把脚本复制到 Git 目录：
# Mac/Linux/Git Bash cp scripts/check_ai_code.sh .git/hooks/pre-commit chmod +x .git/hooks/pre-commit3.让 AI 生成代码 & 提交拦截
正常写业务。提交时：
git add . git commit -m "feat: add user registration" # 若违反约束（如明文存密码），脚本直接阻断。⚠️ Windows 用户注意：运行 Shell 脚本需使用 Git Bash 或 WSL 终端，CMD/PowerShell 默认不支持。
04
踩过的 3 个坑
坑 1：Maven 编译慢，CI 超时
AI 生成代码后，CI 每次全量编译耗时 2-3 分钟。
解法： 开启 Maven 并行编译 mvn clean verify -T 1C，并配置 actions/cache 缓存 ~/.m2/repository。耗时压到 40 秒内。
坑 2：AI 乱加 @Autowired 字段注入
Spring 官方推荐构造器注入，但 AI 默认生成字段注入。
解法： 在 AGENTS.md 加一条：禁止字段注入，必须使用构造器注入或 @RequiredArgsConstructor。 配合 IDE 插件自动转换。
坑 3：Jacoco 覆盖率不达标
AI 生成的测试经常漏边界值，导致 CI 标红。
解法： 在 pom.xml 配置 Jacoco 规则，强制要求核心 Service 覆盖率 ≥80%。不达标直接 BUILD FAILURE。
05
Java 不是包袱，是底线。
你给它的边界越清晰，它给你的惊喜就越大。
别指望一句“帮我写个 Spring Boot 接口”就能搞定一切。
把约束写进文件，把校验交给流水线，把合并权握在自己手里。