I Built a Harness to Build a Harness. One of Them Worked.

2026-07-06T00:00:00+00:00

Here is the number I keep not saying out loud: 78.

That's how many numbered documentation files I wrote to build Context Harness</a> — 13 product requirements docs, 23 architecture decision records, 15 specs, 9 design docs, 18 runbooks — plus five policy documents governing them, plus six AI agents whose only job is to help write more. For a project with one developer. Me.

And when I went back through the git log to write this, the surprise was that the harness worked. I used it — the doc pipeline, the six agents, the whole apparatus — to build the engine feature by feature, and the commits show the seams. That part isn't the confession.

Context Harness works. It's a local-first RAG engine in Rust: ingests your files, chunks and embeds them, serves hybrid search</a> to any AI tool over MCP. Single binary, six build targets, brute-force cosine similarity</a> that clears 10,000 chunks in single-digit milliseconds. I'm not being falsely modest about the engineering — it's real. Forty strangers starred it</a>; a couple hundred people pulled the release binaries across eight versions. What I can't point to is one person — myself very much included — who has aimed it at a problem that wasn't itself. Months on, the only corpus it has really indexed is its own source code: a tool built to hand your context to an AI, whose only context has ever been itself. Stars are interest, downloads are curiosity, and neither is a job.

So before I write four more posts about "harness engineering," here's what I'm actually holding: a harness that did its job — it built the engine — and an engine still waiting for one of its own. Both real. One proven, one not. The gap between them is the whole series.

