For a real software task, an agent's behavior never happens in isolation. It starts from a requirement or a user story, moves through understanding the intent, exploring context, editing code, and verifying the change, and only then produces a contribution someone can review. Looking at the session alone, you can see what the agent did, but it is hard to tell why those actions happened, or which of them actually made it into the final delivery.

So we began treating a single agent delivery as one continuous chain. Today, you only need to run this inside a project directory:

npx @qoder-ai/better-harness inspector

and you get a local, read-only Harness Inspector page that puts the project's agent sessions, file activity, and Git commits into one interactive view.

GitHub: https://github.com/QoderAI/better-harness

From a session to a complete delivery​

Harness Inspector started as a session-debugging tool: a way to see what an agent said, which tools it called, and which files it changed. But as sessions, file activity, and Git history got wired together, we realized the thing worth observing was not the conversation itself, but this:

How a software change starts from an intent, passes through an agent's execution, and ends up as an artifact that can enter the engineering system.

The session is only the middle of that chain.

The delivery chain: from intent to output​

We split a coding-agent delivery into three continuous parts with different boundaries:

• Intent is the semantic starting point of a change — a requirement, an Issue, a Spec, or an architectural constraint.
• Process is how the change actually unfolds. For an agent, that is mostly the session record and the searching, reading, editing, and verifying inside it.
• Output is the final result the agent delivers into the engineering system. For now, the clearest anchor is the code commit.

So Story, Session, and Commit are not three parallel abstractions. They are the observable objects of Intent, Process, and Output in today's software toolchain (intent may also appear as an Issue or a Spec depending on the context). What Harness Inspector does is not to render a conversation more completely, but to rebuild a traceable delivery chain from requirement to commit.

As a narrative it reads like a straight line. In a real project it looks more like an evidence graph: one Story may span several sessions, and one session may touch several commits.

A small example: from Story to Commit​

We published a read-only public sample on the Better Harness docs site (English demo data, no local content is read): https://qoderai.github.io/better-harness/inspector.

Looking at the session alone, you see a stream of search, read, edit, and test activity. It is hard to be sure it stayed anchored to the original requirement, and impossible to know which of those edits reached the repository. Looking at the commit alone, you see which files changed, but not how the agent understood the problem, built context, or verified the result before committing.

Put Story, Session, and Commit in one view, and the change finally becomes a reasonably complete delivery: the Story says why the change was needed, the Session shows how it happened, and the Commit records what was left behind.

Connecting requirement, agent behavior, and commit let us inspect a delivery as a whole for the first time. But once we opened a few real sessions with hundreds of tool calls, another problem showed up fast: being able to connect a delivery is not the same as being able to read it.

How Harness Inspector reads an agent delivery​

Around the Better Harness harness model, we define Harness Inspector like this:

Harness Inspector is a local, read-only workbench for agent deliveries. It brings requirements, agent sessions, file activity, and Git commits into one interactive view, so you can inspect why a software change happened, how it happened, and what it left behind.

Centered on a single complete delivery, it offers three ways to observe the chain from requirement to commit:

• Workbench — the relationships between requirement, session, and commit.
• Trace — the internal structure of a session.
• Replay — the task replayed in event order.

Put simply: Workbench for relationships, Trace for structure, Replay for order. Together they reconstruct how a requirement passes through an agent's understanding, exploration, editing, and verification into a reviewable commit.

Workbench: connecting intent, process, and output​

Workbench is the whole-delivery view. On the left is the user requirement that triggered the session, plus the goal refinements made along the way. In the middle is what happened during the session — searches, reads, tool calls, and Git operations. On the right are the commits observed within the current scope and the files they changed.

Its point is not to pile data together, but to show the relationships between requirement, process, and output that have actually been observed. When the evidence for a relationship is weak, Inspector keeps it as a candidate or leaves it unmapped, rather than auto-assembling a delivery path that only looks complete.

Trace: reading a session as a work trajectory​

Workbench helps you find a delivery; Trace expands the session inside it.

Inside a session, Trace organizes user input, intermediate responses, tool calls, and file activity by Turn, and connects their positions in time along the timeline at the top. Click a segment to jump to the corresponding call; consecutive repeated activity is folded so a flood of similar operations does not drown out the changes that matter.

