Claude code Development Guidelines

# 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`:

“`markdown
## 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”

### 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

## Important Reminders

**NEVER**:
– 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