The word everyone's using and nobody defines the same way</h2> "Harness engineering" arrived fully formed sometime this spring, the way these things do. Rob Earlam wrote a genuinely good five-part series</a> building his own website with an agent pipeline — a Product Owner agent hands to a Design agent hands to a Tech Lead hands to Build hands to QA, an Orchestrator reading a run-state.md</code> between them. It's clean, it's sequential, and if you've ever shipped software you'll recognize the shape immediately: it's the SDLC, staffed by robots.
Meanwhile the phrase itself has at least three parents. Mitchell Hashimoto</a> describes engineering the harness as a habit: any time the agent makes a mistake, you take the time to fix its environment so it can't make that mistake again. LangChain, in "The Anatomy of an Agent Harness"</a>, gave us the tidy equation Agent = Model + Harness — "if you're not the model, you're the harness." And Birgitta Böckeler, on Martin Fowler's site</a>, frames it as a cybernetic governor — feedforward guides that steer before the agent acts, feedback sensors that catch it after — a steering loop, not a one-pass pipeline.
Everyone cites the same kind of stat: hold the model fixed, change only the harness, watch the score jump. The cleanest one I can actually source is LangChain's — same model (gpt-5.2-codex</code>), harness-only changes, 52.8% to 66.5% on Terminal-Bench 2.0</a>, enough to move from outside the top 30 to the top 5. The more dramatic one making the rounds — 42% to 78%</a> — is real too, but it's Claude Opus 4.5 on scientific-reproducibility tasks, and by the time it reaches the LinkedIn post it's lost the part where that isn't the coding you do all day. I'll wave the numbers around like everyone else. I'll also tell you I've never reproduced them, and neither, probably, have you.
What I notice about all of it: it's triumphant. The scores only ever go up and to the right; the pipelines are always clean. Nobody in this literature is holding 78 documents and an engine whose only real user, so far, is itself.
What the harness actually was</h2> Strip the grandeur and here's the machine. Five directories, each a level of authority: docs/prd/</code> (what to build and why), docs/adr/</code> (why I picked an approach), docs/spec/</code> (exactly how it behaves — the contract), docs/design/</code> (thinking out loud, non-authoritative), docs/runbook/</code> (how to operate it). Every file numbered NNNN-kebab-title.md</code>; every directory fronted by a 0000</code> policy that governs the rest. Then six agents — one per layer, plus a coordinator — and here's the part that matters: they don't run anything. A Context Harness agent is a Lua script that generates a prompt and then stops. It never calls a model. Invoke spec-writer</code></a> and it prints exactly what it would hand one: ❯ ctx agent test spec-writer --arg feature="hybrid search API" Agent: spec-writer Source: lua (agents/spec-writer.lua) Tools: search, get System prompt (2343 chars): You are a Spec Writer for Context Harness. Your job is to write authoritative specifications that conform to the Spec Policy. ... ### When to Write a Spec PREFERRED: Implement the feature first, then write the spec describing actual behavior. ... Tools override: search, get Resolved in 239ms </code></pre> In 239 milliseconds, without calling a model once, it did three things. It assembled that 2,343-character system prompt — the whole spec policy, inlined, down to no "could," no "might." It ran a hybrid search over everything already indexed (three queries: the feature, spec <feature></code>, <feature> behavior</code>), deduped the hits, sorted them into existing specs and related docs, and pre-seeded them as context — here's what already exists; get</code> the full text before you write. Then it handed back the prompt, a scoped toolset (search</code>, get</code>), and that retrieved context — and stopped. Whatever model is driving your editor does the actual writing. The doc-coordinator</code></a> sits on top and is even more hands-off. Give it a feature and it searches all five layers, reports what exists and what's missing, and emits an ordered plan — write this PRD, then this ADR, use spec-writer</code> for the contract. Its own instructions state the boundary in one line: "You coordinate but do not write docs yourself." So the real output was never the documents. It was a prompt with the right context already loaded into it — produced deterministically, handed to a model the harness doesn't own. Assemble context, borrow the model. Hold that thought; it turns out to be the entire thesis of this series, and I shipped it as a side effect before I had the words for it. What the machine emitted in the end: 78 numbered documents</a> and a RAG engine that conforms to them. ADR-0015 is a representative specimen — status, context, decision, five numbered principles, alternatives, consequences. Multiply by 78. It is, and I mean this, a genuinely handsome pile of documents. And I did point it at real work — its own. A checked-in config/ctx.toml</code></a> aims the connectors at Context Harness's own ./docs</code>, its ./crates/**/*.rs</code>, and its README, registers all six agents, and opens with a single instruction: # Run from repo root: ctx sync all && ctx serve</code>. The harness indexed the codebase it was building and fed that back to the agents building it. You can watch it in the log — design: multi workspace routing design</code>, then feat: multi-workspace MCP router</code> two days later; feat: sync progress on stderr (design from SYNC_PROGRESS.md)</code> — 145 commits across four months, design turning into features. So when I say the harness is unproven, I don't mean it didn't work. It worked. I mean the engine it built never got aimed at anyone else's problem. How it works: driving it from Claude Code</h2> The agents aren't a CLI party trick — they're served over MCP, so the editor drives them. Install ctx</code></a>, start the server, and point Claude Code at it: ctx serve mcp # search + the six agents, at 127.0.0.1:7331/mcp claude mcp add --transport http context-harness http://127.0.0.1:7331/mcp </code></pre> Type /mcp</code> in Claude Code and the server's capabilities show up split into exactly the two halves from a moment ago. The agents are MCP prompts — you fire them deliberately, as slash commands like /mcp__context-harness__spec-writer</code>. The search</code> and get</code> are MCP tools — the model reaches for them on its own, mid-thought, as mcp__context-harness__search</code>. Prompts are yours to invoke; tools are the model's to call. That split is the entire design in one line. Here's a feature going through it, the way the multi-workspace router actually did. You start at the top, with the coordinator: /mcp__context-harness__doc-coordinator "multi-workspace routing" </code></pre> It hybrid-searches all five doc layers, tells you what exists and what's missing, and hands back a plan — write a PRD, then an ADR, lock the contract with spec-writer</code> — then stops, because it coordinates but does not write. You work the plan by firing the writers it named, one at a time. Each drops a fully-loaded starting point into the chat — the policy inlined, plus the existing docs it retrieved — and from there the model in Claude Code does the writing, calling search</code> and get</code> itself to pull the full text of anything it needs. Then you implement against the spec and commit. design:</code>, then feat:</code>. The trail in the log isn't an accident; it's the shape of the pipeline. The feature-building loop, driven from Claude Code — you fire the agents (prompts), the model does the work, and the harness only plans and retrieves.</figcaption> </figure> Notice what Context Harness never does in that loop: run a model. It plans, retrieves, and assembles; Claude Code brings the intelligence. Assemble context, borrow the model — the same four words as before, except now you can watch them run. It borrows something else, too: the control loop. Three different things get called "orchestration," and it's worth being precise about which one is happening here. The loop — a model calling tools in a cycle toward a goal — is Claude Code's, not the harness's.</li> Subagent orchestration — one agent autonomously spawning and coordinating others (Claude Code's own sub-agents; Rob's Orchestrator firing PO → Design → Build → QA off a state file) — the harness doesn't do at all. The doc-coordinator</code> hands you a plan; it can't fire the writers itself, because MCP prompts are user-invoked and the model can't chain them.</li> What Context Harness does is neither: it's a human-fired context-and-plan injector into someone else's loop. You're the orchestrator; the harness just makes sure each step starts with the right context already loaded.</li> </ul> Whether that's a limitation or the whole point — whether autonomous orchestration earns its keep, or "read the plan, fire the next command" is the boring thing that wins — is a post later in this series. For now the split is clean: the harness assembles the context; the loop and the orchestration are borrowed. I did microservices to myself</h2> Now set my machine beside Rob's. His: a Product Owner agent handing to Design handing to Tech Lead handing to Build handing to QA, an orchestrator shuttling between them. Mine: a coordinator that plans and delegates to single-purpose writers, one per layer. Same shape. We each took a process, chopped it into specialized agents, and wired them to an orchestrator. We built microservices. Not literally — but the instinct is identical, and so is the failure mode. Remember how that went? For about five years the industry believed the answer to every architecture question was "more, smaller services." Then everyone counted the operational cost of all that wiring — the network calls, the distributed failure modes, the sheer ceremony — and quietly retreated to the majestic monolith</a>. Start with the monolith</a>; extract a service only when something concrete forces you to. Most teams that went services-first paid for it. The field didn't land on "it depends, it's all just taste." It developed a spine: a boring default, with an opinion attached. And I think harness engineering is going to travel the exact same arc. Right now we're in the services-first phase — everyone's building elaborate multi-agent pipelines because decomposition feels like rigor. In a couple of years the default will be boring: one capable agent, good context, and a small amount of plumbing that nobody finds impressive. The harness that wins will be the one you can't demo. I have proof this is already happening, because it happened inside my own repo. My spec-driven-development ADR</a> is emphatic: we program to the spec — the implementation conforms to the spec, and the spec is never updated to match the code after the fact. Very rigorous. Very impressive. And then, three principles down in the very same document, the preferred workflow turns out to be: implement first, then write the spec. The ceremony and the pragmatism are sitting side by side, and the pragmatism already won. I just hadn't noticed I'd written down the fight and its outcome. Where I might be wrong</h2> The honest counter to "it deflates into plumbing" is one word: Kubernetes. Kubernetes did not get simpler. It got abstracted. The complexity is all still there — it just moved behind a managed platform you rent, and the "boring default" turned out to be enormous and someone else's problem. That's the other arc this could take, and there are companies betting hard on it right now: LangChain</a>, Databricks</a>, and everyone else selling a managed harness where the orchestration lives in their cloud and you stop thinking about it. So maybe I'm wrong. Maybe the harness doesn't deflate; it gets rented. The signal I'm watching for is which one becomes invisible first — the plumbing, or the platform. If in two years the interesting work is choosing which harness vendor to lock into, the monolith people lost. If it's a boring config file in your repo that you barely think about, I was right. I genuinely don't know yet, and I'd rather tell you that than pick the ending that flatters my thesis. Would I build it again? Yes. Was most of it ceremony? Also yes.</h2> Both are true, and holding both is the only honest position. I would write the specs again — the act of stating what the system should do, in language that forbids "might" and "could," caught real design mistakes before they cost me anything. But if you made me bet, maybe three of those 78 documents are why the project didn't collapse into mud, and the other 75 I performed because ceremony feels like progress. Figuring out which three is the actual point of this series. Not "here's my framework, adopt it." I don't trust anyone who's that sure this early, including the version of me who wrote 78 files. The nail</h2> Here's the part that took me embarrassingly long to say plainly. I don't have a "team context problem" or a "knowledge management problem." Those are euphemisms, and they smuggle in a lie — that the cupboard is bare. It isn't. At work I have real pieces. A registry of reusable skills and agent rules a model can discover on demand over MCP. A hard-won framework for building systems that check the model instead of trusting it — that treat it as an advisor to be verified, not an authority. Both genuinely AI-native. And they don't compose. The skills live in one place; the principles live as a thousand-line design document in another; neither travels. An engineer starting in a different repo can't ask "how do I apply this here?" and get a usable answer — they go find the document, read the whole thing, extract the idea, and re-translate it by hand, in whatever editor they happen to be in. The knowledge is either too welded to the system that birthed it to reuse, or too abstract to apply. A CLAUDE.md</code> in one repo is great — for that one repo. It composes across exactly none of the others. So what I want is a declarative harness for day-to-day development: reproducible, transparent, portable across whatever editor I'm using this month — Cursor, Claude Code, whatever ships next — where a hard-won principle becomes a discoverable skill that travels across repos, and "give the agent cross-repo awareness" does not mean pasting every repo's markdown into the context window until it's full of text and short on attention</a>. In the meantime, what I actually run is duct tape: one CLAUDE.md</code> at the root above all my repos, a wiki, an Obsidian vault. It works — I think. I can't prove it. The only number I can put on it is token spend, which is high, because the whole approach is concatenation: shovel the context in and hope the model reads the right part of it. "The invoice went up" is not the same as "the work got better," and the distance between those two is the honest state of the art. The elaborate harness did its one job — it built the engine — and went quiet. The boring one I lean on every day, and still can't measure. Say that requirement out loud and the redemption is obvious: cross-repo awareness without dumping everything into context is retrieval, not concatenation. Which is the one thing the engine I shelved actually does. I built a retrieval harness, wrote it off because it had no job outside itself, and the whole time it was standing next to the job. So maybe you have the job. It's the same wiring as above — except this time you point ctx.toml</code> at your repos, the several that don't know about each other, and ctx sync all</code> collapses them into one index. Now the model in Claude Code can search</code> and get</code> across all of them, retrieved on demand instead of pasted: your cross-repo context on tap, without shoveling it into the window. It's open source</a>, the docs</a> are thorough, and I'd genuinely like to hear from anyone who finds the deployment I haven't. The bet — and it is a bet, not a conclusion — is that Context Harness stops being a search box and becomes the thing that self-hosts the harness: the agents, the roles, the workflow, backed by a knowledge base you build once and carry with you. The doc-writing agents it already ships are the proof of concept; the missing piece is making that harness portable and its knowledge base buildable and sideloadable — the same substrate underneath Cursor today, Claude Code tomorrow, whatever ships next, local-first and inspectable, not rented from a cloud. That's the thread the rest of this series pulls on. Not a competing editor: I have no interest in fighting Anthropic and Google over the surface, and it's the wrong altitude anyway. The plumbing is the bet — in the prediction, and in what I'm building. Whether it works, I'll find out in public. There's an honest chance that MCP</a> carries context and tools but not the control loop — no primitive in the spec owns the agent's orchestration; that lives in the host — in which case "portable harness" is really "portable context, borrowed orchestration," and I'll say so when I hit that wall. That's the deal for this whole series: real receipts, real numbers, and the parts where I was wrong or just performing rigor, on the record. Next: what retrieval actually buys you, and the specific moments it's slop in, slop out. — Parker Jones

Parker Jones Dev Blog - context-engineering

I Built a Harness to Build a Harness. One of Them Worked.