Trace does not try to recover reasoning the model never exposed. It reorganizes the behavior that was recorded into a readable work trajectory, so you can inspect how the agent searched for context, edited code, and ran verification.

Replay: revisiting a delivery in event order​

Replay walks through the retained events step by step. A reviewer can move through user input, agent response, tool call, file, and commit in order, watching where the agent formed a direction and when it made and verified a change.

It is a read-only replay of evidence only. It does not rerun tools, restore the workspace, or resume the original session; where an exact timestamp was never recorded, it keeps order only and invents nothing that was not observed.

Workbench establishes the delivery context, Trace expands the session's work trajectory, and Replay restores the order of events. Together they turn a requirement-to-commit agent delivery into something you can enter and inspect layer by layer. And once a delivery reads clearly, we can return to the original question: which of the paths in this trajectory are actually worth keeping.

From delivery evidence to SKILL distillation​

Once a delivery can be seen clearly, we can go back to where we started: which experiences inside a session are worth distilling into a SKILL? Clearly not the most frequent tool call. An agent may reread the same file over and over because its context was thin, or retry a failing command repeatedly — behavior that is frequent but is more likely noise than reusable engineering experience.

What is worth keeping is usually a work path that recurs across similar tasks and is supported by the final output and verification result: how the agent scoped the change from the requirement, how it built the necessary context, and how it completed the edit, ran verification, and checked the result. Only by placing those actions back into their Story, Session, and Commit can we tell whether they were an incidental choice for this one task or a relatively stable way of working that transfers to others.

So automatic SKILL distillation is not summarizing one session into a new SKILL.md. It is recognizing stable patterns across many real deliveries, then giving each one its applicable scenario, context boundaries, execution steps, and verification method. What Inspector solves today is the most basic link in that chain: letting real deliveries leave behind bounded, inspectable evidence. Only on that foundation can we compare similar tasks, form SKILL candidates, and verify in later deliveries whether they actually improved how the agent works.

Closing: see the delivery first, then distill the experience​

What we set out to solve was how to recognize reusable work paths inside agent sessions. But once you actually dig in, a session can only record what the agent did — it cannot, on its own, explain why the task began, or prove which actions became an engineering artifact.

Harness Inspector reconnects requirement, session, file activity, and Git commit, making a single agent delivery observable, inspectable, and traceable. Only by seeing a delivery clearly can we judge which behavior was merely incidental and which path is worth distilling into a SKILL.

From session to delivery, and from delivery to distilled experience — that is the starting point of automatic SKILL evolution.

Drawing on how Better Harness is actually developed, this post walks through five engineering practices - spec-driven behavior, context orchestration, deterministic verification, behavioral evaluation, and the evidence loop - that move a plugin capability from "it works when I run it" to a software asset that is verifiable, maintainable, and safe to evolve.

Prologue: starting from Agent plugins​

Over the past three months, alongside designing the Canvas-based Agentic UI system, our other ongoing investment at Qoder has been building the Agent plugin ecosystem. From curating existing software-engineering workflow plugins in the community to creating plugins such as Architecture Visualization and Design Review, we have been trying to package capabilities that used to live scattered across different roles and different tools into something an Agent can discover and call.

In the Architecture Visualization plugin, for example, the Agent can render the dependency relationships between architecture modules directly on Canvas and share the result with teammates so they can understand the structure of the system.

At the beginning, a plugin felt mostly like an extension of the Agent's capability boundary: whatever was missing, we added a Skill, a tool, or a workflow for it. But as the plugins grew in number and complexity, another question surfaced:

How should these capabilities be maintained over the long run?

Building Better Harness made that question impossible to avoid. Better Harness targets workflow analysis and continuous improvement for coding agents, and it contains a core Skill, a large amount of JavaScript, reference material, evaluation logic, and adapters for different Agent hosts.

Once those capabilities became part of a plugin that has to be maintained over time, we realized the problem was no longer "how do I write a good SKILL.md".

What exactly is an Agent Plugin?​

If you are already familiar with Agent Plugins and Agent Skills, skip to the next section.

Put simply, an Agent Plugin is the delivery and distribution boundary of a capability, and a Skill is a unit inside it that an Agent can discover and execute independently. A typical plugin can contain Skills, MCP servers, hooks, and host-specific extensions at the same time:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json
└── com.example.client/
    └── hooks/

