Codebase hygiene

What it means

Codebase hygiene is the observable condition of a repository: how much dead code, duplication, hardcoded values, and inconsistent naming a reader has to work around before changing it. Its unit is the code smell, which Martin Fowler defines as “a surface indication that usually corresponds to a deeper problem in the system”.

Two neighbors get mixed up with it:

• Architecture quality judges the design. Hygiene does not: Enji Guard’s audit documentation says the check “looks at broad repository smells rather than judging architecture style or demanding a rewrite”.
• Technical debt is the cost framing. Fowler describes cruft as “deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system further”; the extra effort per feature is the interest. Hygiene is the current state; debt is what it costs over time.

How it works

Measurement turns smells into a number. SonarQube’s documentation defines technical debt as “the sum of the maintainability issue remediation costs”, each an estimated effort in minutes, divides that sum by an estimated cost to develop the code, and maps the ratio onto a maintainability rating from A at 5% or below to E at 50% or above.

The rules behind the rating decide what it measures. The AI-Generated Smells study on arXiv cautions that earlier findings of more maintainable LLM code “often aggregate superficial code linting issues with deeper structural code smells”; on that reasoning, a check that weighs a semicolon like a god module says little.

Why it matters for AI-written code

Google’s code review standard exists because “codebases degrade through small decreases in code health over time”. Its reviewer guidance adds a default: “If no other rule applies, the author should maintain consistency with the existing code.” A coding agent tends to follow the same default, working from the code in front of it, so a duplicated helper or a swallowed error becomes the template for the next change.

Agents also add smells of their own. The same arXiv study reports “a distinct machine signature of defects”: “as models become more capable, they generate increasingly bloated and coupled code”, agents rewrite invocation logic inline in “a ‘copy-paste’ coding style that inflates code volume and complicates maintenance”, and “neither functional correctness nor detailed prompting mitigates this decay”. None of that shows up in a green test run.

How Enji Guard helps

The catalog action “Run codebase hygiene audit” looks for “repository clutter, dead code, hardcoded values, weak maintenance commands, and patterns that make future changes harder”. Nineteen criteria are scored 0 to 5, among them maintenance commands, author-home paths, magic values, god modules, and ignored errors. A 4–5 means the smell is absent or isolated, 0–1 that it is systemic.

The inspection stage’s stated goal is to “inspect codebase hygiene and maintenance risks using repository evidence, not guesses”, and every finding cites a “file path, command, count, or config name”.

The final score is the lower of the normalized scorecard and a severity score that starts at 100, subtracts 65 per critical, 25 per high, 10 per medium, and 3 per low finding, and is capped at 39 by any critical finding.

• Local scope, not architecture. One selection rule: “Do not recommend broad rewrites unless the evidence directly supports them.”
• Dead code is handed off. Broad smells belong here; the separate dead code audit owns reachability and protected-use reasoning.

The report ends with an Improvement Checklist: normally five tasks, each with a completion signal. The audit reruns as the repository changes, so the Codebase Hygiene block on the project dashboard shows whether this part of the green zone is holding while agents keep committing.

Nothing in the repository changes during this audit: it does not mutate source, clean files, or open issues or pull requests, and no autofix is paired with it. Cleanup is your team’s change; a rerun after the merge confirms the original evidence is gone and nothing intentional went with it.