< cd ..

2026-11-13· Nick Boucart

“Looks Good” Is Not a Quality Gate

The feature works. The tests pass. The coding agent reports that it is done. You glance through the diff and merge it.

Two weeks later, changing a business rule means editing five places. One method handles validation, calculation and persistence. The tests still pass when you deliberately break the calculation.

Nothing in that original handover was necessarily false. The feature did work, and the tests did pass. But neither statement answered the question you actually cared about: is this code on par with what we expect?

To answer that, we need something more useful than “write clean code.” We need explicit guidelines, checks that provide evidence, and a workflow that makes those checks hard to skip.

Expectations are not acceptance criteria

Most teams agree that code should have no unnecessary duplication, no overly long methods and good tests. Agreement gets harder when you ask what those words mean in a particular change.

Is a sixty-line method too long? Are two similar blocks duplication, or do they represent different concepts? Is a test useful because it executes a branch, or because it detects an incorrect result?

Leaving these questions implicit makes review depend on who happens to review the change, how much context they have and how much time they can spend. Coding agents face the same ambiguity. “Keep it simple” gives an agent a direction, but not a reliable stopping condition.

More concrete expectations help:

  • A business decision should live in one place, rather than being copied across callers.
  • A function should have a focused responsibility and control flow that a reviewer can follow.
  • Tests should check observable behavior, not merely confirm that something was called.
  • Deliberately breaking relevant behavior should cause a relevant test to fail.

These are still guidelines requiring judgment. But they give us something to inspect and discuss. Where tools can assess them, they also give us checks we can repeat.

Enter ub-mode

Uncle Bob’s ub-mode is an agent skill that turns engineering principles into instructions for writing and changing code. Its structure is straightforward: first make it work, then make it right, and follow disciplined practices along the way.

Making it work includes writing a failing test, seeing it fail for the expected reason and making the smallest change that makes it pass. Making it right includes fixing root causes, testing behavior, reducing duplication and complexity, and refactoring without changing behavior.

What makes the project interesting is the pairing of those instructions with quality-gate tools:

  • Crapper assesses cyclomatic complexity, test coverage and CRAP scores per function.
  • Dryer detects structural duplication.
  • Mutator uses mutation testing to expose code that tests do not adequately protect.

The distinction matters. A skill tells the agent what it should do. Running a check provides evidence about what it actually produced. Installing instructions is not the same thing as enforcing them.

One business decision, one place

Duplication is not just repeated text. The expensive kind is repeated knowledge.

Suppose checkout and invoice generation both decide whether a customer qualifies for a discount. They start with the same condition, copied into two methods. When the policy changes, someone updates checkout but misses invoice generation. Both pieces of code may look reasonable on their own, yet the system now disagrees with itself.

The useful rule is not “never write similar lines.” It is “do not spread one business decision across multiple places that must stay in sync.”

ub-mode uses Dryer to flag structural duplication at or above its 0.8 similarity threshold. That gives the agent a concrete signal to investigate instead of relying entirely on its own impression of the diff.

A duplication report still needs interpretation. Two blocks can look alike while representing rules that will evolve independently. Combining them too early can create an abstraction full of flags and special cases. The goal is to consolidate shared knowledge, not to minimise repeated characters at any cost.

Short methods are a means, not the goal

Long methods often become a problem because they accumulate responsibilities. Reading input, validating it, calculating a result, saving it and sending a notification all end up in one place. Understanding one decision means keeping the rest in your head.

A line limit can be a useful warning, but it is an incomplete assessment. A short method with tangled branches can be harder to reason about than a longer, straightforward transformation.

ub-mode uses a more specific gate: bring each function’s CRAP score below 10. CRAP combines cyclomatic complexity and test coverage to highlight functions whose branching and lack of coverage make them risky to change.

That is useful evidence, but it does not measure everything we care about. A well-covered function can still mix responsibilities. Splitting a method into arbitrary helpers can improve a metric without making the code easier to understand.

The review question remains: does this structure make the behavior easier to explain, test and change? Extract meaningful responsibilities, then use the metrics to check for remaining risk.

A test should notice when something is wrong

A green test suite tells us that its assertions passed. It does not automatically tell us that those assertions were worth making.

Consider this pricing function:

function discountedTotal(subtotal: number, eligible: boolean): number {
	return eligible ? subtotal * 0.9 : subtotal;
}

Now consider its test:

it('calculates a total', () => {
	expect(discountedTotal(100, true)).toBeDefined();
});