A SKILL.md is not the plugin itself; it is closer to an entry point for one capability inside it. It describes when the capability should be discovered, how it should be executed, and which additional material and tools need to be read next. If a Skill is just a prompt you occasionally use yourself, that distinction hardly matters. The moment it enters a plugin and gets invoked repeatedly by different users, projects, and hosts, it does.

Why do plugins need engineering?​

For personal use, writing down the task and the steps is usually enough. Once a plugin is called repeatedly across users, projects, and hosts, a set of problems that look a lot like software engineering appear on their own:

• Behavioral contract: how is it supposed to work? Which situations should trigger it and which should not; what context does it need, which tools may it call, and which behaviors are forbidden?
• Change verification: is it still correct after a change? When a Skill, a script, or a reference document changes, how do you confirm that the existing capability was not broken and that a fixed problem does not come back?
• Environment compatibility: does it still work elsewhere? When the model, the Agent, the host, or the runtime changes, can the capability still be discovered, loaded, and executed correctly?
• Outcome assessment: did it actually make the Agent better? Even if the Skill is triggered correctly and executed fully, how do you show that it improved the result of a real task compared with not using it?

None of these are solved by "writing a more detailed prompt". They map onto very familiar software-engineering problems: defining contracts, verifying changes, managing compatibility, and assessing real effect. Take them further and you land on specifications, knowledge and dependency organization, interface and permission boundaries, automated tests, regression verification, and cross-model, cross-host behavioral evaluation.

It was during the development of Better Harness that we gradually started to understand Skills differently:

Once a Skill leaves the personal-prompt stage and enters a plugin ecosystem, the problems it faces look increasingly like software, not prompting.

The five engineering practices below follow from that shift.

1. Spec-driven: write Agent behavior as a verifiable contract​

Spec-driven development is the part we started practicing earliest in Better Harness. The core idea is to write down "when to act, what to do, and how well it must be done" as a verifiable contract before implementation.

Our AGENTS.md states it directly:

For non-trivial behavior changes to Skills, scripts, templates, host adapters, or review workflows, establish a spec and traceable acceptance criteria first.

A spec has to answer at least a few questions: which requests should trigger the capability and which similar-sounding requests should not; what information must be read and which tools may be called; which behaviors are explicitly forbidden; whether the Agent should stop, degrade, or hand back to a human when evidence is insufficient; and finally, what evidence proves the implementation matches the intent.

Every acceptance criterion should carry a stable id such as AC-01 or AC-02, each mapped to implementation, test, and review evidence. One of our boundary-hardening specs, for instance, decomposes reproduced problems into AC-01 through AC-09.

Concrete examples: when the Agent scans written content, it must not echo secrets; when analyzing one workspace, it must not quietly count sessions from other directories; when the Git baseline cannot be established, it must stop explicitly instead of disguising failure as "no changes". AC-09 then closes the loop with a full test and packaging verification.

Specs themselves need review. In the triangulate-spec-review Skill, we have at least two - usually three - review Agents inspect the same context from different angles: implementation complexity, ease of use, and long-term evolution. A lead Agent merges duplicate findings, checks evidence, and edits the document; the other reviewers only provide independent judgment and do not touch files. The value of being spec-driven is exactly this: ambiguity moves from run time to design time.

Spec-driven work has a boundary too. When acceptance criteria are written too finely, AI tends to turn tests into word-by-word matching against the Skill text instead of verifying real behavior, which makes the tests less stable. A spec should constrain observable behavior, not freeze specific wording.

A spec defines how a capability should work. The next step is making sure the Agent can actually find the knowledge that supports that behavior while it runs.

2. Context orchestration: make Skill knowledge arrive when it is needed​

Agent Skills generally rely on progressive disclosure: knowledge should not all enter the context at once, but unfold as the task requires.

The host first reads name and description to complete discovery, loads the full SKILL.md only after deciding to use the Skill, and pulls finer material into context as the task demands. This is essentially context engineering for Agents: rather than pushing all knowledge into the model at once, you design when knowledge appears, where it enters from, and how it stays traceable.

Translated into directory structure, the entry point should stay short:

