Code Quality Principles

Architecture

@architecture

Design Principles

@illegal-states

@single-responsibility

@parse-dont-validate

@composition

@open-closed

@explicit-dependencies

@fail-fast

@domain-errors

@immutability

@no-stringly-typed

@happy-path

Code-Level Standards

• Clarity over brevity: Explicit, readable code over clever one-liners
• Reduce nesting: Use early returns to flatten conditionals
• Eliminate redundancy: Remove duplicate logic and dead code
• No workarounds: Fix root causes, never suppress lints without explicit approval

Testing Strategy

1. Property-based testing for pure functions—verify invariants across thousands of inputs
2. Snapshot testing for complex data structures—catch unintended changes
3. Integration tests for the imperative shell—verify I/O coordination

Review Checklist

• Types prevent invalid states (no interacting boolean flags)
• Functions have single responsibility
• Validation happens at boundaries, not scattered throughout
• Dependencies are explicit (no hidden globals)
• Errors surface immediately with context
• Mutations are justified and isolated
• No magic strings where types would work
• No lint suppressions without explicit approval