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. This is an open, deterministic, reproducible one. Each principle below is enforceable: it maps to a named rule and an engine, and the same code scored twice returns the same result.
The standard is the definition; aislop is its reference implementation. The CLI is MIT-licensed and runs with no LLM at runtime, so the standard is verifiable by anyone, sub-second, on every edit.
A definition you can run, not just read.
Security teams map their controls to NIST and OWASP. AI-written code has no such reference. So we authored one: a named set of principles, each tied to a deterministic check, so "clean" stops being a matter of taste and becomes something a machine can prove on every PR.
The deterministic gate runs the standard on every keystroke and every PR. No LLM at runtime, sub-second, reproducible.
Every principle traces to a named rule and a public corpus. Same code in, same score out, so the result is auditable rather than asserted.
The same standard becomes policy: thresholds, attribution by agent, and rules that get stricter as the research corpus grows.
Six principles, each enforceable.
Each principle is one rule, the reason agents violate it, and the named aislop rule and engine that enforce it. Nothing here is advisory; all of it is checkable.
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.
narrative-comment, trivial-comment
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.
swallowed-exception
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.
unsafe-type-assertion, double-type-assertion, ts-directive
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.
unreachable-code, constant-condition, unused-import, empty-function, dead-code
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.
function-length, complexity
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.
generic-naming, thin-wrapper, console-leftover, todo-stub
The principles map to engines.
The standard is grouped, not flat. Each principle is enforced by one or more deterministic engines, so a team can see exactly which layer caught a finding and why.
ai-slop
The 50+ named rules and checks AI agents leave behind: narrative comments, swallowed exceptions, unsafe casts, todo stubs, generic naming, console leftovers.
code-quality
Structural erosion: oversized functions, unreachable code, dead code, and complexity that grows past the point a reviewer can hold it in their head.
security
Risky constructs and unsafe primitives that agents reach for when a prompt asks for "working" code without asking whether it is safe.
architecture
Project-specific rules a team authors once, so the standard adapts to a codebase's real boundaries instead of a generic baseline.
v0.1, and it gets stricter.
This is a draft. The standard is versioned because it is meant to tighten: as the public research corpus grows, repeatable failure classes become new rules and thresholds move. A version pin means a scan is reproducible against the exact definition that was current when it ran.
Every change to the standard is justified by evidence, not opinion. The provenance for each rule lives in the public research program.
See the research behind the rules →- • 6 principles
- • 50+ rules and checks across 6 engines
- • 8 language targets, 14 agent handoffs
Enforce the standard on your repo.
One command runs every principle on this page, deterministically, and hands back a 0–100 score with the exact findings. No setup, no LLM, no per-reviewer drift.
npx aislop scan