The Clean Agent Code Standard.
As agents write more of the code that ships, teams need a shared definition of "good" that does not depend on whoever happens to review the PR. Six principles below — each maps to a named rule and engine. Same code scored twice returns the same result.
Six principles
Each one is the rule, why agents violate it, and the aislop checks that enforce it. Nothing advisory.
- 01
Comments explain intent, not mechanics
A comment exists only to capture a non-obvious WHY. Prose that restates what the code already says is removed.
Agents are trained to narrate their reasoning. They leave the narration in the file: multi-line preambles and line-by-line restatements that duplicate the signature and the operators.
ai-slop·narrative-comment, trivial-comment
- 02
Errors are handled or propagated, never swallowed
Every caught error is logged, recovered from, or rethrown. An empty catch is a defect, not defensive code.
Agents wrap risky calls in try/catch to "be safe" without deciding what should happen on failure. The catch ends up empty and the outage takes hours to trace because no log line exists.
ai-slop·swallowed-exception
- 03
Types are honest
No `as any`, no `as unknown as X`, no unexplained type-checker suppressions. Validate at the boundary, then trust the type.
When an agent cannot derive the real shape, it reaches for an escape hatch. The error disappears in five seconds and every downstream guarantee disappears with it.
ai-slop·unsafe-type-assertion, double-type-assertion, ts-directive
- 04
No dead or unreachable code
Code that can never run, branches gated on constants, unused imports, and stubbed no-op functions do not ship.
Refactors leave statements stranded after a return, hard-coded toggles after testing, and imports orphaned when their consumer is deleted. The code looks load-bearing and does nothing.
ai-slop, code-quality·unreachable-code, constant-condition, unused-import, empty-function, dead-code
- 05
Functions stay within a reviewable size
A function does one thing and fits in a reviewer's head. Oversized bodies get decomposed before merge.
Agents append to a working function rather than refactor it, so a single body accretes branches, side effects, and responsibilities until no human can review it as a unit.
code-quality·function-length, complexity
- 06
Names describe intent
Variables, parameters, and functions are named for the role they play, not generic placeholders like `data`, `result`, or `temp`.
Without seeing how a value is used downstream, agents fall back to generic nouns. Every reader then re-infers the role from context instead of reading it off the name.
ai-slop·generic-naming, thin-wrapper, console-leftover, todo-stub
Engines
- ai-slop — Named anti-patterns agents leave behind.
- code-quality — Structure: size, complexity, dead code.
- security — Risky primitives in “working” solutions.
- architecture — Team-authored boundaries for a real codebase.
Evidence for each rule: research hub →
Enforce the standard on your repo.
One command runs every principle on this page, deterministically, with a 0–100 score and the exact findings.
npx aislop scan