Agentic Smells: From Qualitative to Quantitative

Jordan Gunn — Wed, 22 Apr 2026 17:14:40 +0000

Introduction

Every developer has had the same experience at least once. You pull down code someone else wrote and something is off. The tests pass, the function returns the right type, and the PR description is coherent.

Yet, the code is shaped in a way no experienced developer would have shaped it, and still, you cannot quite say exactly what is wrong.

Code Smells

That feeling has a name.

Our discipline calls it a code smell, a term coined by Kent Beck for his chapter in Fowler's Refactoring (1999). A smell, as Beck described it, is a characteristic of source code that hints at a deeper problem.

The olfactory metaphor is honest. By its own choice of word, it admits that the thing being named resists precise description. Fowler catalogued twenty-two of them in the book, each named for the symptom rather than the structural cause.

Still, the whole lexicon has the grainy authority of a Bigfoot photograph. For a field that claims to love precision, software engineering has a remarkable habit of naming its worst structural failures like a frightened village describing the woods: Code smell. God Class. Shotgun Surgery.

No one really objects, because the language earns its melodrama. The experience is melodramatic. A drop in the gut. The stench of rot. The dawning realization that someone built this in an afternoon and you will spend the next two sprints proving, gently and with citations, that it cannot be allowed to remain on planet earth.

For Those Who Cannot Smell

The irony is that "code smell" was already a blurry term for humans. It worked only because experienced developers were supplying everything the phrase left unsaid: memory, repetition, scar tissue, taste. They could smell rot before they could describe it.

An agent cannot.

In an agentic workflow, ambiguity does not remain ambiguous. It gets compiled. A human says, "this feels messy" or "this function is doing too much," and the model returns something that is often not less messy, but merely more presentable: messy, but wearing glasses and a fake mustache.

The Changing Landscape

An agent can dump hundreds or thousands of lines of plausible-looking code into a diff before the human reviewer has finished their coffee. If careful review costs as much as writing the code in the first place, then the promised productivity gains collapse the moment the advice is followed seriously.

The psychology is worse. Visible successes train trust. Invisible failures train trust even more effectively. What remains is often not review so much as ceremony.

Ceremonial review works because humans are easily reassured by the appearance of rigor. A passing test suite we did not read. A summary that sounds confident. A few hundred new lines of code, whose mere existence now passes for evidence of progress.

The whole process begins to feel less like engineering and more like hiding a dog’s medication in a piece of cheese: the unpleasant thing is still there, but the wrapper is persuasive enough to get it swallowed.

From Qualitative to Quantitative

The proposed fix is not a better synonym for messy. It is not a more elegant way to tell a model that a class feels bloated or a boundary feels wrong. That only widens the interpretation space and asks the same system that produced the ambiguity to resolve it in its own favor.

What agents need is something harsher.

They need a signal that is computable, externally enforced, and too specific to negotiate with. “This feels off” is conversation. “Cognitive Complexity 26, threshold 15” is arithmetic.

Ask an agent to fix a smell and it will often produce a different smell. Ask it to bring Cognitive Complexity below a threshold and you get refactors that satisfy the metric, not a guess at what the user meant.

Agreement is cheap. Arithmetic is not.

Those metrics must exist outside the agent’s own control surface. A model grading itself in natural language is just trial by self-chatter and spent tokens. A metric computed by external tooling is a fixed referent the agent cannot sweet-talk, reinterpret, or quietly omit.

The Research Was Already There

None of this required inventing a new science. The field has already spent decades reducing “this feels wrong” into concrete measurements:

Cyclomatic Complexity gave us path count in 1976.
Halstead counted operators and operands in 1977 to estimate information content and difficulty.
NPath in 1988 caught combinatorial path explosion that cyclomatic complexity can underreport.
The CK suite in 1994 translated class size, coupling, and inheritance structure into arithmetic.
Distance from the Main Sequence pulled package-level architectural drift into a single scalar.
Hotspot analysis combined complexity with churn over time.
Cognitive Complexity finally got closer than anything else to formalizing the feeling of code that is hard to read, not just hard to execute.

This work has been sitting in papers and textbooks for forty years: precise, computable, and mostly ignored until a problem arrived that finally made it necessary.

The field spent decades building ways to measure code quality. Then it built systems capable of producing code at industrial scale.

Then it connected the two with a markdown file.

What Cannot Be Measured

Not every smell survives this translation. Some still require human taste, judgment, or interpretation of intent.

That is fine.

The claim is not that every smell can be reduced to arithmetic. It is that the computable subset is large enough to enforce the constraints agents are least equipped to enforce on their own.

Why Not Just Use SonarQube?

Traditional analysis tools assume a human-operated workflow:

slower startup
heavier configuration
language-specific engines
reports shaped for dashboards

That fits a conventional pipeline. It fits badly inside an agent loop, where the useful tools must meet the minimum UX expectations of typical agentic tooling.

Various primitive command-line tools already exist that fit this shape:

git for provenance and history
fd for file-system discovery
ripgrep for token-level searching
tree-sitter for language/SDK symbol parsing

All of these have agent-friendly properties: fast, composable, token-friendly, and cheap enough to call repeatedly.

The Tool

All of this converges on a simple requirement: agents need a quality signal they cannot negotiate with.

That is what slop is for.

slop is a code-quality linter for codebases where AI agents write most of the diffs. It does not invent new math. It revives old, battle-tested metrics and recalibrates them for a different pace of change: one where files can jump hundreds of lines in a week, complexity can compound inside a single session, and the old assumption, “another human will review this carefully,” no longer holds by default.

A Worked Example

I pointed this metric suite at its own source code with default thresholds. It failed immediately: ten violations, one advisory, exit code 1.

