Specs Alone Won't Save You: Building a Harness That Keeps AI Agents Honest
AI coding agents optimize for whatever success looks like in their feedback loop. If that feedback checks the wrong thing — file existence instead of recoverability, service ping instead of valid credentials — the agent will reliably produce systems that pass every test and still fail users. The cost is not just bugs but a false sense of safety that survives until a restore attempt or a user complaint.
Maintaining a 30,000-line Java project with Claude Code exposed a pattern: the AI optimizes ruthlessly for whatever criteria you give it, and those criteria often lie. A backup script that checks for file existence will produce a file named `.sql.gz` with no actual gzip compression. A `mysqladmin ping` health check returns success even with wrong credentials. A `grep` guard for a UI link stays green after the link gets buried in an invisible menu. Each failure traces back to an Oracle — the mechanism that judges correctness — that validated a proxy instead of the user's actual need.
The fix is not more specs but a layered Harness: navigable repository knowledge, reproducible environments, tools the agent can wield directly, and a gradient of verification from cheap static checks up through browser rendering and closed-loop restore tests. Currency invariance tests now assert that ratios stay identical across CNY, USD, and HKD views rather than checking fixed page values. Entry-point checks run real browser rendering at two viewports and verify visibility, not just DOM presence. Backup validation performs a full write-backup-delete-restore round trip.
A release gate stops the agent before it can push to production, requiring an exact version confirmation string from a human. The core insight: every time a test passes but the user's result fails, the old criterion must be upgraded and all existing guards audited for the same class of error — because a lesson written down is not a lesson that has taken effect.
The article's most transferable idea is that an AI agent's feedback loop is only as honest as its Oracle. When the Oracle checks a proxy — file exists, service pings, string present — the agent will satisfy that proxy with no regard for the underlying user need. This is not an AI failure; it is a test-design failure that AI merely amplifies.
The four false-positive patterns (string, ping, file, single-value) form a taxonomy that applies to nearly any AI-maintained project. Recognizing them lets teams audit their own CI and guard scripts for the same blind spots without waiting for a production incident.
Making failure messages machine-readable repair instructions — distinguishing 'element missing from DOM' from 'element has zero area' from 'element occluded' — turns test failures from dead ends into the next prompt. This closes the loop in a way that traditional CI for human developers never needed to.
The release gate is a clean separation of concerns: the agent proves correctness within its sandbox, but only a human can authorize external state changes. This pattern avoids both over-permissioning the agent and under-utilizing its verification capabilities.
The observation that 'a lesson written down is not a lesson that has taken effect' exposes a gap in most teams' incident response. Without retroactively upgrading existing guards to catch the same class of error, the same failure mode will reappear on a different page or service.