Harness Design for Productive AI Coding Agents
A harness gives AI coding agents context and verification rules: CLAUDE.md, Rules, handovers and quality gates for long-running projects.

TL;DR
A harness is the system of context files, rules, handovers and automated checks that guides an AI coding agent. It helps preserve project knowledge between sessions and catch deviations before code is accepted.
What Is a Harness?
When you work with an AI coding agent, you have a problem: the agent has no memory between sessions. Session 1 and session 100 start with the same knowledge. The agent knows neither your architecture, nor your conventions, nor the mistakes it made yesterday.
A harness is the solution. It's all the files and systems that give the agent the necessary context at every start. Think of it as an onboarding package for a new developer, except that developer starts fresh every day.
In my case, the harness consists of four layers:
- CLAUDE.md: The main document. Commands, stack, architecture decisions.
- Rules: Rule files defining specific standards.
- Memory: Persistent information that applies across sessions.
- Session Handovers: Handover documents passing state between sessions.
Layer 1: CLAUDE.md as the Main Document
CLAUDE.md is the first thing the agent reads. It must be short, precise, and current. In my project, it contains:
- Commands:
bun dev,npm test,tsgo --noEmit. The agent needs to know how to verify the code. - Stack: Next.js 16.2.1, React 19, TypeScript 5.9, Tailwind 4. No guessing.
- Architecture: Three Supabase client patterns (Browser, Server, Admin). Who uses what when.
- Quality Gate:
tsgo --noEmit && bun run build && npm test. Before every deploy.
A common mistake: CLAUDE.md gets too long. Stuffing everything in, 500 lines. The agent skims it and forgets half. My solution: stay under 100 lines. Everything detailed lives in the Rules.
Layer 2: Rules as Domain-Specific Standards
Files in .claude/rules/. Each covers exactly one topic:
error-handling-catch.md: No.catch(() => {}). Every catch must log.api-response-consistency.md: All API responses viaapiResponse.*(). No rawNextResponse.json().test-colocation.md: Tests belong in__tests__/directories next to the source.voice-consistency.md: First-person "I" perspective, no "we" on the website.content-writing-standards.md: No em-dashes. No AI buzzwords.
The key: each rule contains not just the rule, but also anti-patterns and correct examples. An agent that only reads "Use apiResponse" still makes mistakes. An agent that sees a concrete WRONG and CORRECT example makes the right decision.
Layer 3: Session Handovers as Memory Bridges
After every session, I write a handover document. Each handover contains:
- What was done (commits, changes)
- What's open (open issues, known bugs)
- Next steps (prioritized)
The next session's agent reads the handover and immediately knows where to start. Without handovers, the next session could start from zero and redo completed work.
Layer 4: Automated Quality Gates
Humans forget things. So do agents. That's why I automate everything that can be checked:
- TypeScript:
tsgo --noEmit. 0 errors as baseline. Non-negotiable. - Build:
bun run build. Missing translations, broken imports, everything surfaces here. - Tests: Regression tests for the relevant behavioural contracts.
- Content checks: Automated checks for em-dashes, AI buzzwords, i18n parity, CTA repetitions.
- ESLint: Custom rules against
console.log(PII leak prevention) anderror.messagein responses (SEC-015).
The quality gates run before every deploy. The agent cannot deploy without all checks being green.
Common Failure Modes Without a Harness
Examples of what can happen without a harness:
Context Drift: Session 50 starts using patterns that session 30 already replaced. Without rules, there's no reference for what's "current."
Hallucination Accumulation: The agent invents a function that doesn't exist. Without quality gates, this only surfaces in production.
Architecture Erosion: Each session makes small deviations. After 20 sessions, you have five different error-handling patterns in the same project.
Repeated Mistakes: The agent makes the same mistake as 10 sessions ago. Without feedback memory, there's no learning effect.
What Worked in the Project
A few patterns that proved themselves. These lessons connect directly to the broader journey from prototype to shipped product, something I wrote about in From 250+ Prototypes to Product.
-
SSOT files for everything that can change. Prices, biographical facts, service definitions. One file, one truth. The agent doesn't invent, it looks up.
-
Composable middleware instead of copy-paste.
withErrorHandler(),withAdminAuth(),withRateLimit(). Three wrappers that combine freely. Less repeated code across routes. -
Rules with "why." Not just "Use apiResponse." But: "Because raw NextResponse.json() produces inconsistent error shapes and breaks the tests." Agents that know the "why" apply rules correctly even in edge cases.
-
Feedback memory as a learning loop. When the agent makes a mistake and I correct it, I save that as memory. Next session: same mistake doesn't occur.
The Harness Grows With the Project
A CLAUDE.md can grow into a system of rules, handovers, memory and automated quality gates.
The harness isn't a project you set up once. It grows with every problem you solve. Every mistake that occurs twice becomes a rule. Every architecture decision that needs context becomes an SSOT document.
Conclusion
AI coding agents are tools. Like any tool, the result depends on how you use it. The prompts are the obvious part. The harness is the invisible one. And often the decisive one. If you are building custom AI systems and want the engineering to be production-grade from the start, see my way of working for how I approach this kind of work. If you want to build subagents, skills, and hooks like these yourself: that's exactly what I teach, step by step, in Claude Code Capabilities.