claude-initial-setup: Cursor rule for Cursor

Coding Standards

Immutability

Always create new objects instead of mutating. Use spread operators, structuredClone, or library solutions like immer.

// WRONG
user.name = name;
items.push(newItem);

// CORRECT
const updated = { ...user, name };
const added = [...items, newItem];
const removed = items.filter(x => x.id !== id);
const mapped = items.map(x => x.id === id ? { ...x, ...changes } : x);

Python: Use @dataclass(frozen=True) and replace(). Use tuples and frozensets for immutable collections. Go: Use value receivers and return new structs.

File Organization

• 200-400 lines per file, 800 max
• Organize by feature/domain, not by type
• Co-locate tests next to source files
• Move to shared/ only when used by 3+ features
• No god files (utils.ts with 40 exports)

Functions

• Under 50 lines each
• No nesting deeper than 4 levels
• Use early returns and guard clauses

Naming

• Variables: describe WHAT (activeUsers), not HOW (data)
• Booleans: is/has/can/should prefix (isActive, hasPermission)
• Functions: verb + noun (getUserById, formatDate, validateEmail)
• Collections: plural nouns (users, orderItems)
• Constants: SCREAMING_SNAKE (MAX_RETRIES, API_BASE_URL)
• Language casing: camelCase (JS/TS), snake_case (Python), PascalCase (Go exports)

Git Conventions

Commits

Format: <type>(<scope>): <description> Types: feat, fix, refactor, docs, test, chore, perf, ci Rules: imperative mood, lowercase, under 72 chars, no period

Branches

Format: <type>/<ticket>-<description> in kebab-case Types: feature/, fix/, hotfix/, release/

Pull Requests

• Under 400 lines of changes
• Include summary, changes, test plan
• Squash merge for features, merge commit for releases
• Never force-push during review

Testing

TDD Workflow

1. RED: Write failing test
2. GREEN: Write minimal code to pass
3. REFACTOR: Clean up, keep tests green
4. Target 80%+ coverage

Test Structure

• Unit tests co-located: auth.ts / auth.test.ts
• Integration tests: test/integration/
• E2E tests: test/e2e/
• Factories for dynamic data, fixtures for static data