upstream-atomic-crm/.claude/rules/coding-style.md

paths

paths

Coding Style

Immutability (critical)

Always create new objects, never mutate existing ones:

• Wrong: modify original object in-place
• Correct: return a new copy with the change applied

Rationale: prevents hidden side effects, makes debugging easier, enables safe concurrency.

Core principles

KISS — prefer the simplest solution that works. Optimize for clarity over cleverness.

DRY — extract repeated logic into shared functions. Introduce abstractions when repetition is real, not speculative.

YAGNI — do not build features before they are needed. Start simple, refactor when the pressure is real.

Scope discipline: implement exactly what the task asks, no more. An adjacent problem you notice (a nearby bug, a tempting refactor, missing tests elsewhere) is REPORTED, never fixed in the same change. Never expand scope silently.

File organization

Many small files over few large files:

• 200-400 lines typical, 800 max
• High cohesion, low coupling
• Organize by feature/domain, not by type
• Extract utilities from large modules
• Grow the file count, not the file: when an edit would push a file past the ~400-line typical ceiling, extract a new focused module instead of appending to the existing one

Error handling

• Handle errors explicitly at every level
• User-facing code: provide friendly error messages
• Server-side: log detailed error context
• Never silently swallow errors

Input validation

• Validate all user input before processing
• Use schema-based validation where available
• Fail fast with clear error messages
• Never trust external data (API responses, user input, file content)

Naming conventions

• Variables and functions: camelCase
• Booleans: is, has, should, or can prefix
• Interfaces, types, components: PascalCase
• Constants: UPPER_SNAKE_CASE
• Custom hooks: camelCase with use prefix

Code smells to avoid

• Deep nesting (>4 levels) — use early returns
• Magic numbers — use named constants
• Long functions (>50 lines) — split into focused pieces
• Large files (>800 lines) — extract modules