project-always

Project Conventions

These rules are loaded automatically by Cursor on every Agent interaction (alwaysApply: true). They define the baseline behaviour expected across the entire codebase, regardless of file type.

---

Build & Verify Commands

• Build: <your build command>
• Test (single): <your single-test command>
• Lint / typecheck: <your lint command>

Always run lint/typecheck after a series of edits.

Code Style

• Prefer functional programming over OOP; use classes only for connectors and interfaces to external systems.
• Write pure functions — return new values, never mutate input parameters or global state.
• Write single-purpose functions — no multi-mode behaviour, no flag parameters that switch logic branches.
• Never use default parameter values — make all parameters explicit at the call site.
• Create named type definitions for complex data structures; no anonymous inline shapes crossing function boundaries.
• Before writing new logic, search the codebase with rg for existing implementations.
• Follow YAGNI — do not add abstractions for speculative future use cases.
• Keep diffs small; prefer targeted edits over wide refactors unless the full refactor is the explicit task.

Error Handling

• Raise errors explicitly at the point of failure; never swallow exceptions silently.
• Use specific error types; avoid generic catch-alls that hide root causes.
• Fix root causes, not symptoms; no workaround shims unless the root fix is out of scope.
• No fallbacks or degraded-mode logic unless explicitly requested.
• External service calls: retry with exponential backoff, log each retry as a warning, re-raise the last error.
• Error messages must include: request params, response body, status codes, correlation IDs.
• Use structured logging fields — do not interpolate dynamic values into message strings.

Testing

• Match the existing test strategy; do not introduce new frameworks without discussion.
• Do not add tests unless the task explicitly requires them.
• Prefer integration or end-to-end tests over unit tests.
• Avoid mocks when real service calls are practical.
• Unit tests are acceptable for pure data-transformation functions only.
• Never add tests to increase coverage numbers.