Skip to content

CLAUDE.md

Latest commit

 

History

History
174 lines (123 loc) · 5.27 KB

CLAUDE.md

File metadata and controls

174 lines (123 loc) · 5.27 KB
Raw

Development Guidelines

Philosophy

Core Beliefs

  • Incremental progress over big bangs - Small changes that compile and pass tests
  • Learning from existing code - Study and plan before implementing
  • Pragmatic over dogmatic - Adapt to project reality
  • Clear intent over clever code - Be boring and obvious

Simplicity Means

  • Single responsibility per function/class
  • Avoid premature abstractions
  • No clever tricks - choose the boring solution
  • If you need to explain it, it's too complex

Process

1. Planning & Staging

Break complex work into 3-5 stages. Document in IMPLEMENTATION_PLAN.md:

## Stage N: [Name]

**Goal**: [Specific deliverable]
**Success Criteria**: [Testable outcomes]
**Tests**: [Specific test cases]
**Status**: [Not Started|In Progress|Complete]
  • Update status as you progress
  • Remove file when all stages are done

2. Implementation Flow

  1. Understand - Study existing patterns in codebase
  2. Test - Write test first (red)
  3. Implement - Minimal code to pass (green)
  4. Refactor - Clean up with tests passing
  5. Commit - With clear message linking to plan

3. When Stuck (After 3 Attempts)

CRITICAL: Maximum 3 attempts per issue, then STOP.

  1. Document what failed:

    • What you tried
    • Specific error messages
    • Why you think it failed

  2. Research alternatives:

    • Find 2-3 similar implementations
    • Note different approaches used

  3. Question fundamentals:

    • Is this the right abstraction level?
    • Can this be split into smaller problems?
    • Is there a simpler approach entirely?

  4. Try different angle:

    • Different library/framework feature?
    • Different architectural pattern?
    • Remove abstraction instead of adding?

Technical Standards

Architecture Principles

  • Composition over inheritance - Use dependency injection
  • Interfaces over singletons - Enable testing and flexibility
  • Explicit over implicit - Clear data flow and dependencies
  • Test-driven when possible - Never disable tests, fix them

Code Quality

  • Every commit must:

    • Compile successfully
    • Pass all existing tests
    • Include tests for new functionality
    • Follow project formatting/linting

  • Before committing:

    • Run formatters/linters
    • Self-review changes
    • Ensure commit message explains "why"

  • Before pushing:

    • Run npx prettier --check . from the repo root and fix any issues before pushing

Error Handling

  • Fail fast with descriptive messages
  • Include context for debugging
  • Handle errors at appropriate level
  • Never silently swallow exceptions

Decision Framework

When multiple valid approaches exist, choose based on:

  1. Testability - Can I easily test this?
  2. Readability - Will someone understand this in 6 months?
  3. Consistency - Does this match project patterns?
  4. Simplicity - Is this the simplest solution that works?
  5. Reversibility - How hard to change later?

Project Integration

Learning the Codebase

  • Find 3 similar features/components
  • Identify common patterns and conventions
  • Use same libraries/utilities when possible
  • Follow existing test patterns

Tooling

  • Use project's existing build system
  • Use project's test framework
  • Use project's formatter/linter settings
  • Don't introduce new tools without strong justification

Quality Gates

Definition of Done

  • Tests written and passing
  • Code follows project conventions
  • No linter/formatter warnings
  • Commit messages are clear
  • Implementation matches plan
  • No TODOs without issue numbers

Test Guidelines

  • Test behavior, not implementation
  • One assertion per test when possible
  • Clear test names describing scenario
  • Use existing test utilities/helpers
  • Tests should be deterministic

SQLite Migrations

This project uses wa-sqlite in the browser with IndexedDB persistence. Migrations are versioned and immutable once applied.

NEVER modify an existing migration that may have been applied in a user's browser. The migration system records version numbers in schema_migrations and skips already-applied versions. Changing the SQL of an applied migration has no effect — the old SQL is what ran.

ALWAYS:

  • Add a new migration with the next version number for schema changes
  • Use IF NOT EXISTS / IF EXISTS to make migrations idempotent where possible
  • Consider that users may have run ANY previous version of the code — their DB state may not match what the current migration history implies
  • Test that createExpense, createPanel, and other INSERT queries work against the migrated schema (FK constraints with PRAGMA foreign_keys=ON validate referenced tables at statement preparation time, not just execution)
  • Verify migrations in the browser, not just in tests (tests always run all migrations fresh; the browser may have a mix of old and new)

Important Reminders

NEVER:

  • Use git worktrees — always work directly in the main tree
  • Use --no-verify to bypass commit hooks
  • Disable tests instead of fixing them
  • Commit code that doesn't compile
  • Make assumptions - verify with existing code

ALWAYS:

  • Commit working code incrementally
  • Update plan documentation as you go
  • Learn from existing implementations
  • Stop after 3 failed attempts and reassess