my-skill/
├── SKILL.md          # trigger conditions, main flow, stop conditions
├── references/       # judgment rules loaded on demand
├── scripts/          # deterministic logic that can be re-run
└── assets/           # templates and delivery skeletons

SKILL.md owns triggering, routing, and stop conditions; detailed judgment goes into references/; stable executable logic goes into scripts/; templates and delivery skeletons go into assets/.

In practice, though, we found that splitting knowledge apart is not enough: a file existing does not mean the Agent can find it, and having been referenced once does not mean the path still resolves after a refactor.

So we protect knowledge routing along three axes:

• Discoverable: bring relevant material into the Agent's knowledge path through explicit entry points and references in SKILL.md, rather than relying on ad-hoc search.
• Reachable: use automated tests to check that relative links resolve and that every document a Skill needs is genuinely routed from its entry point.
• Traceable: generate a Mermaid graph from the real Markdown references with a doc-link-graph generator, and verify that the generated output still matches the current reference relationships.

That way the Markdown references themselves are the source of truth, and the graph is only a verifiable projection of knowledge routing. When documents move, links break, or routing changes, a machine notices in time instead of relying on maintainers to sync manually.

The goal of context orchestration is not to make the Agent read more, but to make the right knowledge enter the context at the right moment through a path that still works. Once knowledge arrives reliably, the next question is which boundaries should be decided by a program rather than guessed by a model.

3. Deterministic verification: give the machine what it can decide​

Not every question inside a Skill or a plugin should be handed to the model. Keywords, regular expressions, and program checks are well suited to problems with clear boundaries and decidable outcomes - metadata, directory structure, broken links, data formats, deprecated names, permission declarations. What they cannot do is prove that the Agent understood the task, and they are no substitute for semantic quality review.

In Better Harness we hold those boundaries with three deterministic layers:

• Lint: check file headers, directory structure, broken links, data formats, and permission declarations, catching cheap and decidable problems early.
• Unit tests: verify deterministic logic such as scripts, parsers, and template transforms, so basic capabilities still hold after a change.
• Contract tests: verify what a command or entry point is actually allowed to do, including inputs and outputs, error states, artifact locations, and side-effect boundaries.

A representative example is how Better Harness tests the --help path. better-harness-cli.test.mjs does not merely check that the help text is correct; it further verifies that running a help command must not read the workspace, write files, wait on standard input, spawn a child process, or access the network. If any one of those side effects occurs, the test fails.

What is really being verified here is not what the help text looks like, but what this entry point is and is not permitted to do. That is the value of deterministic verification: boundaries that model behavior can easily paper over become engineering constraints that are checked automatically and regressed continuously. In an Agent system, models are better at understanding, planning, and trading off; deterministic programs are better at verifying, constraining, and refusing.

If a program can decide it, do not make the model guess. If it needs semantic judgment, do not force it into a string assertion.

Deterministic verification only guards decidable boundaries, though. It cannot prove the Agent actually follows the Skill in a real task. That requires behavioral evaluation.

4. Behavioral evaluation: verify the Agent really does it​

A Skill existing, being discovered, being loaded, being executed, and finally producing an improvement are five different things. Passing static checks only says that the files and scripts have no obvious defects. Whether the Agent chooses the Skill at the right moment, performs the key steps, and stops when evidence is insufficient still needs behavioral evaluation.

In Better Harness we usually prepare three kinds of scenarios: positive cases that should trigger, negative cases that should not, and boundary cases worded similarly but with a different intent. During execution we watch four things:

• Selection: was it used when it should be, and not misfired when it should not be?
• Context: did it read the material it genuinely needed?
• Execution: did the key steps, tools, and permissions stay within the constraints?
• Outcome: can the final artifact pass independent verification?

The same scenario also needs repeated runs, because one success only proves that this particular run worked, not that the behavior is stable.

At the host boundary, Better Harness additionally runs end-to-end verification through the real Qoder CLI and plugin loading chain, launched from a neutral directory:

python3 <skill-creator-root>/scripts/quick_validate.py <skill-dir>
qodercli --cwd <neutral-dir> --plugin-dir <plugin-root> -p "<forward-test-prompt>"
qodercli plugin validate <plugin-root>