i. The Linter Output

complexity
  cyclomatic
    slop/engine.py:16 run_lint — CCX 17 exceeds 10
    slop/rules/architecture.py:27 run_distance — CCX 14 exceeds 10
    slop/cli.py:122 main — CCX 11 exceeds 10

  cognitive
    slop/engine.py:16 run_lint — CogC 26 exceeds 15
    slop/rules/architecture.py:27 run_distance — CogC 20 exceeds 15
    slop/cli.py:357 cmd_doctor — CogC 16 exceeds 15

halstead
    slop/engine.py:16 run_lint — Volume 1763 exceeds 1500
    slop/engine.py:16 run_lint — Difficulty 30.9 exceeds 30

npath
    slop/cli.py:122 main — NPath 1024 exceeds 400
    slop/engine.py:16 run_lint — NPath 450 exceeds 400

ii. What This Actually Shows

The interesting part was not that something failed. It was how the metrics agreed.

run_lint was flagged five different ways: cyclomatic complexity, cognitive complexity, Halstead volume, Halstead difficulty, and NPath.

Different measurements, different formulas, same function.

None of the refactors that followed were especially impressive. This is precisely the point.

The problem was not that the code required unusual brilliance to fix. The problem was that it had been allowed to remain in a shape that experienced developers should distrust on sight, inside a workflow that still likes to pretend review is comprehensive and deliberate.

NPath 1024 is a good example. That is not an aesthetic complaint. It implies a branching structure so large that full path coverage would require an absurd testing burden.

No serious team would choose that shape on purpose. The danger was not that the code was broken. The danger was that it already worked well enough to be left alone.

In practice, the fixes were ordinary. One orchestration function was split by responsibility. One long conditional chain became a dispatch table. The code did not become better in any heroic sense. It simply stopped being structurally irresponsible.

iii. Before and After the Refactor

Function	Metric	Before	After	Default threshold
`run_lint`	CCX	17	9	10
`run_lint`	CogC	26	13	15
`run_lint`	Volume	1763	1034	1500
`run_lint`	Difficulty	30.9	18.0	30
`run_lint`	NPath	450	14	400
`run_distance`	CCX	14	8	10
`run_distance`	CogC	20	10	15
`main`	CCX	11	4	10
`main`	NPath	1024	8	400
`cmd_doctor`	CogC	16	6	15

Ten violations before. Zero after. All tests still green.

That is precisely the point. The tests were never the issue. The code already worked.

The issue was that the structure had drifted into shapes that experienced developers would distrust immediately, while the surrounding workflow still encouraged everyone to act as though plausible output plus nominal review was an acceptable substitute for stronger control surfaces.

Why This Matters More Than Ever

None of the refactors above were especially novel. They were the sort of things an experienced reviewer would often flag immediately. The if-chain wanted to be a dispatch table. The orchestration function wanted to be three smaller functions. The complexity was not invisible. It was merely unmeasured long enough to feel normal.

That is the real danger of capable agentic tooling.

It does not eliminate structural drift. It lowers the friction required to produce it, wraps the result in enough surface coherence to be trusted, and then asks humans to supervise at a volume that makes meaningful review economically unstable. By the time the failure is obvious, it is usually compound, distributed, and difficult to attribute cleanly.

Code smell was a useful human interface for judgment.

Agents need something harsher.

They need arithmetic.

Closing

The field already solved most of the hard part. The metrics exist. The papers exist. What changed is the environment.

Code is now produced at a pace, and merged under a style of confidence, that the old human workaround can no longer absorb.

That is the case for reviving these measurements now: not as academic relics or dashboard furniture, but as control surfaces. As external constraints. As the difference between asking an agent to “clean this up” and forcing it to collide with something it cannot reinterpret.

The metrics are old.
The problem is not.

So it's time we started asking ourselves:

Did the model get worse, or did we stop asking it to be better?

Project

Source Code and Documentation

On PyPi: agent-slop-lint

Installation + Setup

pip install agent-slop-lint

cd path/to/project/
slop init

# [Optional] Install skill and/or commit hook
slop hook                  # Disable w/ slop hook --disable
slop skill .claude/skills  # Or whatever agent tooling you use

Ask your Agent About It

llms.txt

Academic References

Topic	Source
Code smells	Fowler, M. Refactoring: Improving the Design of Existing Code. Addison-Wesley, 1999.
Cyclomatic Complexity	McCabe, T. J. “A Complexity Measure.” IEEE Transactions on Software Engineering, 1976.
Halstead Metrics	Halstead, M. H. Elements of Software Science. Elsevier, 1977.
NPath Complexity	Nejmeh, B. A. “NPATH: A Measure of Execution Path Complexity and Its Applications.” Communications of the ACM, 1988.
CK Metric Suite	Chidamber, S. R., and Kemerer, C. F. “A Metrics Suite for Object Oriented Design.” IEEE Transactions on Software Engineering, 1994.
Main Sequence / Package Metrics	Martin, R. C. “OO Design Quality Metrics: An Analysis of Dependencies.” 1994; see also Agile Software Development, Principles, Patterns, and Practices, 2002.
Dependency Cycles / ADP lineage	Lakos, J. Large-Scale C++ Software Design. Addison-Wesley, 1996.
Hotspots / Change Coupling	Tornhill, A. Your Code as a Crime Scene. Pragmatic Bookshelf, 2015.
Cognitive Complexity	Campbell, G. A. “Cognitive Complexity.” SonarSource white paper, 2018.
Automation and supervision failure	Bainbridge, L. “Ironies of Automation.” Automatica, 1983.

DEV Community: Jordan Gunn