codebase-hygiene

Load applicable rules

Loaded references are authoritative.

• Structural movement, ownership migration, and compatibility cleanup: references/refactoring.md
• Test assessment, addition, deletion, and scoring: references/testing.md
• Calls, dispatch, callbacks, continuations, imports, initialization, startup, and runtime cost: references/execution-topology.md
• Dependencies, lockfiles, installers, scripts, CI actions, runtimes, compilers, and third-party tools: references/dependency-safety.md
• Load every reference matching a repository language: references/js-ts.md, references/python.md, references/go.md, references/rust.md
• React components, Hooks, rendering, state, and framework boundaries: references/react.md
• For other languages, use repository evidence and current official ecosystem documentation.
• Scores and caps: references/scoring-rubric.md. Score only when requested or already required.

Goal: leave a codebase that another agent can navigate efficiently, change coherently, verify quickly, and explain to a human from the code itself.

Inspect before editing

Optimize for agents working through search, bounded reads, and coherent multi-file edits. Do not imitate one-file-at-a-time human editing.

Read governing instructions, owning files, consumers, contracts, tests, active checks, runtime edges, and generated or framework-owned areas. Read every file you will change in full, continuing through tool chunks when needed. Search confirms callers and edges but does not replace understanding the owner.

Shape ownership

1. Resist append bias. Before adding a branch, field, handler, test, or helper, decide whether it strengthens the current owner or reveals another responsibility.
2. Exclude generated, vendored, and framework-owned files from size judgment unless maintained directly.
3. Treat a maintained file above roughly 300 lines as a godfile candidate, not an automatic failure. Inspect mixed concerns, unrelated change reasons, central-path growth, hidden state, and agent readability. Cohesive stable tables, protocols, and algorithms may remain large. Growing mixed-responsibility files may not.
4. Treat a function above roughly 50 lines as a review candidate. Split across ownership, abstraction level, state transition, effect, or failure-policy boundaries. Keep coherent algorithms and state machines together when extraction hides ordering.
5. Collapse one-use helpers, wrapper factories, interfaces, and microfiles that add navigation without owning a decision, contract, translation, effect, lifecycle, resilience, security, or diagnostic boundary.