Refactor

Language-agnostic

Principles that apply regardless of stack.

Modular (no god files)

Changes should land in small, cohesive units with obvious homes. Prefer many clear files over one warehouse file.

Before adding or extending code

1. Single reason to change: Would two unrelated features both edit this same file? If yes, introduce a boundary (subfolder, service, hook, adapter) instead of growing the god file.
2. Naming matches responsibility: File name reflects what it owns; avoid utils.ts, helpers.ts, or stuff.ts as dumping grounds unless scope is narrowly defined (e.g. date-utils.ts only date formatting).
3. Layers stay thin at the top: Routes/pages/containers orchestrate; they do not own every type, transformer, and side effect inline.
4. Imports tell a story: If a module imports widely unrelated domains, split by domain or by layer (presentation vs logic vs IO).

God file warning signs