Skip to content

Development 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:

1
2
3
4
5
## 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:
  2. What you tried
  3. Specific error messages

  4. Why you think it failed

  5. Research alternatives:

  6. Find 2-3 similar implementations

  7. Note different approaches used

  8. Question fundamentals:

  9. Is this the right abstraction level?
  10. Can this be split into smaller problems?

  11. Is there a simpler approach entirely?

  12. Try different angle:

  13. Different library/framework feature?
  14. Different architectural pattern?
  15. 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"

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