Starting from a neutral directory prevents the Agent from accidentally borrowing configuration, context, or undeclared dependencies from the current repository, which would make "it works" look more optimistic than reality. At the same time, whatever qodercli answers counts only as model-behavior evidence; whether the run passes is still decided by deterministic evidence such as the local validator, artifact inspection, and Git status.

Simulated cases cover exceptional and boundary situations; real host tests verify whether the chain from plugin loading to Skill discovery, material reading, tool invocation, and final delivery is genuinely connected. What behavioral evaluation sets out to prove is not that the Agent has seen the Skill, but that the key behaviors the Skill requires actually happened.

Proving that the Agent executed the Skill, however, is still not proof that the Skill produced a better result. That belongs to the evidence loop.

5. Evidence loop: prove the Skill works before talking about self-evolution​

Behavioral evaluation answers "did the Agent follow the Skill". The evidence loop goes one step further: given the same task, does the Agent actually do better with this Skill?

In Better Harness this is designed as an evaluation execution protocol. Holding the task, model, tools, permissions, and test environment constant, we run three arms: no Skill, current Skill version, candidate Skill version.

An evaluation looks at more than the final success rate. It also observes whether the key steps were executed, whether verification was complete, the time and token cost, and whether extra side effects appeared. Otherwise a Skill that looks "better" may simply be using more permissions or more resources.

One failure mode deserves special attention: fake usage, where the Agent finds the Skill and reads SKILL.md but never performs the steps it requires. Better Harness calls this routed-but-not-applied.

So we keep judging along an evidence chain:

• Does it exist? Are the Skill and its supporting mechanisms present?
• Can it be found? Can a real task discover and select it?
• Was it executed? Did the required key steps actually happen?
• Is it effective? Compared with not using the Skill, did the result improve?

In the Agent Work Loop this maps to Present → Wired → Exercised → Outcome-supported. There is a single governing principle: a conclusion may only go as far as the evidence goes.

That also matches where recent Skill-evaluation research is heading. SkillsBench focuses on the outcome difference between using and not using a Skill on the same task; Skill Coverage further checks whether the behaviors a Skill requires really appear in the execution trace. The former answers "did the result get better", the latter "did the process actually happen".

Outcome improvement and process coverage are both required; neither alone is enough. Only after that evidence chain is in place does self-evolution become meaningful. Otherwise Trace2Skill, EvoSkill, CoEvoSkills, or SkillOpt may just help an Agent produce more unverified Skills faster.

Skill evolution should not start from "generate more experience". It should start from proving that this change really made the next run better.

Conclusion​

The core of Agent plugin engineering is not writing more elaborate Skills. It is treating the capabilities inside a plugin as software assets: constrain behavior with specs, organize knowledge with context orchestration, hold boundaries with deterministic verification, confirm execution with behavioral evaluation, and judge effect with controlled comparison.

When those mechanisms work together, a plugin finally moves from "it works when I run it" to "verifiable, maintainable, and safe to evolve".

Developing Agent plugins as software also means that every change should leave behind enough evidence to show that it got better.

In its first three days, 100,000 people tried Better Harness.

The answer is yes.

Today, Better Harness is officially open source. You can find the project at github.com/QoderAI/better-harness.

Better Harness is an open-source analysis and continuous-improvement tool for coding-agent workflows. It connects the engineering practices, evaluation model, and runtime capabilities of Harness Engineering and Loop Engineering. The initial open-source release supported Claude Code, Codex, Qoder, and Cursor with one shared judgment model, although session analysis, evidence coverage, and output capabilities were not yet identical across the four hosts. Qoder, which had already been exercised repeatedly in real development workflows, was the most complete reference implementation at launch.

Editor's note: This table records the launch state. Better Harness now publishes additional host integrations, and entrypoints differ by host. See the current Installation guide before installing or running a review.

At launch, the shared workflow was commonly invoked as:

/better-harness

You could start the analysis, inspect the report as it ran, and continue reading this article. When a category of evidence was unavailable, Better Harness preserved that boundary in the result instead of substituting config counts or data from another host.

Better Harness cares about what the agent did in the task​

Imagine that an agent modifies a module, runs one test command, and declares the task complete. The real question is not whether the repository has tests. It is whether that test was relevant to the change, covered the main risks, and produced enough evidence to support delivery.

