Project Rules

General Principles

• Write code for correctness and clarity first; optimize only after measuring.
• Make the smallest change that solves the problem — no drive-by refactors outside the task's scope.
• Never leave dead code, commented-out blocks, or speculative abstractions behind; delete them.
• Prefer boring, well-understood solutions over clever ones.
• When requirements are ambiguous, state your assumptions explicitly; ask before guessing at an interface.
• Keep modules focused: one responsibility per file, one concern per commit.
• Verify your work before declaring it done: run the tests, the type checker, and the linter.

TypeScript Style

• Keep strict TypeScript enabled; the build must pass with zero type errors.
• Avoid any — use unknown at system boundaries and narrow it deliberately.
• Rely on inference for locals; annotate every exported function signature.
• Model state with discriminated unions instead of boolean flag parameters.
• const by default; never reassign parameters; prefer pure data flow.
• Handle every case in a switch over a union type — make impossible states unrepresentable.
• Keep exported surfaces small: export only what other modules actually consume.
• Prefer async/await over raw promises; only catch errors you can handle, otherwise rethrow with added context.
• Limit functions to roughly 50 lines; extract helpers only when the extraction improves clarity.

Testing Principles

• Test behavior through public interfaces, not private implementation details.
• Follow Arrange–Act–Assert; one logical assertion per test.
• Name tests as specifications: "returns 404 when the build artifact is missing".
• Every bug fix ships with a regression test that fails without the fix.
• Tests must be deterministic: no sleeps, no reliance on wall-clock time or iteration order — inject fakable clocks.
• Cover the happy path, edge cases (empty, boundary, invalid), and failure paths.
• Keep tests independent — shared mutable fixture state is a bug factory; build fresh state with factories.
• Mock only at true boundaries (network, filesystem, clock), never the code under test.