Code Hygiene

Code Hygiene

Treat code hygiene as craft work. The goal is not only to make files shorter. The goal is to make the system easier to understand, safer to change, easier to test, and more pleasant to work in.

Core Standard

Hard guardrails:

• New files stay under 700 LOC.
• Existing files over 700 LOC are refactored before adding meaningful code.
• Functions over about 150 LOC are decomposed.
• Duplication is not tolerated. Consolidate it or parameterize the variation.

These numbers are guardrails, not the whole craft. Also look for boundary clarity, ownership, naming, dependency direction, test shape, and developer experience.

Operating Mode

When the user asks for a hygiene pass:

1. Read local project instructions first.
2. Recall project context through cm when available.
3. Check the worktree before editing.
4. Measure before judging.
5. Find natural seams before moving code.
6. Prefer existing files when ownership already fits.
7. Create a new module only when no existing module can own the code cleanly.
8. Move behavior mechanically first, then improve shape.
9. Verify after every meaningful slice.

If the user asks only to "take a look" or "find seams", produce a refactor map without editing. If they ask to continue or fix it, implement.

Measurement Pass

Start with cheap facts:

git status --short
find . -name AGENTS.md -o -name CLAUDE.md -o -name LESSONS.md
rg --files | wc -l
wc -l TARGET_FILES

Use structure tools when available:

• Use fmm for indexed repos: file topology, outlines, exports, dependency graphs, downstream blast radius, and symbol reads.
• Use rg for targeted text search.
• Use language tools when they exist: cargo, ruff, mypy, pytest, pnpm, tsc, eslint, go test, gofmt, or repo native just targets.

Avoid reading huge files end to end unless you are about to edit them. Use outlines, symbol reads, or a bounded summary first.

Health Signals

Look for these signals:

Natural Seam Heuristics

Prefer seams that match how the system thinks:

• Models and vocabulary: pure dataclasses, structs, enums, types, constants, request or response shapes.
• Domain core: pure logic with no IO, framework, process, or clock.
• Adapters: filesystem, network, database, subprocess, browser, CLI, framework, or platform specific code.
• Orchestration: lifecycle, registry, retries, rollback, locks, and state transitions.
• Fanout and transport: queues, streams, listeners, sockets, broadcast, backpressure, and replay.
• Serialization: JSON, wire format, schema conversion, parser, emitter.
• Policy: validation, authorization, routing, feature flags, limits.
• Test harnesses: fake services, builders, fixtures, process harnesses.

Prefer moving code to an existing owner when the owner is already clear. For example, PTY process constants belong with PTY process primitives; browser viewer replay does not belong there if that file is intentionally low level.

Refactor Strategy

Use small reversible slices.

1. Name the ownership map. Say which responsibility goes where and why.
2. Move pure vocabulary first. Types and constants usually move safely.
3. Extract cohesive behavior next. Move one behavior cluster at a time.
4. Keep lifecycle invariants together. Do not split teardown, rollback, cancellation, lock release, or transaction boundaries until tests protect them.
5. Keep public contracts stable unless the repo allows breakage. If the repo is pre release and breakage is welcome, still make the break explicit.
6. Preserve compatibility shims only when useful. Delete obsolete paths once callers are migrated.
7. Update tests and imports in the same slice.

Mechanical movement comes before clever improvement. First prove behavior is unchanged. Then simplify names, consolidate duplication, or strengthen tests.

Boundary Rules

• A lower layer must not import an upper layer.
• Pure model modules should not import framework or runtime modules.
• Adapter modules may depend on the domain. Domain modules should not depend on adapters.
• A module name should tell a future maintainer what belongs there.
• A neutral seam should import cleanly in a fresh subprocess when the language makes import cycles possible.
• Generated code, vendored code, and migration snapshots may be exempt from LOC limits, but do not hide hand written complexity there.

Verification

Run the smallest tests that prove the moved behavior, then the repo gate when feasible.

Useful language defaults:

For boundary refactors, add or update boundary tests:

• Import boundary tests.
• Subprocess import tests for neutral modules.
• Dependency direction tests when the repo has a tool for it.
• Focused regression tests for lifecycle, rollback, stream ordering, or data migration invariants.

Never report success until the command output and exit code were observed.

Output Shape

For an inspection only:

• Current measurements.
• Natural seams.
• What should move to existing files.
• What deserves a new file.
• What must stay together for now.
• Suggested order and verification gates.

For an implemented refactor:

• Files changed.
• LOC before and after for important files.
• Ownership changes.
• Behavior intentionally unchanged or explicitly changed.
• Verification commands with observed results.

Keep the final report concise. The value is in the cleaner code and the proof, not in a long essay.