Better Harness therefore does not treat the presence of AGENTS.md, Rules, Skills, MCP servers, Hooks, memories, tests, or CI as proof that they influenced the task. Every improvement item—a Finding—must include traceable evidence, a specific user impact, the smallest repair boundary, and a way to verify the result after the repair.

In one self-analysis snapshot produced from Codex, Better Harness did not turn the absence of an executed Codex host test into the stronger claim that “Codex has failed.” It kept the unexecuted host test as an explicit evidence boundary. Scores can help locate a problem, but the conclusion, impact, repair scope, and verification method are what matter.

That is the difference between Better Harness and a configuration checklist. A checklist tells you what the project possesses. Better Harness asks whether those capabilities actually helped the agent complete a trustworthy task.

And if the judgments in a report are meant to be inspected, changed, and reverified, open source cannot stop at publishing an executable entrypoint.

The three-layer open-source system behind Better Harness​

Publishing the /better-harness prompt on GitHub would technically qualify as open source. But for a coding agent, no single prompt determines the result. What matters is the full working method behind it: what is worth checking, what counts as evidence, how judgments are formed, and how they can keep running and changing in real projects.

That is why Better Harness opens three connected layers.

Layer 1: Harness Engineering best practices​

This layer answers a practical question: when we examine sessions, CLIs, observability, Rules, Skills, MCP servers, memories, Hooks, and automation, what should we check—and which conclusions cannot be drawn merely from the presence of configuration?

The knowledge is organized by problem domain under references/:

Better Harness does not load one endlessly expanding master prompt on every run. It reads the judgment criteria for the problem at hand. A diagnostic issue routes to observability practices. A Skill issue routes to Skill Review. A repeated workflow first triggers a decision about whether a Skill, Hook, script, or automation should own it over time.

Layer 2: the Agent Work Loop evaluation model​

This layer turns engineering practices into questions that can be checked one by one, while constraining the relationship between evidence, scores, and conclusions. The current model and evidence states are public in the Agent Work Loop model.

Because the standard is still emerging, we did not want one model to define a “good harness” subjectively. The first internal evaluation selected 30 real GitHub projects. Four model families independently evaluated them using OpenAI's Harness Engineering article as a starting point, producing 120 standardized reports. Cross-model comparison and human calibration then clarified evidence requirements, judgment boundaries, and differences between project types before every project was evaluated again under the updated criteria.

This loop—automated evaluation, automated aggregation, human calibration, and automated reruns—produced the first reproducible Harness Engineering evaluation model that we could continue to adjust.

The first version still resembled a conventional software-engineering maturity scan. It focused on whether a project had documentation, tests, CI, and safety mechanisms. We soon learned that static assets cannot prove that an agent actually completed a task.

Better Harness itself is developed through a spec-driven process so that changes in the model and product capabilities remain traceable. As more than 200 specs accumulated, the model shifted from asking “What exists in the repository?” to asking “What actually happened in the task?”

The evaluation target narrowed from a repository or a session to a concrete task. A session stopped being the thing being evaluated and became a container for evidence. The model then stabilized around five dimensions: task understanding, controlled execution, change verification, reliable delivery, and experience capture. File existence, config counts, temporal proximity, and even a successful command can no longer be treated as direct proof that a capability was effective.

The Agent Work Loop is therefore not a static scorecard. It is a judgment system centered on real tasks, designed to be reproduced and continuously calibrated.

Layer 3: a runnable engineering implementation​

The third layer makes the practices and model repeatable in real projects. Better Harness starts an analysis through a plugin or CLI—the JavaScript code under the project's scripts/ directory—freezes the task scope, and collects three evidence lanes independently:

• Session Evidence reconstructs the agent's behavior in real tasks.
• Project Harness checks whether the project can be started, diagnosed, verified, and recovered.
• Agent Customize checks the configuration, routing, and usage evidence for Rules, Skills, MCP servers, memories, and Hooks.

The lanes remain separate during collection and analysis. Only then does the Lead reconcile them using the criteria in references/ and the Agent Work Loop model. “The project has this capability” and “the agent used this capability in the task” remain two different facts.

The output is not just a score. It is a set of Findings with evidence boundaries, user impact, repair scope, and verification methods. Once rendered and validated, the report can enter a repair flow. If the analysis finds stable repeated work, Loop Engineering determines whether a Skill, Hook, script, automation, or another mechanism should own it over time.

