We Let Claude Code Refactor Our 200K-Line Java Monolith. Here's the Honest Result.

// Before (Java 11 era):
public class PaymentResult {
    private final String status;
    private final String transactionId;
    private final String errorMessage;

    public PaymentResult(String status, String transactionId, String errorMessage) {
        this.status = status;
        this.transactionId = transactionId;
        this.errorMessage = errorMessage;
    }
    // ... 40 lines of getters, equals, hashCode, toString
}

// After (Java 21 record):
public record PaymentResult(String status, String transactionId, String errorMessage) {}

It converted 67 POJOs to records, replaced 23 switch statements with switch expressions, and modernized 31 Optional usages (removing the Optional.get() calls that were landmines waiting to explode). Every conversion passed the test suite.

For this, it was genuinely better than a code review — it caught every instance, not just the ones in files you happened to open.

Architectural Decision Documentation

We asked Claude Code to write a CHANGELOG entry for every meaningful change. What we got was better than most human-written ADRs:

## [2026-08-14] Extracted AuditEvent to audit-trail module

**Moved:** `com.company.monolith.audit.AuditEvent` → `com.company.modules.audit.AuditEvent`

**Callers updated:** 23 references across 18 files.

**Breaking change:** The class is no longer in the monolith classpath. Any Spring beans 
in the monolith that directly autowire AuditEvent must now import from 
`com.company.modules.audit`. Updated affected beans in PaymentService, AccountService, 
CustomerService.

**Remaining concern:** TransactionService still uses AuditEvent via a deprecated utility 
method (AuditUtils.logEvent). This dependency is in scope for the next session.

That last paragraph — "remaining concern" — appeared consistently and accurately. The model knew what it hadn't finished and said so. That's more than I can say for many ticket systems.

What It Silently Broke

Now the part you actually came for.

Test Coverage Erosion

This was the most insidious failure. On day 3 of autonomous runs, all tests were passing — but our test coverage had dropped from 68% to 61%.

Claude Code wasn't deleting tests. It was moving classes while leaving test classes behind in the old package. Since the test classes still compiled (the old package still existed during the transition), the tests ran but now covered a class that was no longer in the primary codebase.

The verification script checked that tests passed, not that they covered the right code. We didn't catch this for 3 days.

Fix: Added a coverage gate to the verification script:

./mvnw test jacoco:report
# Fail if overall coverage drops below 65%
awk '/INSTRUCTION/ && /TOTALCOUNT/' target/site/jacoco/jacoco.csv | ...

Harder lesson: autonomous AI systems find the exact edge of your success criteria and stop there. If your definition of "correct" has a gap, the model will discover it — not maliciously, but because that's what optimization does.

The 16 Adapter Classes Problem

On day 5, a senior engineer reviewing the morning's diffs flagged something odd: 16 new classes had appeared with names like PaymentServiceCompatibilityAdapter, AccountRepositoryBridgeImpl, AuditEventLegacyWrapper.

These weren't in our design. The model had invented them.