The test executes the discount calculation. But change the multiplier from 0.9 to 1, and it still passes. Remove the discount entirely, and the test still passes. It provides almost no protection for the behavior named in its description.

A more useful test makes the expected outcome explicit:

it('applies a ten percent discount to eligible purchases', () => {
	expect(discountedTotal(100, true)).toBeCloseTo(90);
});

it('leaves ineligible purchases unchanged', () => {
	expect(discountedTotal(100, false)).toBe(100);
});

Now removing the discount breaks a test. Applying it to everyone breaks another. Real pricing code would also need an explicit policy for rounding and boundary cases; these tests illustrate the distinction between executing code and checking its behavior.

This is why coverage alone is insufficient. Coverage shows which code ran. It does not show whether a test would detect an incorrect result.

Mutation testing checks the checks

Mutation testing deliberately changes the program in small ways and runs the tests against those changes. Depending on the tool, a mutation might alter a condition, replace an operator or change a return value.

If a test fails, the mutant is killed: the suite detected the change. If the tests still pass, the mutant survives, giving us something to investigate.

ub-mode’s instructions for Mutator are concise: cover the uncovered, kill the survivors and delete dead code.

In the discount example, changing 0.9 to 1 is exactly the kind of mistake our tests should catch. A surviving mutation would expose the weakness of the first test much more clearly than a green coverage report.

Not every surviving mutant means a missing assertion. Some mutations are equivalent: they do not change observable behavior for valid inputs. Others may expose an unclear requirement. The response should be to understand the survivor, not to add assertions blindly until a score improves.

There are two complementary habits here. During test-driven development, observe a new test failing before implementing the behavior. Later, use mutation testing to challenge whether the completed suite notices relevant defects. Both help prevent false confidence.

Put the rules in the delivery loop

Guidelines are most useful when they change how work gets accepted. A document that nobody consults cannot do that, and an agent’s claim that it followed the document is not independent verification.

A practical loop looks like this:

  1. Define the expected behavior. State what a user or caller should observe, including important failure cases.
  2. Write a test and observe the failure. Check that it fails for the intended reason, rather than because the setup is broken.
  3. Make the smallest working change. Avoid speculative abstractions and unrelated cleanup.
  4. Inspect structure. Check duplication and complexity, then assess whether responsibilities and boundaries make sense.
  5. Challenge the tests. Run mutation testing and investigate uncovered code and surviving mutants.
  6. Refactor and recheck. Change structure while preserving behavior, then rerun the relevant checks.

For an agent, make those expectations available in its project instructions or skills. Ask it to report which checks it ran, their results and any unresolved findings. “Not run” must remain distinct from “passed.”

For the team, put fast, reliable checks in CI so acceptance does not depend on remembering a prompt. Introduce slower checks, such as mutation testing, at a cadence that fits the project. If the full run is expensive, use focused runs during development and broader runs periodically, while being explicit about what each run covers.

Start with a small set of meaningful rules. In an existing codebase, it may be more practical to prevent new violations and improve changed code than to block every contribution on historical debt.

Guardrails, not metric worship

No combination of duplication thresholds, complexity scores and mutation results proves that a system is correct. A change can pass all of them and still implement the wrong requirement, expose sensitive data or introduce a poor architectural boundary.

Rules work best when their purpose is visible. We reduce duplication to prevent inconsistent decisions. We simplify methods to reduce the effort of understanding and changing them. We test behavior to detect mistakes that matter to users.

When a rule produces a worse design, investigate why. A justified, documented exception is better than rearranging code solely to satisfy a number. But “the agent says it is fine” is not a justification.

The value of ub-mode is not that its particular thresholds are universal. It is that it connects engineering expectations to a repeatable process and concrete evidence. We have not benchmarked these tools ourselves; their effectiveness in a particular project still needs evaluation.

Define what done means

For KAIZEN, this is an important part of working with coding agents. Generating a plausible implementation is only one step. We also need a dependable way to assess whether that implementation meets the team’s expectations.

Explicit rules reduce ambiguity. Automated checks make some of those rules repeatable. Human review interprets the results and covers what the tools cannot.

The feature working once is the beginning of that assessment, not the end.

Do not just tell an agent—or a teammate—to write better code. Define what better means, and show how you will check it.

$ cat ./partners

  • Sirris
  • Universiteit Antwerpen
  • Karel de Grote Hogeschool

$ cat ./funding

VLAIO

$ exit 0 — KAIZEN, a COOCK+ project funded by VLAIO