From Vibe Coding to Harness Engineering: Controlling AI‑Assisted JDK Upgrades

Why AI Coding Needs More Than Code Generation

AI coding tools have evolved from simple code completion to project‑level assistants, yet most real‑world engineering effort is spent on maintenance tasks such as framework migration, version upgrades, and security patches. The difficulty lies not in writing new code but in making changes that are safe, stable, and compliant with existing project constraints.

Challenges of a JDK Upgrade

Upgrading from an older JDK to JDK 21 appears to be a simple version bump, but it triggers a cascade of changes across the Spring framework, third‑party dependencies, compiler plugins, JVM parameters, startup scripts, and test suites. Missing any of these can prevent the service from starting.

From Vibe Coding to Harness Engineering

Vibe Coding gives AI freedom to modify code, which often leads to uncontrolled changes. Harness Engineering instead defines clear boundaries and processes before AI acts, similar to providing a construction blueprint rather than a vague instruction.

Three Pillars of Harness Engineering

Execution Constraints – Define what AI may change and what it must not. Example constraints include:

## Core Constraint Specification
> **All upgrade actions must obey the following rules**
1. **Do not modify business logic code**
2. **Do not refactor or optimise business methods**
3. **Do not add new features**
4. **Do not delete existing functionality**
5. **Do not change API input/output signatures**
6. **Only perform compatibility changes required for JDK 21 + Spring Boot 3.5.3**

Knowledge Context Construction – Capture hidden expert knowledge (e.g., files generated by Thrift, required Maven parameters like -Plocal, or JVM start‑up scripts) into a structured specification that AI can consume.

Feedback Loop – After each step, run verification (unit/integration tests, compile checks) and feed results back to the AI so it can correct mistakes before they propagate.

Tool Orchestration Layer

Each engineering action (dependency scanning, conflict resolution, integration testing, result parsing) is wrapped as a tool with explicit input, output, and failure paths. AI only decides which tool to invoke, ensuring stable behavior for each well‑defined operation.

Skill Definition – The jdk-upgrade Skill

The upgrade process is encoded as a reusable skill with clear steps and constraints:

### Step 1 — Maven Plugin Upgrade
**Goal**: Enable JDK 21 compilation and JUnit 5 testing.
- Upgrade <code>maven-compiler-plugin</code> to >= 3.12.1, set <code>source/target=21</code>
- Upgrade <code>spring-boot-maven-plugin</code> to 3.5.3
- Upgrade <code>maven-surefire-plugin</code> to >= 3.2.5

### Step 2 — Pom Dependency Handling
**Goal**: Migrate from javax to Jakarta EE.
- Remove <code>javax.annotation-api</code>, <code>javax.validation:validation-api</code>, <code>junit:junit</code>
- Replace <code>javax.*</code> with <code>jakarta.*</code>
- Upgrade <code>spring-boot-starter</code> to 3.5.3, <code>lombok</code> to >= 1.18.32

### Step 3 — JVM Parameter Adjustment
**Goal**: Drop deprecated flags and add module‑system / new GC options.
- Remove all CMS‑related and PermGen flags
- Add <code>--add-opens</code> module permissions and G1GC/ZGC flags

### Step 4 — Code Compatibility Changes
**Goal**: Eliminate <code>javax.*</code> references and migrate tests to JUnit 5.
- Replace package names (e.g., <code>javax.annotation → jakarta.annotation</code>)
- Convert <code>@Before/@After</code> to <code>@BeforeEach/@AfterEach</code>
- If compilation fails, revisit Steps 1‑4

### Step 5 — Verification
- <code>mvn clean compile -pl <module></code>
- <code>mvn test -pl <module></code>
- On test failure, analyse reports and repeat fixes

Standardized Execution Flow

The skill is split into five explicit steps, each ending with a verification checkpoint that forms the feedback loop. This prevents error propagation and makes the upgrade process repeatable.

Experience Back‑Propagation

After a successful upgrade, the AI automatically generates a jdk-upgrade‑lessons hook that summarizes obstacles, hidden traps, configuration omissions, dependency conflicts, and code migration quirks. The hook creates a structured document ( SKILL.md) and a new versioned skill (e.g., jdk-upgrade-21) for future upgrades.

Quantitative Results

In a typical project the upgrade touched 30+ files, 50+ dependencies, and numerous configuration and start‑up parameters. AI performed the majority of analysis, planning, code changes, compilation, and error fixing; developers only performed final code review. Metrics after upgrade:

CPU usage reduced by ~22.5% on average.

Heap memory reduced by ~23% under the same load.

GC pause time dropped below 1 ms per minute.

P99 latency improved by 18.1% (max reduction 47%).

Peak QPS increased >30% at 60% CPU load.

Approximately 70% of projects completed the upgrade in a single AI‑driven conversation; the remaining 30% required a few manual interventions at critical checkpoints.

Key Takeaways

Structured constraints become more valuable than raw code; they enable AI to act safely.

Documentation’s primary audience shifts from humans to AI, so it must be machine‑executable.

Developers transition from code writers to constraint designers, focusing on “what may be done” rather than “how to code it”.

The same Harness Engineering methodology can be applied to framework migrations, security fixes, and dependency governance, turning AI from a one‑off assistant into a sustainable engineering productivity engine.