code-humanizer

Overview

The prose humanizer catalogs AI writing tells — em-dashes, “it's not just X, it's Y,” rule-of-three. code-humanizer catalogs AI coding tells: the structural debt coding agents leave behind when they optimize for “tests pass” instead of a codebase that stays healthy.

It's a single-Markdown agent skill (SKILL.md) — no build step, no dependencies. Default mode is scan → report (a findings table with pattern #, severity, evidence, proposed fix, and behavior risk); fix mode runs only on your approval, one pattern-class per commit, tests green after every step.

The pattern catalog

16 numbered AI-coding tells in 5 tiers — each with detection signals and before/after examples in the skill. Every finding gets a severity 0–4.

Tier 1 — Duplication & reinvention

• 1. Reimplementing an existing helper (the signature tell) — a new private function duplicating something in utils / a sibling module; agents write from the prompt outward, not from the repo inward
• 2. _v2 / _new / _impl clones — foo and foo_v2 both alive; two sources of truth
• 3. Reinventing stdlib / installed deps — hand-rolled groupby, deep-copy-via-JSON, manual URL parsing

Tier 2 — Speculative architecture

• 4. Single-implementation abstraction — an ABC / registry / “pluggable backend” with exactly one implementation and one call site
• 5. Dead “for future use” code — helpers with no call site; docstrings promising flexible, extensible, seamless
• 6. Wrapper that adds nothing — a function whose body is one same-argument call
• 7. Config / API sprawl for a local case — a global flag or public parameter consulted from exactly one place

Tier 3 — Defensive slop

• 8. Broad exception swallowing — except Exception: return "" turns visible crashes into invisible corruption
• 9. Unjustified try-import fallback — try: import ujson except ImportError: import json with no benchmark, extras entry, or fallback test
• 10. Attribute-probing chains — hasattr/getattr/isinstance ladders accepting “dict or object or maybe None”
• 11. Paranoid re-validation — if x is not None on values just constructed

Tier 4 — Noise

• 12. Narrating comments — the comment restates the next line (# Join the rows with newlines)
• 13. Boilerplate docstrings — the function name with spaces; robust, comprehensive, seamless
• 14. Dead imports, unused variables, banners — leftovers from deleted attempts; # ===== SECTION =====; stray debug prints

Tier 5 — Test slop (report-only by default)

• 15. Tests that assert the mock — every collaborator mocked; the test can never fail for a real reason
• 16. Trivial or duplicated assertions — asserting literals; the same case re-tested under three names

Why it's not just a pattern list

Modern agents already recognize most slop when pointed at a file. Where they fail is discipline. In the baseline test, an agent without this skill cleaned a slop file nicely — and silently changed a public error type along the way (swapped an AttributeError for a “nicer” ValueError), in one un-reviewable mega-change, editing before ever running the tests. So the skill's core is three iron rules the catalog hangs off:

1. Behavior preservation is absolute — including error types and timing. Latent bugs get reported, never silently “improved.”
2. No tests → no edits. The suite is the oracle for “meaning-preserving”; a missing oracle means report-only mode.
3. One pattern-class per commit, suite run after each, behavior-risk changes isolated in [BEHAVIOR]-labeled commits.

Plus a false-positive guard: severity 1 = “present but justified” (fallbacks with documented reasons, defensive code at trust boundaries, plugin registries, migration-period _v2s) is exempt. The goal is a healthier repo, not a body count.

Real-world run

First field test: a private ML research repo — 13.4k LOC of Python (a 21-module package + 36 experiment scripts + 20 test files), written largely by coding agents under human review. Scan mode, zero edits, git status clean before and after.

24 findings, with a sharp profile. Defensive slop (broad excepts, try-import fallbacks, probing chains, narrating comments): zero. Test slop: zero across all 20 test files. The debt was almost entirely Tier-1 duplication (11 findings, 40+ pasted instances) — and the copies were already biting: a provenance helper pasted into 20 of 22 run scripts had already drifted (3 copies gained an env-var fallback the other 17 lack); an experiment class copied into a “learned” variant whose metric method silently diverged. 4 findings were exempted as justified; 8 of 36 scripts and 6 of 21 modules came back fully clean — and were reported as clean.

The take-away matched the skill's premise: agents working under review don't swallow errors — they rewrite what already exists. Repo-context duplication detection is the tier that matters.

Install & use

Copy or clone the directory into your agent's skills folder:

git clone https://github.com/LeonardNJU/code-humanizer ~/.claude/skills/code-humanizer

Any harness that reads SKILL.md agent skills works the same way — one Markdown file, no build step, no dependencies. Then just ask:

> use code-humanizer to scan this PR
> deslop pkg/report.py — you have my approval to fix
> this repo was vibe-coded, humanize it (report first)

Scope

• Examples are Python; the patterns and workflow are language-agnostic (signals mention Python idioms — port as needed).
• It removes structural debt, not formatting opinions — that's your linter's job.
• Judgment-heavy debt (root-cause-vs-workaround fixes) is reported, not auto-fixed.

Introduction threads: linux.do · NJU-AIA forum