Completing a repair still does not prove that the workflow improved. The loop is closed only when a later task of the same kind produces a better observed result.

Start with the first verifiable problem​

For Qoder users​

At the time of the announcement, Qoder Desktop included Better Harness in the Quest view as Better Harness (Beta) and exposed /better-harness directly. Qoder CLI and the JetBrains plugin could use the same capability on a machine where Qoder Desktop had already been installed. Refer to the current Installation guide for today's supported Qoder entrypoints.

From the open-source repository​

Visit the Better Harness GitHub repository and follow the current README or Installation guide. For example, Claude Code users can run:

/plugin marketplace add QoderAI/better-harness
/plugin install better-harness@better-harness

Then start a review with:

/better-harness Analyze my project's harness and generate an HTML report

Your first Better Harness run does not need to build a complete agent engineering system, and it does not need to chase a perfect score. A more practical starting point is one problem with clear evidence, a concrete impact, and a fast verification path.

It might be a check command the agent cannot find, an error log with no useful next diagnostic step, or a Skill that exists but has never entered the task routing path.

Fix one problem, run the review again, and observe whether a later task of the same kind changes. Harness Engineering is not a one-time configuration project. It is the continuous work of making a project easier for an agent to understand, execute, and verify.

We know it is not complete​

Better Harness has been run and calibrated repeatedly in Qoder's real development workflows, but the current model still reflects the project types and task scenarios we know best.

Different technology stacks, project sizes, team constraints, and coding agents may reveal blind spots. Better Harness needs more real evidence to keep correcting them.

If you would like to contribute, there are several useful starting points:

• Add an engineering practice. Add a judgment guide for a language, framework, or common workflow under references/. No code is required.
• Add an evaluation perspective. Add an evidence-backed dimension or detector under models/ or scripts/, together with fixtures and tests.
• Add host support. Complete evidence collection and verification for another coding agent. The repository Roadmap lists candidate work.
• Add a real case study. Contribute a redacted team example under case-studies/.

If you disagree with a Finding, please open an issue. A counterexample from a real project is more useful to us than a star—although we will happily accept the star too. 😁

Born in Qoder, returned to the community. Give every coding agent a foundation of verified engineering practice.

An agent usually cycles through understanding the task, taking action, checking the result, and adjusting its next step. That is the Agent Loop. A reliable loop does more than keep the agent moving: it gives the agent a clear goal, defines what it must not touch, explains how to judge the result, and provides a recovery path when something fails. Without those boundaries, an agent may change a great deal of code and run many tests while still being unable to prove that the task is actually complete.

This is the problem that Loop Engineering and Harness Engineering address. They equip the agent with project context, relevant development tools, effective verification methods, and explicit safety boundaries so that every loop moves closer to a reliable delivery.

Building on Qoder's internal experience and the broader community's work on coding agents, agent loops, and software engineering, we introduced Better Harness (Beta).

In current versions of Qoder, you can open Better Harness and start an analysis and repair from the visual interface, or run the /better-harness Skill directly. It examines how the agent worked through the current task, identifies missing or weak elements in the loop, and helps you decide what to improve next.

How Better Harness diagnoses, improves, and rechecks the loop​

Better Harness does not grade the quality of a single answer. It examines the entire harness that supports a coding agent as it completes a task:

• Are the goal and context clear?
• Is the project easy to run?
• Are permissions under control?
• Does verification provide meaningful evidence?
• Is delivery safe?
• Can the team and the agent learn from the task?

Its main analysis flow is:

1. Map the current harness. Identify the goal, context, execution entrypoints, feedback paths, delivery mechanisms, and learning mechanisms.
2. Find the breaks. Explain which part of the loop lacks a mechanism, integration, observed execution, or outcome evidence.
3. Choose the smallest improvement vehicle. Route the problem to the most appropriate Rule, Skill, Hook, script, automation, or human gate.
4. Repair and recheck. Keep the fix bounded, run the relevant verification, and run /better-harness again to see whether the loop actually improved.

The main analysis flow first collects the underlying evidence. It then asks three independent, read-only subagents to interpret three evidence lanes:

• Agent customization assets, such as Rules, Skills, and Hooks;
• Real task-session records, which show what the agent actually did and how the task ended; and
• The project's software-engineering foundation.

