Code Quality Standards¶
Deep-dive reference for SOLID principles and type safety. See Core Principles in CLAUDE.md for the essentials.
SOLID Principles¶
- Single Responsibility: Each module/class should have one reason to change
- Open/Closed: Open for extension, closed for modification
- Liskov Substitution: Subtypes must be substitutable for base types
- Interface Segregation: Prefer small, specific interfaces over large general ones
- Dependency Inversion: Depend on abstractions, not concretions
DRY (Don't Repeat Yourself)¶
- Knowledge duplication (must fix): Same business logic in multiple places
- Incidental duplication (evaluate carefully): Similar code that may evolve differently
- Maintain a single source of truth for business logic
Type Safety¶
- Use strict typing where available
- Avoid
anytypes in TypeScript (if applicable) - Use type narrowing and discriminated unions
- Leverage compile-time type checking
Performance Checklist¶
- N+1 query patterns (loops with DB calls)
- Blocking I/O in async paths (readFileSync, execSync)
- Excessive memory allocations
- Missing pagination
- Inefficient algorithms (O(n²) when O(n) possible)
- Cache opportunities missed
Quality Gates¶
All of these must pass before committing:
- Tests pass
- Linter passes
- Type checker passes (if applicable)
- Build succeeds
- Security audit passes
Refactoring Discipline¶
Two Hats Rule: Never mix refactoring and optimization in the same session.
- Hat 1: Refactoring - Change structure, NOT behavior. Tests must pass unchanged.
- Hat 2: Optimization - Improve performance, NOT behavior. Benchmarks required.
When switching hats, commit first, then switch context.
Naming Conventions (suggested defaults)¶
Suggested defaults — customize per project.
- Files: camelCase (e.g.,
userService.ts,authMiddleware.py) - Components: PascalCase (e.g.,
UserProfile.tsx,LoginForm.vue) - Directories: kebab-case for multi-word (e.g.,
api-utils/,auth-handlers/) - Constants: UPPER_SNAKE_CASE
- Variables/functions: camelCase (JS/TS), snake_case (Python/Go/Rust)
Structured Logging¶
- Use a structured logger instead of raw console/print calls
- Include correlation IDs for request tracing
- Log levels: ERROR (failures), WARN (degraded), INFO (key events), DEBUG (troubleshooting)
- Never log secrets, tokens, or PII
Automated Quality Suite¶
Generic categories — configure with the tools appropriate for your stack.
| Phase | Checks |
|---|---|
| Pre-commit | Lint + format + type check + secret scan |
| CI pipeline | Lint + secret scan + vulnerability scan + tests |
| Continuous | Dependency updates + security advisories |