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:report
03
怎么跑起来？（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-commit
3.让 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 接口”就能搞定一切。
把约束写进文件，把校验交给流水线，把合并权握在自己手里。