The three lanes are collected independently and reconciled only afterward, so that one category of evidence does not contaminate the conclusions drawn from another.

Agent customization: from capability inventory to actual use​

In coding agents such as Qoder, Rules, Skills, Custom Agents, MCP servers, plugins, memories, and Hooks are the building blocks of an effective loop. Better Harness inventories these custom capabilities and checks whether they are complete, discoverable, and usable.

But having the building blocks does not make the loop reliable. A project can have tests without running the relevant tests for a task. A Skill can exist without the agent invoking it when it matters. Better Harness therefore also examines evidence that Rules and Skills were actually used, helping users find context-engineering gaps and reduce wasted credits.

Qoder Canvas presents this evidence in a detailed report, including patterns such as Skill usage over a recent period. Better Harness also looks for repeated work in task sessions that might justify a reusable Rule or Skill. However, not every observation should become a Skill, and not every repeated task should be automated. The report keeps those distinctions explicit and offers bounded improvement suggestions.

For an identified opportunity, the user can select Plan a fix and let the AI generate and execute a repair plan. More importantly, the result does not have to remain a one-off fix. It can become a reusable Rule, Skill, memory, or other asset that strengthens the user's own agent harness.

Each task analysis can therefore improve more than the current task. As the asset base grows, the agent learns more about the user and the quality, efficiency, and control of later loops can improve as well.

Real task sessions: reconstructing how the Agent Loop actually ran​

Capability inventory alone cannot prove that a loop worked. Better Harness also analyzes real task-session records—by default, from the most recent 30 days—to understand what the agent actually did and what outcome it produced.

The basic unit of analysis is a task episode: one user goal plus an observable acceptance boundary. Within each episode, Better Harness looks for four kinds of signals:

1. Repeated workflows. When the same task repeatedly requires the same steps or corrections, the project may be missing a Skill, Rule, or script.
2. Closed-loop verification. Did the agent actually run the relevant tests, lint checks, builds, or regressions in the right place? Repeating a check is not enough; the subsequent result must also be accepted and used.
3. Attribution of friction. When a task stalls, did the problem come from the harness, the project, the model, or the requirement itself? Not every failure should be blamed on the agent.
4. High-impact one-off events. Did a permission block, missing diagnostic entrypoint, or failed recovery materially change the direction of the task?

This lane is analyzed by an independent, read-only subagent. It sees only redacted factual summaries, not raw prompts, private paths, secrets, or other sensitive material. These signals make it possible to assess the real use of Skills and Rules, identify context-engineering problems that affect the loop, and reduce unnecessary credit consumption.

Project engineering foundations: make it findable, runnable, and verifiable​

The project's existing software-engineering foundations also shape the quality of every agent loop. A repository may contain extensive documentation, scripts, and tests, but those capabilities cannot help if the agent cannot find the correct entrypoint, run it successfully, or decide what to do after it fails.

Better Harness examines five aspects of a project's readiness for agent work:

1. Findable. Can the agent quickly locate the relevant code, module boundaries, project constraints, and required checks for a specific task?
2. Runnable. Are dependencies, configuration, build steps, and startup instructions clear? When the environment breaks, can the agent diagnose it, reset safely, and start again?
3. Fast feedback. After a code change, do the available checks and tests quickly show what failed, where it may have failed, and what to try next?
4. Enforceable rules. Are architecture, security, API compatibility, and database-migration requirements checked by tools rather than existing only as documentation or convention?
5. Controlled changes. Are change boundaries explicit, do high-risk actions require confirmation, and can a failed operation be rolled back, recovered, or exited safely?

For example, a test command in the README proves only that the project exposes a test entrypoint. Inspecting the script reveals what the command actually covers. Only running the relevant check in a real task and responding to its result can show that the feedback path has truly entered the Agent Loop.

Turn every Agent Loop into an asset for the next one​

A /better-harness analysis is not the finish line. It helps you find breaks, generate a repair plan, and verify whether a new Rule, Skill, Hook, or script actually entered the agent's workflow.

The most reusable lessons can then become personal or team-owned agent assets, making later loops more stable, efficient, and controllable. Open Better Harness in Qoder—or run /better-harness—and find the next part of your loop that is worth strengthening.