Here's what happened: when Claude Code encountered a dependency it couldn't cleanly resolve (a circular reference, a class that served two modules), it created an adapter class as a bridge. The tests passed. The architecture check passed (the adapters were in a designated compat package we'd created for legitimate use cases).

But the adapters duplicated business logic. PaymentServiceCompatibilityAdapter had its own validation rules that were subtly different from the canonical PaymentService. When those two diverged (which they did, two weeks later), we had a production bug that took 4 hours to trace.

Fix: Added an explicit CLAUDE.md rule: "Creating any class with 'Adapter', 'Bridge', 'Wrapper', 'Compat', or 'Legacy' in the name requires explicit justification in the CHANGELOG. The default answer is: refactor instead of wrap."

Transactional Boundary Confusion

This was the most technically dangerous failure.

When extracting classes across module boundaries, the model sometimes removed @Transactional annotations that spanned what were now separate services. The tests didn't catch it because our test transactions were scoped per test — in production, calls that needed to be atomic now weren't.

// Before (correct — single transaction):
@Transactional
public void processPayment(PaymentRequest request) {
    PaymentResult result = paymentGateway.execute(request);
    auditService.log(AuditEvent.of(result));  // same transaction
    accountService.debit(request.amount());    // same transaction
}

// After (broken — Claude split these across modules):
// PaymentService (payment-processing module):
@Transactional  // only covers paymentGateway.execute
public PaymentResult processPayment(PaymentRequest request) {
    return paymentGateway.execute(request);
}

// Callers now responsible for atomicity — but weren't written to be

The model correctly identified that auditService and accountService were now in different modules. It correctly removed the cross-module @Transactional — that annotation genuinely can't span service boundaries. But it didn't flag that this was a design decision requiring human judgment, not a mechanical transformation.

We caught this in QA because a test for partial payment failure showed inconsistent audit state. In production, this would have been a compliance issue.

Fix: Added to CLAUDE.md: "If removing a @Transactional annotation, create a BLOCKING_ISSUE entry in CHANGELOG.md and do not commit. A human must review any transaction boundary change."

The Hybrid Model We Actually Shipped

After week 3, we stopped running fully autonomous overnight sessions. The failure rate on complex cases was too high and the failures were too subtle.

What we replaced it with — and what actually shipped — was a human-gated autonomous loop:

1. Engineer scopes the session — opens a GitHub issue describing exactly one refactoring task (e.g., "Extract CustomerProfile to customer-portal module")
2. Claude Code runs with plan mode — generates a plan, stops for review before making any changes
3. Engineer approves the plan — 5 minutes, not 30
4. Claude Code executes with the verification script — stops on any failure, documents blockers
5. Engineer reviews the diff — 15 minutes, not 2 hours
6. Merge or reject

This is slower than fully autonomous. It's still 4–5x faster than purely manual refactoring. We finished the extraction in 6 weeks rather than the estimated 4–6 months. The production bugs were zero.

The key insight: AI is fastest when humans define the boundary of each session narrowly. Open-ended autonomous runs exposed Claude Code to decisions it wasn't equipped to make. Tightly-scoped sessions with human gates at the boundaries — that's where the velocity is.

What Changes About the Senior Engineer's Job

The engineers on this project spent less time:

• Doing mechanical import updates
• Writing boilerplate class migrations
• Searching for every reference to a moved class

They spent more time:

• Reviewing plans before execution (critical path thinking)
• Writing better CLAUDE.md constraints (the AI is only as good as your specification)
• Designing verification scripts (defining "correct" in a machine-checkable way)
• Catching subtle failures (the @Transactional case required deep understanding of Spring's transactional model)

None of those second activities are junior work. They're the work that separates senior engineers from everyone else — and AI made that work more prominent, not less.

The engineers who struggled were the ones who wanted to hand the task off entirely and come back to finished code. The ones who thrived treated Claude Code as an exceptionally fast junior engineer who needs very clear scope and explicit constraints.

Numbers, Honestly

That one holdout? He's the one who caught the transactional bug in QA. He's right to be cautious.

What We'd Do Differently

1. Define "correct" before you start, not after you fail. Every gap in your CLAUDE.md is a gap in the output. Write the "what NOT to do" section first.

2. Coverage gates are mandatory. Tests passing is table stakes. Coverage delta is what tells you whether the tests are still testing the right thing.

3. Never let the AI make transaction boundary decisions. @Transactional spans, database schema changes, event ordering — these require human judgment. Add explicit blockers for these in CLAUDE.md.

4. Scope sessions to single classes or single extractions. "Extract everything" is not a plan. "Extract CustomerProfile and its 3 direct dependencies" is.

5. Review the CHANGELOG, not the diff. The model's own explanation of what it did is often clearer than reading 800 changed lines. Start there, then verify specific concerns in the diff.

Should You Try This?

Yes — with the hybrid model, not the fully autonomous one. The velocity gain is real and the failure modes are manageable once you know them.

The question isn't "can AI refactor our codebase?" It can. The question is "how do we design the human-AI collaboration so that AI handles what it's genuinely better at and humans handle what they're genuinely better at?"

Mechanical transformations at scale: AI. Architectural decisions that span module boundaries: human. Verification criteria: human. Execution within those criteria: AI. Review of anything involving transactions, security, or compliance: human, always.

That's not a limitation of the technology. That's what good engineering teams have always done — except now one of your team members can execute 200 changes overnight without getting tired or making typos.

If your team is considering a similar project, I'm happy to share the full CLAUDE.md template we used. Drop a comment or reach out directly — details in the footer.

Avaneesh Yadav is Engineering Manager at HashedIn by Deloitte. He leads AI-augmented engineering initiatives for enterprise clients and writes about production AI architecture at buildingai.in.