Halfcycle is a module that runs a five-layer build method inside your own Claude Code or OpenAI Codex (npx halfcycle).
A coding agent is a model plus a harness. The model writes the code. The harness is everything around it: what the agent is told, what it is allowed to touch, what checks its work, what it remembers, and who decides it is finished.
Harness engineering is the practice of building that second part on purpose. The term caught on because teams kept noticing the same thing. Swap in a better model and the results improve a little. Change the harness and the results change a lot. On one public benchmark, the same model scored noticeably higher inside one harness than inside another, with nothing else different.
So the question for a team is no longer which model to use. It is what surrounds the model, and who maintains it. This piece goes through what a working harness is made of, part by part, what each part needs from the others, and how to tell a working harness from a pile of plugins.
The loop every harness runs
Every coding agent, whatever it is called, runs the same loop. The harness assembles what the model sees. The model decides on one action: read a file, edit one, run a command, hand work to another agent. The harness carries the action out, or refuses it. The result goes back into what the model sees, and the loop goes round again until something decides the work is done.
That last part is where most of the engineering lives. A model will happily declare victory. The harness is what decides whether it gets to.
Look at the loop and the seven parts fall out of it. Something has to choose what goes into the model's view each turn. Something has to say what the work is before the loop starts. Something has to sit between the model's decision and the action, and something after it. Something has to read the finished work with fresh eyes. When more than one loop is running, something has to keep them apart. And something has to carry what was learned in one run of the loop into the next.
The seven parts
1. Instructions sized to the step
The agent needs to know what you are building and what step it is on. It does not need your whole wiki pasted into every session. Too little context and it guesses. Too much and the important line is buried under the unimportant ones, and models pay less attention to the middle of a long context than to its ends.
The usual failure is a single instruction file that grows a line every time something goes wrong, until it is thousands of words of rules the agent mostly skims. The fix is not a better file. It is serving the right slice at the right moment: the plan when planning, the feature's spec and the rules it must keep when building, the checklist when reviewing. This part is what most people now call context engineering.
2. A written plan before any code
What the product is for, how it is put together, what each feature must do, written down with acceptance criteria someone can check. This is spec-driven development. Without it the agent fills every gap with a plausible guess, and plausible guesses are expensive to find later, because the code around them looks finished.
A plan an agent can build from has layers. The product plan says what is in and what is out. The architecture says what the parts are, how they talk, and which rules hold everywhere. The phase plan says which features ship together and in what order. Only then does a feature get its spec. Skip the upper layers and every feature spec is sensible on its own and inconsistent with the next one, which is a very common way for an AI-built product to fall apart around its fourth feature. We went deeper on this in spec-driven development with AI coding agents.
3. Limits that act before the mistake
Some actions should simply not happen: editing outside the agreed area, deleting work that was never saved, rewriting shared history, reading credentials, publishing. A rule in a prompt is a request. The model weighs it against everything else in its context and, most of the time, complies. A hook that refuses the action is a limit. It runs outside the model, so it does not depend on the model remembering.
The trade-off is false alarms. A limit that interrupts constantly gets switched off, and then it protects nothing. So a limit has to be tried against real traffic before it is trusted. When we replayed 68,843 real agent actions through Halfcycle's limits, they stopped to ask the person 12 times. This is the part people mean by guardrails.
4. Checks that run on what was written
Tests the agent did not get to mark as passing itself. Lints that were proven to work by breaking them on purpose once. Something that runs after each edit, not once at the end.
Two habits separate checks that work from checks that only look as if they do. First, a test has to fail before the code exists and pass after it. A test that has never failed has never been shown to test anything, and agents are very good at writing tests that pass against whatever they just built. Second, every check should be seen failing on purpose before it is trusted. A lint that quietly stopped matching anything months ago reads exactly like a lint that finds nothing wrong.
5. A reviewer who did not write the code
The agent that wrote a change is the worst-placed reader of it, for the same reason a person is. It already believes the code does what it meant. A second agent with fresh context and no stake in the work finds things the first one walks past.
Two details decide whether review earns its cost. The reviewer needs something to review against, which is the spec; without one it reviews style. And each finding needs an outcome. A finding that is listed and never answered is noise. Each one should end up fixed, declined with a reason, or deferred on purpose, and the work should not count as done while one is open. When two rounds of review fail on the same task, the right move is usually not a third attempt but a fresh look at why: the spec was wrong, the order was wrong, or the task was too big.
6. More than one agent, coordinated
Larger work splits into tasks with dependencies between them. Some can run side by side, each in its own copy of the code so they do not collide. Something has to decide what runs next and put the pieces back together.
The rule that matters most is a boring one: two tasks that change the same file must not run at the same time, and the plan should say so before anyone starts. The second is that each worker reports in a fixed shape, what it changed, what it checked and what it did not, so the coordinator merges facts rather than summaries. Done badly, multi-agent orchestration produces the same mess faster, and in several places at once.
7. Memory that outlasts the session
What went wrong last time, and what fixed it. Without this, every session starts as a new hire on their first morning.
Memory has three reaches, and most setups stop at the first. Within a session, the context window is the memory, and it is gone when the session ends. Within a project, notes and a record of decisions carry over, so the agent does not re-argue what was settled last week. Across projects is the reach almost nobody has, and it is the one that compounds. We come back to it below.
Why one piece on its own does not hold
Most writing on harness engineering covers one of these parts well. That is useful, and it is also where teams get stuck, because each part depends on the others.
A reviewer with no spec has nothing to review against, so it reviews style. Checks with no plan test whatever the agent decided the feature was. Limits with no plan block the obvious accidents and none of the expensive ones. Orchestration with no independent review multiplies whatever the first agent got wrong across every worker. Memory with nothing feeding it stays empty.
The pieces are a system. Put three of them in place and you get some of the benefit and most of the maintenance.
That maintenance is the part nobody budgets for. A harness is software. Its hooks need updating when the agent's tools change. Its instructions drift as the project grows. Its checks need testing themselves, or one day they quietly stop checking. Teams that build their own usually find the harness has become a second product with no owner.
One size fits nobody
A harness that gives every change the same treatment fails in both directions. A full plan, spec and review cycle for a one-line copy fix is ceremony, and people stop following a process the week it wastes their time. A one-line note for a payments change is negligence.
So a working harness sizes the process to the change, from what the change touches rather than from how it was described. In Halfcycle that comes out as three paths. A small change runs in one session and is reviewed by an agent that did not make it. A change across parts that fits one short spec runs as a mini phase. Anything larger is a full phase, with its plan, its specs and a check of the whole at the end. The session says which path it chose and why, and a small change that turns out to cross parts is moved up.
A folder of documents cannot do this, because it cannot tell a two-screen internal tool from a payments integration. It hands both the same ceremony.
The part a homemade harness cannot do
There is one more property, and a team cannot build it alone however good they are.
A harness built in-house learns from one team's mistakes. When a project implementation goes wrong, the useful things to keep are the cause and the fix. Keep only the cause and you have a warning. Keep both and you have an answer.
If the harness is served instead of copied, both reach every other project automatically. From your side that gives two outcomes. Most problems of that kind never arrive on your project at all. The few that do arrive with the answer already attached, because someone else hit them first. And the list keeps growing, so a harness you copied last month is already behind.
What travels back from a project is the shape of a problem, never the code or the documents. We do not train on anyone's work.
How to judge a harness
Whether you build one or adopt one, these questions separate a working harness from a collection of parts. Ask them of anything you are considering, ours included.
| Part | The question to ask |
|---|---|
| Instructions | Does the agent get the slice it needs for this step, or the same long file every time? |
| Plan | Is there a product plan and an architecture above the feature specs, and is the code checked against them? |
| Limits | Are risky actions stopped by something outside the model, and how often does it interrupt for nothing? |
| Checks | Has each test been seen failing before it passed? Has each lint been seen catching something? |
| Review | Is the reviewer a different agent from the builder, and does each finding end with an outcome? |
| Coordination | Can two tasks that change the same file run at once? What does a worker report when it finishes? |
| Memory | Does a lesson from last week reach today's session? Does a lesson from another project reach yours? |
| Sizing | Does a one-line fix get the same process as a payments change? |
| Upkeep | Who updates the harness when the agent's tools change, and how do you know its checks still work? |
What Halfcycle is
Halfcycle is a harness that ships with all seven parts already working together. You run one command in your project, open it in Claude Code or OpenAI Codex, and say what you are building.
From there:
- Planning comes first. You are interviewed one decision at a time, then the product plan, the architecture and each feature's spec are written, with acceptance criteria. A separate agent reviews the specs before any code exists.
- The agent gets only what the current step needs, and is told what comes next, so nobody has to remember the order.
- Risky actions are asked about in plain words before they happen, by hooks rather than polite instructions. Checks run after edits, and those checks were themselves tested by breaking them on purpose.
- Tests have to fail before the code is written and pass after, and Halfcycle runs them itself.
- Work is split into tasks with their dependencies. Up to eight builder and reviewer agents run at once, each in its own copy of the code, and two tasks that would change the same file are not run together.
- Each task is reviewed twice by an agent that did not build it, first against what was asked and then for quality, and each finding is recorded with its outcome. At the end of a phase, an agent that built none of it checks each acceptance criterion in the plan, and another walks the delivered product before the phase can close.
- The process is sized to the change: a small change, a mini phase or a full phase, and you are told which and why.
- What went wrong and what fixed it is remembered across sessions and, through the method Halfcycle serves, across projects.
- A console on the web and your phone shows the progress, the phases, the system design and every agent at work.
The result is less rework and less time spent steering. You describe what you want, answer the questions that are genuinely yours to answer, and the rest of the team around your coding agent is already there.
Where it is not the right choice
Some honest limits, since you will find them anyway.
Halfcycle needs a connection, because the method is served and not stored in your repository. If you need to work fully offline, it is not for you today. It works with two coding agents, Claude Code and OpenAI Codex; OpenCode support is coming. You cannot yet plug your own hooks or presets into it. And if your work is one small script, a good set of instructions in a single file is probably all the harness you need.
For anything bigger, the question is not whether you need a harness. You do. It is whether you want to build and maintain one, or start with one that is already working and keeps getting better.
Getting started
npx halfcycle
Run that in the folder you want to work in, then open it in Claude Code or OpenAI Codex and say what you are building. Needs Node 20 or newer. There is nothing to learn first, and it tells you what is next when it is next.
Top comments (1)
The point about proving a check works by breaking it on purpose is the one most teams skip. In our own small product, the habit that paid off most was a real end-to-end check against the live site after each deploy: unit tests were green while a rarely rendered branch still threw an error for real users. Curious how the reviewer agent in your setup handles problems that only show up in the running product, not in the diff.