continuous-refactor

Continuous refactor

Agents reflexively add and rarely delete. Without explicit pressure to remove, projects calcify in weeks. Refactor passes are standing practice, not occasional cleanup.

When to apply

• After shipping a feature commit-set (a coherent group of feat/fix commits that delivered a user-visible change).
• On a scheduled cadence — weekly is a reasonable starting point.
• When a file or module is conspicuously growing without a corresponding shrink elsewhere.

Greenfield projects start lower; mature projects trend higher. Aim for refactor work to be a meaningful share of total commits over time — not a footnote.

The pass

1. Look for slop, not perfection. Unused imports, dead branches, abandoned helpers, commented-out code, defensive checks for impossible scenarios, premature abstractions with one caller.
2. Look for cross-file duplication. Two near-identical functions in different modules usually want to be one.
3. Look for architectural residue. Modules whose responsibilities have drifted; abstractions added for a hypothetical second implementation that never arrived.
4. Delete more than you add. A refactor commit with a positive line count usually isn't a refactor.
5. Tests stay green throughout. A refactor that requires changing tests changes behavior; that's not a refactor.

Tooling

Concern	TS / JS	Python equivalent
Dead code	knip	vulture
Cross-file duplication	jscpd	jscpd . (works on Python too via npx)
AST pattern rules	ast-grep	ast-grep or semgrep
Linting	eslint	ruff (extend rules as patterns formalize)
Cyclomatic complexity	(varies)	radon

These belong in the refactor pass, not the regular dev loop. Ruff / eslint baseline rules already catch most line-level slop on every commit; the refactor pass is for what they don't see.

Anti-patterns

• Refactor PRs bundled with feature changes. Split.
• "Refactors" that mostly rename things. Renaming alone rarely earns the churn cost.
• Premature abstraction in the name of refactoring. Three similar lines is better than the wrong abstraction.
• Touching code you don't understand to make it "cleaner." If you can't explain why the original author wrote it that way, leave it.

How to tell it's working

The refactor commit-set ships separately from feature work, deletes more than it adds (typically), and the test suite stays green throughout. Over time, the share of refactor: commits in the log trends up — that's the signal that slop reduction is keeping pace with feature work.