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 入参必须加 ValidDTO 字段必须加 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-commitmvn 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/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: { java-version: 17, distribution: temurin } - name: Cache Maven uses: actions/cachev4 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 个坑坑 1Maven 编译慢CI 超时AI 生成代码后CI 每次全量编译耗时 2-3 分钟。解法 开启 Maven 并行编译 mvn clean verify -T 1C并配置 actions/cache 缓存 ~/.m2/repository。耗时压到 40 秒内。坑 2AI 乱加 Autowired 字段注入Spring 官方推荐构造器注入但 AI 默认生成字段注入。解法 在 AGENTS.md 加一条禁止字段注入必须使用构造器注入或 RequiredArgsConstructor。 配合 IDE 插件自动转换。坑 3Jacoco 覆盖率不达标AI 生成的测试经常漏边界值导致 CI 标红。解法 在 pom.xml 配置 Jacoco 规则强制要求核心 Service 覆盖率 ≥80%。不达标直接 BUILD FAILURE。05Java 不是包袱是底线。你给它的边界越清晰它给你的惊喜就越大。别指望一句“帮我写个 Spring Boot 接口”就能搞定一切。把约束写进文件把校验交给流水线把合并权握在自己手里。