对于一次软件开发任务来说，Agent 的行为并不是孤立发生的。它从一个需求或者用户故事开始，经过对需求的理解、上下文探索、代码修改和验证，最终才形成一次可以被评审的代码贡献。只看中间的 Session，我们能看到 Agent 做了什么，却很难判断这些行为为什么发生，又有哪些行为真正进入了最后的交付。

因此，我们开始把一次 Agent 的交付理解成一条连续的链路。现在，只需要在项目目录执行：

npx @qoder-ai/better-harness inspector

就可以生成一个本地、只读的 Harness Inspector 页面，把当前项目中的 Agent Session、文件活动和 Git Commit 放到同一个交互界面里。

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

从 Session 到一次完整的交付过程​

Harness Inspector 最初只是一个会话调试工具：帮助我们查看 Agent 说了什么、调用了哪些工具，以及修改了哪些文件。但随着 Session、文件活动和 Git 历史逐渐被连接起来，我们发现，真正需要观察的并不是会话本身，而是：

一次软件变更如何从一个意图出发，经过 Agent 的执行，最终形成可以进入工程系统的产出。

Session 只是这条链路的中间部分。

从意图到产出的交付链​

我们将一次 Coding Agent 的交付拆成三个连续、但边界不同的部分：

• 意图（Intent） 是一次变化的语义化起点，例如用户的需求、Issue、Spec 或者架构约束。
• 过程（Process） 体现的是这次变化真正发生的过程，对于 Agent 来说，主要体现为 Session 记录以及其中的搜索、读取、修改和验证。
• 产出（Output） 则是 Agent 交付到工程系统的最终结果，现阶段最清晰的锚点就是代码 Commit。

所以，Story、Session 和 Commit 并不是三个并列的抽象概念，它们分别是 Intent、Process 和 Output 在当前软件开发工具链中的可观察对象（意图在不同场景下也可能表现为 Issue 或 Spec）。Harness Inspector 要做的，也不是把一段对话展示得更完整，而是重新建立这条从需求到提交、可以追溯的交付链路。

从叙述上看，它是一条连续的交付链；但在真实项目中，它更接近一张证据图。一个 Story 可能经历多个 Session，一段 Session 也可能涉及多个 Commit。

一个简单的示例：从 Story 到 Commit​

我们在 Better Harness 文档页创建了一个只读的公开样本（英文示例数据，不读取本地内容）：https://qoderai.github.io/better-harness/inspector。

只看 Session，我们只能看到它是一串搜索、读取、修改和测试活动，很难确定它是否一直围绕最初的需求展开，也不知道其中哪些修改真正进入了代码库。单独看 Commit，我们虽然可以看到最终修改了哪些文件，却无法知道 Agent 在提交之前如何理解问题、建立上下文和完成验证。

当 Story、Session 和 Commit 被放到同一个界面后，这次变化才成为一段相对完整的交付过程：Story 说明为什么要修改，Session 展示修改是怎样发生的，Commit 则记录最后留下了什么。

把需求、Agent 行为和代码提交连接起来，让我们第一次能够从整体上检查一次交付。但真正打开一些包含数百次 Tool Call 的真实 Session 后，另一个问题很快出现了：能够把一次交付连接起来，并不意味着我们已经能够读懂它。

Harness Inspector 如何读懂一次 Agent 交付？​

围绕 Better Harness 的 Harness 模型，我们将 Harness Inspector 定义为：

Harness Inspector 是一个面向 Agent 交付过程的本地、只读工作台。它将需求、Agent Session、文件活动和 Git Commit 放在同一个交互界面中，用来检查一次软件变化为什么发生、怎样发生，以及最终留下了什么。

Harness Inspector 以一次完整交付为中心，围绕从需求到提交的链路，提供了三种观察方式：

• Workbench：查看需求、Session 与 Commit 之间的关系；
• Trace：查看 Session 内部的工作结构；
• Replay：按照事件顺序重新观察任务如何展开。

简单来说，Workbench 看关系，Trace 看结构，Replay 看顺序。三者共同帮助我们还原一个需求如何经过 Agent 的理解、探索、修改和验证，最终形成一次可以被评审的代码提交。

