# harness-java-demo

**Repository Path**: giugen/harness-java-demo

## Basic Information

- **Project Name**: harness-java-demo
- **Description**: Java版本的harness engineering实战demo
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java AI Harness Demo

> AI 写代码快，但一上生产就崩？
> 这个 Demo 工程展示了如何通过 **Harness Engineering（约束工程）** 让 Java/Spring Boot 代码的可靠性提升 10 倍。

## 📂 目录结构

```text
.
├── AGENTS.md              # [约束层] AI 的行为准则与边界
├── .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 测试用例
```

## 🚀 快速开始

### 1. 安装依赖
```bash
# 确保已安装 Java 17+ 和 Maven 3.9+
mvn clean install
```

### 2. 运行测试
确保业务逻辑正确，且 AI 生成的代码通过了单元测试。
```bash
mvn clean verify
```

### 3. 配置 Pre-commit Hook
安装钩子后，每次 `git commit` 都会自动运行 Lint 和 Harness 校验。
```bash
pip install pre-commit
pre-commit install
```

### 4. 测试拦截效果
尝试提交一段包含明文密码的代码，Hook 会直接拦截：
```bash
# 修改代码加入 password = "123456"
git add .
git commit -m "test: trigger harness check"
# 预期输出：❌ [AI Harness] ... 发现明文赋值密码 ...
```

## 🛡️ 四层架构说明

| 层级 | 文件 | 作用 |
| :--- | :--- | :--- |
| **约束层** | `AGENTS.md` | 告诉 AI"能做什么/不能做什么"。AI 启动时自动读取。 |
| **校验层** | `.pre-commit-config.yaml` | 开发者提交代码时，自动跑 Lint 和自定义脚本，拦截幻觉代码。 |
| **执行层** | `config/harness.yaml` | 限制 AI Agent 的 JVM 参数与危险命令。 |
| **监控层** | `.github/workflows/ai-check.yml` | PR 合并前，CI 强制跑完整测试与覆盖率。不达标，不准合入。 |

## 💡 常见问题

**Q: 为什么不用 Maven 跑 pre-commit？**
A: `mvn checkstyle:check` 启动 JVM 太慢。Pre-commit 需要毫秒级响应。重型检查交给 CI。

**Q: AI 还是写出了违规代码？**
A: 检查 `AGENTS.md` 是否放在了项目根目录。部分 IDE 需要重启项目才能重新读取规则。

## 📄 License

MIT License. 欢迎 Fork 并应用到你的团队项目中。

欢迎关注微信公众号[AI提效随笔]，更多精彩内容期待你的关注。