Workbench：连接需求、过程与产出​

Workbench 是一次交付的整体视图。在左侧，我们可以看到触发这段 Session 的用户需求，以及执行过程中对目标的补充和调整；中间展示 Agent 在 Session 中发生的搜索、读取、工具调用和 Git 操作；右侧则是当前范围内观察到的 Commit，以及它最终修改的文件。

它关注的不是简单地把数据放在一起，而是展示需求、过程和产出之间已经观察到的关系。关系证据不足时，Inspector 会继续把它保留为候选或未映射，而不是自动拼出一条看起来完整的交付路径。

Trace：把 Session 读成一条工作轨迹​

Workbench 帮助我们找到一次交付，Trace 则进一步展开其中的 Session。

进入 Session 后，Trace 会按照 Turn 组织用户输入、中间回复、Tool Call 和文件活动，并通过顶部的时间轴连接事件在时间上的位置。点击某个区段可以跳转到对应调用，连续重复的活动也会被折叠，避免大量相似操作淹没真正重要的变化。

Trace 并不试图还原模型没有暴露的思考过程，而是将已经记录下来的行为重新组织成一条可以阅读的工作轨迹，帮助我们检查 Agent 如何搜索上下文、修改代码和执行验证。

Replay：沿事件顺序回看一次交付​

Replay 则沿着已经保留的事件逐步回看任务如何展开。Reviewer 可以依次查看用户输入、Agent 回复、Tool Call、文件和 Commit，观察 Agent 在什么上下文中形成方向，又在什么时候进行了修改和验证。

它只是一次只读的证据回放，不会重新运行工具、恢复工作区或者继续原来的 Session；没有精确时间的内容，也只保留顺序，不会补充没有被记录的过程。

Workbench 建立交付上下文，Trace 展开 Session 的工作轨迹，Replay 补充事件发生的顺序。三者共同把一次从需求到提交的 Agent 交付，变成可以逐层进入和检查的过程。当我们真正把一次交付读清楚之后，就可以回到最初的问题：这条轨迹里，哪些经验真正值得留下来。

从交付证据到 SKILL 沉淀​

当一次交付能够被看清之后，我们才能重新回到最初的问题：Session 中的哪些经验，真正值得沉淀成 SKILL？答案显然不是出现次数最多的 Tool Call。Agent 可能因为上下文不足而反复读取同一个文件，也可能因为命令失败不断重试；这些行为虽然频繁出现，却更可能是一次交付中的噪声，而不是值得复用的工程经验。

真正值得沉淀的，通常是一条能够在相似任务中重复出现，并且得到最终产出与验证结果支持的工作路径。例如，Agent 如何从需求中确定修改边界，如何建立必要的上下文，又如何完成修改、执行验证并检查最终结果。只有把这些行为放回对应的 Story、Session 和 Commit 中，我们才能判断它们是当前任务中的偶然选择，还是一套相对稳定、可以迁移到其他任务中的工作方式。

因此，SKILL 自动沉淀并不是将一段 Session 总结成新的 SKILL.md，而是从多次真实交付中识别稳定模式，再为它补充适用场景、上下文边界、执行步骤和验证方式。Inspector 当前解决的，正是这一过程最基础的一环：先让真实交付留下边界清晰、可以检查的证据。只有在此基础上，我们才可能进一步比较相似任务，形成 SKILL 候选，并在后续交付中验证它是否真的改善了 Agent 的工作方式。

结语：先看清交付，再沉淀经验​

我们最初想解决的是，如何从 Agent Session 中识别可复用的工作路径。但真正分析之后会发现，Session 只能记录 Agent 做了什么，却无法单独解释任务为什么开始，也不能证明哪些行为最终形成了工程产出。

Harness Inspector 将需求、Session、文件活动和 Git Commit 重新连接起来，让一次 Agent 交付变得可以观察、检查和追溯。只有先看清一次交付，我们才可能判断哪些行为只是偶然选择，哪些路径值得进一步沉淀成 SKILL。

从 Session 到交付，再从交付中沉淀经验，这正是 SKILL 自动演进的起点。

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.